CPAN::Meta::Spec

(原始碼, CPAN)

版本 2.150010

名稱
版本
概要
說明
術語
資料類型
- 布林
- 字串
- 清單
- 映射
- 授權字串
- 網址
- 版本
- 版本範圍
結構
- 必要欄位
  - 摘要
  - 作者
  - 動態設定
  - 產生者
  - 授權
  - 元規格
  - 名稱
  - 發布狀態
  - 版本
- 選用欄位
  - 說明
  - 關鍵字
  - 不索引
  - 選用功能
  - 先決條件
  - 提供
  - 資源
- 已棄用欄位
  - 建置需求
  - 組態需求
  - 衝突
  - 發行類型
  - 授權網址
  - 私人
  - 建議
  - 需求
版本號碼
- 版本格式
- 版本範圍
先決條件
- 先決條件規格
  - 階段
  - 關係
- 合併和解析先決條件
序列化
實作注意事項
另請參閱
歷史
作者
版權和授權

#名稱

CPAN::Meta::Spec - CPAN 套件中繼資料規格

#版本

版本 2.150010

#概要

my $distmeta = {
  name => 'Module-Build',
  abstract => 'Build and install Perl modules',
  description =>  "Module::Build is a system for "
    . "building, testing, and installing Perl modules. "
    . "It is meant to ... blah blah blah ...",
  version  => '0.36',
  release_status => 'stable',
  author   => [
    'Ken Williams <kwilliams@cpan.org>',
    'Module-Build List <module-build@perl.org>', # additional contact
  ],
  license  => [ 'perl_5' ],
  prereqs => {
    runtime => {
      requires => {
        'perl'   => '5.006',
        'ExtUtils::Install' => '0',
        'File::Basename' => '0',
        'File::Compare'  => '0',
        'IO::File'   => '0',
      },
      recommends => {
        'Archive::Tar' => '1.00',
        'ExtUtils::Install' => '0.3',
        'ExtUtils::ParseXS' => '2.02',
      },
    },
    build => {
      requires => {
        'Test::More' => '0',
      },
    }
  },
  resources => {
    license => ['http://dev.perl.org/licenses/'],
  },
  optional_features => {
    domination => {
      description => 'Take over the world',
      prereqs     => {
        develop => { requires => { 'Genius::Evil'     => '1.234' } },
        runtime => { requires => { 'Machine::Weather' => '2.0'   } },
      },
    },
  },
  dynamic_config => 1,
  keywords => [ qw/ toolchain cpan dual-life / ],
  'meta-spec' => {
    version => '2',
    url     => 'https://metacpan.org/pod/CPAN::Meta::Spec',
  },
  generated_by => 'Module::Build version 0.36',
};

#說明

本文件說明 CPAN 套件中繼資料規格的版本 2，也稱為「CPAN Meta Spec」。

本規格的修訂版（例如修正錯字和文字說明）可能會以 CPAN::Meta::Spec 2.x 發布。這些修訂版絕不會變更語意，也不會新增或移除已規定的行為。

套件中繼資料說明 Perl 套件的重要屬性。套件建置工具（例如 Module::Build、Module::Install、ExtUtils::MakeMaker 或 Dist::Zilla）應根據本規格建立中繼資料檔案，並將其包含在套件中，供自動化工具索引、檢查、封裝或安裝 Perl 套件時使用。

#術語

#套件: 這是中繼資料說明的主要物件。在本文件中，它通常是指模組、指令碼和/或文件，供其他開發人員一起使用。套件的範例包括 Class-Container、libwww-perl 或 DBI。
#模組: 這是包含在單一檔案中的可重複使用程式庫。模組通常包含一個或多個套件，而且通常以可對應到檔案名稱的主要套件名稱來稱呼。例如，我們可能會稱呼 File::Spec，而不是 File/Spec.pm
#套件: 這是使用 Perl package 陳述式宣告的命名空間。在 Perl 中，套件通常具有版本號碼屬性，由命名空間中的 $VERSION 變數提供。
#使用者: 這指的是讀取元資料檔案、將其反序列化成記憶體中的資料結構，或詮釋元資料元素資料結構的程式碼。
#製作程式: 這指的是建構元資料資料結構、序列化成位元組串和/或寫入磁碟的程式碼。
#必須、應該、可以等: 這些術語的詮釋如 IETF RFC 2119 中所述。

