CPAN::Meta::History::Meta_1_1

(原始碼, CPAN)

#名稱

CPAN::Meta::History::Meta_1_1 - META.yml 的 1.1 版元資料規格

#序言

與原始版本的差異

從原始 HTML 轉換為 POD 格式
包含 Module::Build 0.18 的有效授權清單，而非連結到該模組，並針對文字和連結進行小幅更新，以反映發布時的版本。
修正一些失效連結，指向可用的資源。

#說明

本文件說明 META.yml 規格的 1.1 版。

META.yml 檔案說明已貢獻的 Perl 套件的重要屬性，例如在 CPAN 上找到的套件。它通常由 Module::Build 和 ExtUtils::MakeMaker 等工具建立。

META.yml 檔案中的欄位旨在協助維護模組集合（例如 CPAN）的人員、撰寫安裝工具（例如 CPAN 或 CPANPLUS）的人員，或只是想在下載並開始安裝之前了解配發資訊的人員。

#格式

META.yml 檔案以 YAML 格式撰寫。我們選擇 YAML 而非 XML 或 Data::Dumper 的原因已在 MakeMaker 郵件清單的此執行緒中討論。

META.yml 檔案的第一行應為有效的 YAML 文件標頭，例如 "--- #YAML:1.0"

#欄位

META.yml 檔案的其餘部分是一個大型 YAML 對應，其金鑰在此處說明。

#名稱

範例：Module-Build

配發的名稱。通常透過採用配發中的「主要模組」並將「::」變更為「-」來建立。然而，有時會完全不同，例如 libwww-perl 配發。

#版本

範例：0.16

META.yml 檔案所指的配發版本。這是一個強制性欄位。

版本基本上是一個任意字串，但必須僅包含 ASCII 字元，且強烈建議採用整數-點-數字-數字格式，即 25.57，後方可選擇加上底線-數字-數字，即 25.57_04。

處理模組配發的標準工具（PAUSE、CPAN 等）會透過連接「名稱」與「版本」屬性（以破折號 (-) 字元）來為每個配發建立識別碼。準備處理沒有版本號碼的配發的工具通常也會省略破折號。

#授權

範例：perl

授權的描述性術語 ... 不具權威性，但必須與 READMEs、文件等中的授權聲明一致。

此配發可使用和重新配發的授權。

必須是下列授權之一

#perl: 散布可以根據與 perl 本身相同的條款進行複製和重新散布（這是 CPAN 上模組最常見的授權選項）。這是一個雙重授權，使用者可以在 GPL 版本 1 或 Artistic 版本 1 授權之間選擇。
#gpl: 散布根據 GNU 通用公共授權版本 2 條款進行散布 (http://opensource.org/licenses/GPL-2.0).
#lgpl: 散布根據 GNU 較寬鬆通用公共授權版本 2 條款進行散布 (http://opensource.org/licenses/LGPL-2.1).
#artistic: 散布根據 Artistic 授權版本 1 進行授權，如同標準 perl 散布中的 Artistic 檔案所指定 (http://opensource.org/licenses/Artistic-Perl-1.0).
#bsd: 散布根據 BSD 3 條款授權進行授權 (http://opensource.org/licenses/BSD-3-Clause).
#open_source: 散布根據 http://www.opensource.org/licenses/ 所列出的其他開放原始碼倡議核准的授權進行授權。
#unrestricted: 散布根據未經 www.opensource.org 核准，但允許無限制散布的授權進行授權。
#restrictive: 散布不得在未經作者和/或版權持有者特別許可的情況下重新散布。

#license_uri

這應包含可找到授權確切條款的 URI。

（將「unrestricted」改為「redistributable」？）

#distribution_type

範例：module

此散布中包含哪種類型的內容。CPAN 上的大多數內容都是 module（也可以表示模組的集合），但有些內容是 script。

此欄位基本上沒有意義，而且工具（例如 Module::Build 或 MakeMaker）未來可能會停止產生它。

#私有

這裡發生了什麼事？

index_ignore：任何索引散佈內容的應用程式（PAUSE、search.cpan.org）都應該忽略項目（套件、檔案、目錄、命名空間階層）。

#需求

範例

Data::Dumper: 0
File::Find: 1.03

一個 YAML 對應，指出此散佈所需的 Perl 模組才能正常運作。金鑰是模組名稱，而值是版本規格，如 Module::Build 的「需求」參數文件中所述。

注意：">= 1.2, != 1.5, < 2.0" 等精緻規格的確切性質可能會變更。將在此處提供預先通知。"1.2" 等簡單規格的格式不會變更。

#建議

範例

Data::Dumper: 0
File::Find: 1.03

一個 YAML 對應，指出此散佈建議使用的 Perl 模組以增強運作。

#建置需求

範例

Data::Dumper: 0
File::Find: 1.03

一個 YAML 對應，指出建置和/或測試此散佈所需的 Perl 模組。這些相依性在模組安裝後不需要。

#衝突

範例

Data::Dumper: 0
File::Find: 1.03

一個 YAML 對應，指出在安裝此散佈時無法安裝的 Perl 模組。這是相當不常見的情況。

- 可能會將測試時間先決條件分開，複雜性包括：測試是否可以有意義地保留以供稍後執行？測試時間先決條件是否除了建置時間之外，還是獨佔的？

- 建立已安裝 *散佈* 的官方位置，其中可以包含測試等。

#動態設定

範例：0

一個布林旗標，指出是否必須執行 Build.PL 或 Makefile.PL（或類似），或是否可以僅透過諮詢其元資料檔案來建置、測試和安裝此模組。如果模組在建置/安裝程序中執行一些動態設定（詢問問題、感測環境等），則將此設定為真值的主要原因。

目前 Module::Build 實際上並未對此旗標執行任何操作 - 這可能取決於 CPAN.pm 等較高層級的工具來對其執行有用的操作。它可能會帶來許多安全性、封裝和便利性改善。

#由下列產生

範例：Module::Build 版本 0.16

指出用於建立此 META.yml 檔案的工具。包含工具名稱和版本是良好的習慣，但此欄位基本上是不透明的，至少目前是如此。

#Ingy 的建議

#short_description: 新增為欄位，包含摘要，最多 80 個字元，建議至少 40 個字元
#description: 摘要的長版本，是否應新增？
#maturity: alpha、beta、gamma、mature、stable
#author_id、owner_id
#categorization、keyword、chapter_id
#進一步資訊的 URL: 在 PAUSE 上預設為 search.cpan.org
#namespaces: 可透過在前面加上點分格式來指定單一元素，例如「com.example.my_application.my_property」。META.yml 的預設命名空間可能是「org.cpan.meta_author」或類似名稱。我想，這項先例來自於 Apple 的 Carbon 命名空間。

#歷史記錄

2003 年 3 月 14 日（圓周率日） - 建立此文件版本 1.0。
2003 年 5 月 8 日 - 新增「dynamic_config」欄位，此欄位遺漏於初始版本中。