CPAN::Meta::History::Meta_1_3 - META.yml 的 1.3 版元資料規格
這是 META.yml 檔案 1.3 版規格的歷史副本，版權所有者為 Ken Williams，並採用與 Perl 相同的條款授權。
與原始版本的差異
修正各種拼寫錯誤
包含 Module::Build 0.2805 的有效授權清單，而非連結到該模組，並針對文字和連結進行小幅更新，以反映發布時的版本。
修正一些失效連結，指向可用的資源。
--- #YAML:1.0
name: Module-Build
abstract: Build and install Perl modules
version: 0.20
author:
- Ken Williams <kwilliams@cpan.org>
license: perl
distribution_type: module
requires:
Config: 0
Cwd: 0
Data::Dumper: 0
ExtUtils::Install: 0
File::Basename: 0
File::Compare: 0
File::Copy: 0
File::Find: 0
File::Path: 0
File::Spec: 0
IO::File: 0
perl: 5.005_03
recommends:
Archive::Tar: 1.00
ExtUtils::Install: 0.3
ExtUtils::ParseXS: 2.02
Pod::Text: 0
YAML: 0.35
build_requires:
Test: 0
urls:
license: http://dev.perl.org/licenses/
meta-spec:
version: 1.3
url: http://module-build.sourceforge.net/META-spec-v1.3.html
generated_by: Module::Build version 0.20本文件說明 META.yml 規格的 1.3 版。
META.yml 檔案描述已貢獻 Perl 發行版的相關重要屬性，例如在 CPAN 上找到的那些。它通常由 Module::Build、Module::Install 和 ExtUtils::MakeMaker 等工具建立。
META.yml 檔案中的欄位旨在協助維護模組集合（例如 CPAN）的人員、撰寫安裝工具（例如 CPAN.pm 或 CPANPLUS）的人員，或只是想在下載和開始安裝發行版之前了解一些相關資訊的人員。
注意：此規格的最新穩定版本隨時可在 http://module-build.sourceforge.net/META-spec-current.html 找到，而最新開發版本（可能包含不會納入穩定版本的項目）隨時可在 http://module-build.sourceforge.net/META-spec-blead.html 找到。
META.yml 檔案以 YAML 格式撰寫（請參閱 http://www.yaml.org/）。
請參閱以下連結，了解我們為何選擇 YAML 而不是 XML 或 Data::Dumper
這是 META.yml 規格所描述的主要物件。在此文件脈絡中，它通常是指模組、指令碼和/或文件集合，這些集合會一起發行給其他開發人員使用。發行版的範例包括 Class-Container、libwww-perl 或 DBI。
這是指通常包含在單一檔案中的可重複使用程式庫。目前，我們主要討論 perl 模組，但此規格應足夠開放，以便套用於其他語言（例如 python、ruby）。模組的範例包括 Class::Container、LWP::Simple 或 DBD::File。
META.yml 檔案的第一行應為有效的 YAML 文件標頭，例如 "--- #YAML:1.0"。
META.yml 檔案的其餘部分是一個大型 YAML 對應，其鍵在此處描述。
範例
meta-spec:
version: 1.3
url: http://module-build.sourceforge.net/META-spec-v1.3.html（規格 1.1）[必要] {URL} 此欄位指出所使用的 META.yml 規格版本的所在位置。
範例
name: Module-Build(規範 1.0) [必填] {字串} 套件的名稱，通常是取套件中的「主模組」，並將「::」改為「-」。不過，有時會完全不同，例如 libwww-perl 套件（請參閱 http://search.cpan.org/dist/libwww-perl/）。
範例
version: 0.20(規範 1.0) [必填] {版本} META.yml 檔案所指的套件版本。
範例
abstract: Build and install Perl modules.(規範 1.1) [必填] {字串} 套件用途的簡要說明。
範例
author:
- Ken Williams <kwilliams@cpan.org>(規範 1.1) [必填] {字串清單} YAML 序列，指出套件的作者。建議的格式為作者姓名 <電子郵件地址>。
範例
license: perl(規範 1.0) [必填] {字串} 允許使用和重新散布此套件的授權。
必須是下列授權之一
套件根據 Apache 軟體授權版本 1.1 授權（http://opensource.org/licenses/Apache-1.1）。
套件根據 Artistic 授權版本 1 授權，如標準 perl 套件中的 Artistic 檔案所指定（http://opensource.org/licenses/Artistic-Perl-1.0）。
套件根據 BSD 3 條款授權授權（http://opensource.org/licenses/BSD-3-Clause）。
套件根據 GNU 通用公共授權版本 2 散布（http://opensource.org/licenses/GPL-2.0）。
套件根據 GNU 寬通用公共授權版本 2 散布（http://opensource.org/licenses/LGPL-2.1）。
套件根據 MIT 授權授權（http://opensource.org/licenses/MIT）。
此套件的授權條款為 Mozilla Public License。（http://opensource.org/licenses/MPL-1.0 或 http://opensource.org/licenses/MPL-1.1）
此套件的授權條款為其他經 Open Source Initiative 核准的授權條款，詳見 http://www.opensource.org/licenses/。
此套件可以依據 perl 本身的條款進行複製和再發行（這是 CPAN 模組最常見的授權選項）。這是一種雙重授權，使用者可以在 GPL 第 1 版或 Artistic 第 1 版授權之間進行選擇。
未經作者和/或著作權持有人的特別許可，不得重新發行此套件。
此套件的授權條款未經 www.opensource.org 核准，但允許不受限制地進行發行。
範例
distribution_type: module(規範 1.0) [選用] {字串} 此套件中包含哪種類型的內容。CPAN 上的大部分內容都是 module（也可能是多個模組的集合），但有些內容是 script。
很遺憾，這個欄位基本上沒有意義，因為許多套件都是多種類型的混合體，或者是一些新事物，或者根據使用者的不同而有主觀上的不同重點。Module::Build 和 MakeMaker 等工具可能會停止產生這個欄位。
範例
requires:
Data::Dumper: 0
File::Find: 1.03(規範 1.0) [選用] {map} YAML 對應，指出此套件正確運作所需的 Perl 模組。金鑰是模組名稱，而值是 "VERSION SPECIFICATIONS" 中所述的版本規格。
範例
recommends:
Data::Dumper: 0
File::Find: 1.03(規範 1.0) [選用] {map} YAML 對應，指出此套件建議用於增強運作的 Perl 模組。金鑰是模組名稱，而值是 "VERSION SPECIFICATIONS" 中所述的版本規格。
替代方案：建議向使用者說明哪些功能依賴於哪些模組，以便他們可以明智地決定要安裝哪些建議模組。
範例
optional_features:
- foo:
description: Provides the ability to blah.
requires:
Data::Dumper: 0
File::Find: 1.03
- bar:
description: This feature is not available on this platform.
excludes_os: MSWin32(規格 1.1) [選用] {map} YAML 序列，包含選用功能的名稱，當其需求條件符合時，這些功能就會提供。對於每個功能，都會提供說明，以及任何 "requires"、"build_requires"、"conflicts"、requires_packages、requires_os 和 excludes_os，這些在這個子內容中的意義與本文件中其他地方所述相同。
範例
build_requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {map} YAML 對應，指出建置和/或測試此套件所需的 Perl 模組。金鑰是模組名稱，而值是 "版本規格" 中所述的版本規格。安裝模組後，就不再需要這些相依性。
範例
conflicts:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {map} YAML 對應，指出安裝此套件時無法安裝的 Perl 模組。這是一個相當罕見的情況。conflicts 的金鑰是模組名稱，而值是 "版本規格" 中所述的版本規格。
範例
dynamic_config: 0(規格 1.0) [選用] {boolean} 布林旗標，指出建置此套件時是否必須執行 Build.PL 或 Makefile.PL（或類似檔案），或者是否可以只透過查閱其元資料檔案來建置、測試和安裝。設定此值為 true 的主要原因是，您的模組會在建置/安裝程序中執行一些動態設定（發問問題、偵測環境等）。
目前，Module::Build 實際上並未對此旗標做任何事 - 可能會由 CPAN 等較高層級的工具對其做一些有用的事。它有可能帶來許多安全性、封裝和便利性的改善。
如果省略此欄位，它會預設為 1 (true)。
(已棄用) (規格 1.0) [選用] {map} 此欄位已重新命名為 "no_index"。請見下方。
範例
provides:
Foo::Bar:
file: lib/Foo/Bar.pm
version: 0.27_02
Foo::Bar::Blah:
file: lib/Foo/Bar/Blah.pm
Foo::Bar::Baz:
file: lib/Foo/Bar/Baz.pm
version: 0.3(規格 1.1) [選用] {map} YAML 對應，說明此套件提供的套件。此資訊可以（在某些情況下會）由 PAUSE、CPAN 和 search.cpan.org 等套件和自動化機制使用，以建置索引，說明可以在哪些套件中找到各種套件。
當使用像 Module::Build 這樣的工具，它可以自動為您的發行版產生 provides 映射時，請務必檢查它所產生的內容，以確保它有意義 - 如果存在 provides 欄位，索引器通常會信任它，而不是掃描發行檔案本身以找出套件和版本。這是件好事，因為這表示您可以使用 provides 欄位精確地告訴索引器您希望關於您的發行版編制索引的內容，而不是依賴它們基本上猜測您希望編制索引的內容。
範例
no_index:
file:
- My/Module.pm
directory:
- My/Private
package:
- My::Module::Stuff
namespace:
- My::Module::Stuff(規範 1.1) [選用] {map} 描述任何檔案、目錄、套件和名稱空間的 YAML 映射，這些檔案、目錄、套件和名稱空間是私有的（即實作人工製品），不供搜尋和編制索引工具使用。當沒有 provides 欄位時，這很有用。
例如，http://search.cpan.org/ 在搜尋 POD 時會排除在 no_index 中列出的項目，表示這些目錄中的檔案不會轉換成 HTML 並公開 - 如果您有範例或測試 POD，而您不希望搜尋引擎瀏覽它們，這會很有用。
(規範 1.1) [選用] 排除任何列出的檔案。
(規範 1.1) [選用] 排除列出的目錄(含)以下的所有內容。
[註：規範的先前版本使用 dir 而不是 directory，但我認為 MakeMaker 和各種使用者開始使用 directory，所以出於尊重，我們改用它。]
(規範 1.1) [選用] 排除列出的套件。
(規範 1.1) [選用] 排除列出的名稱空間(含)以下的所有內容，但不排除列出的名稱空間本身。
範例
keywords:
- make
- build
- install(規範 1.1) [選用] {list} 描述此發行版的關鍵字/詞組序列。
範例
resources:
license: http://dev.perl.org/licenses/
homepage: http://sourceforge.net/projects/module-build
bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
repository: http://sourceforge.net/cvs/?group_id=45731
MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general(規範 1.1) [選用] {map} 與此發行版相關的任何 URL 資源的映射。所有小寫鍵，例如 homepage、license 和 bugtracker，都由本規範保留，因為它們在此規範中定義了「官方」含義。如果您想新增您自己的「特殊」項目（例如上面的「MailingList」項目），請使用至少一個大寫字母。
目前的官方鍵組是
範例
generated_by: Module::Build version 0.20（規範 1.0）[必填] {字串} 指出用於建立此 META.yml 檔案的工具。最好同時包含工具名稱及其版本，但此欄位基本上是不透明的，至少目前是如此。如果 META.yml 是手動建立的，建議在此處指定作者。
[註：我用於收集 META.yml 使用率統計資料的 meta_stats.pl 腳本偏好以上所列的格式，也就是說，它會以 /\s+version\s+/ 分割，將第一個欄位視為產生檔案的工具名稱，將第二個欄位視為該工具的版本。RWS]
有些欄位需要版本規範（例如 "requires"、"recommends"、"build_requires" 等），以指出可能作為先決條件的某些其他模組的特定版本。此部分詳細說明目前支援的版本規範格式。
版本規範最簡單的格式就是版本號碼本身，例如 2.4。這表示至少必須有 2.4 版本。若要指出先決條件的任何版本都可以，即使先決條件根本沒有定義版本，請使用版本 0。
您也可以使用運算子 <（小於）、<=（小於或等於）、>（大於）、>=（大於或等於）、==（等於）和 !=（不等於）。例如，規範 < 2.0 表示先決條件的任何版本小於 2.0 都合適。
在較複雜的情況中，版本規範可以使用逗號進行 AND 運算。規範 >= 1.2, != 1.5, < 2.0 指出版本必須至少為 1.2、小於 2.0 且不等於 1.5。
建立此文件的 1.0 版。
新增 "dynamic_config" 欄位，此欄位在初始版本中遺漏。
新增更多 YAML 基本原理文章。
修正現有連結至 YAML 討論串，指向新的 http://nntp.x.perl.org/group/ 網站。
新增且棄用 "private" 欄位。
新增 "abstract"、configure、requires_packages、requires_os、excludes_os 和 "no_index" 欄位。
版本升級。
新增 generation、authored_by 欄位。
新增 "recommends" 欄位的備用建議。
新增 requires_build_tools 欄位的建議。
新增連結至 CPAN 上此規格的最新版本。
新增 "VERSION SPECIFICATIONS" 區段。
將名稱從 Module::Build::META-spec 變更為 CPAN::META::Specification。
新增 auto_regenerate 欄位的建議。
新增 index 欄位，作為 "no_index" 的補充
新增 "keywords" 欄位，作為協助搜尋發行版的工具。
新增 "TERMINOLOGY" 區段，說明可能含糊不清的特定術語。
移除許多從未實際支援過的項目（generation、requires_build_tools、requires_packages、configure、requires_os、excludes_os、auto_regenerate），這些項目更像是集思廣益的記錄。
將 authored_by 變更為 "author"，因為這一直是實際 META.yml 檔案中實際稱呼它的方式。
將 "==" 算子新增至支援的版本檢查算子清單中。
指出 "distribution_type" 欄位基本上沒有意義，實際上不應該使用。
進一步說明 "dynamic_config"。
移除名稱 CPAN::META::Specification，因為這暗示了一個實際上不存在的模組。