#資料類型

"結構" 區段中的欄位描述資料元素，每個元素都有如本文所述的關聯資料類型。有四種基本類型：布林值、字串、清單和對應。其他類型是基本類型的子類型，定義複合資料結構或定義資料元素值的約束。

#布林值

布林值 用於提供真或假的值。它必須表示為定義的值，可能是 "1" 或 "0"，或字串化為這些值。

#字串

字串是包含非零長度 Unicode 字元序列的資料元素，例如不是參考的一般 Perl 標量。

#清單

清單是零個或多個資料元素的有序集合。清單的元素可以是混合類型。

製作程式必須使用明確指出可能有多個值的資料結構來表示清單元素，例如 Perl 陣列的參考（「陣列參考」）。

預期清單的消費者必須將字串視為長度為 1 的清單。

#對應

對應是零個或多個資料元素（「值」）的無序集合，由關聯的字串元素（「鍵」）索引。對應的值元素可以是混合類型。

#授權字串

授權字串 是值受限的字串子類型。有效值在"授權"欄位的說明中詳細描述。

#URL

URL 是包含統一資源定位器或識別碼的字串子類型。[ 這個類型稱為 URL 而不是 URI，是基於歷史原因。 ]

#版本

版本是包含描述套件或發行版版本號碼值的字串子類型。格式限制在"版本格式" 區段中詳細描述。

#版本範圍

版本範圍類型是字串的子類型。它描述了可能存在或已安裝以滿足先決條件的版本範圍。它在「版本範圍」部分中詳細說明。

#結構

元資料結構是 Map 類型的資料元素。本節說明 Map 中的有效金鑰。

本規範文件中未說明的任何金鑰（無論是頂層或本文件中說明的複合資料結構內）都被視為自訂金鑰，必須以「x」或「X」開頭，後面接底線；亦即它們必須符合模式：qr{\Ax_}i。如果自訂金鑰是指複合資料結構，其中的子金鑰不需要「x_」或「X_」前綴。

元資料的使用者可以忽略部分或全部自訂金鑰。本文件中未說明的所有其他金鑰都是無效的，使用者應忽略這些金鑰。產生者不得產生或輸出無效金鑰。

對於每個金鑰，會提供範例，後接說明。說明從金鑰新增或定義修改的規範版本開始，說明金鑰是必要的還是選用的，以及對應資料元素的資料類型。這些項目分別以括號、方括號和大括號表示。

如果資料類型是 Map 或 Map 子類型，也會說明有效的子金鑰。

有些欄位標記為已棄用。這些欄位顯示為歷史背景，不得在版本 2 或更高版本的任何元資料結構中產生或使用。

#必要的欄位

#摘要

範例

abstract => 'Build and install Perl modules'

(規範 1.2) [必要] {字串}

這是發行目的的簡短說明。

#作者

範例

author => [ 'Ken Williams <kwilliams@cpan.org>' ]

(規範 1.2) [必要] {一個或多個字串的清單}

此清單指出關於發行事項的聯絡人。聯絡字串的首選格式為

contact-name <email-address>

此欄位提供一個一般聯絡清單，獨立於「資源」欄位中提供的其他結構化欄位，例如 bugtracker。收件人可以針對任何目的進行聯絡，包括但不限於發行的（安全性）問題、關於發行的問題或發行中的錯誤。

發行的原始作者通常是此欄位中列出的聯絡人。共同維護者、繼任維護者或專門針對發行事項的郵件清單也可以列在原始作者旁邊或取代原始作者。

