ExtUtils::MakeMaker::Tutorial

(源代码, CPAN)

内容

名称
概要
描述
- 口诀
- 布局
参见

#名称

ExtUtils::MakeMaker::Tutorial - 使用 MakeMaker 编写模块

#概要

use ExtUtils::MakeMaker;

WriteMakefile(
    NAME            => 'Your::Module',
    VERSION_FROM    => 'lib/Your/Module.pm'
);

#描述

这是一个使用 MakeMaker 编写简单模块的简短教程。实际上并不难。

#口诀

MakeMaker 模块使用以下简单口诀安装

perl Makefile.PL
make
make test
make install

还有很多其他命令和选项，但上面的命令已经足够了。

#布局

模块中的基本文件看起来像这样。

Makefile.PL
MANIFEST
lib/Your/Module.pm

这些是严格必要的。您可能需要添加其他文件

lib/Your/Other/Module.pm
t/some_test.t
t/some_other_test.t
Changes
README
INSTALL
MANIFEST.SKIP
bin/some_program

#Makefile.PL

当您运行 Makefile.PL 时，它会生成一个 Makefile。这是 MakeMaker 的主要目的。Makefile.PL 是一个简单的程序，它加载 ExtUtils::MakeMaker 并运行 WriteMakefile() 函数来生成 Makefile。

以下是一个简单模块所需的示例

use ExtUtils::MakeMaker;

WriteMakefile(
    NAME            => 'Your::Module',
    VERSION_FROM    => 'lib/Your/Module.pm'
);

NAME 是模块的顶级命名空间。VERSION_FROM 是包含整个发行版中 $VERSION 变量的文件。通常，它与您的顶级模块相同。

#MANIFEST

包含您发行版中所有文件的简单列表。

Makefile.PL
MANIFEST
lib/Your/Module.pm

MANIFEST 中的文件路径始终使用 Unix 约定（即 /），即使您不在 Unix 上也是如此。

您可以手动编写此文件，也可以使用“make manifest”生成它。

有关更多详细信息，请参阅 ExtUtils::Manifest。

#lib/

这是您希望安装的 .pm 和 .pod 文件所在的目录。它们根据命名空间进行布局。因此，Foo::Bar 是 lib/Foo/Bar.pm。

#t/

您的模块的测试放在这里。每个测试文件名以 .t 结尾。因此，t/foo.t 'make test' 将运行这些测试。

通常，t/ 测试目录是扁平的，所有测试文件都直接位于其中。但是，您可以在子目录中嵌套测试，例如

t/foo/subdir_test.t

为此，您需要在 Makefile.PL 文件中以以下方式通知 WriteMakefile()

test => {TESTS => 't/*.t t/*/*.t'}

这将运行 t/ 中的所有测试，以及位于 t/ 下的所有子目录中的所有测试。您可以根据项目的需要进行深度嵌套。只需在测试位置字符串中添加另一个条目即可。例如，要测试

t/foo/bar/subdir_test.t

您将使用以下 test 指令

test => {TESTS => 't/*.t t/*/*/*.t'}

请注意，在上面的示例中，第一个子目录中的测试将不会运行。要运行测试文件所在的中间子目录之前的子目录中的所有测试，您需要明确地指出它

test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'}

如果您只想在特定子目录中进行测试，则无需指定通配符。以下示例将仅运行 t/foo 中的测试

test => {TESTS => 't/foo/*.t'}

测试从发行版的顶层运行。因此，在测试内部，您将引用 ./lib 来进入 lib 目录，例如。

#Changes

您对该模块所做的更改的日志。布局是自由格式的。以下是一个示例

1.01 Fri Apr 11 00:21:25 PDT 2003
    - thing() does some stuff now
    - fixed the wiggy bug in withit()

1.00 Mon Apr  7 00:57:15 PDT 2003
    - "Rain of Frogs" now supported

#README

对您的模块的简短描述，它做什么，为什么有人会使用它以及它的局限性。CPAN 会自动从存档中提取您的 README 文件并将其提供给 CPAN 用户，这是他们决定您的模块是否适合他们的首要内容。

#INSTALL

有关如何安装您的模块以及任何依赖项的说明。建议在此处包含的信息

any extra modules required for use
the minimum version of Perl required
if only works on certain operating systems

#MANIFEST.SKIP

这是一个包含正则表达式的文件，用于在使用 'make manifest' 生成 MANIFEST 时排除。这些正则表达式会与发行版中找到的每个文件路径进行匹配（因此您匹配的是 "t/foo.t" 而不是 "foo.t"）。

以下是一个示例

~$          # ignore emacs and vim backup files
.bak$       # ignore manual backups
\#          # ignore CVS old revision files and emacs temp files

由于 # 可以用作注释，因此 # 必须转义。

MakeMaker 带有一个默认的 MANIFEST.SKIP，以避免诸如版本控制目录和备份文件之类的文件。指定您自己的文件将覆盖此默认文件。

#bin/

#另请参阅

perlmodstyle 提供了编写模块的风格指南。

perlnewmod 提供了有关如何编写模块的更多信息。

有一些模块可以帮助您完成编写模块的过程：ExtUtils::ModuleMaker、Module::Starter、Minilla::Tutorial、Dist::Milla::Tutorial、Dist::Zilla::Starter