28、Perl测试与CPAN贡献指南

最新推荐文章于 2025-12-04 13:04:31 发布

元编程奶

最新推荐文章于 2025-12-04 13:04:31 发布

阅读量1

点赞数

CC 4.0 BY-SA版权

分类专栏：深入Perl：从模块到对象文章标签： Perl测试 CPAN贡献 PAUSE账户

本文链接：https://blog.youkuaiyun.com/b9c0d/article/details/155569841

深入Perl：从模块到对象专栏收录该内容

33 篇文章 ¥499.90

订阅专栏¥69.90

会员秒杀 ¥9.9 重磅福利

超级会员免费看

Perl测试与CPAN贡献指南

1. Perl测试相关内容

在Perl编程中，测试是确保代码质量的重要环节。我们可以从模块中设置测试计划，但测试脚本很可能会使用其他模块，而只有一个模块能设置计划，所以通常让 Test::More 来处理。

例如，当Gilligan没有他所需的所有物品时，测试会失败，并打印出 not ok 以及诊断信息：

not ok 1
1..1
# Gilligan needs preserver sunscreen jacket.
#     Failed test (/Users/Ginger/Desktop/package_test.pl at line 49)
# Looks like you failed 1 test of 1.

现在我们创建了 Test::Minnow::RequiredItems 模块，那如何测试这个测试模块呢？可以使用 Test::Builder::Tester 模块，不过这需要你自己去研究。

下面是一些相关的练习：
1. [30分钟] 使用 Test::File 模块检查Unix系统上 /etc/hosts 文件和Windows系统上 C:\windows\system32\drivers\etc\hosts 文件的存在性和可读性。如果没有这些文件，可以选择你有的文件。通过检查 $^O （大写O）变量的值，跳过非当前平台的测试。你可以将这个测试文件添加到 My::List::Util 的发行版中，或者作为独立程序使用。
2. [30分钟] 编写自己的测试模块 Test::My::List::Util ，该模块有一个单一的测试函数 sum_ok ，它接受两个参数：实际总和和预期总和。如果两者不匹配，打印诊断信息。示例代码如下：

my $sum = sum( 2, 2 );
sum_ok( $sum, 4, 'The sums match' );

除了本章的示例，你还可以查看 Test::File （或大多数其他 Test::* 模块）的源代码来获取模块编写的灵感。

2. 向CPAN贡献模块

CPAN（Comprehensive Perl Archive Network）是一个几乎有20年历史、拥有超过100,000个不同模块的平台，我们可以通过它将自己创建的模块和发行版分享给整个Perl社区。

2.1 准备工作

要向CPAN贡献内容，需要满足两个条件：
- 有要贡献的内容，理想情况下已经是模块的形式。
- 拥有Perl Authors Upload Server（PAUSE）账户。

PAUSE账户是向CPAN贡献内容的通行证。获取PAUSE账户很简单，只需填写一个包含基本信息（如姓名、电子邮件地址和首选PAUSE账户名）的网络表单。目前，PAUSE名称必须在4到9个字符之间（一些旧的PAUSE名称只有3个字符长）。所有账户都需要人工审核，主要是为了防止机器人和重复账户，审核可能需要一天左右的时间，通常很少会出现问题。

一旦拥有了PAUSE账户，就需要从全局角度考虑自己的贡献。由于我们的模块将与其他作者的模块一起在程序中使用，所以要确保模块的包名不会与现有模块冲突，也不会让浏览CPAN的人感到困惑。幸运的是，Perl Modules列表（ modules@perl.org ）上有一群志愿者，他们在CPAN和模块方面有丰富的经验，可以帮助你解决大多数问题。

2.2 PAUSE的工作原理

PAUSE是将我们的模块和程序插入CPAN的途径。每个账户都有自己的目录，例如Randal的目录是 authors/id/M/ME/MERLYN 。当上传发行版时，它会进入上传者的目录。

PAUSE会对每个发行版进行索引，并生成从命名空间到发行版的映射，即 modules/02packages.details.txt.gz 文件，该文件包含命名空间、版本和发行版路径的信息。例如：
| 命名空间 | 版本 | 发行版路径 |
| ---- | ---- | ---- |
| File::Finder | 0.53 | M/ME/MERLYN/File−Finder−0.53.tar.gz |
| File::Finder::Steps | 0.53 | M/ME/MERLYN/File−Finder−0.53.tar.gz |
| File::Findgrep | 0.02 | S/SB/SBURKE/File−Findgrep−0.02.tar.gz |
| File::FindLib | 0.001001 | T/TY/TYEMQ/File−FindLib−0.001001.tar.gz |
| File::Flock | 2008.01 | M/MU/MUIR/modules/File−Flock−2008.01.tar.gz |