#dynamic_config

範例

dynamic_config => 1

(規範 2) [必要] {布林值}

一個布林值旗標，表示是否必須執行 Build.PL 或 Makefile.PL (或類似) 來確定先決條件。

如果套件在組態過程中執行一些動態組態 (提出問題、偵測環境等)，則應將此欄位設定為 true 值。如果要表示元資料中包含的先決條件可視為最終且有效，以進行靜態分析，則應將此欄位設定為 false 值。

注意：當此欄位為 true 時，無法保證組態後先決條件與元資料中所述的任何關係，依賴它們這樣做是一種錯誤。另請參閱執行人員備註中的 "動態組態套件的先決條件"。

此欄位明確不表示是否可以在不使用 Makefile 或 Build 檔案的情況下安全地執行安裝，因為可能需要安裝特殊檔案或自訂安裝目標 (例如，存在於 CPAN 和 Perl 核心中的雙重生命週期模組)。此欄位僅定義元資料中所述的先決條件是否完全相同。

#generated_by

範例

generated_by => 'Module::Build version 0.36'

(規範 1.0) [必要] {字串}

此欄位表示用於建立此元資料的工具。此欄位沒有定義的語意，但傳統上會使用 "Generating::Package 版本 1.23" 形式的字串，或如果檔案是手動產生的，則會使用作者姓名。

#license

範例

license => [ 'perl_5' ]

license => [ 'apache_2_0', 'mozilla_1_0' ]

(規範 2) [必要] {一個或多個授權字串的清單}

套件中部分或全部檔案適用的授權。如果列出多個授權，應參閱套件文件以釐清多個授權的詮釋。

下列授權字串清單為有效

string          description
-------------   -----------------------------------------------
agpl_3          GNU Affero General Public License, Version 3
apache_1_1      Apache Software License, Version 1.1
apache_2_0      Apache License, Version 2.0
artistic_1      Artistic License, (Version 1)
artistic_2      Artistic License, Version 2.0
bsd             BSD License (three-clause)
freebsd         FreeBSD License (two-clause)
gfdl_1_2        GNU Free Documentation License, Version 1.2
gfdl_1_3        GNU Free Documentation License, Version 1.3
gpl_1           GNU General Public License, Version 1
gpl_2           GNU General Public License, Version 2
gpl_3           GNU General Public License, Version 3
lgpl_2_1        GNU Lesser General Public License, Version 2.1
lgpl_3_0        GNU Lesser General Public License, Version 3.0
mit             MIT (aka X11) License
mozilla_1_0     Mozilla Public License, Version 1.0
mozilla_1_1     Mozilla Public License, Version 1.1
openssl         OpenSSL License
perl_5          The Perl 5 License (Artistic 1 & GPL 1 or later)
qpl_1_0         Q Public License, Version 1.0
ssleay          Original SSLeay License
sun             Sun Internet Standards Source License (SISSL)
zlib            zlib License

下列授權字串也為有效，表示上述未說明的其他授權

string          description
-------------   -----------------------------------------------
open_source     Other Open Source Initiative (OSI) approved license
restricted      Requires special permission from copyright holder
unrestricted    Not an OSI approved license, but not restricted
unknown         License not provided in metadata

所有其他字串在授權欄位中無效。

#meta-spec

範例

'meta-spec' => {
  version => '2',
  url     => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
}

(規範 1.2) [必要] {對應}

此欄位表示應使用哪個版本的 CPAN Meta Spec 來詮釋元資料。使用者必須盡快檢查此金鑰，如果使用者不支援 meta-spec 版本，則中止進一步的元資料處理。

下列的鍵值是有效的，但只有 version 是必要的。

#version

此子鍵給予 CPAN Meta Spec 的整數版本，用於產生文件。

#url

這是對應給定版本的元資料規格文件之 URL。這僅供人類使用，不應影響文件的詮釋。

對於版本 2 規格，建議使用下列任一個

