CPAN::Meta::History::Meta_1_2 - META.yml 的 1.2 版元資料規格
這是 META.yml 檔案 1.2 版規格的歷史副本，版權所有者為 Ken Williams，授權條款與 Perl 相同。
與原始版本的差異
修正拼寫錯誤
包含 Module::Build 0.2611 的有效授權清單，而非連結至模組，並針對文字和連結進行小幅更新，以反映發布時的版本。
修正一些失效連結，指向有效資源。
--- #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.2
url: http://module-build.sourceforge.net/META-spec-v1.2.html
generated_by: Module::Build version 0.20本文件說明 META.yml 規格的 1.2 版。
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 規格描述的主要物件。在此文件脈絡中，它通常是指供其他開發人員使用的模組、指令碼和/或文件集合。
這是指通常包含在單一檔案中的可重複使用程式庫。目前，我們主要討論 perl 模組，但此規格應足夠開放，也可套用於其他語言（例如 python、ruby）。
有些欄位需要版本規格（例如 "requires"、"recommends"、"build_requires" 等）。本節詳細說明目前支援的版本規格。
如果列出單一版本，則該版本會被視為支援的最低版本。
如果將 0 指定為版本號碼，則支援任何版本。
此外，對於更複雜的要求，此規格支援版本清單，每個版本都可以選擇在前面加上關係運算子。
支援的運算子包括 <（小於）、<=（小於或等於）、>（大於）、>=（大於或等於）、==（等於）和 !=（不等於）。
如果提供清單，則會從左到右評估清單，以便清單中與先前規格衝突的任何規格都會被後面的規格覆寫。
範例
>= 1.2, != 1.5, < 2.0從 1.2 版開始的任何版本，但版本 1.5 除外，且也早於 2.0 版。
META.yml 檔案的第一行應為有效的 YAML 文件標頭，例如 "--- #YAML:1.0"。
META.yml 檔案的其餘部分是一個大型 YAML 對應，其鍵在此處描述。
範例
meta-spec:
version: 1.2
url: http://module-build.sourceforge.net/META-spec-v1.2.html(規範 1.1) [必填] {URL} 此欄位指出所使用的 META.yml 規範版本的位置。
範例
name: Module-Build(規範 1.0) [必填] {字串} 套件的名稱，通常是取套件中的「主要模組」，並將「::」改為「-」。不過，有時會完全不同，例如 libwww-perl 套件（請參閱 http://search.cpan.org/author/GAAS/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) [必填] {字串} 允許使用和重新散佈此套件的授權。
必須為下列授權之一
套件可以在與 perl 本身相同的條款下複製和重新散佈（這是 CPAN 上模組最常見的授權選項）。這是一種雙重授權，使用者可以在 GPL 版本 1 或 Artistic 版本 1 授權之間選擇。
套件在 GNU 通用公共授權版本 2 的條款下散佈 (http://opensource.org/licenses/GPL-2.0）。
套件在 GNU 寬通用公共授權版本 2 的條款下散佈 (http://opensource.org/licenses/LGPL-2.1）。
套件在 Artistic 授權版本 1 下授權，正如標準 perl 散佈中的 Artistic 檔案所指定 (http://opensource.org/licenses/Artistic-Perl-1.0）。
套件在 BSD 3 條款授權下授權 (http://opensource.org/licenses/BSD-3-Clause）。
套件在 http://www.opensource.org/licenses/ 中列出的其他開放原始碼倡議核准授權下授權。
此發行版本已取得授權，但此授權未經 www.opensource.org 核准，但允許無限制地發行。
未經作者和/或版權持有人的特別許可，不得重新發行此發行版本。
範例
distribution_type: module(規格 1.0) [選用] {字串} 此發行版本中包含哪種類型的內容。CPAN 中的大部分內容為 模組（也可能表示模組集合），但有些內容為 指令碼。
很遺憾，此欄位基本上沒有意義，因為許多發行版本都是多種內容的混合體，或是一些新內容，或視使用者的不同而有不同的重點。Module::Build 和 MakeMaker 等工具可能會停止產生此欄位。
範例
requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出此發行版本正常運作所需的 Perl 模組。金鑰為模組名稱，而值為 Module::Build 中「需要」參數所述的版本規格。
範例
recommends:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出此發行版本建議使用的 Perl 模組，以增強運作。
替代方案：建議向使用者顯示哪些功能取決於哪些模組，以便他們可以明智地決定要安裝哪些建議的模組。
範例
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) [選用] {對應} 一個 YAML 序列，其中包含可選功能的名稱，當其需求得到滿足時，這些功能就會提供。對於每個功能，都會提供說明，以及任何 「需要」、「建置需要」、「衝突」、requires_packages、requires_os 和 excludes_os，這些功能在此子內容中的意義與本文檔中其他地方所述相同。
範例
build_requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出建置和/或測試此發行版本所需的 Perl 模組。模組安裝後，不需要這些依賴項。
範例
conflicts:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出在此發行版本已安裝時無法安裝的 Perl 模組。這是一個非常罕見的情況。
範例
dynamic_config: 0(規格 1.0) [選用] {布林值} 一個布林值旗標，指出建置此發行版本時是否必須執行 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）用來建構索引，說明可在哪些套件中找到各種套件。
在使用可自動為您的套件產生 provides 對應的工具（例如 Module::Build）時，請務必檢查它所產生的內容是否合理 - 如果存在 provides 欄位，索引器通常會信任它，而不是掃描套件檔案本身來找出套件和版本。這是一件好事，因為這表示您可以使用 provides 欄位明確告訴索引器您希望對您的套件建立索引的內容，而不是依賴它們基本上猜測您希望建立索引的內容。
範例
no_index:
file:
- My/Module.pm
dir:
- My/Private
package:
- My::Module::Stuff
namespace:
- My::Module::Stuff（規格 1.1）[選用] {map} YAML 對應，描述任何檔案、目錄、套件和名稱空間，它們是私有的（即實作人工製品），不供搜尋和索引工具使用。當沒有 provides 欄位時，這很有用。
（注意：我實際上不確定誰會查看此欄位，或他們確切對它做了什麼。此規格在某些方面可能與實際使用情況不同。）
（規格 1.1）[選用] 排除任何列出的檔案。
（規格 1.1）[選用] 排除列出的目錄以下的任何內容。
（規格 1.1）[選用] 排除列出的套件。
(規範 1.1) [選用] 排除列出的命名空間以下的任何項目，但不排除列出的命名空間本身。
範例
keywords:
- make
- build
- install(規範 1.1) [選用] {清單} 一系列描述此發行版的關鍵字/片語。
範例
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
MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general(規範 1.1) [選用] {對應} 與此發行版相關的任何 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]
建立本文件的 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 上此規格的最新版本。
新增 "版本規格" 章節。
將名稱從 Module::Build::META-spec 變更為 CPAN::META::Specification。
為 auto_regenerate 欄位新增建議。
新增 index 欄位作為 "no_index" 的補充
新增 "關鍵字" 欄位作為協助搜尋 distribution 的方法。
新增 "術語" 章節，說明可能含糊不清的特定術語。
移除從未實際支援過的一堆項目（generation、requires_build_tools、requires_packages、configure、requires_os、excludes_os、auto_regenerate），這些項目更像是集思廣益的紀錄。
將 authored_by 變更為 "作者"，因為這始終是實際 META.yml 檔案中實際稱呼的方式。
將 "==" 算子新增至支援的版本檢查算子清單中。
註明 "distribution_type" 欄位基本上沒有意義，不應實際使用。
進一步釐清 "dynamic_config"。
移除名稱 CPAN::META::Specification，因為這表示一個實際上不存在的模組。