CPAN客户端使用这些数据来查找安装模块所需的发行版。当运行客户端命令 % cpan File::Finder 时，程序会在 modules/02packages.details.txt.gz 中查找 File::Finder ，获取最新版本号并与已安装的版本进行比较。如果索引中的版本号更大，客户端会获取相应的发行版文件。

下面是PAUSE工作流程的mermaid流程图：

graph TD;
    A[上传发行版到PAUSE] --> B[进入作者目录];
    B --> C[PAUSE索引发行版];
    C --> D{命名空间是否首次出现};
    D -- 是 --> E[上传者获得该命名空间的优先权限，索引命名空间和版本];
    D -- 否 --> F{上传者是否有维护权限};
    F -- 是 --> G{新版本号是否更大};
    G -- 是 --> H[索引命名空间并更新版本];
    G -- 否 --> I[不索引命名空间，发送失败报告];
    F -- 否 --> J[不索引命名空间，发行版仍进入上传者目录];
    E --> K[更新02packages.details.txt.gz];
    H --> K;
    I --> L[发行版在上传者目录，但命名空间不在元数据文件中];
    J --> L;

2.3 模块维护者

模块维护者有以下几种类型：
- 第一上传维护者 ：第一个上传命名空间的人。模块列表维护者还需要完成可选的命名空间注册步骤（https://pause.perl.org/pause/authenquery?ACTION=apply_mod）。
- 主要维护者 ：负责命名空间权限的人。默认情况下是第一上传者，但主要维护权也可以传递给其他人。主要维护者可以为其他人分配共同维护权限，但主要维护者只有一个。
- 共同维护者 ：有上传和索引命名空间的权限，但不能为其他人分配共同维护权限。

有时候所有维护者可能会消失，当没有人愿意移交模块时，PAUSE管理员可以帮助将命名空间的控制权转移给新的开发者。具体的接管流程可以在http://pause.perl.org/pause/query?ACTION=pause_04about#takeover和CPAN FAQ（http://www.cpan.org/misc/cpan-faq.html）中查看。

在开始编写模块之前，我们应该进行一些研究，以节省时间。例如，检查是否已经有能满足需求的模块，是否在重复造轮子，或者是否可以将自己的工作作为补丁贡献给其他模块。同时，要为模块选择一个合适的名称，这个名称要在整个CPAN生态中有意义，并且一旦发布就很难更改。可以向 module-authors@perl.org 和 modules@perl.org 邮件列表上的人寻求帮助，也可以参考PAUSE管理员的命名指南（https://pause.perl.org/pause/authenquery?ACTION=pause_namingmodules）。

3. 准备发行版

确定模块名称并测试后，要确保模块准备好发行。以下是具体步骤：
1. 创建或更新README文件 ：该文件会在CPAN存档中自动提取为单独的文件，让用户在获取或解压其余内容之前查看或下载发行版的关键信息。
2. 检查构建文件 ：制作并测试 Makefile.PL 或 Build.PL 。没有工作构建文件或根本没有构建文件的模块仍然可以进入CPAN，但通常会收到下载者的抱怨，常见问题是构建文件中缺少必要的依赖项。
3. 更新MANIFEST文件 ：确保 MANIFEST 文件是最新的。发行版存档只包含该文件中列出的文件。可以使用 ./Build manifest （或 make manifest ）命令更新 MANIFEST 文件，使其与发行版目录中的内容一致。如果 ./Build manifest 添加了过多文件，可以创建 MANIFEST.SKIP 文件，其中包含一组Perl正则表达式，用于告诉 ./Build manifest 忽略哪些文件。示例 MANIFEST.SKIP 文件如下：

# Avoid configuration metadata file
^MYMETA\.
# Avoid Module::Build generated and utility files.
\bBuild$
\bBuild.bat$
\b_build
\bBuild.COM$
\bBUILD.COM$
\bbuild.com$
^MANIFEST\.SKIP
# Avoid archives of this distribution
\bAnimal−[\d\.\_]+

如果每次操作都要向 MANIFEST.SKIP 文件添加条目会很麻烦，幸运的是，可以在文件中包含 #!include_default 这一行，它会将 ExtUtils/MANIFEST.SKIP 中的默认模式添加到现有的 MANIFEST.SKIP 文件中。可以使用 perldoc -m ExtUtils/MANIFEST.SKIP 查看默认模式列表。
4. 增加版本字符串 ：使用有意义的发行版版本字符串，并且该字符串在数值上要大于PAUSE之前索引的版本。例如，版本1.9大于版本1.10。在 Build.PL 文件中，可以通过 VERSION 或 VERSION_FROM 指定版本。如果发行版中只有一个模块文件（如 .pm 文件），通常最好使用 dist_version_from （或 Makefile.PL 中的 VERSION_FROM ）从该文件中获取版本号。如果有多个 .pm 文件，可以指定其中一个作为版本号的来源。示例代码如下：

my $builder = Module::Build->new(
  module_name         => 'Animal',
  dist_version_from   => 'lib/Animal.pm',
  ...
);