https://metacpan.org/pod/CPAN::Meta::Spec
http://search.cpan.org/perldoc?CPAN::Meta::Spec

#name

範例

name => 'Module-Build'

(規範 1.0) [必要] {字串}

這個欄位是發行版的名稱。這通常是透過取發行版中的「主要套件」並將 :: 改為 - 而建立的，但名稱可能與發行版中的套件完全無關。例如，LWP::UserAgent 是以發行版名稱「libwww-perl」的一部分來發行的。

#release_status

範例

release_status => 'stable'

(規格 2) [必要] {字串}

此欄位提供此發行版的發行狀態。如果 version 欄位包含底線字元，則 release_status 不得為「stable」。

release_status 欄位必須具有下列值之一

#stable: 這表示一個普通的「最終」版本，應由 PAUSE 或其他索引器編入索引。
#testing: 這表示一個「測試版」版本，已大致完成，但有較高的錯誤風險，需要額外的測試。在沒有使用者明確要求或其他確認的情況下，不應將此發行版安裝在穩定版本之上。此發行狀態也可使用於發行版的「候選版本」。
#unstable: 這表示一個「開發中」版本，目前處於積極開發中，但已發布以供早期回饋或測試，可能缺少功能或有嚴重的錯誤。在沒有使用者明確要求或其他確認的情況下，不應將此發行版安裝在穩定版本之上。

消費者可以使用此欄位來決定如何為 CPAN 或其他儲存庫建立索引，以取代或補充基於版本號碼或檔案名稱的啟發式方法。

#version

範例

version => '0.36'

(規範 1.0) [必填] {版本}

此欄位提供元資料結構所參照的發行版本。

#選用欄位

#description

範例

description =>  "Module::Build is a system for "
  . "building, testing, and installing Perl modules. "
  . "It is meant to ... blah blah blah ...",

(規範 2) [選用] {字串}

比 abstract 關鍵字提供的發行用途或預期用途更長、更完整的說明。

#keywords

範例

keywords => [ qw/ toolchain cpan dual-life / ]

(規範 1.1) [選用] {零個或多個字串的清單}

描述此發行的關鍵字清單。關鍵字不得包含空白。

#no_index

範例

no_index => {
  file      => [ 'My/Module.pm' ],
  directory => [ 'My/Private' ],
  package   => [ 'My::Module::Secret' ],
  namespace => [ 'My::Module::Sample' ],
}

(規範 1.2) [選用] {對應}

此對應描述發行包裝或實作中任何私有的檔案、目錄、套件和命名空間，且應由索引或搜尋工具忽略。請注意，這是排除清單，且規範未定義要包含什麼 - 如需更多資訊，請參閱實作者備註中的「索引發行，例如 PAUSE」。

有效的子關鍵字如下

#file

檔案的相對路徑清單。路徑必須使用 unix 慣例指定。

#directory

目錄的相對路徑清單。路徑必須使用 unix 慣例指定。

[註：規範的先前版本使用 dir，而非 directory ]

#package

套件名稱清單。

#namespace

套件命名空間清單，其中命名空間以下的任何內容都必須忽略，但不包括命名空間本身。

在 no_index 的上述範例中，My::Module::Sample::Foo 會被忽略，但 My::Module::Sample 不會。

#optional_features

範例

optional_features => {
  sqlite => {
    description => 'Provides SQLite support',
    prereqs => {
      runtime => {
        requires => {
          'DBD::SQLite' => '1.25'
        }
      }
    }
  }
}

(規格 2) [選用] {Map}

此 Map 描述具有遞增先決條件的選用功能。optional_features Map 的每個金鑰都是用於識別功能的字串，每個值都是包含有關功能的其他資訊的 Map。有效的子金鑰包括

#description

這是描述功能的字串。每個選用功能都應提供描述

#prereqs

此項目是必要的，且其結構與 "prereqs" 金鑰的結構相同。它提供功能獲得支援或啟用所必須滿足的套件需求清單。

