第二十二章 CPAN

CPAN（"the Comprehensive Perl Archive Network"全面的 Perl 存档网络）是
查找任何 Perl 有关的东西的中心仓库。它包含从整个 Perl 社区收集来的智慧：
成百上千的 Perl 模块和脚本，相当于好几本书的文档，以及整个 Perl 发布。如果
有东西是用 Perl 写的，而且这个东西很有用而且是自由的，那么它很有可能就在
CPAN 上。CPAN 在全世界都有镜象，你可以在位于 http://www.perl.com/CPAN 的
CPAN 路牌上找到离你最近的镜象。那块路牌会记住你选择的是哪个镜象并且你以后再
访问 http://www.perl.com/CPAN/ （注意最后的斜杠）的时候就会自动重新定向到
那个镜象。另外，你也可以从 www.cpan.org 开始。这个站的界面不同，但是数据是
一样的。

一旦你进入 CPAN 的主目录，你就会看到下面的几个子目录：

• authors
  • 这个目录包含许多子目录，每个贡献者一个。比如，如果你想找 Lincoln Stein 那些写得非常好的 CGI 模块（现在是标准 Perl 版本的一部分了），并且你碰巧知道是他写了这些模块，那么你就可以到authors/Lincoln_stein 目录里看看。如果你不知道是他写了这些模块，那么你可以到下面描述的 modules 目录里找。

• doc
  • 这个目录保存所有风格的 Perl 文档，包括 Perl 的官方手册页的好几种不同的排列和格式，比如文本，HTML，PostScript，和 Perl 自身的 pod 格式，pod 格式在第二十六章，简单老式文本，里叙述。

• modules
  • 这个目录包含用 Perl 或者 Perl 和 C 混合写成的模块。参阅后面 modules 目录的讨论。

• ports
  * 这个目录包含源代码，有时候还有一些预编译好的可执行的 Perl 移植，主要针对那些在标准版本里并不直接支持的操作系统，或者某些很难用的编译器。这些移植都是它们各自的作者的独立的努力成果，因此运行起来可能和本书描写的不完全一样。目前很少有系统需要移植。不过此目录的索引文档倒是很值得看看，因为它还包括每种系统何时开始包括 Perl 的详细信息。

• scripts
  * 这个目录包含少量从全世界各地发来的各种各样的 Perl 程序。它们可以用做独立的程序，或者也可以用做例子（尽管那些代码可能经不起质量检查）。目前，这里面还没有很多程序列出，不过，我们希望随着时间的推移，这个区域会变得越来越丰富。Perl Power Tools project （Perl 万能工具箱，PPT）也放在这里。PPT 的目标是用 Perl 重新制作所有 Unix 工具。大多数标准的已经完成了，另外还有有些不那么标准的也做完了。

• src
  • 在这个目录里，你可以找到标准 Perl 发布版本的源程序。实际上，是两个标准 Perl 版本的源程序，一个标记着 stable（稳定版），另外一个是 devel （开发版）。（该目录的索引页有详细解释。）它们都只是相应版本的链接。早我们写这些的时候，stable.tar.gz 是到 perl-5.6.0.tar.gz（通常的方案是：如果版本号的第二个数字是偶数，那么它就是正式版本，如果是奇数，那么是开发版。后面的 .tar.gz 后缀有时候是 .tgz，表示它是一个标准的互联网格式：GNU 压缩的 tar 归档，常称做“tarball”）的符号链接，不过到你读这些的时候，它们很可能指向一个更高的版本数。这个巨大的文件包含 Perl 的所有源程序和文档。配置和安装在大多数平台上应该都是非常直接的。如果不是，请参阅早先描述的 ports。

22.1 CPAN 模块目录

尽管 CPAN 包含 Perl 的完整的源程序，几种便于没有 C 编译器的系统使用的二进制
发布，以及一些程序，但令 CPAN 闻名的却是它收集的的一堆模块。