也可以直接在 Build.PL 中指定版本：

my $builder = Module::Build->new(
  module_name         => 'Animal',
  dist_version        => '1.023',
  ...
);

测试发行版 ：到目前为止，我们使用 % ./Build test 命令在当前工作目录中测试工作，该目录包含我们添加的所有文件。但在打包发行版时，只包含 MANIFEST 文件中的文件。如果忘记更新该文件或在 MANIFEST.SKIP 中使用了过于严格的模式，可能会导致测试所需的文件未包含在发行版中。

Perl测试与CPAN贡献指南

4. 详细操作步骤总结

为了更清晰地展示整个向CPAN贡献模块的流程，下面将各个步骤进行详细总结：

4.1 获取PAUSE账户

访问http://www.cpan.org/modules/04pause.html ，填写包含姓名、电子邮件地址和首选PAUSE账户名的网络表单。
等待人工审核，通常需要一天左右时间。

4.2 模块开发与测试

编写模块 ：确保模块实现所需功能，并且包名不会与现有模块冲突。
编写测试脚本 ：使用 Test::More 等模块进行测试，可参考以下练习：
- 使用 Test::File 模块检查文件的存在性和可读性，根据 $^O 变量跳过非当前平台的测试。
- 编写自定义测试模块 Test::My::List::Util ，包含 sum_ok 函数进行总和比较。

4.3 准备发行版

步骤	操作	说明
创建或更新README文件	编写或修改README文件	提供发行版关键信息，方便用户查看
检查构建文件	制作并测试 `Makefile.PL` 或 `Build.PL`	确保构建文件能正常工作，包含必要依赖项
更新MANIFEST文件	使用 `./Build manifest` 或 `make manifest` 更新	确保发行版存档包含所需文件，可使用 `MANIFEST.SKIP` 排除不需要的文件
增加版本字符串	在 `Build.PL` 中指定版本	版本号要在数值上大于之前PAUSE索引的版本
测试发行版	使用 `% ./Build test` 测试	确保发行版在只包含 `MANIFEST` 文件中文件的情况下能正常工作

4.4 上传发行版到PAUSE

登录PAUSE，访问https://pause.perl.org/pause/authenquery?ACTION=add_uri 上传发行版。

5. 常见问题及解决方法

在向CPAN贡献模块的过程中，可能会遇到一些常见问题，以下是一些解决方法：

5.1 命名空间冲突问题

如果发现自己选择的模块名称与现有模块冲突，可采取以下措施：
- 向Perl Modules列表（ modules@perl.org ）上的志愿者寻求帮助，他们可以提供建议并帮助解决冲突。
- 参考PAUSE管理员的命名指南（https://pause.perl.org/pause/authenquery?ACTION=pause_namingmodules ），重新选择合适的名称。

5.2 发行版未正确索引问题

如果PAUSE未正确索引发行版的命名空间，可能有以下原因及解决方法：
| 原因 | 解决方法 |
| ---- | ---- |
| 上传者没有维护权限 | 联系命名空间的主要维护者，请求分配维护权限 |
| 新版本号小于之前索引的版本 | 增加版本字符串，确保新版本号在数值上大于之前的版本 |
| 命名空间已存在且上传者无权限 | 与现有维护者沟通，看是否可以合作或转移维护权限 |

5.3 测试文件未包含在发行版中问题

如果在测试发行版时发现测试所需的文件未包含在发行版中，可检查以下内容：
- 确保 MANIFEST 文件已更新，包含所有必要的文件。
- 检查 MANIFEST.SKIP 文件，确保没有排除测试所需的文件。

6. 总结与建议

向CPAN贡献模块是一个有意义的过程，不仅可以分享自己的工作成果，还能为Perl社区做出贡献。在整个过程中，需要注意以下几点：
- 提前规划 ：在开始编写模块之前，进行充分的研究，避免重复造轮子，选择合适的模块名称。
- 严格测试 ：编写全面的测试脚本，确保模块在不同环境下都能正常工作。
- 遵循规范 ：按照PAUSE的要求和命名指南进行操作，确保发行版能顺利上传和索引。
- 积极沟通 ：遇到问题时，及时向Perl社区的志愿者和维护者寻求帮助，共同解决问题。

通过以上步骤和建议，相信大家能够顺利地向CPAN贡献自己的模块，为Perl社区的发展添砖加瓦。

下面是整个贡献流程的mermaid流程图：

graph LR;
    A[获取PAUSE账户] --> B[模块开发与测试];
    B --> C[准备发行版];
    C --> D[上传发行版到PAUSE];
    D --> E{PAUSE索引发行版};
    E -- 成功 --> F[发行版可在CPAN使用];
    E -- 失败 --> G[处理索引问题];
    G --> D;

希望以上内容能帮助大家更好地理解和掌握向CPAN贡献模块的方法和技巧。