有一個重要的限制：選用功能的先決條件不得包含 configure 階段先決條件。

使用者不得在未經使用者明確指示的情況下將選用功能包含為先決條件（無論是透過互動式提示、函數參數或組態值等）。

如果使用者使用選用功能來新增其他先決條件，使用者應使用相同的語意將選用功能先決條件合併到 prereqs 金鑰所提供的先決條件中。請參閱"合併和解決先決條件"以取得有關合併先決條件的詳細資訊。

建議廢止：由於目前沒有任何方法讓發行版指定對另一個依賴項的選用功能的依賴性，因此不建議使用 optional_feature。請改為建立一個獨立的可安裝發行版，以確保所需的選用功能可用。例如，如果 Foo::Bar 有 Baz 功能，請發布一個獨立的 Foo-Bar-Baz 發行版，以滿足該功能的需求。

#prereqs

範例

prereqs => {
  runtime => {
    requires => {
      'perl'          => '5.006',
      'File::Spec'    => '0.86',
      'JSON'          => '2.16',
    },
    recommends => {
      'JSON::XS'      => '2.26',
    },
    suggests => {
      'Archive::Tar'  => '0',
    },
  },
  build => {
    requires => {
      'Alien::SDL'    => '1.00',
    },
  },
  test => {
    recommends => {
      'Test::Deep'    => '0.10',
    },
  }
}

(規格 2) [選用] {Map}

這是描述發行版所有先決條件的 Map。金鑰是活動階段，例如 configure、build、test 或 runtime。值是 Map，其中金鑰命名先決條件關係的類型，例如 requires、recommends 或 suggests，而值提供先決條件關係的集合。關係集合必須指定為套件名稱對應版本範圍的 Map。

此欄位的完整定義在"先決條件規格"區段中提供。

#provides

範例

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.2) [選用] {對應}

這描述此發行版提供的所有套件。此資訊由發行版和自動化機制（例如 PAUSE、CPAN、metacpan.org 和 search.cpan.org）使用，以建立索引，說明可以在哪些發行版中找到各種套件。

provides 的金鑰是可以從發行版中找到的套件名稱。如果提供套件名稱金鑰，它必須具有包含下列有效子金鑰的 Map

#file: 此欄位是必要的。它必須包含從發行版目錄根目錄到包含或產生套件的檔案的 Unix 風格相對檔案路徑。它可以指定為 META.yml 或 META.json，以宣告套件進行索引，而不需要 *.pm。
#version: 如果存在，此欄位必須包含套件的版本字串。如果套件沒有$VERSION，則必須省略此欄位。

#資源

範例

resources => {
  license     => [ 'http://dev.perl.org/licenses/' ],
  homepage    => 'http://sourceforge.net/projects/module-build',
  bugtracker  => {
    web    => 'http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN-Meta',
    mailto => 'meta-bugs@example.com',
  },
  repository  => {
    url  => 'git://github.com/dagolden/cpan-meta.git',
    web  => 'http://github.com/dagolden/cpan-meta',
    type => 'git',
  },
  x_twitter   => 'http://twitter.com/cpan_linked/',
}

(規格 2) [選用] {Map}

此欄位說明與此發行版相關的資源。

有效的子金鑰包括

#首頁

此專案在網路上官方首頁。

#授權

與此發行版授權相關的URL清單。與頂層授權欄位一樣，應參閱發行版文件以釐清在此提供多個授權的詮釋。

#錯誤追蹤

此項目說明此發行版的錯誤追蹤系統。它是具有下列有效金鑰的 Map

web    - a URL pointing to a web front-end for the bug tracker
mailto - an email address to which bugs can be sent

#儲存庫

此項目說明此發行版的原始碼控制儲存庫。它是具有下列有效金鑰的 Map

url  - a URL pointing to the repository itself
web  - a URL pointing to a web front-end for the repository
type - a lowercase string indicating the VCS used

