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 <[email protected]>
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: https://dev.perl5.cn/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 <[email protected]>(规范 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 公共许可证下获得许可。（http://opensource.org/licenses/MPL-1.0 或 http://opensource.org/licenses/MPL-1.1）
该发行版在 http://www.opensource.org/licenses/ 上列出的其他一些开放源代码计划批准的许可下获得许可。
该发行版可以按照与 perl 自身相同的条款进行复制和重新分发（这是 CPAN 上模块最常见的许可选项）。这是一个双重许可，用户可以在 GPL 版本 1 或 Artistic 版本 1 许可之间进行选择。
未经作者和/或版权持有者的特别许可，不得重新分发该发行版。
该发行版在未经 www.opensource.org 批准但允许无限制分发的许可下获得许可。
示例
distribution_type: module（规范 1.0）[可选] {string} 此发行版中包含哪种内容。CPAN 上的大多数内容都是模块（也可以表示模块集合），但有些内容是脚本。
不幸的是，此字段基本上没有意义，因为许多发行版都是多种内容的混合体，或一些新内容，或者根据使用者的不同而主观上关注点不同。Module::Build 和 MakeMaker 等工具可能会停止生成此字段。
示例
requires:
Data::Dumper: 0
File::Find: 1.03（规范 1.0）[可选] {map} 一个 YAML 映射，指示此发行版正常运行所需的 Perl 模块。键是模块名称，值是 “版本规范” 中描述的版本规范。
示例
recommends:
Data::Dumper: 0
File::Find: 1.03（规范 1.0）[可选] {map} 一个 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）[可选] {map} 一个 YAML 序列，其中包含可选功能的名称，当满足其要求时，这些功能将可用。对于每个功能，都提供了说明以及任何 “requires”、“build_requires”、“conflicts”、requires_packages、requires_os 和 excludes_os，这些内容在此子上下文中具有与本文档中其他地方描述的相同含义。
示例
build_requires:
Data::Dumper: 0
File::Find: 1.03(规范 1.0) [可选] {map} 指示构建和/或测试此发行版所需的 Perl 模块的 YAML 映射。键是模块名称，值是 "VERSION SPECIFICATIONS" 中描述的版本规范。安装模块后不需要这些依赖项。
示例
conflicts:
Data::Dumper: 0
File::Find: 1.03(规范 1.0) [可选] {map} 指示在此发行版安装期间无法安装的 Perl 模块的 YAML 映射。这是一个非常罕见的情况。conflicts 的键是模块名称，值是 "VERSION SPECIFICATIONS" 中描述的版本规范。
示例
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: https://dev.perl5.cn/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）[必需] {string} 指示用于创建此 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 基本原理文章。
修复了指向新 http://nntp.x.perl.org/group/ 站点的现有 YAML 讨论线程链接。
添加并弃用了 "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，因为它暗示了一个实际上不存在的模块。