perlnewmod - 为发布准备新模块
本文档提供了一些关于如何编写 Perl 模块、准备发布以及通过 CPAN 提供模块的建议。
Perl 强大的原因之一是 Perl 黑客倾向于分享他们遇到的问题的解决方案，这样你和我就不必再为同一个问题而苦苦挣扎。
他们主要通过将解决方案抽象成 Perl 模块来做到这一点。如果你不知道什么是 Perl 模块，那么本文档的其余部分对你来说毫无用处。你错过了很多有用的代码；在回来之前，请先看看 perlmod、perlmodlib 和 perlmodinstall。
当你发现没有可用的模块来完成你想要做的事情，并且你不得不自己编写代码时，请考虑将解决方案打包成一个模块并上传到 CPAN，以便其他人可以从中受益。
你还可以看看 perlmodstyle，了解制作模块的最佳实践。
我们将主要关注 Perl 模块，而不是 XS 模块。XS 模块的用途不同，在发布之前，你应该考虑不同的因素，例如你正在粘合的库的流行程度、对其他操作系统的可移植性等等。但是，关于准备模块的 Perl 部分以及打包和发布模块的说明同样适用于 XS 模块和纯 Perl 模块。
任何你认为对其他人有用的代码，都应该做成一个模块。任何可能填补公共库空白的东西，其他人可以直接将其插入到他们的程序中。你的代码中任何可以隔离、提取并插入其他东西的部分，都是一个可能的候选者。
举个例子，假设你正在将数据从本地格式读取到 Perl 中的哈希-哈希中，将其转换为树，遍历树，然后将每个节点管道到 Acme Transmogrifier 服务器。
现在，相当多的人拥有 Acme Transmogrifier，而你不得不从头开始编写一些东西来与协议通信 - 你几乎肯定想将其做成一个模块。你发布它的级别由你决定：你可能想要类似于 Net::SMTP 的协议级模块，然后与类似于 Mail::Send 的更高级模块进行通信。选择权在你，但你确实想为该服务器协议获得一个模块。
地球上没有其他人会使用你的本地数据格式，所以我们可以忽略它。但中间的东西呢？从 Perl 变量构建树结构，然后遍历它们是一个很好的通用问题，如果还没有人编写一个模块来完成这项工作，你可能也想要将该代码模块化。
所以希望你现在对哪些东西适合模块化有了一些想法。现在让我们看看它是如何完成的。
在我们开始提取代码之前，我们还需要提前做一些事情。
深入研究一些模块，看看它们是如何编写的。我建议从 Text::Tabs 开始，因为它在标准库中，而且非常简单，然后看看更复杂一些的 File::Copy。对于面向对象的代码，WWW::Mechanize 或 Email::* 模块提供了一些很好的例子。
这些应该让你对模块的布局和编写方式有一个整体的了解。
CPAN 上有很多模块，很容易错过一个与你计划贡献的模块类似的模块。仔细浏览 https://metacpan.org，确保你不是在重新发明轮子！
你可能很喜欢它。你可能觉得其他人也需要它。但实际上可能没有真正的需求。如果你不确定你的模块的需求，可以考虑询问 [email protected] 邮件列表（发送电子邮件到 [email protected] 订阅；更多信息和档案链接，请参见 https://lists.perl.org/list/module-authors.html）。
CPAN 上包含的 Perl 模块有一个命名层次结构，你应该尽量符合它。有关此工作原理的更多详细信息，请参见 perlmodlib，并浏览 CPAN 和模块列表以了解它。至少，请记住这一点：模块应该以标题大小写命名，(This::Thing) 应该与类别相符，并简明地解释其目的。
在你这样做的时候，要确保你没有错过一个与你即将编写的模块类似的模块。
当你确定了名称，并且确定你的模块是需要的，而且目前还没有，就可以开始编码了。
module-starter 实用程序作为 Module::Starter CPAN 包的一部分进行分发。它根据最新的模块开发“最佳实践”创建了一个包含所有必要文件存根的目录，并从命令行调用，因此
module-starter --module=Foo::Bar \
--author="Your Name" [email protected]如果您不想从 CPAN 安装 Module::Starter 包，h2xs 是一个较旧的工具，最初用于开发 XS 模块，它与 Perl 发行版一起打包。
对于纯 Perl 模块，h2xs 的典型调用方式如下：
h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar -A 省略 Autoloader 代码，-X 省略 XS 元素，--skip-exporter 省略 Exporter 代码，--use-new-tests 设置现代测试环境，-n 指定模块名称。
模块代码必须是警告和严格清洁的，因为您无法保证它将被使用的条件。此外，您也不希望分发不符合警告或严格清洁的代码，对吧？
Carp 模块允许您从调用者的角度呈现错误消息；这为您提供了一种方法来向调用者而不是您的模块发出问题信号。例如，如果您说：
warn "No hostname given";用户将看到类似以下内容：
No hostname given at
/usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.这看起来像是您的模块出了问题。相反，您希望将责任归咎于用户，并说：
No hostname given at bad_code, line 10.您可以通过使用 Carp 并将您的 warn 替换为 carp 来做到这一点。如果您需要 die，请改为说 croak。但是，为了您的理智检查，请将 warn 和 die 保持在适当的位置 - 这些位置确实是您的模块出错的地方。
Exporter 为您提供了一种标准方法，可以将符号和子例程从您的模块导出到调用者的命名空间。例如，说 use Net::Acme qw(&frob) 将导入 frob 子例程。
包变量 @EXPORT 将决定当调用者简单地说 use Net::Acme 时将导出哪些符号 - 您几乎永远不想在那里放任何东西。另一方面，@EXPORT_OK 指定您愿意导出的符号。如果您确实要导出大量符号，请使用 %EXPORT_TAGS 并定义一个标准导出集 - 请查看 Exporter 以获取更多详细信息。
在完成所有工作之前，你需要完成一些文档工作，你需要花一些时间为你的模块编写一些文档。module-starter 或 h2xs 会为你提供一个可以填写的模板；如果你不确定格式，请查看 perlpod 以获取介绍。提供一个关于如何在代码中使用你的模块的良好概述，一个描述，然后是关于各个子例程或方法的语法和功能的说明。使用 Perl 注释作为开发人员注释，使用 POD 作为最终用户注释。
建议你为你的模块创建自测，以确保它在 Perl 支持的众多平台上按预期工作；如果你将你的模块上传到 CPAN，许多测试人员会构建你的模块并将测试结果发送给你。同样，module-starter 和 h2xs 提供了一个你可以扩展的测试框架 - 你应该做的不仅仅是检查你的模块是否可以编译。 Test::Simple 和 Test::More 是编写测试套件时可以参考的良好起点。
如果你要上传到 CPAN，自动化的程序会提取 README 文件并将其放置在你的 CPAN 目录中。如果你将模块添加到模块列表中，它也会出现在主要的 by-module 和 by-category 目录中。最好在这里详细说明模块的实际功能。
将自上次发布以来的任何用户可见的更改添加到你的 Changes 文件中。
每个在 CPAN 上发布模块的开发人员都需要一个 CPAN ID。访问 https://pause.perl.org/，选择“请求 PAUSE 帐户”，然后等待 PAUSE 管理员批准你的请求。
再次，module-starter 或 h2xs 已经为你完成了所有工作。它们会生成你在下载和安装模块时看到的标准 Makefile.PL，它会生成一个带有 dist 目标的 Makefile。
perl Makefile.PL && make test && make distcheck && make dist一旦你确保你的模块通过了它自己的测试 - 这始终是一个好习惯 - 你可以运行 make distcheck 来确保一切正常，然后运行 make dist，Makefile 应该会为你生成一个漂亮的模块压缩包，准备上传。
你在收到 CPAN ID 时收到的电子邮件会告诉你如何登录 PAUSE（Perl 作者上传服务器）。从那里的菜单中，你可以将你的模块上传到 CPAN。
或者，你可以使用 cpan-upload 脚本，它是 CPAN 上 CPAN::Uploader 发行版的一部分。
一旦你开始积累用户，他们就会向你发送 bug 报告。如果你幸运的话，他们甚至会向你发送补丁。欢迎来到维护软件项目的乐趣...
Simon Cozens，[email protected]
由 Kirrily "Skud" Robert 更新，[email protected]
perlmod，perlmodlib，perlmodinstall，h2xs，strict，Carp，Exporter，perlpod，Test::Simple，Test::More ExtUtils::MakeMaker，Module::Build，Module::Starter https://www.cpan.org/