当我们谈到“模块”的时候，我们指的是三种事情：100% 纯 Perl 模块（在第十一章，
模块，和第十二章，对象，里描述）扩展（那些依赖 C 代码的模块，在第二十一章，
内部和外部，描述）和用法（包含给 Perl 编译器的特殊指令的模块，在第三十一章，
用法模块，里描述）。另外在 CPAN 里还有模块包。模块包是一系列模块的集合，
这些模块解决某一类的问题，并且通常是模块的作者为了对某一类问题提供一揽子解决
方法而制作的。如果一个模块以来另外一个模块（并且可能是某一特定版本），开发人
员通常将模块捆绑在一起。比如，你可以看看 Bundle-XML。

浏览 CPAN 的模块的一个方法是反问 http://search.cpan.org，它为 CPAN 提供
一个搜索器前端。另外一个方法是访问你的本地 CPAN 镜像并且进入 modlues 目录，
在那里你可以看到子目录：by-authors，by-category，和 by-name。如果你的
浏览器有搜索功能的话，那么 by-name 目录可能是最有用的了——尽管（有些让人
不快）有些模块只能在作者的目录里找到。如果你按照目录搜索，你会有下列选择：

Perl 核心模块，语言扩展，和文档工具

这些包括用法和其他标准模块，帮你改变 Perl 的模块，与 Perl 编译器相关的模块，源码过滤器，以及于 Perl 的 pod 文档格式相关的模块。这个目录还包括用于生成 Java 字节码的模块。

开发支持

这个目录包括用语创建和检查 Perl 如何运行程序的模块。

操作系统接口和硬件驱动

这里你会找到与和操作系统， PalmPilot^?，串口这样的特殊的东西交互的模块。

网络，设备控制，和进程间通讯

这里包括实现网络协议，操作网络数据，操作调制解调器，以及控制你家里的装置的模块。

数据类型和数据类型工具

这个目录包括那些应用与数学，统计学，算法，数据结构（和它们的永久存储），日期和时间，面向对象的编程，PDL（Perl Data Language，用于数据压缩），以及 POE （Perl Object Environment，一个面向对象的，事件驱动的调度器。）

数据库接口

这里你可以找到让你从 Perl 里操作好几十种数据库系统的模块，它们大多数都带有 Perl DBI 系统。包括数据库相关的 DBD 模块。

用户接口（字符和图形界面）

这里包括用于操作用户终端（命令行编辑和 curses(3) 风格的字符图形）， 以及 Perl/Tk 和用于写你自己的 GUI 的与 Gtk，Gnome，Sx 和 Qt 的捆绑。

与其他编程语言的接口或者仿真器

这个目录里有让你从 Perl 里使用其他编程语言，或者把 Perl 假装成其他的什么东西的模块。如果 你对在 C 里用 Perl 或者在 Perl 里用 C 感兴趣，请参阅第二十一章。

文件名，文件系统，和文件锁

这里包括用于检查，创建，锁定和操作文件和目录的模块。

字串处理，语言文本处理，分析和搜索

这个目录包含文本操作的模块，文本操作是：加连字符，封装，分析，找词干，以及搜索。这里包括操作 PostScript^?，XML，和 RTF 的模块。

选项，参数，开关和配置文件处理

这个目录包含用于处理命令行参数（在 myprlprog -x 里的 -x）和处理配置文件（象点文件）的模块。

国际化和本地化

这个目录包括用于把你的 Perl 程序剪裁成适用于特定国家和语言的场合的模块。

认证，安全，和加密

你可以在这里找到管理用户密码，计算信息摘要，加密数据，和认证用户的模块。

world wide web，HTML，HTTP，CGI，MIME

这个目录有那些让你可以创建以 CGI 为基础的网页，web 机器人，以及以 web 为基础的内容管理系统。其他模块让你可以管理 cookie，分析 HTML 和MIME 消息，以及操作 web 缓冲。这里还有那些你能嵌入 Apache web 服务器的 Perl 模块的特殊目录。

服务器和守护工具