由於像http://myrepo.example.com/這樣的 URL 在類型上不明確，因此製作人應在提供url金鑰時提供type。type欄位應為用於處理儲存庫的最常見程式名稱，例如git、svn、cvs、darcs、bzr或hg。

#已棄用欄位

#建置需求

（已在 Spec 2 中棄用） [選用] {字串}

已由prereqs取代

#組態需求

（已在 Spec 2 中棄用） [選用] {字串}

已由prereqs取代

#衝突

（已在 Spec 2 中棄用） [選用] {字串}

已由prereqs取代

#發行版類型

（已在 Spec 2 中棄用） [選用] {字串}

此欄位表示「模組」或「指令碼」，但被認為沒有意義，因為許多發行版都是各種事物的混合體。

#授權 URI

（已在 Spec 1.2 中棄用） [選用] {URL}

已在資源中由授權取代

#私人

（已在 Spec 1.2 中棄用） [選用] {Map}

此欄位已重新命名為 "no_index"。

#建議

（已在 Spec 2 中棄用） [選用] {字串}

已由prereqs取代

#需求

（已在 Spec 2 中棄用） [選用] {字串}

已由prereqs取代

#版本號碼

#版本格式

此區段定義版本類型，由 CPAN Meta Spec 中的幾個欄位使用。

版本號碼必須視為字串，而不是數字。例如，1.200 不得序列化為1.2。版本比較應委派給 Perl version 模組，版本 0.80 或更新版本。

除非另有說明，否則版本號碼必須以兩種格式之一出現

#十進位版本

十進位版本是具有某些限制的常規「十進位數字」。它們必須是非負數，並且必須以數字開頭和結尾。可以包含一個底線，但必須在兩個數字之間。它們不得使用科學記號（「1.23e-2」）。

version => '1.234'       # OK
version => '1.23_04'     # OK

version => '1.23_04_05'  # Illegal
version => '1.'          # Illegal
version => '.1'          # Illegal

#點分整數版本

點分整數（又稱點分十進位）版本由正整數組成，並以句點字元（即「點」、「句點」或「小數點」）分隔。它們的格式等同於 Perl「v 字串」，但形式上有一些額外的限制。它們必須以「正規」形式提供，其中包含開頭的「v」字元和至少三個整數組成部分。為了與十進位版本保持一對一的對應關係，第一個組成部分之後的所有組成部分應該限制在 0 到 999 的範圍內。最後一個組成部分可以用底線字元代替句點分隔。

version => 'v1.2.3'      # OK
version => 'v1.2_3'      # OK
version => 'v1.2.3.4'    # OK
version => 'v1.2.3_4'    # OK
version => 'v2009.10.31' # OK

version => 'v1.2'          # Illegal
version => '1.2.3'         # Illegal
version => 'v1.2_3_4'      # Illegal
version => 'v1.2009.10.31' # Not recommended

#版本範圍

某些欄位（prereq、optional_features）會指出作為先決條件所需的特定其他模組版本。本節詳細說明用於提供此資訊的版本範圍類型。

版本範圍最簡單的格式僅為版本號碼本身，例如 2.4。這表示至少必須存在版本 2.4。若要表示先決條件的任何版本都可以，即使先決條件根本沒有定義版本，請使用版本 0。

或者，版本範圍可以使用運算子 <（小於）、<=（小於或等於）、>（大於）、>=（大於或等於）、==（等於）和 !=（不等於）。例如，規格 < 2.0 表示先決條件的任何版本小於 2.0 都合適。

對於更複雜的情況，版本規格可以使用逗號進行 AND 運算。規格 >= 1.2, != 1.5, < 2.0 表示版本必須至少為 1.2、小於 2.0 且不等於 1.5。

#先決條件

#先決條件規格

頂層元資料中的 prereqs 鍵和 optional_features 中的 prereqs 鍵定義發行版與其他套件之間的關係。先決條件規格結構是階層式資料結構，它將先決條件分為安裝程序中的活動階段和表示應如何解析先決條件的關係。

