CPAN - 从 CPAN 站点查询、下载和构建 Perl 模块
交互模式
perl -MCPAN -e shell-- 或者 --
cpan基本命令
# Modules:
cpan> install Acme::Meta # in the shell
CPAN::Shell->install("Acme::Meta"); # in perl
# Distributions:
cpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell
CPAN::Shell->
install("NWCLARK/Acme-Meta-0.02.tar.gz"); # in perl
# module objects:
$mo = CPAN::Shell->expandany($mod);
$mo = CPAN::Shell->expand("Module",$mod); # same thing
# distribution objects:
$do = CPAN::Shell->expand("Module",$mod)->distribution;
$do = CPAN::Shell->expandany($distro); # same thing
$do = CPAN::Shell->expand("Distribution",
$distro); # same thingCPAN 模块自动或至少简化了 Perl 模块和扩展的制作和安装。它包含一些基本的搜索功能，并知道如何使用 LWP、HTTP::Tiny、Net::FTP 和某些外部下载客户端从网络获取发行版。
这些是从一个或多个镜像的 CPAN（综合 Perl 档案网络）站点获取的，并解压缩到一个专用目录中。
CPAN 模块还支持命名和版本化的捆绑包模块。捆绑包简化了相关模块集的处理。请参阅下面的捆绑包。
该包包含一个会话管理器和一个缓存管理器。会话管理器跟踪当前会话中已获取、构建和安装的内容。缓存管理器跟踪 make 进程占用的磁盘空间，并使用简单的 FIFO 机制删除多余的空间。
提供的所有方法都可以在程序员风格和交互式 shell 风格中访问。
通过运行以下命令进入交互模式
perl -MCPAN -e shell或者
cpan这会把你带入一个命令行界面。如果安装了 `Term::ReadKey` 和 `Term::ReadLine::Perl` 或 `Term::ReadLine::Gnu` 中的任何一个，则支持历史记录和命令补全。
在命令行中，输入 `h` 可以查看一页帮助信息；其他内容应该不言自明。
函数调用 `shell` 接受两个可选参数：第一个是提示符，第二个是默认的初始命令行（后者只有在安装了真正的 ReadLine 接口模块时才有效）。
交互模式最常见的用途是
对于这四类，分别对应着单字母命令 `a`、`b`、`d` 和 `m`，以及另一个命令 `i`，用于表示上述四类中的任何一种。这四种实体都以类的形式实现，它们具有略微不同的方法来显示对象。
这些命令的参数可以是与对象的标识符字符串完全匹配的字符串，也可以是不区分大小写的正则表达式，与对象的各种属性匹配。解析器只在用斜杠将正则表达式括起来时才会识别它。
原则是，找到的对象数量会影响项目的显示方式。如果搜索找到一个项目，则结果将使用比较详细的方法 `as_string` 显示，但如果找到多个项目，则每个对象将使用简洁的方法 `as_glimpse` 显示。
示例
cpan> m Acme::MetaSyntactic
Module id = Acme::MetaSyntactic
CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
CPAN_VERSION 0.99
CPAN_FILE B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
UPLOAD_DATE 2006-11-06
MANPAGE Acme::MetaSyntactic - Themed metasyntactic variables names
INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
INST_VERSION 0.99
cpan> a BOOK
Author id = BOOK
EMAIL [...]
FULLNAME Philippe Bruhat (BooK)
cpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz
Distribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz
CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>)
CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
UPLOAD_DATE 2006-11-06
cpan> m /lorem/
Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz)
Module Text::Lorem (ADEOLA/Text-Lorem-0.3.tar.gz)
Module Text::Lorem::More (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
Module Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz)
cpan> i /berlin/
Distribution BEATNIK/Filter-NumberLines-0.02.tar.gz
Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz)
Module Filter::NumberLines (BEATNIK/Filter-NumberLines-0.02.tar.gz)
Author [...]这些示例说明了几个方面：前三个查询直接针对模块、作者或发行版，并产生一个结果。最后两个使用正则表达式，并产生多个结果。最后一个同时针对包、模块、作者和发行版。当有多个结果可用时，它们将以单行格式打印。
get、make、test、install、clean 模块或发行版这些命令接受任意数量的参数，并调查执行操作所需的步骤。参数处理如下
known module name in format Foo/Bar.pm module
other embedded slash distribution
- with trailing slash dot directory
enclosing slashes regexp
known module name in format Foo::Bar module如果参数是分发文件名（通过嵌入的斜杠识别），则会对其进行处理。如果它是模块，CPAN 会确定包含此模块的分发文件并对其进行处理，并遵循模块的 META.yml 或 Makefile.PL 中指定的任何依赖项（此行为由配置参数 prerequisites_policy 控制）。如果参数用斜杠括起来，则将其视为正则表达式：它会被扩展，如果结果是单个对象（分发、捆绑或模块），则会处理此对象。
示例
install Dummy::Perl # installs the module
install AUXXX/Dummy-Perl-3.14.tar.gz # installs that distribution
install /Dummy-Perl-3.14/ # same if the regexp is unambiguousget 下载分发文件并将其解压缩或解压缩，make 构建它，test 运行测试套件，install 安装它。
任何 make 或 test 都将无条件运行。一个
install <distribution_file>也将无条件运行。但对于
install <module>CPAN 会检查是否需要安装，如果包含该模块的分发文件不需要更新，则会打印 模块已更新。
CPAN 还会跟踪它在当前会话中所做的事情，并且不会尝试第二次构建包，无论它是否成功。如果测试之前已成功运行，它不会重复测试运行。安装运行也是如此。
force 标记可以放在另一个命令之前（当前：get、make、test 或 install），以从头开始执行命令并尝试在某些错误后继续。请参阅下面关于 force 和 fforce 标记的部分。
notest 标记会跳过构建过程中的测试部分。
示例
cpan> notest install Tkclean 命令会导致
make clean在分发文件的 working 目录中执行。
readme、perldoc、look 模块或分发readme 显示关联分发的 README 文件。Look 获取并解压缩（如果尚未完成）分发文件，更改到相应的目录并在该目录中打开一个子 shell 进程。perldoc 以 html 或纯文本格式显示模块的 pod 文档。
ls glob 表达式第一种形式列出作者的 CPAN 目录中以及该目录下所有分发文件，如 CPAN 上分发的 CHECKSUMS 文件中所存储的那样。列表会递归进入子目录。
第二种形式使用 shell glob 来限制或扩展输出，如以下示例所示
ls JV/make*
ls GSAR/*make*
ls */*make*最后一个例子非常慢，并且输出额外的进度指示器，破坏了结果的对齐方式。
请注意，globbing 仅列出明确要求的目录，例如 FOO/* 不会列出 FOO/bar/Acme-Sthg-n.nn.tar.gz。这可能被视为一个 bug，可能会在未来的某个版本中更改。
failedfailed 命令报告所有在当前运行的 shell 会话中因某种原因在 make、test 或 install 中失败的分布。
如果安装了 YAML 或 YAML::Syck 模块，则在每个步骤之后，所有模块的内部状态记录都会写入磁盘。这些文件包含当前运行的 perl 版本的签名，以便日后查看。
如果配置变量 build_dir_reuse 设置为真值，则 CPAN.pm 会读取收集的 YAML 文件。如果存储的签名与当前运行的 perl 相匹配，则存储的状态将加载到内存中，从而有效地建立会话之间的持久性。
force 和 fforce 编译指示为了在复杂的安装场景中加快速度，CPAN.pm 会跟踪它已经完成的操作，并拒绝第二次执行某些操作。get、make 和 install 不会重复。test 仅在之前的测试不成功时才会重复。当 CPAN.pm 拒绝第二次执行某些操作时，诊断消息是 已解包|制作|测试成功 或类似内容。CPAN 拒绝执行操作的另一种情况是，如果相应的 test 不成功，则执行 install。
在所有这些情况下，用户可以通过在命令前加上 force 一词来覆盖这种固执的行为，例如
cpan> force get Foo
cpan> force make AUTHOR/Bar-3.14.tar.gz
cpan> force test Baz
cpan> force install Acme::Meta每个强制命令都与其内存的相应部分一起执行。
fforce 编译指示是一种变体，它模拟 force get，它会擦除整个内存，然后执行指定的动作，有效地从头开始重新启动整个 get/make/test/install 过程。
交互式会话维护一个锁文件，默认情况下为 ~/.cpan/.lock。批处理作业可以在没有锁文件的情况下运行，并且不会互相干扰。
当另一个进程持有锁文件时，shell 会提供以降级模式运行。这是一个实验性功能，尚未经过充分测试。第二个 shell 不会写入历史文件，不会使用元数据文件，并且具有不同的提示符。
CPAN.pm 为 SIGINT 和 SIGTERM 安装信号处理程序。当您在 cpan-shell 中时，您可以随时按下 ^C 并返回到 cpan-shell 提示符。SIGTERM 将导致 cpan-shell 清理并退出 shell 循环。您可以通过发送两个连续的 SIGINT 来模拟 SIGTERM 的效果，这通常意味着按下 ^C 两次。
CPAN.pm 忽略 SIGPIPE。如果用户设置了 inactivity_timeout，则在运行 perl Makefile.PL 或 perl Build.PL 子进程期间使用 SIGALRM。SIGALRM 也用于模块版本解析，并由 version_timeout 控制。
shell 接口中可用的命令是 CPAN::Shell 包中的方法。如果您输入 shell 命令，您的输入将由 Text::ParseWords::shellwords() 例程拆分，该例程的行为类似于大多数 shell。第一个词被解释为要调用的方法，其余的词被视为方法的参数。通过在行尾添加一个文字反斜杠来支持续行。
autobundle 将一个捆绑文件写入 $CPAN::Config->{cpan_home}/Bundle 目录。该文件包含一个列表，其中列出了所有既可从 CPAN 获取又当前安装在 @INC 中的模块。每个发行版的副本都被抑制。捆绑文件的文件名基于当前日期和计数器，例如 Bundle/Snapshot_2012_05_21_00.pm。这可以通过运行 cpan Bundle::Snapshot_2012_05_21_00 或从 CPAN shell 安装 Bundle::Snapshot_2012_05_21_00 来再次安装。
返回值：写入文件的路径。
注意：此功能仍处于 alpha 状态，可能会在 CPAN.pm 的未来版本中发生变化
此命令提供最近下载活动的统计概述。此数据收集在 cpan_home 目录中的 YAML 文件 FTPstats.yml 中。如果未配置 YAML 模块或未安装 YAML，则不会提供统计信息。
安装所有已成功测试但尚未安装的发行版。另请参见 is_tested。
列出所有已成功测试但尚未安装的发行版的构建目录。另请参见 install_tested。
mkmyconfig() 将您自己的 CPAN::MyConfig 文件写入您的 ~/.cpan/ 目录，以便您可以保存自己的首选项而不是系统范围的首选项。
扫描当前的 perl 安装以查找在 CPAN 上有更新版本的模块，并提供它们的列表。如果在没有参数的情况下调用，则列出所有潜在的升级；如果在有参数的情况下调用，则将列表过滤到作为参数给出的模块和正则表达式。
列表看起来像这样
Package namespace installed latest in CPAN file
CPAN 1.94_64 1.9600 ANDK/CPAN-1.9600.tar.gz
CPAN::Reporter 1.1801 1.1902 DAGOLDEN/CPAN-Reporter-1.1902.tar.gz
YAML 0.70 0.73 INGY/YAML-0.73.tar.gz
YAML::Syck 1.14 1.17 AVAR/YAML-Syck-1.17.tar.gz
YAML::Tiny 1.44 1.50 ADAMK/YAML-Tiny-1.50.tar.gz
CGI 3.43 3.55 MARKSTOS/CGI.pm-3.55.tar.gz
Module::Build::YAML 1.40 1.41 DAGOLDEN/Module-Build-0.3800.tar.gz
TAP::Parser::Result::YAML 3.22 3.23 ANDYA/Test-Harness-3.23.tar.gz
YAML::XS 0.34 0.35 INGY/YAML-LibYAML-0.35.tar.gz它在 in CPAN file 列中抑制重复项，因此具有多个可升级模块的发行版仅列出一次。
请注意，列表未排序。
recent 命令下载 CPAN 上最近上传的列表并缓慢地显示它们。在命令运行时，$SIG{INT} 在显示当前项目后退出循环。
注意：此命令需要安装 XML::LibXML。
注意：整个命令目前只是一个 hack，可能会在 CPAN.pm 的未来版本中更改，但总体方法可能会保留。
注意：另请参见 smoke
recompile() 是一个特殊的命令，它不接受任何参数，并对所有已安装的动态加载扩展（也称为 XS 模块）以“force”方式运行 make/test/install 循环。此命令的主要目的是完成网络安装。假设您有两个不同架构的公共源代码树。您决定进行完全独立的新安装。您在第一个架构上使用之前生成的 Bundle 文件的帮助开始。CPAN 为您安装了整个 Bundle，但是当您尝试在第二个架构上重复该工作时，CPAN 会对所有模块响应 "Foo up to date" 消息。因此，您在第二个架构上调用 CPAN 的 recompile，然后您就完成了。
recompile 的另一个常见用途是在 Perl 出现二进制兼容性问题时充当救援工具。如果 CPAN 使用的模块依赖于二进制兼容性（因此无法运行 CPAN 命令），则应尝试使用 CPAN::Nox 模块进行恢复。
report 命令临时启用 test_report 配置变量，然后使用给定参数运行 force test 命令。force 准则会重新运行测试并重复可能之前失败的每个步骤。
***警告：此命令会从 CPAN 下载并执行软件到您的计算机，其状态完全未知。您不应该在正常帐户下执行此操作，最好使用专门的、隔离且安全的机器来执行此操作。***
smoke 命令会获取 recent 命令提供的 CPAN 最近上传列表，并对所有上传进行测试。在命令运行期间，$SIG{INT} 被定义为跳过当前项目的含义。
注意：整个命令目前只是一个 hack，可能会在 CPAN.pm 的未来版本中更改，但总体方法可能会保留。
注意：另请参见 recent
upgrade 命令首先使用给定参数运行 r 命令，然后安装该命令列出的所有模块的最新版本。
CPAN::* 类：作者、捆绑包、模块、发行版尽管它可能被认为是内部的，但类层次结构对用户和程序员都很重要。CPAN.pm 处理上面提到的四个类，这些类都共享一组方法。经典的单一多态性生效。元类对象注册所有类型的对象，并使用字符串对其进行索引。引用对象的字符串具有一个分隔的命名空间（好吧，不是完全分隔的）
Namespace Class
words containing a "/" (slash) Distribution
words starting with Bundle:: Bundle
everything else Module or Author模块知道它们关联的发行版对象。它们始终引用最新的官方版本。开发人员可以将其版本标记为不稳定的开发版本（通过在模块版本号中插入下划线，这也会反映在运行“make dist”时的发行版名称中），因此最热门和最新的发行版并不总是默认的。如果模块 Foo 在 CPAN 上以 1.23 和 1.23_90 两个版本流通，CPAN.pm 提供了一种方便的方法来安装 1.23 版本，方法是说
install Foo这将安装完整的发布文件（例如 BAR/Foo-1.23.tar.gz）以及所有附带的材料。但是，如果您想安装版本 1.23_90，则需要知道发布文件在 CPAN 上相对于 authors/id/ 目录的位置。如果作者是 BAR，这可能是 BAR/Foo-1.23_90.tar.gz；因此您需要说
install BAR/Foo-1.23_90.tar.gz第一个示例将由 CPAN::Module 类的对象驱动，第二个示例将由 CPAN::Distribution 类的对象驱动。
注意：此功能仍处于 alpha 状态，可能会在 CPAN.pm 的未来版本中发生变化
Distribution 对象通常是来自 CPAN 的发行版，但对于 Distribution 对象，也存在一个稍微退化的案例，即保存在本地磁盘上的项目。这些发行版对象与本地目录具有相同的名称，并以点结尾。当使用 CPAN.pm 时，点本身也允许表示当前目录。所有操作，例如 make、test 和 install，都直接应用于该目录。这使得命令 cpan . 具有有趣的意义：虽然在没有 CPAN.pm 的情况下安装 CPAN 模块的正常口诀是
perl Makefile.PL perl Build.PL
( go and get prerequisites )
make ./Build
make test ./Build test
make install ./Build install命令 cpan . 一次完成所有这些操作。它会找出哪种口诀是合适的，获取并安装所有先决条件，递归地处理它们，最后完成当前目录中模块的安装，无论它是否是 CPAN 模块。
典型的用例是用于本地磁盘上的私有模块或来自远程存储库的项目的正在使用的副本。
cpan shell 仅 **在空格包围的情况下** 识别常用的 shell 重定向符号 | 和 >。因此，将管道输出到分页器或将输出重定向到文件在某种程度上与普通 shell 中的操作类似，但需要您键入额外的空格。
插件是实现当前八种方法中的任何一种的对象
pre_get
post_get
pre_make
post_make
pre_test
post_test
pre_install
post_installplugin_list 配置参数包含一个字符串列表，其格式为
Modulename=arg0,arg1,arg2,arg3,...例如
CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1在运行时，每个列出的插件都通过运行等效于此伪代码的代码来实例化为一个单例对象
my $plugin = <string representation from config>;
<generate Modulename and arguments from $plugin>;
my $p = $instance{$plugin} ||= Modulename->new($arg0,$arg1,...);生成的单例对象从实例化开始一直保留到 shell 会话结束。<plugin_list> 可以在运行时随时重新配置。当 cpan shell 运行时，它会在上述 8 个参考点中的每一个点检查所有激活的插件，如果该对象实现了相应的方法，则运行该方法。该方法将使用传入的活动 CPAN::Distribution 对象作为参数调用。
当第一次使用 CPAN 模块时，配置对话框会尝试确定一些特定于站点的选项。对话框的结果存储在一个哈希引用 $CPAN::Config 中，该引用位于文件 CPAN/Config.pm 中。
在 CPAN/Config.pm 文件中定义的默认值可以在用户特定文件中覆盖：CPAN/MyConfig.pm。此类文件最好放在 $HOME/.cpan/CPAN/MyConfig.pm 中，因为 $HOME/.cpan 在 use() 或 require() 语句之前被添加到 CPAN 模块的搜索路径中。mkmyconfig 命令会为您编写此文件。
o conf 命令具有各种功能
如果您安装了 ReadLine 模块，您可以在命令行中的任何位置按下 TAB 键，o conf 将为您提供内置子命令和/或配置变量名称的自动补全。
显示简短的帮助信息
显示此配置变量的当前值。如果没有指定 KEY，则显示所有子命令和配置变量。
示例
o conf shell如果 KEY 以斜杠开头和结尾，则中间的字符串将被视为正则表达式，并且只显示与该正则表达式匹配的键。
示例
o conf /color/将配置变量 KEY 设置为 VALUE。空字符串可以在 shell 中像往常一样用 '' 或 "" 指定。
示例
o conf wget /usr/bin/wget如果配置变量名称以 list 结尾，则它是一个列表。o conf KEY shift 删除列表的第一个元素，o conf KEY pop 删除列表的最后一个元素。o conf KEYS unshift LIST 将一个值列表添加到列表的开头，o conf KEYS push LIST 将一个值列表添加到列表的末尾。
同样，o conf KEY splice LIST 将 LIST 传递给相应的 splice 命令。
最后，任何其他参数列表都被视为 KEY 变量的新列表值，并丢弃先前值。
示例
o conf urllist unshift http://cpan.dev.local/CPAN
o conf urllist splice 3 1
o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org将所有配置变量恢复到保存的配置文件中的状态。
将所有配置变量保存到当前配置文件（CPAN/Config.pm 或 CPAN/MyConfig.pm，在启动时加载）。
配置对话框可以在以后的任何时间再次启动，方法是在 CPAN shell 中发出 o conf init 命令。可以通过发出 o conf init WORD 来运行配置对话框的子集，其中 WORD 是任何有效的配置变量或正则表达式。
以下键在哈希引用 $CPAN::Config 中当前定义
allow_installing_module_downgrades
allow or disallow installing module downgrades
allow_installing_outdated_dists
allow or disallow installing modules that are
indexed in the cpan index pointing to a distro
with a higher distro-version number
applypatch path to external prg
auto_commit commit all changes to config variables to disk
build_cache size of cache for directories to build modules
build_dir locally accessible directory to build modules
build_dir_reuse boolean if distros in build_dir are persistent
build_requires_install_policy
to install or not to install when a module is
only needed for building. yes|no|ask/yes|ask/no
bzip2 path to external prg
cache_metadata use serializer to cache metadata
check_sigs if signatures should be verified
cleanup_after_install
remove build directory immediately after a
successful install and remember that for the
duration of the session
colorize_debug Term::ANSIColor attributes for debugging output
colorize_output boolean if Term::ANSIColor should colorize output
colorize_print Term::ANSIColor attributes for normal output
colorize_warn Term::ANSIColor attributes for warnings
commandnumber_in_prompt
boolean if you want to see current command number
commands_quote preferred character to use for quoting external
commands when running them. Defaults to double
quote on Windows, single tick everywhere else;
can be set to space to disable quoting
connect_to_internet_ok
whether to ask if opening a connection is ok before
urllist is specified
cpan_home local directory reserved for this package
curl path to external prg
dontload_hash DEPRECATED
dontload_list arrayref: modules in the list will not be
loaded by the CPAN::has_inst() routine
ftp path to external prg
ftp_passive if set, the environment variable FTP_PASSIVE is set
for downloads
ftp_proxy proxy host for ftp requests
ftpstats_period max number of days to keep download statistics
ftpstats_size max number of items to keep in the download statistics
getcwd see below
gpg path to external prg
gzip location of external program gzip
halt_on_failure stop processing after the first failure of queued
items or dependencies
histfile file to maintain history between sessions
histsize maximum number of lines to keep in histfile
http_proxy proxy host for http requests
inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
after this many seconds inactivity. Set to 0 to
disable timeouts.
index_expire refetch index files after this many days
inhibit_startup_message
if true, suppress the startup message
keep_source_where directory in which to keep the source (if we do)
load_module_verbosity
report loading of optional modules used by CPAN.pm
lynx path to external prg
make location of external make program
make_arg arguments that should always be passed to 'make'
make_install_make_command
the make command for running 'make install', for
example 'sudo make'
make_install_arg same as make_arg for 'make install'
makepl_arg arguments passed to 'perl Makefile.PL'
mbuild_arg arguments passed to './Build'
mbuild_install_arg arguments passed to './Build install'
mbuild_install_build_command
command to use instead of './Build' when we are
in the install stage, for example 'sudo ./Build'
mbuildpl_arg arguments passed to 'perl Build.PL'
ncftp path to external prg
ncftpget path to external prg
no_proxy don't proxy to these hosts/domains (comma separated list)
pager location of external program more (or any pager)
password your password if you CPAN server wants one
patch path to external prg
patches_dir local directory containing patch files
perl5lib_verbosity verbosity level for PERL5LIB additions
plugin_list list of active hooks (see Plugin support above
and the CPAN::Plugin module)
prefer_external_tar
per default all untar operations are done with
Archive::Tar; by setting this variable to true
the external tar command is used if available
prefer_installer legal values are MB and EUMM: if a module comes
with both a Makefile.PL and a Build.PL, use the
former (EUMM) or the latter (MB); if the module
comes with only one of the two, that one will be
used no matter the setting
prerequisites_policy
what to do if you are missing module prerequisites
('follow' automatically, 'ask' me, or 'ignore')
For 'follow', also sets PERL_AUTOINSTALL and
PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" if
not already set
prefs_dir local directory to store per-distro build options
proxy_user username for accessing an authenticating proxy
proxy_pass password for accessing an authenticating proxy
pushy_https use https to cpan.org when possible, otherwise use http
to cpan.org and issue a warning
randomize_urllist add some randomness to the sequence of the urllist
recommends_policy whether recommended prerequisites should be included
scan_cache controls scanning of cache ('atstart', 'atexit' or 'never')
shell your favorite shell
show_unparsable_versions
boolean if r command tells which modules are versionless
show_upload_date boolean if commands should try to determine upload date
show_zero_versions boolean if r command tells for which modules $version==0
suggests_policy whether suggested prerequisites should be included
tar location of external program tar
tar_verbosity verbosity level for the tar command
term_is_latin deprecated: if true Unicode is translated to ISO-8859-1
(and nonsense for characters outside latin range)
term_ornaments boolean to turn ReadLine ornamenting on/off
test_report email test reports (if CPAN::Reporter is installed)
trust_test_report_history
skip testing when previously tested ok (according to
CPAN::Reporter history)
unzip location of external program unzip
urllist arrayref to nearby CPAN sites (or equivalent locations)
urllist_ping_external
use external ping command when autoselecting mirrors
urllist_ping_verbose
increase verbosity when autoselecting mirrors
use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
use_sqlite use CPAN::SQLite for metadata storage (fast and lean)
username your username if you CPAN server wants one
version_timeout stops version parsing after this many seconds.
Default is 15 secs. Set to 0 to disable.
wait_list arrayref to a wait server to try (See CPAN::WAIT)
wget path to external prg
yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode
yaml_module which module to use to read/write YAML files您可以在 cpan shell 中使用 o conf 或 o conf init 命令交互式地设置和查询这些选项，如下所示。
o conf <标量选项>打印标量选项的当前值
o conf <标量选项> <值>将标量选项的值设置为值
o conf <列表选项>以 MakeMaker 的 neatvalue 格式打印列表选项的当前值。
o conf <列表选项> [shift|pop]在列表选项变量中移位或弹出数组
o conf <列表选项> [unshift|push|splice] <列表>像相应的 perl 命令一样工作。
为匹配的变量运行交互式配置对话框。如果没有参数，则对所有支持的配置变量运行对话框。要指定 MATCH，参数必须用斜杠括起来。
示例
o conf init ftp_passive ftp_proxy
o conf init /color/注意：这种设置配置变量的方法通常比手册页提供更多关于变量功能的解释。
CPAN.pm 经常更改当前工作目录，并且需要确定自己的当前工作目录。默认情况下，它使用 Cwd::cwd，但如果由于某种原因它在您的系统上不起作用，请根据下表配置替代方案
调用 Cwd::cwd
调用 Cwd::getcwd
调用 Cwd::fastcwd
调用 Cwd::getdcwd
调用外部命令 cwd。
urllist 参数是根据 RFC 1738 的 URL。如果您的 URL 不符合标准，我们会进行一些猜测，但如果您在使用 file URL 时遇到问题，请尝试使用正确的格式。要么
file://localhost/whatever/ftp/pub/CPAN/或者
file:///home/ftp/pub/CPAN/配置表中的urllist参数包含用于下载的 URL 列表。如果列表中包含任何file URL，CPAN 始终会优先尝试这些 URL。此功能对索引文件被禁用。因此，对于包含 CPAN 内容的 CD-ROM 所有者，建议：在 urllist 的末尾包含您的本地（可能已过时）CD-ROM 作为file URL，例如：
o conf urllist push file://localhost/CDROM/CPAN然后，CPAN.pm 将从 urllist 开头的 CPAN 站点之一获取索引文件。之后，它将检查每个模块，以查看是否存在最新版本的本地副本。
urllist 的另一个特点是，我们成功从中获取最后一个文件的站点会自动获得一个优先级标记，并在下次请求时作为第一个站点尝试。因此，如果您在运行时添加一个新站点，先前优先的站点可能会再次被尝试。这意味着，如果您想禁止在下次传输中使用某个站点，则必须将其从 urllist 中显式删除。
如果您安装了 YAML.pm（或在yaml_module中配置的其他 YAML 模块），CPAN.pm 会收集有关最近下载的一些统计数据。您可以使用hosts命令查看统计数据，或直接查看cpan_home目录中的FTPstats.yml文件。
为了获得一些有趣的统计数据，建议设置randomize_urllist；这会在 URL 选择中引入一定程度的随机性。
requires 和 build_requires 依赖关系声明从 CPAN.pm 版本 1.88_51 开始，根据配置变量build_requires_install_policy，分布式声明为build_requires 的模块将被不同地对待。通过将build_requires_install_policy设置为no，这样的模块不会被安装。它只会被构建和测试，然后保留在已测试但未安装的模块列表中。因此，它在依赖模块的构建过程中可用，方法是将blib/arch和blib/lib目录的路径集成到环境变量 PERL5LIB 中。如果build_requires_install_policy设置为yes，则声明为requires和build_requires的模块都将被同等对待。通过设置为ask/yes或ask/no，CPAN.pm 会询问用户并相应地设置默认值。
allow_installing_* 参数在 make 阶段进行评估。如果设置为 yes，则允许测试和安装当前发行版，否则没有影响。如果设置为 no，则可能会中止构建（阻止测试和安装），具体取决于 blib/ 目录的内容。blib/ 目录是包含所有将在 install 阶段安装的文件的目录。
allow_installing_outdated_dists 将 blib/ 目录与 CPAN 索引进行比较。如果它在 blib/ 目录中找到根据索引属于不同发行版的任何内容，它将中止当前构建。
allow_installing_module_downgrades 将 blib/ 目录与已安装的模块进行比较，实际上是它们由 ExtUtils::MakeMaker 或等效工具确定的版本号。如果要安装的模块会降级已安装的模块，则当前构建将中止。
当 distroprefs 文档要求通过 goto 安装过时的发行版，而 allow_installing_outdated_dists 禁止这样做时，就会出现一个有趣的转折。如果没有额外的规定，这将使 allow_installing_outdated_dists 获胜，而 distroprefs 失败。因此，在这种情况下，正确的安排是为 goto 指向的发行版编写第二个 distroprefs 文档，并在其中覆盖 cpanconfig。例如：
---
match:
distribution: "^MAUKE/Keyword-Simple-0.04.tar.gz"
goto: "MAUKE/Keyword-Simple-0.03.tar.gz"
---
match:
distribution: "^MAUKE/Keyword-Simple-0.03.tar.gz"
cpanconfig:
allow_installing_outdated_dists: yes(注意：此功能已在 CPAN.pm 1.8854 中引入)
CPAN 上的发行版通常按照我们所说的 CPAN 格言行事。或者自从 Module::Build 出现以来，我们应该谈论两个格言
perl Makefile.PL perl Build.PL
make ./Build
make test ./Build test
make install ./Build install但是，有些模块无法使用此格言构建。它们试图通过环境、额外参数或交互方式从用户那里获取一些额外数据，从而干扰大型捆绑包（如 Phalanx100）或具有许多依赖项的模块（如 Plagger）的安装。
CPAN.pm 的 distroprefs 系统通过允许用户在 YAML 文件中指定额外信息和配方来解决此问题，从而：
向四个命令之一传递额外的参数，
设置环境变量
实例化一个 Expect 对象，该对象从控制台读取，等待一些正则表达式并输入一些答案
临时覆盖各种 CPAN.pm 配置变量
指定原始维护者遗漏的依赖项
完全禁用对象的安装
请参阅 CPAN.pm 发行版中 distroprefs/ 目录中的 YAML 和 Data::Dumper 文件以获取示例。
YAML 文件本身必须具有 .yml 扩展名；所有其他文件都被忽略（两个例外请参见下面的 回退 Data::Dumper 和 Storable）。包含目录可以在 CPAN.pm 中的 prefs_dir 配置变量中指定。在 CPAN shell 中尝试 o conf init prefs_dir 来设置和激活 distroprefs 系统。
每个 YAML 文件都可以根据 YAML 规范包含任意文档，并且每个文档都被视为可以指定单个发行版处理方式的实体。
文件名可以任意选择；CPAN.pm 始终读取所有文件（按字母顺序）并以 match 为键（请参见下面的 语言规范）作为包含匹配条件的哈希引用，这些条件决定当前发行版是否与 YAML 文档匹配。
如果您的配置的 yaml_module 和 YAML.pm 都没有安装，CPAN.pm 会回退到使用 Data::Dumper 和 Storable，并在 prefs_dir 目录中查找扩展名为 .dd 或 .st 的文件。这些文件预计将包含一个或多个哈希引用。对于 Data::Dumper 生成的文件，预计通过定义 $VAR1、$VAR2 等来完成。YAML shell 将使用以下命令生成这些文件
ysh < somefile.yml > somefile.dd对于 Storable 文件，规则是它们必须构建为 Storable::retrieve(file) 返回一个数组引用，并且数组元素分别代表一个 distropref 对象。从 YAML 的转换将如下所示
perl -MYAML=LoadFile -MStorable=nstore -e '
@y=LoadFile(shift);
nstore(\@y, shift)' somefile.yml somefile.st在引导情况下，通常只需将几个 YAML 文件转换为 Data::Dumper 即可，例如 YAML::Syck、YAML.pm 和 Expect.pm 等关键模块。如果您更喜欢 Storable 而不是 Data::Dumper，请记住提取一个 Storable 版本，该版本写入的格式比所有其他需要读取它们的 Storable 版本都旧。
以下示例包含所有支持的关键字和结构，除了 eexpect，它可以代替 expect 使用。
---
comment: "Demo"
match:
module: "Dancing::Queen"
distribution: "^CHACHACHA/Dancing-"
not_distribution: "\.zip$"
perl: "/usr/local/cariba-perl/bin/perl"
perlconfig:
archname: "freebsd"
not_cc: "gcc"
env:
DANCING_FLOOR: "Shubiduh"
disabled: 1
cpanconfig:
make: gmake
pl:
args:
- "--somearg=specialcase"
env: {}
expect:
- "Which is your favorite fruit"
- "apple\n"
make:
args:
- all
- extra-all
env: {}
expect: []
commandline: "echo SKIPPING make"
test:
args: []
env: {}
expect: []
install:
args: []
env:
WANT_TO_INSTALL: YES
expect:
- "Do you really want to install"
- "y\n"
patches:
- "ABCDE/Fedcba-3.14-ABCDE-01.patch"
depends:
configure_requires:
LWP: 5.8
build_requires:
Test::Exception: 0.25
requires:
Spiffy: 0.30每个 YAML 文档都代表一个单一的哈希引用。此哈希中有效的键如下所示
注释
临时覆盖各种CPAN.pm配置变量。
支持：build_requires_install_policy、check_sigs、make、make_install_make_command、prefer_installer、test_report。如果您需要支持其他变量，请将其作为错误报告。
所有三种类型，即configure_requires、build_requires和requires，都以META.yml规范中指定的方式支持。当前实现将指定的依赖项合并到包维护者声明的依赖项中。在未来的实现中，这可能会更改为覆盖原始声明。
指定此发行版将完全不处理。
处理META.yml中optional_features的实验性实现。仍然需要与安装程序软件协调，目前仅适用于声明dynamic_config=0的META.yml。谨慎使用。
要安装的委托发行版的规范名称。当新版本虽然自身测试正常，但破坏了其他东西，或者开发者发布的版本或分支已经上传，并且比最后一个发布的版本更好时，这很有用。
CPAN 咒语的make install或./Build install阶段的处理指令。请参阅下面的处理指令。
CPAN 咒语的make或./Build阶段的处理指令。请参阅下面的处理指令。
一个具有一个或多个键的哈希引用，这些键是distribution、module、perl、perlconfig和env，它们指定文档是否针对特定的CPAN发行版或安装。以not_为前缀的键会否定相应的匹配。
相应的键值被解释为正则表达式。与distribution相关的键将与规范的发行版名称匹配，例如“AUTHOR/Foo-Bar-3.14.tar.gz”。
与module相关的键将与发行版中所有模块匹配，直到有一个模块匹配。
与perl相关的键将与$^X匹配（但使用绝对路径）。
与 perlconfig 关联的值本身是一个哈希引用，它与 Config.pm 模块中 %Config::Config 哈希中的对应值匹配。以 not_ 为前缀的键会否定相应的匹配。
与 env 关联的值本身是一个哈希引用，它与 %ENV 哈希中的对应值匹配。以 not_ 为前缀的键会否定相应的匹配。
如果指定了多个 module、distribution 等限制，则必须所有单独计算的匹配值的结果都匹配。如果是这样，YAML 文档表示的哈希引用将作为当前发行版的首选项结构返回。
CPAN 或本地磁盘上的补丁数组，需要通过外部补丁程序按顺序应用。如果 -p 参数的值为 0 或 1，则通过预先读取补丁来确定。每个补丁的路径要么是本地文件系统上的绝对路径，要么相对于 patches_dir 配置变量中指定的补丁目录，要么采用规范发行版名称的格式。有关示例，请参阅 CPAN.pm 发行版中的 distroprefs/ 目录（这些示例默认情况下不会安装）。
注意：如果安装了 applypatch 程序并且 CPAN::Config 知道它，并且 makepatch 程序编写了补丁，那么 CPAN.pm 将允许 applypatch 应用补丁。makepatch 和 applypatch 都可以在 CPAN 的 JV/makepatch-* 发行版中找到。
CPAN 咒语的 perl Makefile.PL 或 perl Build.PL 阶段的处理指令。请参阅下面的“处理指令”。
CPAN 咒语的 make test 或 ./Build test 阶段的处理指令。请参阅下面的“处理指令”。
要添加到命令行的参数
通过 system() 运行的完整命令行。在执行期间，环境变量 PERL 设置为 $^X（但使用绝对路径）。如果指定了 commandline，则不会使用 args。
扩展 expect。这是一个哈希引用，包含四个允许的键：mode、timeout、reuse 和 talk。
您必须安装 Expect 模块才能使用 eexpect。CPAN.pm 不会为您安装它。
mode 可以具有以下值：deterministic（所有问题都按写下的顺序出现）和 anyorder（问题可以按任何顺序出现）。默认模式为 deterministic。
timeout 表示以秒为单位的超时时间。浮点型超时时间也是可以的。当 mode=deterministic 时，超时时间表示每个问题的超时时间；当 mode=anyorder 时，超时时间表示从流或问题接收到的每个字节的超时时间。
talk 是一个包含交替出现的问题和答案的数组的引用。问题是正则表达式，答案是字面字符串。Expect 模块会监视从外部程序执行（perl Makefile.PL、perl Build.PL、make 等）开始的流。
对于 mode=deterministic，CPAN.pm 会在流匹配正则表达式后立即注入相应的答案。
对于 mode=anyorder，CPAN.pm 会在输入流中下一个字节的超时时间到达后立即回答问题。在这种模式下，您可以使用 reuse 参数来决定问题-答案对在使用后会发生什么。在默认情况下（reuse=0），它将从数组中删除，避免意外再次使用。如果您想多次回答问题 Do you really want to do that，那么它必须在数组中至少包含您希望给出此答案的次数。将参数 reuse 设置为 1 使这种重复变得不必要。
在命令执行期间要设置的环境变量
您必须安装 Expect 模块才能使用 expect。CPAN.pm 不会为您安装它。
expect: <array> 是此 eexpect 的简写形式
eexpect:
mode: deterministic
timeout: 15
talk: <array>Kwalify 进行模式验证如果您安装了 Kwalify 模块（它是 Bundle::CPANxxl 的一部分），那么您的所有 distroprefs 文件都会被检查语法正确性。
CPAN.pm 附带了一组示例 YAML 文件。请注意，这些只是示例，不应在没有谨慎的情况下使用，因为它们无法满足所有人的目的。毕竟，提出问题的包的作者有提问的必要，因此您应该注意他们的问题，并根据您的环境和需求调整示例。我已经提醒过您了：-)
如果您不进入 shell，则 shell 命令既可用作方法（CPAN::Shell->install(...)），也可用作调用包中的函数（install(...)）。在调用低级命令之前，有必要初始化您需要的 CPAN 组件，例如：
CPAN::HandleConfig->load;
CPAN::Shell::setup_output;
CPAN::Index->reload;高级命令会自动执行此类初始化。
目前只有一个类具有稳定的接口 - CPAN::Shell。所有在 CPAN shell 中可用的命令都是类 CPAN::Shell 的方法。命令行上的参数作为参数传递给方法。
因此，如果您以 shell 命令为例
notest install A B C实际执行的命令是
CPAN::Shell->notest("install","A","B","C");每个生成模块列表的命令（r、autobundle、u）也会返回列表中所有模块的 ID 列表。
程序中所有可用对象的 ID 都是字符串，可以使用 CPAN::Shell->expand("Module",@things) 方法扩展为相应的真实对象。Expand 根据给定的 @things 参数返回一个 CPAN::Module 对象列表。在标量上下文中，它只返回列表的第一个元素。
与 expand 类似，但返回适当类型的对象，即捆绑包的 CPAN::Bundle 对象、模块的 CPAN::Module 对象和发行版的 CPAN::Distribution 对象。注意：它不会扩展到 CPAN::Author 对象。
这使程序员能够执行将 shell 中可用的功能组合在一起的操作。
# install everything that is outdated on my disk:
perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
# install my favorite programs if necessary:
for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
CPAN::Shell->install($mod);
}
# list all modules on my disk that have no VERSION number
for $mod (CPAN::Shell->expand("Module","/./")) {
next unless $mod->inst_file;
# MakeMaker convention for undefined $VERSION:
next unless $mod->inst_version eq "undef";
print "No VERSION in ", $mod->id, "\n";
}
# find out which distribution on CPAN contains a module:
print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file或者，如果您想安排一个cron作业来监视CPAN，您可以列出所有需要更新的模块。首先是一个快速而肮脏的方法
perl -e 'use CPAN; CPAN::Shell->r;'如果您不希望所有模块都更新时有任何输出，请解析上述命令的输出以查找正则表达式/modules are up to date/，并且仅在不匹配时才决定发送输出。
如果您更喜欢以编程的方式在一个单一进程中完成它，那么以下内容可能更适合您
# list all modules on my disk that have newer versions on CPAN
for $mod (CPAN::Shell->expand("Module","/./")) {
next unless $mod->inst_file;
next if $mod->uptodate;
printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
$mod->id, $mod->inst_version, $mod->cpan_version;
}如果每天输出太多，您可能只想监视三个模块。您可以写
for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")) {作为第一行。或者您可以将上述一些技巧结合起来
# watch only for a new mod_perl module
$mod = CPAN::Shell->expand("Module","mod_perl");
exit if $mod->uptodate;
# new mod_perl arrived, let me know all update recommendations
CPAN::Shell->r;返回作者的单行描述
返回作者的多行描述
返回作者的电子邮件地址
返回作者的姓名
fullname 的别名
返回包的单行描述
返回包的多行描述
递归地对包中包含的所有项目运行clean方法。
返回一个捆绑包中包含的对象 ID 列表。关联的对象可能是捆绑包、模块或发行版。
强制 CPAN 执行一项它通常会拒绝执行的任务。force 接受一个要调用的方法名称和任意数量的附加参数作为参数，这些参数应该传递给调用的方法。对象的内部会进行必要的更改，以便 CPAN.pm 不拒绝采取该操作。force 会递归地传递给所有包含的对象。另请参阅上面关于 force 和 fforce pragma 的部分。
递归地对捆绑包中包含的所有项目运行 get 方法
返回捆绑包在 @INC 或 $CPAN::Config->{cpan_home} 中安装的最高版本。请注意，这与 CPAN::Module::inst_file 不同。
与 CPAN::Bundle::inst_file 相似，但返回 $VERSION
如果捆绑包本身及其所有成员都已更新，则返回 1。
递归地对捆绑包中包含的所有项目运行 install 方法
递归地对捆绑包中包含的所有项目运行 make 方法
递归地对捆绑包中包含的所有项目运行 readme 方法
递归地对捆绑包中包含的所有项目运行 test 方法
返回发行版的单行描述
返回发行版的多行描述
返回上传此发行版的维护者的 CPAN::Author 对象
返回形如 "AUTHORID/TARBALL" 的字符串，其中 AUTHORID 是作者的 PAUSE ID，TARBALL 是发行版文件名。
返回发行版文件名，不含任何归档后缀。例如 "Foo-Bar-0.01"
更改到发行版解压缩的目录，并在其中运行 make clean。
返回发行版文件中包含的模块的 ID 列表。仅适用于 02packages.details.txt.gz 文件中列出的发行版。这通常意味着只涵盖发行版的最新版本。
更改到发行版解压缩的目录，并在其中运行类似以下内容的命令
cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version。
返回此发行版解压缩到的目录。
强制 CPAN 执行一项它通常会拒绝执行的任务。force 接受一个要调用的方法名和任意数量的附加参数作为参数，这些参数应该传递给调用的方法。对象的内部会进行必要的更改，以便 CPAN.pm 不再拒绝执行该操作。另请参阅上面关于 force 和 fforce 编译指示的章节。
从 CPAN 下载发行版并解压缩。如果发行版已在当前会话中下载并解压缩，则不执行任何操作。
更改到发行版解压缩的目录，并在其中运行外部命令 make install。如果尚未运行 make，则会先运行它。无论如何都会发出 make test，如果失败，则会取消安装。可以通过让 force 为您运行 install 来避免取消。
此安装方法只有在没有依赖项的情况下才能安装发行版。要安装一个对象及其所有依赖项，请使用 CPAN::Shell->install。
请注意，install() 不会返回有意义的值。请参阅 uptodate()。
如果此发行版文件似乎是 perl 发行版，则返回 1。通常，这是仅从文件名推断出来的，但 CPAN 的索引可以包含提示，以便对其他文件名也返回 true。
更改解包分发包的目录并打开一个子 shell。退出子 shell 返回。
首先运行 get 方法以确保分发包已下载并解包。更改解包分发包的目录并运行外部命令 perl Makefile.PL 或 perl Build.PL 以及 make。
下载与分发包关联的文件的 pod 文档（HTML 格式），并通过 $CPAN::Config->{lynx} 中指定的外部命令 lynx 运行。如果 lynx 不可用，则使用外部命令 html2text 将其转换为纯文本，并通过 $CPAN::Config->{pager} 中指定的分页器运行。
返回用户在 prefs_dir/ 目录中存放的第一个匹配的 YAML 文件的哈希引用。第一个成功的匹配获胜。prefs_dir/ 中的文件按字母顺序处理，规范的分发包名称（例如 AUTHOR/Foo-Bar-3.14.tar.gz）与存储在 $root->{match}{distribution} 属性值中的正则表达式匹配。此外，分发包中包含的所有模块名称都与 $root->{match}{module} 属性值中的正则表达式匹配。这两个匹配值进行 AND 操作。这两个属性都是可选的。
返回分发包宣布的 requires 和 build_requires 元素的哈希引用。这些元素可以通过 META.yml（如果权威）声明，也可以在运行 Build.PL 后存放在 ./_build/prereqs 文件中，或者在运行 Makfile.PL 后作为 PREREQ_PM 哈希写入生成的 Makefile 中的注释。注意：此方法仅在尝试 make 分发包后才有效。否则返回 undef。
下载与发行版关联的 README 文件，并通过 $CPAN::Config->{pager} 中指定的分页器运行它。
从 www.cpantesters.org 下载此发行版的报告数据，并显示其中的一部分。
将此发行版的 META.yml 内容作为哈希引用返回。注意：仅在尝试过 make 发行版后才有效。否则返回 undef。如果 META.yml 的内容不是权威的，也会返回 undef。（关于什么内容是权威的规则仍在不断变化。）
更改到发行版解压缩的目录，并在该目录中运行 make test。
如果发行版中包含的所有模块都是最新的，则返回 1。依赖于 containsmods。
强制重新加载所有索引。
如果索引没有在 $CPAN::Config->{index_expire} 天内读取，则重新加载所有索引。
CPAN::Author、CPAN::Bundle、CPAN::Module 和 CPAN::Distribution 继承此方法。它打印与对象关联的数据结构。对调试很有用。注意：数据结构被认为是内部的，因此可能会在未经通知的情况下发生更改。
以四列的形式返回模块的一行描述：第一列包含单词 Module，第二列包含一个字符：如果此模块已安装且是最新的，则为等号，如果此模块已安装但可以升级，则为小于号，如果模块未安装，则为空格。第三列是模块的名称，第四列给出维护者或发行版信息。
返回模块的多行描述
对与该模块关联的发行版进行清理。
返回与该模块关联的 CPAN 上的文件名。
返回该模块在 CPAN 上可用的最新版本。
对与该模块关联的发行版运行 cvs_import。
返回该模块的 44 个字符的描述。仅适用于模块列表中列出的模块（CPAN/modules/00modlist.long.html 或 00modlist.long.txt.gz）。
返回包含该模块当前版本的 CPAN::Distribution 对象。
返回一个哈希引用。哈希的键是字母 D、S、L、I 和 <P>，分别代表开发状态、支持级别、语言、接口和公共许可证。DSLIP 状态的数据由 pause.perl.org 在作者注册其命名空间时收集。5 个哈希元素的值是一个字符的单词，其含义在下面的表格中描述。还有 5 个哈希元素 DV、SV、LV、IV 和 <PV>，它们承载 5 个状态变量的更详细的值。
其中“DSLIP”字符具有以下含义
D - Development Stage (Note: *NO IMPLIED TIMESCALES*):
i - Idea, listed to gain consensus or as a placeholder
c - under construction but pre-alpha (not yet released)
a/b - Alpha/Beta testing
R - Released
M - Mature (no rigorous definition)
S - Standard, supplied with Perl 5
S - Support Level:
m - Mailing-list
d - Developer
u - Usenet newsgroup comp.lang.perl.modules
n - None known, try comp.lang.perl.modules
a - abandoned; volunteers welcome to take over maintenance
L - Language Used:
p - Perl-only, no compiler needed, should be platform independent
c - C and perl, a C compiler will be needed
h - Hybrid, written in perl with optional C code, no compiler needed
+ - C++ and perl, a C++ compiler will be needed
o - perl and another language other than C or C++
I - Interface Style
f - plain Functions, no references used
h - hybrid, object and function interfaces available
n - no interface at all (huh?)
r - some use of unblessed References or ties
O - Object oriented using blessed references and/or inheritance
P - Public License
p - Standard-Perl: user may choose between GPL and Artistic
g - GPL: GNU General Public License
l - LGPL: "GNU Lesser General Public License" (previously known as
"GNU Library General Public License")
b - BSD: The BSD License
a - Artistic license alone
2 - Artistic license 2.0 or later
o - open source: approved by www.opensource.org
d - allows distribution without restrictions
r - restricted distribution
n - no license at all强制 CPAN 执行一项它通常会拒绝执行的任务。Force 接受一个要调用的方法名称和任意数量的附加参数作为参数，以传递给该方法。对象的内部机制会进行必要的更改，以便 CPAN.pm 不会拒绝采取该操作。另请参阅上面关于 force 和 fforce 编译指示的章节。
对与该模块关联的发行版运行 get。
返回在 @INC 中找到的模块的文件名。报告找到的第一个文件，就像 perl 本身在找到模块后停止搜索 @INC 一样。
返回在 PERL5LIB 或 @INC 中找到的模块的文件名。 报告找到的第一个文件。 此方法相对于 inst_file 的优势在于，它包含了已测试但尚未安装的模块，因为 PERL5LIB 会跟踪已测试的模块。
以可读格式返回已安装模块的版本号。
以可读格式返回可用模块的版本号。
对与该模块关联的发行版运行 install。
更改到与该模块关联的发行版已解压缩的目录，并在其中打开一个子 shell。 退出子 shell 会返回。
对与该模块关联的发行版运行 make。
如果模块已安装，则查看模块的手册页，读取标题并返回它。 此外，如果模块已在此会话中下载，则即使它尚未安装，也会对下载的模块执行等效操作。
对该模块运行 perldoc。
对与该模块关联的发行版运行 readme。
调用关联的发行版对象上的 reports() 方法。
对与该模块关联的发行版运行 test。
如果模块已安装且是最新的，则返回 1。
返回模块的作者 ID。
目前，缓存管理器只跟踪构建目录（$CPAN::Config->{build_dir}）。它是一个简单的 FIFO 机制，一旦所有目录的大小超过 $CPAN::Config->{build_cache}（以 MB 为单位），就会删除 build_dir 下的完整目录。此缓存的内容可用于以后手动执行的重新安装，但 CPAN 本身永远不会信任它。这是因为用户可能会使用这些目录在不同的架构上构建模块。
还有一个目录（$CPAN::Config->{keep_source_where}），用于保存原始发行版文件。此目录不受缓存管理器管理，必须由用户控制。如果您选择将同一个目录作为 build_dir 和 keep_source_where 目录，那么您的源代码将使用相同的 FIFO 机制删除。
捆绑包只是一个 Bundle:: 命名空间中的 Perl 模块，它不定义任何函数或方法。它通常只包含文档。
它以一个 Perl 模块的包声明和一个 $VERSION 变量开始。之后，pod 部分看起来与其他 pod 一样，唯一的区别是存在一个以（逐字）开头的特殊 pod 部分
=head1 CONTENTS在此 pod 部分中，每行都遵循以下格式
Module_Name [Version_String] [- optional text]唯一必需的部分是第一个字段，即模块的名称（例如 Foo::Bar，即不是发行版文件的名称）。该行的其余部分是可选的。注释部分由一个连字符分隔，就像手册页标题一样。
捆绑包的发行应该遵循与其他发行版相同的约定。
捆绑包在 CPAN 包中得到特殊处理。如果您说“安装 Bundle::Tkkit”（假设存在这样的捆绑包），CPAN 将安装 pod 的 CONTENTS 部分中的所有模块。您可以通过将符合规范的 Bundle 文件放置到您的 @INC 路径中的某个位置来在本地安装自己的捆绑包。shell 接口中可用的 autobundle() 命令会为您执行此操作，方法是将所有当前安装的模块包含在一个快照捆绑包文件中。
CPAN 程序试图尽可能少的依赖，以便用户可以在恶劣的环境中使用它。它在环境提供更多功能时运行得更好。例如，如果您在 CPAN shell 中尝试
install Bundle::CPAN或者
install Bundle::CPANxxl您会发现 shell 比之前的裸 shell 更方便。
如果您有 CPAN 的本地镜像，并且可以使用 "file:" URL 访问所有文件，那么您只需要一个比 perl5.003 更晚的 perl 来运行此模块。否则强烈建议使用 Net::FTP。对于非 UNIX 系统，或者如果您的最近 CPAN 站点与非 ftp: 的 URL 相关联，则可能需要 LWP。
如果您既没有 Net::FTP 也没有 LWP，则有一个回退机制用于外部 ftp 命令或外部 lynx 命令。
此模块假设 CPAN 上的所有包
以易于解析的方式声明其 $VERSION 变量。这个先决条件几乎无法放宽，因为将所有包加载到正在运行的程序中仅仅为了确定 $VERSION 变量会消耗太多内存。目前所有处理版本的程序都使用类似以下的方法
perl -MExtUtils::MakeMaker -le \
'print MM->parse_version(shift)' filename如果您是包的作者，并且想知道您的 $VERSION 是否可以解析，请尝试上述方法。
作为压缩或 gzip 压缩的 tar 文件或 zip 文件，并包含 Makefile.PL 或 Build.PL（好吧，我们尝试处理更多，但没有多少热情）。
调试此模块比有点复杂，因为会受到 CPAN 上生成索引的软件、CPAN 上的镜像过程、打包、配置、同步，甚至（喘不过气来！）CPAN.pm 模块本身的 bug 的干扰。
为了在交互模式下调试 CPAN.pm 本身的代码，可以使用以下方法为 CPAN.pm 中的大多数包打开一些调试辅助工具
为包设置调试模式。
取消设置包的调试模式。
为所有包打开调试。
直接设置调试包。请注意，o debug 0 会关闭调试。
一个看似成功的策略是将reload cpan和调试开关结合起来。在 shell 中运行时添加一个新的调试语句，然后执行reload cpan，就可以立即看到新的调试消息，而不会丢失当前上下文。
o debug 不带参数会列出有效的包名和当前处于调试模式的包集。o debug 内置了补全支持。
对于 CPAN 数据的调试，可以使用dump命令，它接受与 make/test/install 相同的参数，并输出每个对象的 Data::Dumper 转储。如果参数看起来像一个 Perl 变量，并且包含$、@或%，则会对其进行 eval() 并直接传递给 Data::Dumper。
CPAN.pm 即使没有网络访问也能正常工作。如果您维护的机器完全没有联网，您应该考虑使用file: URL。您需要先将模块收集到某个地方。因此，您可以使用 CPAN.pm 在联网机器上将所有需要的模块组合在一起。然后将 $CPAN::Config->{keep_source_where}（但不是 $CPAN::Config->{build_dir}）目录复制到软盘上。这个软盘就像一个个人 CPAN。非联网机器上的 CPAN.pm 可以很好地使用这个软盘。另请参阅下面关于 CD-ROM 支持的段落。
如果模块已安装，则返回 true。用于将所有被认为是可选的模块加载到正在运行的 CPAN.pm 中。配置变量dontload_list会拦截has_inst()调用，这样即使可选模块可用，也不会加载它。例如，以下命令将阻止加载YAML.pm
cpan> o conf dontload_list push YAML有关详细信息，请参阅源代码。
与has_inst()类似，尝试加载可选库，但如果库不可用，也会退出
如果模块已安装并处于可用状态，则返回 true。仅对少数内部使用的模块有用。有关详细信息，请参阅源代码。
用于表示模块、发行版、作者和捆绑包的所有单例的构造函数。如果对象已存在，此方法将返回该对象；否则，它将调用构造函数。
前端对象的 getter/setter。该方法仅允许对 CPAN.pm 进行子类化。
CPAN.pm 中没有强大的安全层。CPAN.pm 帮助您在机器上安装来自外部的、未屏蔽的、未签名的代码。我们将其与来自网络的校验和进行比较，就像分发文件本身一样。但我们试图让按需添加安全性变得容易。
从 1.77 版本开始，CPAN.pm 能够使用 Module::Signature 验证加密签名模块分发。CPAN 模块可以由其作者签名，从而提供更高的安全性。CPAN 之前使用的简单未签名的 MD5 校验和主要防止意外文件损坏。
您需要安装 Module::Signature，这反过来又要求您至少安装一个 Crypt::OpenPGP 模块或命令行 gpg 工具。
您还需要能够连接到互联网上的公共密钥服务器，例如 pgp.mit.edu，以及它们的端口 11731（HKP 协议）。
配置参数 check_sigs 用于打开或关闭签名检查。
默认情况下，包 CPAN 中的大多数函数都会导出。这样做的原因是，主要用途是用于 cpan shell 或单行命令。
当 CPAN shell 通过 look 命令进入子 shell 时，它会将环境变量 CPAN_SHELL_LEVEL 设置为 1，或者如果该变量已设置，则递增该变量。
当 CPAN 运行时，它会将环境变量 PERL5_CPAN_IS_RUNNING 设置为正在运行的进程的 ID。它还会设置 PERL5_CPANPLUS_IS_RUNNING，以防止可能发生在旧版 Module::Install 中的失控进程。
在运行 perl Makefile.PL 时，环境变量 PERL5_CPAN_IS_EXECUTING 被设置为正在执行的 Makefile.PL 的完整路径。这可以防止使用较新版本的 Module::Install 出现失控进程。
当配置变量 ftp_passive 设置时，所有下载都将在环境变量 FTP_PASSIVE 设置为该值的情况下运行。这通常是一个好主意，因为它会影响基于 Net::FTP 和 LWP 的连接。通过在设置了此环境变量的情况下启动 cpan shell，可以实现相同的效果。对于 Net::FTP 来说，还可以通过运行 libnetcfg 来始终设置被动模式。
如果你维护一个私有的 bundle 定义文件，那么用你最喜欢的模块填充一个新安装的 perl 非常容易。要获得 bundle 定义文件的实用蓝图，可以在 CPAN shell 命令行中使用 autobundle 命令。此命令会为当前 perl 解释器安装的所有模块编写一个 bundle 定义文件。建议只运行一次此命令，然后在私有名称下手动维护该文件，例如 Bundle/my_bundle.pm。使用一个巧妙的 bundle 文件，你就可以简单地说
cpan> install Bundle::my_bundle然后回答几个问题，然后去喝咖啡（甚至可以在另一个城市）。
维护 bundle 定义文件意味着跟踪两件事：依赖关系和交互性。CPAN.pm 有时无法计算依赖关系，因为并非所有模块都正确定义了所有 MakeMaker 属性，因此 bundle 定义文件应尽早指定先决条件。另一方面，许多发行版需要一些交互式配置，这很烦人。因此，你可以在你的私有 bundle 文件中尝试实现的是，将需要配置的包放在文件开头，将温和的包放在后面，这样你就可以在几分钟后出去喝咖啡，让 CPAN.pm 无人看管地继续运行。
感谢 Graham Barr 为以下关于 perl 与各种防火墙配置之间交互的段落做出了贡献。有关防火墙的更多信息，建议查阅 ncftp 程序附带的文档。如果你无法通过简单的 Perl 设置通过防火墙，则可能可以配置 ncftp 使其能够通过防火墙工作。
防火墙可以分为三种基本类型。
当防火墙机器运行一个 web 服务器时，要访问外部世界，你必须通过该 web 服务器进行访问。如果你设置了像 http_proxy 或 ftp_proxy 这样的环境变量，其值为以 http:// 开头的值，或者在你的 web 浏览器中设置了代理信息，那么你就知道你是在 http 防火墙后面运行的。
要使用 perl 访问这些类型的防火墙之外的服务器（即使是 ftp），你需要 LWP 或 HTTP::Tiny。
当防火墙机器运行一个 ftp 服务器时。这种类型的防火墙只允许你访问防火墙之外的 ftp 服务器。这通常通过使用 ftp 连接到防火墙，然后输入一个用户名，例如 "[email protected]" 来完成。
要使用 perl 访问这些类型的防火墙之外的服务器，你需要 Net::FTP。
单向可见性意味着这些防火墙试图对防火墙内部的用户保持隐形。FTP 数据连接通常是通过将您的 IP 地址发送到远程服务器，然后监听返回连接来建立的。但是，由于防火墙的存在，远程服务器将无法连接到您。对于这些类型的防火墙，FTP 连接需要在被动模式下进行。
我能想到两种方法。
如果您能够使用例如 lynx 穿越防火墙，可能使用类似以下命令：
/usr/local/bin/lynx -pscott:tiger那么您将使用以下命令配置 CPAN.pm：
o conf lynx "/usr/local/bin/lynx -pscott:tiger"就是这样。类似地，对于 ncftp 或 ftp，您将配置类似以下内容：
o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"您的结果可能会有所不同...
我安装了模块 X 的新版本，但 CPAN 仍然说我安装了旧版本
您可能确实安装了旧版本。如果模块将自身安装到 @INC 路径中与之前安装位置不同的目录，则可能会发生这种情况。这并不是 CPAN.pm 的问题，您在手动安装模块时也会遇到相同的问题。防止这种行为最简单的方法是在 make install 调用中添加参数 UNINST=1，这就是为什么许多人通过配置永久添加此参数的原因：
o conf make_install_arg UNINST=1那么为什么 UNINST=1 不是默认值呢？
因为有些人对谁可以在 @INC 路径中的哪个位置安装以及谁使用哪个 @INC 数组有明确的期望。在经过精心调整的环境中，UNINST=1 会造成损害。
我想清理我的混乱，并安装一个新的perl以及我拥有的所有模块。我该怎么做呢？
为您的旧perl运行autobundle命令，并选择性地重命名生成的bundle文件（例如Bundle/mybundle.pm），使用Configure选项prefix安装新的perl，例如
./Configure -Dprefix=/usr/local/perl-5.6.78.9使用类似以下命令安装您在第一步中生成的bundle文件
cpan> install Bundle::mybundle您就完成了。
当我使用一个命令安装bundle或多个模块时，输出太多，无法跟踪。
您可能想要配置类似以下内容
o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"以便将STDOUT捕获到文件中，以便以后检查。
我不是root用户，如何在个人目录中安装模块？
从CPAN 1.9463开始，如果您没有权限写入默认的perl库目录，CPAN的配置过程会询问您是否要引导<local::lib>，这使得维护个人perl库目录变得容易。
您应该牢记的另一件事是，当您安装到私有区域时，UNINST参数可能很危险，因为您可能会意外删除其他依赖于该私有区域但未使用该私有区域的模块。
如何获取一个包，解压缩它，并在构建之前进行更改？
看看look (!)命令。
我安装了一个Bundle，并且出现了一些错误。当我重试时，一切都顺利解决了。这可以修复为第一次尝试就成功吗？
造成这种情况的原因是，CPAN在开始时并不知道所有模块的依赖关系。为了决定要安装的额外项目，它只使用META.yml文件或生成的Makefile中找到的数据。未检测到的缺失部分会破坏进程。但很可能是您的Bundle在某些依赖项之后安装了一些先决条件，因此您的第二次尝试能够解决所有问题。请注意，CPAN.pm事先不知道依赖关系树，无法以拓扑排序的方式对要安装的项目队列进行排序。如果所有模块都使用MakeMaker的PREREQ_PM属性或Module::Build的requires节正确声明了先决条件，则它可以完美地解决。对于失败且需要经常安装的bundle，建议手动对Bundle定义文件进行排序。
在我们的内网中，我们有许多用于内部使用的模块。如何将这些模块与CPAN.pm集成，但又不将这些模块上传到CPAN？
看看CPAN::Site模块。
当我运行CPAN的shell时，我收到有关/etc/inputrc（或~/.inputrc）文件中的内容的错误消息。
这些是 readline 问题，只能通过研究您架构上的 readline 配置并相应地调整引用文件来解决。请备份 /etc/inputrc 或 ~/.inputrc 并编辑它们。通常，对某些参数进行无害的更改，例如大写或小写，就可以解决问题。
有些作者的姓名中有奇怪的字符。
CPAN.pm 在内部使用 UTF-8 字符集。如果您的终端期望 ISO-8859-1 字符集，则可以通过在您的配置文件中将 term_is_latin 设置为真值来激活转换器。一种方法是
cpan> o conf term_is_latin 1如果需要其他字符集支持，请向 rt.cpan.org 提交针对 CPAN.pm 的错误报告，并描述您的需求。也许我们可以扩展支持，或者也许 UTF-8 终端将变得广泛可用。
注意：此配置变量已弃用，将在 CPAN.pm 的未来版本中删除。它将被 $LANG 和 $LC_* 环境变量系列周围的约定所取代。
当安装由于某种原因失败，然后我纠正错误条件并重试时，CPAN.pm 拒绝安装模块，并显示 已经尝试过，但没有成功。
使用 force pragma，如下所示
force install Foo::Bar或者您可以使用
look Foo::Bar然后在子 shell 中直接 make install。
如何安装模块的“开发人员版本”？
默认情况下，CPAN 将安装模块的最新非开发人员版本。如果您想安装开发人员版本，则必须指定从作者 ID 开始到您要安装的 tarball 的部分路径，如下所示
cpan> install KWILLIAMS/Module-Build-0.27_07.tar.gz请注意，您可以使用 ls 命令来获取此路径列表。
如何在不提示任何内容的情况下，从命令行安装模块及其所有依赖项，即使我的 CPAN 配置（或缺少配置）？
CPAN 使用 ExtUtils::MakeMaker 的 prompt() 函数来询问其问题，因此，如果您设置了 PERL_MM_USE_DEFAULT 环境变量，则您不应该被询问任何问题（假设您正在安装的模块也很好地遵守了该变量）
% PERL_MM_USE_DEFAULT=1 perl -MCPAN -e 'install My::Module'如何从基于 ExtUtils::MakeMaker 的 Makefile.PL 创建一个基于 Module::Build 的 Build.PL？
http://search.cpan.org/dist/Module-Build-Convert/
我经常对 CPAN shell 无法帮助我选择合适的镜像感到恼火。
CPAN 现在可以帮助您选择一个“好的”镜像，根据哪个镜像的“ping”往返时间最短。在 shell 中，使用命令“o conf init urllist”，并允许 CPAN 自动为您选择镜像。
除此之外，urllist 配置参数由您掌控。您可以随意添加和删除站点。您应该找出哪些站点拥有最佳的更新频率、带宽、可靠性等，并且在拓扑结构上靠近您。有些人更喜欢快速下载，有些人更喜欢更新频率，有些人更喜欢可靠性。您可以决定尝试哪些站点以及尝试的顺序。
Henk P. Penning 维护着一个收集有关 CPAN 站点数据的网站。
http://mirrors.cpan.org/此外，您可以随意尝试实验性功能。运行
o conf init randomize_urllist ftpstats_period ftpstats_size并选择您最喜欢的参数。在运行几次下载后，运行 hosts 命令可能会帮助您选择最佳的镜像站点。
为什么每次启动 shell 时都会被问到相同的问题？
您可以通过调用命令 o conf commit 使您的配置更改永久生效。或者，通过运行 o conf init auto_commit 并用“yes”回答以下问题来将 auto_commit 变量设置为 true。
旧版本的 CPAN.pm 将所有 tarball 的原始根目录放在构建目录中。现在，这些目录名称总是附加了随机字符。为什么要这样做？
随机字符由 File::Temp 提供，并确保每个模块的单独构建目录都是唯一的。这使得在并发进程中同时运行 CPAN.pm 变得安全。
说到构建目录，我是否需要自己清理它？
您可以选择将配置变量 scan_cache 设置为 never。然后您必须自己清理它。其他可能的取值 atstart 和 atexit 分别在您启动（更准确地说，在第一次提取到构建目录后）或退出 CPAN shell 时清理构建目录。如果您从未启动 CPAN shell，您可能也必须自己清理构建目录。
如何切换到 sudo 而不是 local::lib？
以下 5 个环境变量需要重置为之前的取值：PATH、PERL5LIB、PERL_LOCAL_LIB_ROOT、PERL_MB_OPT、PERL_MM_OPT；并且这两个 CPAN.pm 配置变量必须重新配置：make_install_make_command 和 mbuild_install_build_command。这五个环境变量可能在您的 $HOME/.bashrc 或类似文件中被覆盖。您可以在那里找到它们并删除它们的痕迹，然后注销/登录，或者根据您的具体需求临时覆盖它们。这两个 cpanpm 配置变量可以使用以下命令设置
o conf init /install_.*_command/可能后面跟着
o conf commitCPAN.pm 定期测试在 5.005 及其更新版本上运行。在较旧的 Perl 版本上，要满足最低要求越来越困难。在这些版本上，几乎不可能让整个 Bundle::CPAN 正常工作。如果您只能使用这些旧版本，请注意 CPAN 旨在在没有安装 Bundle::CPAN 的情况下正常工作。
为了开始使用，请注意 GBARR/Scalar-List-Utils-1.18.tar.gz 与古老的 Perl 版本兼容，并且 File::Temp 列为先决条件，但如果缺少，CPAN 具有合理的解决方法。
这个模块及其竞争对手 CPANPLUS 模块都比另一个更酷。CPAN.pm 比较老。CPANPLUS 旨在更模块化，但它从未打算与 CPAN.pm 兼容。
在 2010 年，App::cpanminus 推出，它是一种新的 cpan shell 方法，具有相当小的占用空间。非常酷的东西。
此软件使您能够升级计算机上的软件，因此本质上是危险的，因为新安装的软件可能包含错误，并且可能会改变计算机的工作方式，甚至使其无法使用。请考虑在每次升级之前备份您的数据。
请通过 http://rt.cpan.org/ 报告错误
在提交错误之前，请确保通过按照该软件包的安装说明从 shell 构建 Perl 模块软件包的传统方法在您的环境中仍然有效。
Andreas Koenig <[email protected]>
此程序是自由软件；您可以根据与 Perl 本身相同的条款重新分发和/或修改它。
参见 https://perldotcom.perl5.cn/perl/misc/Artistic.html
Kawai,Takanori 在 http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm 提供了该手册页非常旧版本的日语翻译。
许多人通过运行 cpan 实用程序来进入 CPAN shell，该程序与 perl 本身安装在同一个目录中。因此，如果您在 PATH 变量（或您的操作系统中的等效项）中包含此目录，那么在控制台窗口中键入 cpan 对您来说也是有效的。除此之外，该实用程序还提供了一些命令行快捷方式。
melezhik（Alexey）给我发了一个链接，他在其中发布了一个使用 CPAN.pm 的 chef 食谱：http://community.opscode.com/cookbooks/cpan。