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 目錄，例如。

#變更記錄

您對此模組所做的變更記錄。配置是自由格式。以下是範例

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 使用者，這是他們用來決定您的模組是否適合他們的首要資訊。

#安裝

安裝模組及相關相依套件的說明。建議在此處納入的資訊

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，以避免像版本控制目錄和備份檔案之類的項目。指定您自己的 MANIFEST.SKIP 會覆寫此預設值。

#bin/

#另請參閱

perlmodstyle 提供撰寫模組的風格說明。

perlnewmod 提供有關如何撰寫模組的更多資訊。

有許多模組可協助您完成撰寫模組的流程：ExtUtils::ModuleMaker、Module::Starter、Minilla::Tutorial、Dist::Milla::Tutorial、Dist::Zilla::Starter