例如，若要指定 Data::Dumper 在 test 階段為必要，此項目將出現在發行版元資料中

prereqs => {
  test => {
    requires => {
      'Data::Dumper' => '2.00'
    }
  }
}

#階段

常規使用需求必須列在 runtime 階段。其他需求應列在需要它們的最早階段，而使用者必須在執行活動之前累積並滿足跨階段的需求。例如，build 需求也必須在 test 階段可用。

before action       requirements that must be met
----------------    --------------------------------
perl Build.PL       configure
perl Makefile.PL

make                configure, runtime, build
Build

make test           configure, runtime, build, test
Build test

安裝發行版的使用者必須確保也安裝了執行時期需求，並可以安裝來自其他階段的相依性。

after action        requirements that must be met
----------------    --------------------------------
make install        runtime
Build install

#組態: 組態階段發生在嘗試任何動態組態之前。組態階段所需的函式庫必須在執行發行版建置工具之前可用。
#建置: 建置階段是發行版的原始碼編譯（如有必要）並準備好安裝的時機。
#測試: 測試階段是發行版的自動化測試套件執行時機。任何只在測試中需要，而後續使用中不需要的函式庫都應該在此列出。
#執行時間: 執行時間階段不僅指發行版內容安裝的時機，也指持續使用的時機。任何此發行版規律使用中必備的函式庫都應該在此指出。
#開發: 開發階段的前置需求是函式庫，用於處理發行版的原始碼，就像作者所做的那樣。這些工具可能是建置發行 tarball、執行僅供作者的測試，或執行與開發發行版新版本相關的其他任務時所需要的。

#關係

#需要: 這些依賴關係必須安裝才能適當地完成階段。
#建議: 強烈建議使用建議的依賴關係，除了資源受限的環境之外，都應該滿足這些依賴關係。
#建議: 這些依賴關係是選用的，但建議用於增強所述發行版的操作。
#衝突: 這些函式庫在階段運作時無法安裝。這是非常罕見的情況，conflicts 關係應該非常小心地使用，甚至完全不使用。

#合併和解析前置需求

每當元資料消費者合併前置需求，無論是來自不同的階段或來自 optional_features，他們都應該以一種保留前置需求結構預期語意的方式合併。通常，這表示使用逗號串接版本規格，如 "版本範圍" 區段中所述。

解析前置需求時可能發生的另一個微妙錯誤來自於 CPAN 上的模組索引到發行檔案的方式。當模組從發行中刪除時，呼叫該模組的前置需求可能會指出應該安裝較舊的發行，可能會覆寫較新發行中的檔案。

例如，截至 2009 年 10 月 31 日，CPAN 索引檔案包含這些模組-發行對應關係

Class::MOP                   0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
Class::MOP::Class            0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
Class::MOP::Class::Immutable 0.04  S/ST/STEVAN/Class-MOP-0.36.tar.gz

考慮已安裝 "Class::MOP" 0.94 的情況。如果發行指定 "Class::MOP::Class::Immutable" 作為前置需求，可能會導致安裝 Class-MOP-0.36.tar.gz，覆寫 Class-MOP-0.94.tar.gz 中的任何檔案。

元資料消費者應該測試前置需求是否會導致已安裝的模組檔案「降級」到較舊版本，並且可以警告使用者或忽略會導致這種結果的前置需求。

#序列化

配送中繼資料應序列化（作為雜湊）為 JSON 編碼資料，並與配送打包為檔案 META.json。

過去，配送中繼資料結構已與配送打包為 META.yml，這是 YAML Tiny 格式的檔案（請參閱 YAML::Tiny）。從磁碟使用配送中繼資料的工具應能夠載入 META.yml，但如果同時找到兩個檔案，則應優先選擇 META.json。

#實作人員注意事項

#從 Perl 模組中擷取版本號碼