这里包括创建网络和事件服务器的模块。

归档，压缩，和转换

你在这里能找到用于压缩和打包文件，以及在不同文件格式（甚至是 Apple II 文件格式）之间转换的模块。

图象，影片，以及位图处理，描绘，和画图

这个目录包含创建图片，GIF，VRML，和用于与 Gimp 共同使用的模块。

*邮件和新闻组 *

你可以在这个目录里找到发送，接收和过滤邮件和新闻组的模块。

控制流工具

这个目录包含用于在临时执行 Perl 代码的模块。

文件句柄，目录句柄和输入/输出流工具

这里的模块是用于输入输出文件，包括日志文件的。包括所有 IO:: 模块和一个用于与网络服务或者 其他交互程序自动转换的 Expect 模块。

Microsoft Windows 模块

这里包括操作 Windows 注册表，ASP，ODBC，OLE，以及其他 Windows 特有 的技术的模块。

杂项模块

这里你可以找到用于天文学，生物学，化学，验证信用卡有效期（或者令信用卡失效），分期付款，音频，视频，MIDI，天气和游戏等模块。

22.2 使用 CPAN 模块

你在 CPAN 找得到的大多数模块都是“tarball”形式，也就是说，它们有一个
.tar.gz 的文件扩展，并且展开后可以到一个带有模块代码和任意附属文件的
目录中，通常包括一个README 和一个 Makefile.PL 文件。

在你的程序上使用 CPAN 模块有四个步骤：解压缩，解包，制作，和安装。每个步骤的
具体实施方法取决于你的操作系统和被安装的模块，因此我们无法给你一个任何时候都
能用的傻瓜型的方法。如果你有问题，可以阅读 README 和 INSTALL 文件，这些文件
很可能和该模块一起发布。同时也要读一下 perlmodinstall 手册页。

不过如果你使用 CPAN 模块（与 Perl 版本一起捆绑）或者 PPM
（Perl Package Manager，Perl 包管理器和 Perl 的 ActiveState^? 版本一起
捆绑），你可能永远不用考虑安装过程。要使用 CPAN 模块（不要和 CPAN 本身混淆
了），在你的命令行上键入：

   %perl -MCPAN -e "shell"

开始配置过程。在你完成一系列关于你喜欢怎样检索文件的问题之后，你就可以通过在
CPAN 模块的 shell里敲入下面命令安装模块：

   install Some::Module

或者在你普通的命令行上键入：

   %perl -MCPAN -e "install 'Some::Module'"

如果你手头没有 CPAN 模块和 PPM，那你就必须手工走过下面节描述的步骤。那些
命令是用于 Unix，Windows，和 Macintosh 的；其他操作系统，请参考
perlmodinstall 手册页。

22.2.1. 解压缩和解开 CPAN 模块的包

在 CPAN 上的成千的工具中的大部分是压缩过的，这样他们就可以少用一些磁盘空间。
一旦你检索出一个模块的压缩包，首先你需要把它转换成你的操作系统里的一个
目录树：对压缩包进行解压缩和解包。在 Unix 上，你可以用 gzip 和 tar 来完成
这些工作。（在许多系统上，tar 两件事都可以干。）在 Windows 上，WinZip 会帮
你解压缩和解包。在 Macintosh 上，你可以使用 StuffIt^? 和 DropStuff^?，
MacGzip^?，或者 suntar。

22.2.2 Build CPAN 模块

有一小部分 CPAN 模块是以 C 源程序的形式发布的，因此你需要为你的系统编译
它们，通常对那些缺乏 C 编译器的系统而言是一个问题。制作一个 CPAN 模块的标准
步骤（有或者没有 C 代码）是下面三条命令，在命令行上执行。（如果你没有命令行，
或者一个等效的 make，那么你就需要求助于更剧烈的，系统相关的步骤。Windows
用户有命令行，不过坑内需要使用 nmake 工具而不是 make 工具。）

   % perl Makefile.PL
   % make
   % make test

