CPAN::Meta::History::Meta_1_4 - META.yml 的 1.4 版元資料規格
這是 META.yml 檔案 1.4 版規格的歷史副本，版權所有者為 Ken Williams，並採用與 Perl 相同的條款授權。
與原始版本相比的修改
各種拼寫修正
包含 Module::Build 0.2807 的有效授權清單，而非連結至模組，並針對文字和連結進行小幅更新，以反映發布時的版本。
修正一些失效連結，指向可用的資源。
--- #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
resources:
license: http://dev.perl.org/licenses/
meta-spec:
version: 1.4
url: http://module-build.sourceforge.net/META-spec-v1.3.html
generated_by: Module::Build version 0.20此文件說明 META.yml 規格的 1.4 版。
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.4
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) [必填] {version} META.yml 檔案所指的發行版本。
範例
abstract: Build and install Perl modules.(規範 1.1) [必填] {string} 對發行用途的簡短說明。
範例
author:
- Ken Williams <kwilliams@cpan.org>(規範 1.1) [必填] {字串清單} 指出發行作者的 YAML 序列。建議格式為作者姓名 <電子郵件地址>。
範例
license: perl(規範 1.0) [必填] {string} 此發行可使用和重新發行的授權。
必須是下列授權之一
此發行根據 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 公共授權 (http://opensource.org/licenses/MPL-1.0 或 http://opensource.org/licenses/MPL-1.1) 授權。
此發行根據其他開放原始碼促進會核准的授權，詳見 http://www.opensource.org/licenses/。
此發行可根據與 perl 相同的條款複製和重新發行（這是 CPAN 上模組最常見的授權選項）。這是一種雙重授權，其中使用者可以在 GPL 或 Artistic 授權中選擇其一。
未經作者和/或著作權持有人的特別許可，不得重新發行此發行。
此發行根據未經 www.opensource.org 核准，但允許無限制發行的授權。
範例
distribution_type: module(規格 1.0) [選用] {字串} 此散佈所包含的內容類型。CPAN 上的大多數內容為「模組」（也可能表示模組集合），但有些內容為「指令碼」。
很遺憾，此欄位基本上沒有意義，因為許多散佈都是多種內容的混合體，或某些新內容，或視使用者的不同而有主觀上的不同重點。Module::Build 和 MakeMaker 等工具可能會停止產生此欄位。
範例
requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出此散佈正確運作所需的 Perl 先決條件。金鑰為先決條件的名稱（模組名稱或「perl」），而值則為 「版本規格」 中所述的版本規格。
範例
recommends:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出此散佈建議的 Perl 先決條件，以增強運作。金鑰為先決條件的名稱（模組名稱或「perl」），而值則為 「版本規格」 中所述的版本規格。
替代方案：建議向使用者顯示哪些功能取決於哪些模組，以便他們可以明智地決定要安裝哪些建議的模組。
範例
optional_features:
foo:
description: Provides the ability to blah.
requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.1) [選用] {對應} 一個 YAML 對應，其中包含可選功能的名稱，當其需求得到滿足時，這些功能就會提供。對於每個功能，都會提供說明，以及任何 「需求」、「建置需求」 和 「衝突」，這些需求和衝突在此子內容中的意義與本文檔其他地方所述相同。
範例
build_requires:
Data::Dumper: 0
File::Find: 1.03(規格 1.0) [選用] {對應} 一個 YAML 對應，指出建置和/或測試此散佈所需的 Perl 先決條件。金鑰為先決條件的名稱（模組名稱或「perl」），而值則為 「版本規格」 中所述的版本規格。安裝散佈後，不需要這些相依性。
範例
configure_requires:
Module::Build: 0.2809
Data::Dumper: 0
File::Find: 1.03(規格 1.4) [選用] {對應} 一個 YAML 對應，指出設定此散佈之前所需的 Perl 先決條件。金鑰為先決條件的名稱（模組名稱或「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 (真)。
(已棄用) (規範 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) [選用] {清單} 描述此套件的一系列關鍵字/片語。
範例
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) [選用] {對應} 與此套件相關的任何 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 上此規格的最新版本。
新增 "版本規格" 區段。
將名稱從 Module::Build::META-spec 變更為 CPAN::META::Specification。
針對 auto_regenerate 欄位新增提案。
新增 index 欄位，作為 "no_index" 的補充
新增 "keywords" 欄位，作為協助搜尋發行版的工具。
新增 "術語" 區段，說明可能含糊不清的特定術語。
移除許多從未實際支援過的項目（generation、requires_build_tools、requires_packages、configure、requires_os、excludes_os、auto_regenerate），這些項目更像是集思廣益的記錄。
將 authored_by 改為 "作者"，因為這一直是實際 META.yml 檔案中實際稱呼的方式。
將 "==" 運算子新增至支援的版本檢查運算子清單中。
註明 "distribution_type" 欄位基本上沒有意義，不應該實際使用。
稍微釐清 "dynamic_config"。
移除名稱 CPAN::META::Specification，因為這暗示了一個實際上不存在的模組。