若要從 Perl 模組中取得版本號碼，使用者應使用 ExtUtils::MakeMaker 或 Module::Metadata 提供的 MM->parse_version($file) 方法。例如，對於 $mod 所提供的模組，可以使用下列其中一種方式來擷取版本

# via ExtUtils::MakeMaker
my $file = MM->_installed_file_for_module($mod);
my $version = MM->parse_version($file)

私人 _installed_file_for_module 方法可以替換為其他方法，以在 @INC 中找到模組。

# via Module::Metadata
my $info = Module::Metadata->new_from_module($mod);
my $version = $info->version;

如果只有檔案名稱可用，可以使用下列方法

# via Module::Build
my $info = Module::Metadata->new_from_file($file);
my $version = $info->version;

#比較版本號碼

version 模組提供最可靠的方式來比較版本號碼，無論它們在模組中以何種方式提供或存在。給定包含版本號碼的兩個字串 $v1 和 $v2，應在使用一般比較運算子之前將它們轉換為 version 物件。例如

use version;
if ( version->new($v1) <=> version->new($v2) ) {
  print "Versions are not equal\n";
}

如果只需要比較已安裝的模組是否為足夠高的版本，可以使用 eval 的字串形式和 use 函數來進行直接測試。例如，對於模組 $mod 和版本先決條件 $prereq

if ( eval "use $mod $prereq (); 1" ) {
  print "Module $mod version is OK.\n";
}

但是，如果 $mod 和 $prereq 的值尚未清除，這會造成安全性問題。

#動態組態配送的先決條件

當 dynamic_config 為 true 時，假設配送中繼資料中提供的先決條件與配送的實際先決條件有任何關係都是錯誤的。

然而，在實務上，通常可以預期此類先決條件為下列兩者之一

分發的最低先決條件，動態組態只會新增項目
無論在發佈時間發佈者電腦上組態的組態為何

第二種情況通常會產生與第一種情況相同的結果，儘管只是意外。

因此，使用者可以將此資料用於資訊分析，但將其呈現給使用者作為規範或依賴它，無疑是愚蠢至極。

#索引分發 a la PAUSE

雖然 no_index 告訴您在索引時必須忽略什麼，但此規格對您如何取得要索引的項目初始候選清單沒有任何意見。對於「一般」分發，您可以考慮僅索引 lib/ 的內容，但 CPAN 上有許多令人著迷的奇特之處，還有許多來自於將主 .pm 檔案放在分發檔案根目錄中很正常的那個時期的分發 - 因此 PAUSE 目前會索引所有 .pm 和 .PL 檔案，這些檔案既不是 (a) 特別由 no_index 排除 (b) 在 inc、xt 或 t 目錄中，也不是常見的「錯誤」目錄，例如 perl5。

或者：如果您嘗試類似 PAUSE，請務必略過 inc、xt 和 t，以及標記為 no_index 的任何內容。

另請記住：如果 META 檔案包含 provides 欄位，您不應該從一開始就索引任何內容 - 只需使用它即可。

#另請參閱

#歷程

Ken Williams 於 2003 年撰寫了原始的 CPAN Meta 規格（也稱為「META.yml 規格」），並在社群中多位成員的意見回饋下，歷經多次修訂來維護它。2005 年，Randy Sims 將它從 HTML 重新編寫為 POD，以供 1.2 版發行。Ken 持續維護此規格至 1.4 版。

2009 年底，David Golden 組織了 2 版提案審查流程。David 和 Ricardo Signes 在提案流程中，根據 1.4 版規格和修補程式，於 2010 年 4 月起草了 2 版最終規格。

#作者

David Golden <dagolden@cpan.org>
Ricardo Signes <rjbs@cpan.org>
Adam Kennedy <adamk@cpan.org>

#著作權和授權

此軟體的著作權為 2010 年 David Golden、Ricardo Signes、Adam Kennedy 和貢獻者所有。

這是免費軟體；您可以在與 Perl 5 程式語言系統相同的條款下重新散布或修改它。