perl Makefile.PL 命令将试图创建 Makefile，该文件是随后的 make 命令用于检查
需要按照什么顺序制作什么工具。最后一条命令，make test，运行模块作者包含的
测试套件。

22.2.3. 把 CPAN 模块安装到 Perl 库中

假设你遵循了前面的步骤，现在你有一个已经制作和测试过的模块，但是还没有安装到
Perl 的库中。在往你的系统中安装 Perl 的时候，创建了一个 lib 目录用于保存
模块，用法，以及相关文件。这个就是 Perl 库，在 Unix 系统上
通常是一些 /usr/local/lib/perl5 或者在 Windows 系统上缺省是 C:\PERL\LIB
这样的目录。在制作 Perl 之后安装的模块存放在 Perl 库的 site_perl 子目录中。
你可以用下面的命令看到你的所有库目录（和一堆其他东西）：

   %perl -v

要安装该模块，键入：

   %make install

通常需要超级用户的访问权限，即使是将模块安装到你的平台相关的 Perl 库目录中也如此。

你稍做努力，就可以把该模块安装到你的 Perl 库以外的地方（比如你的家目录）。
如果你平时是敲入 perl Makefile.PL 来创建 Makefile 的，那么你可以用下面的
替身：

   %perl Makefile.PL LIB=/my/dir/perllib       INSTALLMAN1DIR=/my/dir/man/man1       INSTALLMAN3DIR=/my/dir/man/man3       INSTALLBIN=/my/dir/bin            INSTALLSCRIPT=/my/dir/scripts

这样将在 /my/dir/perllib 目录里的某个地方安装该模块，并且把其他文件安装到它
们相应的位置。（如果你觉得这样要敲一堆东西，那么你甚至可以写一个小 Perl 程序
来干这件事情，Perl 干这种事情很在行。）

然后你就可以让 Perl 在你的特殊的目录里搜索模块，在你的程序试图装载该模块之前
增加一句：

   use lib "/my/dir/perllib";

到你的程序里。你还可以设置 PERL5LIB 环境变量为该目录，或者用 Perl 的 -I
开关。参阅第三十一章的 use lib 用法获取一个这方面的例子。

22.3. 创建 CPAN 模块

如果你有一个模块，并认为可能对其他人有帮助，那么你可以把它上载到 CPAN，让
世界更美好。操作新模块的提交的服务器叫 PAUSE（Perl Authors Upload Server，
Perl 作者上载服务器），可以在 https://pause.kbx.de/pause/ 找到。在你能够
上载你的模块之前，你得先获取一个 PAUSE 帐号。这就和你成为“注册的 Perl 开发人员”非常相似。

如果你称自己为一个注册的 Perl 开发人员，那么你就应该知道给你的模块写文档的
内容。Perl 有一个在源程序里嵌入文档的方法。（这样，你就绝不会丢失文档。）
这种嵌入的文档是一种叫“pod”（Plain Old Documentation）的格式存在的，它在
第二十六章描述。

你应该考虑把你的模块制作成线程安全的。参阅第十七章，线程。

你还应该为你可爱的小模块多考虑一些安全性的问题：它是否会破坏它的使用者的
安全？因为其他人有比你更充分的理由更加关心安全。参阅第二十三章，安全，获取
一些如何避免为发起第三次世界大战以及其他麻烦事负责的经验。

如果准备在 CPAN 发布的模块应该包括一个叫 Makefile.PL 的 Perl 程序，运行
它的时候会生成 Makefile，还要包括一个 README 文件，简单地介绍模块是干什么的
以及如何安装它。Makefil 还会希望你的模块包括一个测试套件。你可以用 h2xs
工具一次性创建所有这些文件：

   h2xs -X -n Foo::Bar

（如果你制作的模块有一个 XS 组件，那么用 -A 代替 -X。XS 在第二十一章里
描述。）h2xs 程序为你创建一个目录，里面有一些框架性的文件，你可以填充这些
文件，增加自己的东西。如果你完成这些工作，那么你可以把你的压缩包上载到
PAUSE。

h2xs 生成的 Makefile.PL 看起来象下面这样：

   use ExtUtils::MakeMaker;
   # 参阅 ExtUtils/MakeMaker.pm 获取如何影响
   # 输出的 Makefile 的内容的详细方法

   WriteMakefile(
      NAME      => 'Mytest',
      VERSION_FROM => 'Mytest.pm',# 找 $VERSION
      LIBS      => [' '],   # 比如， '-lm'
      DEFINE      =>' ',      # 比如，'-DHAVE_SOMETHING'
      INC      =>' ',      # 比如，'-I/usr/include/other'
   );

Makefile.PL 做的第一件事情就是输入 ExtUtils^?::MakeMaker 模块。MakeMaker
的 WriteMakefile^? 函数有许多选项（这里定义的选项将近 88 个）以帮助你做一些
用户从 CPAN 下载该模块，键入 perl Makefile.PL 开始制作它之后的客户化工作。
所有这些东西的好处就是，因为用户运行的 perl 可能以后也还要使用，那么你就
可以获得丰富的配置信息（通过 Config 模块或者 $^O 特殊变量）帮助你决定如何
驱动 MakeMaker^?。换句话说，MakeMaker 非常擅长于寻找几乎所有东西的良好的缺省
值，因此 h2xs 写的框架性文件可能就是你需要的全部，可能只需要仔细构造
一到两个。关于这方面的更多的信息，请参考 ExtUtils^?::MakeMaker 的扩展性联机
文档。

如果写一个通用目的的 Perl 模块，你应该允许用户的 Perl 版本可以和你的不一样。
你还应该在 README 里放上任何依赖性（特定版本的 Perl，或者系统要求，或者其他
模块）信息的英文描述。不过，即使这样做也可能不够，因为有些人可能会使用聪明的
CPAN 模块自动下载和安装你的模块，因而可能看不到这些警告。因此你应该在
Makefile.PL 里检查那些依赖性。下面是一个确保下载你的模块的用户运行在
Perl 5.6 或更高版本的方法：

   eval { require 5.6.0 }
      or die <<'EOD';
   ###########
   ###  This module requires lvaluable subroutines, which are no available
   ###  in versions of Perl earlier than 5.6. Please upgrade!
   ###########
   EOD

22.3.1. 内部测试

安装一个模块的标准指导告诉用户在用 make 制作完模块后运行 make test。所以，
请给你上载给 CPAN 的任何模块包括一个象样的测试脚本。你应该模拟那种 Perl 在
自己的测试套件里的 ok/no ok 风格，以便于用户判断每个测试情况的输出。h2xs
生成的 test.pl 可以帮助你起步。第二十一章里有一些你可以追加到 test.pl 后面的测试例子。

如果你有许多测试情况，你可能想模拟 Perl 的测试套件：在模块的目录里创建一个
叫 t/ 的子目录，然后给你的不同的测试脚本名字后面附加 .t。当你运行
make test 的时候，所有测试文件都会被自动执行。

22.3.2. 外部测试

上载到 CPAN 的模块会被许多志愿者在许多不同的平台上测试。每当一个新的模块上载
之后，这些 CPAN 测试人员都会通过邮件被告之，并且他们会回答给邮件列表 PASS，
FAIL，NA（不能用于该平台），或者UNKNOWN（不知道），以及任何相关的注释。你
可以在 cpan-testers@perl.org 找到 CPAN 测试者的邮件列表；测试结果张贴到
http://testers.cpan.org/。

当然，这些只是非常基本的测试。真正的测试发生在某人把你的模块插入到一个每天
有几百万次点击的 web 服务器以后。或者是你的模块用于帮助设计很快你就会搭乘的
飞机的时候。

所以，想想看，人们是否关心你写了那些让人讨厌的小测试 ...

<!--

• Set MYTITLE = CPAN, the Comprehensive Perl Archive Network

-->