perlmeditation
ELISHEVA
<p>The last day or two I've been learning how to prepare a module for CPAN distribution. There doesn't seem to be a good tutorial anywhere explaining how this all works. The two tutorials I found on Perl Monks are quite old. [id://158999|One] was written in 2002 and [id://431702|the other] in 2005. Neither discusses newer tools like [mod://Module::Build]. Nor do they explain how CPAN works, let alone discuss how this process can be safely and reliably customized.</p>
<p>To answer that question, one needs to know (a) what happens only on the developer's machine, (b) what happens on the target machine and (c) how CPAN itself uses the data in a distribution package.</p>
<p>There is no shortage of information, of course, but it all seems to be scattered here and there. I thought I'd write up my learnings and practical observations in case they would help others. Once one becomes familiar with something it is all too easy to forget what was hard.</p>
<p>I'd very much appreciate feedback from experienced CPAN developers. Are their practical tips I've missed? Did I form a misimpression or jump to a false conclusion about something because of my brief experience?</p>
<p>Many thanks in advance for feedback. -- beth</p>
<readmore>
<h3>1. CPAN Distribution - Technical Overview</h3>
<h4>1.1 Contents of a CPAN package</h4>
<p>A CPAN package is a tarball that is expected to have the following
contents.</p>
<dl>
<dt><c>META.json</c> or <c>META.yml</c></dt>
<dd><p>A JSON or YAML file describing the package. For the specification of that file, see [mod://CPAN::Meta::Spec]. The JSON file is name <c>META.json</c>. The YAML file is named <c>META.yml</c>. CPAN uses the information in this file to index the package and decide how and where to display it in CPAN.</p></dd>
<dt><c>MANIFEST</c></dt>
<dd><p>This file contains a list of all of the files in the distribution tarball.</p></dd>
<dt><c>SIGNATURE</c></dt>
<dd><p>An optional signature file calculated using the list of files in the distribution's manifest file.</p></dd>
<dt><c>Build.PL</c> and/or <c>Makefile.PL</c></dt>
<dd><p>These are both Perl scripts that that customize build instructions to work on the target machine. Ideally both should be present.</p></dd>
<dt>the actual files listed in <c>MANIFEST</c></dt>
<dd><p>The organization of the source files depends on Build.PL/make.PL. Both these scripts generate files based on some rather rigid expectations about how files are organized. For example, if <c>Build.PL</c> is in directory "foo", it expects all Perl source files to be in "foo/lib" and all tests to be in "foo/t".</p></dd>
</dl>
<h4> 1.2 Downloading and installing using a CPAN client</h4>
<p>When a distribution file is downloaded from CPAN, the installation process includes seven steps:
<ol>
<li>Unpack the tarball into a directory</li>
<li>Generate the <c>Build</c> script and/or makefile
by running <c>Build.PL</c> or <c>Makefile.PL</c>. The choice depends on the version of CPAN installed on the target machine. Older versions of CPAN only know how to work with <c>Makefile.PL</c>. If the version knows how to use <c>Build.PL</c> it will use that. Otherwise it will
use <c>Makefile.PL</c>.</li>
<li>Generate source code files using scripts marked for that purpose.</li>
<li>Generate documentation files. Either man pages, html, or both will be generated depending on the target systems <c>Config.pm</c> file. The <c>Config.pm</c> file is part of a Perl installations configuration. On Debian it is found in /usr/lib/perl/5.N/Config.pm</li>
<li>Place all source code files, raw and generated, into a staging area (by convention, called "./blib/")</li>
<li>Run tests</li>
<li>Copy files to their final locations and perform custom installation actions.</li>
</ol>
<p>Steps 1&2 are handled by a CPAN client. Steps 3-6 are handled by either <c>./Build test</c> or <c>make test</c>. The final seventh step is handled by either <c>./Build install</c> or <c>make install</c>.</p>
<p>To get a sense of how to install a CPAN tarball without benefit of a CPAN client, see [doc://perlmodinstall].</p>
<h4>1.3 Build.PL vs. Makefile.PL</h4>
<p><c>Build.PL</c>generates a Perl script named "Build" but only works with newer versions of the CPAN client. <c>Makefile.PL</c> generates a make file that can be used even with older versions of the client. However, it is less portable because it assumes that make (or some related tool like nmake/dmake) is installed.</p>
<p>To complete the installation using the makefile generated by <c>Makefile.PL</c>, CPAN runs the commands <c>make test</c> and <c>make install</c>. This means, of course, that the installation process will fail if the new machine doesn't have <c>make</c> installed. This is one of the reason why newer versions of CPAN use <c>Build.PL</c> if available. Since it is a Perl script it can run on any machine where Perl is installed. No third party software is needed. Some systems, like Microsoft Windows, do not have <c>make</c> installed as a matter of course.</p>
<p>Even on systems that do have <c>make</c>, <c>make</c>'s use of the command shell can cause problems. Each operating system has a different preferred implementation of the command shell: C, Korn, Bourne, Bash, Ash, to name a few. There are subtle syntax differences between these shells and it is quite possible that a make file that works well on one flavor of Linux/Unix will fail on another because it relies on a different flavor of Linux/Unix shell.</p>
<h4>1.4 Choosing packaging tools</h4>
<p>These files are not magic. Both the Perl Build script and the make file can contain any instructions immaginable as long as they know how to understand the commands 'test' and 'install'. Thus the Perl script generated by <c>Build.PL</c> must be able to called like this: <c>./Build test</c> and <c>./Build install</c>. The generated make file must support <c>make test</c> and <c>make install</c>.</p>
<p>However, handcrafting the meta files (META.json, META.yml) and writing a build script/make file generator requires a great deal of domain knowledge. Most developers therefore rely on one of four main tool kits to package up their modules:</p>
<ul>
<li><p>[mod://ExtUtils::MakeMaker] - the oldest of these four tools generates make files. It is used to write Makefile.PL files, often with the help of [doc://h2xs], [mod://ExtUtils::ModuleMaker]</p></li>
<li><p>[mod://Module::Build] - generates a Build script. It is used to write <c>Build.PL</c> files. It will automatically generate a <c>Makefile.PL</c> file with the help of [mod://Module::Build::Compat], if requested, as well.</p></li>
<li><p>[mod://Module::Install]</p></li>
<li><p>[mod://Dist::Zilla]</p></li>
</ul>
<h3>2. Building a module with [mod://Module::Build]</h3>
<h4>2.1 Arranging your files</h4>
<p>[mod://Module::Build] expects that you will be developing your
code in a project directory that looks like this:</p>
<dl>
<dt><c>Build.PL</c></dt>
<dd>instructions for generating the Build command. This is a
file you write. See below for details.</dd>
<dt><c>script/</c></dt>
<dd>stores your Perl scripts, i.e. your .pl files</dd>
<dt><c>lib/</c></dt>
<dd>stores your Perl modules, i.e. your .pm files</dd>
<dt><c>t/</c></dt>
<dd>stores your test scripts, i.e. your .t files</dd>
<dt><c>test.pl</c></dt>
<dd>A script responsible for running all tests. If missing,
the tests in <c>t/</c> will be
run via <c>TAP::Harness</c> or <c>Test::Harness</c> depending
on how you configure the <c>Build.PL</c> and <c>Makefile.PL</c>
files. If present, the <c>test.pl</c> determines how to run
the tests and in what order. <c>Build test</c> will run
<c>test.pl</c> instead of trying to run the tests in
<c>t/</c> on its own.</dd>
<dt><c>inc/</c></dt>
<dd>supplemental files used by your packaging and installation
process. They will be included in the tarball, but the meta
data file will be set up so that they will be ignored by
CPAN's indexing mechanism. For a practical use of this
directory, see [mod://Module::Build::Cookbook]'s discussion of
how to bundle [mod://Module::Build] with your package.</dd>
<dt><c>MANIFEST.SKIP</c></dt>
<dd>a set of regular expressions matching files and
directories to ignore in <c>/lib</c>, <c>/script</c>,
<c>/t</c> and <c>/inc</c>. These files will be excluded
from the tarball even though they are within the project
directory.</dd>
</dl>
<p>The directories listed above should contain only the files that
belong to your project. [mod://Module::Build] doesn't have a good
way of extracting files from a single common source tree shared by
multiple projects. It assumes that all files in the lib directory
belong in your project unless you specifically exclude them via a
regular expression in the <c>MANIFEST.SKIP</c> file.</p>
<p>It is also essential that <c>.pl</c> files be placed in
<c>scripts/</c> and not <c>lib/</c>. When [mod://Module::Build] sees
<c>.PL</c> (or <c>.pl</c> in a case insensitive system) in the
<c>lib/</c> directory, it assumes that the file is meant to generate
a module rather than be used as a script. It will run the script
and put the output of the script into a file that has the same
name as the script file, less the <c>.PL</c> suffix. Thus
<c>lib/foobar.pm.PL</c> would be expected to generate
<c>lib/foobar.pm</c>.</p>
<h5>Module names</h5>
<p>For portability reasons, each module name component should be
11 or fewer charaters. The first 8 of these must be different from
any other module on CPAN. This ensures that the module will behave
well on operating systems that have a very short file names.</p>
<p>The PAUSE documents recommend informative names over "cool" or
poetic names. For more information, see the following links:</p>
<ul>
<li>[https://pause.perl.org/pause/authenquery?ACTION=pause_namingmodules|Choosing a Good Module Name]</li>
<li>[http://www.cpan.org/modules/00modlist.long.html#ID2_Guidelinesf|Guidelines for Module Creation] - see particular section 2.5 "Select a name for the module".</li>
</ul>
<h5>If you use an alternate organization for your projects</h5>
<p>If you have an alternate arrangement of files, for example,
storing all source code in a common tree rather than in per-project
directories, you will have to move the files into place before
beginning the build process. There are ways to automate this proces,
but it requires subclassing [mod://Module::Build] and adding an
extra action, called 'makeproject' or 'import'.</p>
<h4>2.2 Writing <c>Build.PL</c></h4>
<p><c>Build.PL</c> is a file you write. At a minimum it contains
three basic instructions: (a) loading [mod://Module::Build] or
a subclass (b) initializing a new builder object with project
specific property values and (c) generating a Perl script named
"Build".</p>
<code>
use 5.008008; # NOT 5.8.8 - needed by CPAN testers
use Module::Build;
my $builder = Module::Build
->new( module_name => 'Exception::Lite'
, license => 'perl'
, requires => { perl => '>= 5.8.8' }
, dist_version => '0.099_001'
, create_makefile_pl => 'traditional'
);
$builder->create_build_script; #generate Build
</code>
<p>You can get a full list of parameters to pass <c>new</c> in
[mod://Module::Build::API].</p>
<h5>Making your Build.PL file CPAN testers friendly</h5>
<p>The page [http://wiki.cpantesters.org/wiki/CPANAuthorNotes] has
some helpful pointers for making it easier for CPAN testers to
work with your distribution. The key points related to
<c>Build.PL</c> and <c>Makefile.PL</c> are:</p>
<ul>
<li>put <c>use VERSION</c> at the top of your <c>Build.PL</c> file.
Although the constructor for [mod://Module::Build] allows one
to specify a required version of Perl, older versions of the
CPAN client don't know how to read this and may try to test
packages not designed for them.</li>
<li>When you specify the version number for <c>use VERSION</c>,
use the old style version format M.mmmppp where mmm is a
3 digit 0 padded placeholder for the minor version and ppp is
a three digit 0 padded placeholder for the patch/development
release number. Thus <c>5.008008</c> rather than
<c>5.8.8</c>.</li>
<li>If your system only supports a specific set of operating
systems, the <c>Build.PL</c> script should begin with code
that dies with one of the following messages
"No support for OS" or "OS unsupported". The CPAN testing
tools know to look for this messsage and will consider the
platform not applicable for any distribution that generates
this message.</li>
<li>If you need threads your tests should be configured so that
those tests are skipped if threads are not installed.</li>
</ul>
<h5>Distribution version numbers</h5>
<p>The <c>dist_version</c> property identifies the version number
for your distribution package. All distributions <i>MUST</i> have
a version number.</p>
<p>If you omit the <c>dist_version</c> property number, Perl will
try to guess the version number by looking for
a variable named <c>$VERSION</c> in the 'module_name' module. For
the example above, had 'dist_version' been omitted,
[mod://Module::Build] would have looked for <c>$VERSION</c> in
'lib/Exception/Lite.pm'</p>
<p>The version number is an especially important parameter because
CPAN uses it to track distribution files. It consists of three
components: a major number indicating a collection of binary
compatible releases; a 3 digit minor version number indicating feature
enhancements within that binary compatible group, and a 3 digit patch
or development release number.</p>
<p>If the third component is preceded by '_', CPAN counts the upload as a development release. The intended features for the minor version may be partially implemented as well. Thus '0.099_001' would be the first development release for feature set '0.999'. It is meant to be available for testing but not as a published download. </p>
<p>This intention is enforced softly. The CPAN distribution page marks it with a label in big red letters saying "DEVELOPEMENT RELEASE". CPAN clients are encourged not to install it as the default version even if its version number is higher than any others. They should be downloaded only if the user requests that specific version, presumably for testing purposes.</p>
<p>If the patch number is preceded by a '.' then it will be published
and available for downloading via CPAN. For more information, see
[mod://Perl::Version].</p>
<p>No two uploads may have exactly the same version number. If you
mess up and need to reupload a distribution file, you must change
the patch or development release number.</p>
<h5>Configuring documentation generation</h5>
<p>Unfortunately, there don't seem to be many options to control this
process. For HTML generation there is only one user definable option:
<c>html_css</c>:
my $oBuilder = Module::Build->new (....);
$oBuilder->html_css('MyLayout.css');
<p>See [mod://Pod:Html] and [mod://Module::Build::API] for more
information about setting css.</p>
<p>Another related issue concerns the content of pod files. The
syntax and handling of the <c>L<link_descriptor></c> has changed
over time. Two changes in particular may cause problems:</p>
<ul>
<li>Links without text fields: Some older generators assumed that any non url style link without explicitly specified text were man pages. Instead of rendering the link text literally, they would substitute <c>L<foo></c> with "the foo man page" or the foo documentation". As tedious as it may be, if your distribution is meant to work on older Perl installations, you may prefer to explicitly provide text for each link. In otherwards, your pod should use <c>L<Module::Foo|Module::Foo></c>
rather than just plain <c>L<Module::Foo></c>.</li>
<li>URL style links cannot have link text prior to Perl 12.0. You cannot do <c>L<foo|html://example.com/foo.html></c> but rather must do
<c>L<html://example.com/foo.html></c> without the link text.</li>
</ul>
<h5>Output of <c>Build.PL</c></h5>
<p>The script generated by this simple file contains a number of
default commands. In addition to the <c>test</c> and <c>install</c>
commands, there are several that are generally used only by developers
preparing their code for packaging.</p>
<p>For a list of commands, see [mod://Module::Build]</p>
<h5>Advanced <c>Build.PL</c> files</h5>
<p>You can also have much more elaborate scripts for generating
<c>Build.PL</c>. This one subclasses [mod://Module::Build] on the
fly and adds a routine that imports project files from a single
codebase source tree. The routine is very simple and would benefit
from many improvements (portable path name construction, checking
for deleted files, validating the copy). It is meant only for
illustration purposes:</p>
<code>
use 5.008008; # NOT 5.8.8
my $sClass = Module::Build->subclass(code => <<'EOF');
my $MODULE_BASE = 'Exception/Lite';
my @LIB_SOURCES = ('.pm', '.pod', '.t');
sub ACTION_makeproject {
my $oBuilder = Module::Build->current();
my $sProjectRoot=$oBuilder->args('srctree');
if (!defined($sProjectRoot)) {
warn "No source tree root defined\n";
return;
}
$sProjectRoot .= '/' unless ($sProjectRoot =~ m{/$});
my $sModuleSrc = $sProjectRoot . $MODULE_BASE;
require File::Copy;
if (! -d 'lib') { mkdir 'lib' or die $!; }
if (! -d 'lib/Exception') { mkdir 'lib/Exception' or die $! }
my $sModuleLib = 'lib/' . $MODULE_BASE;
print STDERR
"Making a project <$MODULE_BASE> from <$sProjectRoot>\n"
. "Copying files to lib ... ";
foreach my $sSrc (@LIB_SOURCES) {
File::Copy::copy($sModuleSrc.$sSrc, $sModuleLib.$sSrc);
}
print STDERR "lib/ is built\n";
}
EOF
my $builder = $sClass
->new( # command line options to hard-code data needed by
# makeproject action defined above
get_options => {srctree => { type => '=s' }}
, module_name => $MODULE_NAME
, license => 'perl'
, requires => { perl => '>= 5.8.8' }
, test_files => [ $MODULE_ROOT.'.t']
, dist_version => '0.099_001'
, create_makefile_pl => 'traditional'
);
# called on command line like this
# perl Build.PL --srctree='/X/Y/Z/';
# makeproject command run like this
# ./Build makeproject
</code>
<p>Building a subclass with <c>Module::Build->subclass(code=>...)</c>
is only practical for very short snippets of code. Code defined via
the <c>code</c> property is compiled without benefit of <c>strict</c>
or <c>warnings</c> so it is especially easy for variable name
mispellings to slip through. Also syntax highlighting doesn't
necessarily work in here documents (on Xemacs it all gets colored as
a string) so the probability of mistakes is increased even further.</p>
<p>If you do choose to use <c>Module::Build->subclass(code=>...)</c>,
everything you plan to use must be placed within the here document
assigned to the <c>code</c> property. The <c>Build.PL</c> file and
code that is part of it is never used after <c>Build.PL</c> runs.
In fact the code snippet that you define in the here document is
simply used to generate a subclass definition file that is placed in
the <c>_build</c> directory. Anything outside of that snippet will
never make it into the generated subclass file. That is why you
cannot do something like this in your <c>Build.PL</c> file:</p>
<code>
{
package MyBuilder;
our @ISA=qw(Module::Build);
... my code here ...
}
my $builder = MyBuilder->new(...various arguments...);
</code>
<p>If you need to define extensive amounts of code you are better off
defining your specialist code in a dedicated subclass file and
placing that file in the <c>inc</c> directory of your project
directory. See [mod://Module::Build::Authoring] for more
information.</p>
<h4>2.3 Running the <c>Build.PL</c> Command</h4>
<p>As a developer there are two reasons you will want to run the
<c>Build.PL</c> command. First, the generated <c>Build</c> file
defines many commands that are useful to developers. Second, you
will want to test your installation process and generating
<c>Build</c> from <c>Build.PL</c> is part of that installation
process.</p>
<p>To generate <c>Build</c> you simply type <c>perl Build.PL</c> in
the top level of the project directory.</p>
<p>The <c>Build.PL</c> command must be run from the top level of the
project directory. The script generation routines in
[mod://Module::Build] simply assumes that "lib/", "inc/", etc are
in the current directory where the script was launched. It will
complain about not being able to find modules if run from any other
directory.</p>
<h5>Generating both a build script and makefile</h5>
<p>If you want to generate both the build script and the makefile
your <c>Build.PL</c> file can set the <c>create_makefile_pl</c>
property in the parameter list to <c>Module::Build->new(...)</c>.</p>
<p>Setting this parameter is the easiest way to generate a makefile
and it will work for most simple installations. However, if your
installation process is complex, you may need to take more control
over this process. For details, see [mod://Module::Build::Compat] and
[mod://Module::Build::API]'s documentation on the <c>create_makefile_pl</c> parameter.</p>
<h5>Deleting the generated script and starting over</h5>
<p>Running <c>Build.PL</c> adds two items to the top level of the
project directory:</p>
<dl>
<dt>Build</dt>
<dd>A script defining commands for use by developers and CPAN's
automated installation process. This file will be regenerated
each time <c>Build.PL</c> is run.</dd>
<dt>_build</dt>
<dd>Data files used by the <c>Build</c> script.</dd>
</dl>
<p>You can completely remove the <c>Build</c> script and the
<c>_build</c> directory, by running the command
<c>./Build realclean</c>. The name of this action is a bit of a
misnomer. It always removes the build script and the <c>_build/</c>
directory. It sometimes removes the <c>blib/</c> directory, the
distribution staging area, and temporary files produced during the html
generation process. What determines when things are removed and when they are not is not at all clear.</p>
<p>It appears to never remove the following files:</p>
<ul>
<li><c>META.yml</c></li>
<li><c>MANIFEST</c></li>
<li><c>MANIFEST.SKIP</c></li>
<li><c>Makefile.PL</c></li>
<li><c>tarballs generated by the dist action</c></li>
</ul>
<p>If you want to regenerate these from scratch, you must manually
remove them.</p>
<h4>2.4 Packaging up your module for distribution</h4>
<p>To package your module you must run the following commands in
sequence:</p>
<code>
./Build manifest
./Build disttest
./Build dist
</code>
<p>The build script generated by <c>Build.PL</c> does not accept more
than one action at a time so you can't combine the commands into
one single action, such as "./Build manifest disttest dist". Only the
first command will be run.</p>
<dl>
<dt>manifest</dt>
<dd>generates the MANIFEST file and creates a MANIFEST.SKIP file if
that is missing. If the MANIFEST files exists already, it will
update it.
<p>Please note, if you decide that certain files are
no longer needed by your project and you remove them from the
project directory, the <c>manifest</c> action will <i>not</i>
remove them from the manifest file. It will merely warn you
about the missing files. You must delete them from the manifest
file manually. Alternatively, you can manually delete the file
and regenerate <c>MANIFEST</c> from scratch. Also note,
the <c>realclean</c> action does not remove the <c>MANIFEST</c>
or <c>MANIFEST.SKIP</c> files. If you want to regenerate them
from scratch you must remove them manually.</p>
</dd>
<dt>disttest</dt>
<dd>collects all the files that will be placed in the tarball into
a staging directory. If there is no <c>META.yml</c> file, it
will generate it and copy it to the staging area. Then it
verifies that <c>Build.PL</c> can be run, followed by
<c>Build test</c>. It does not install anything.
<p>This method will complain if it can't find
a <c>MANIFEST</c> file so you must run the "manifest" action
before running this action. It will not run it automatically
for you.</p>
<p>The staging directory name is just the module name with
each :: replaced by '-' and '-version' tacked onto the end.
Thus <c>Exception::Lite</c> gets a distribution directory named
"Exception-Lite-0.099_001".</p>
</dd>
<dt>dist</dt>
<dd>converts the staging area directory into a tarball. If the
sign property is set when calling <c>ModuleBuild->new</c> and
your system has [mod://Module::Signature] installed, the
tarball will also be signed and the results stored in a file
called <c>SIGNATURE</c>.
<p>During the creation process, the directory will be removed
and in its place you will see a tarball. Thus the directory
<c>Exception-Lite-0.099_001</c> is replaced by the tarball
<c>Exception-Lite-0.999_001.tar.gz</c></dd>
</dl>
<h4>2.5 Additional testing options</h4>
<p>The disttest routine only verifies that the module has the
files needed to upload the module to CPAN, download it and run its
tests. To make sure your module installs properly you will need to
run additional tests. Additional testing may also be required
to make sure that the released code fits your quality control
standards.</p>
<h5>Emulating what happens after the tarball is unpacked</h5>
<p>To emulate what happens after the tarball is unpacked, you can
run the following sets of commands:
<code>
./Build test
./Build fakeinstall
-or-
perl Build.PL --destdir /tmp/foo/
./Build test
./Build install
</code>
<p>The first set of commands builds <c>blib/</c> as normal, tests
the files and generates documentation as normal. However, instead
of copying the files to their final destination it merely reports
on what files it would have copied and to which locations.</p>
<p>The second set of commands does an actual fake installation to a
directory other than the normal site directory. In this case the
files are installed to <c>/tmp/foo</c>. You can verify this by running
<c>./Build fakeinstall</c>. Instead of the normal site locations, the
copy destinations will all be in <c>/tmp/foo/</c>.</p>
<p>Please note that the second method requires rebuilding the
<c>Build</c> script. The destination directory is hard coded into the
script and there is no option for changing the destination
directory on the build script itself.</p>
<p>To clean out generated files and start all over you can use. In
theory this should clean out the <c>blib/</c> directory generated
by the 'test' action. It is best to double check that the file was
in fact removed. For some reason, from time to time, the "blib/"
directory won't go away even when this command is run.</p>
<code>
./Build clean
</code>
<h5>Testing installation on systems other than your own.</h5>
<p>There is very limited support for this. If you want to test
the generatio of documentation that would not normally be generated
on your system you can use the following two commands:</p>
<dl>
<dt>html</dt>
<dd>Generates the html documentation from pod files printing out
error messages about unresolvable links and other difficulties.
This is guarenteed to generate html even if the current system
does not normally request it.
<p>Note: the 'html' action complains about being unable to
resolve links to documentation pages and modules that only have
a top level name (example: the documentation pages for
<c>UNIVERSAL</c>, <c>Exception</c> generate exceptions even
though these can be found on CPAN and have man pages visible
via the <c>perldoc</c> command.</p></dd>
<dt>manpages</dt>
<dd>Generates the man page documentation from pod files even if
the current system is not configured to request it. This
action is available version 0.28 and up only - earlier versions
relied on the fact that nearly all systems were configured to
request man pages.</dd>
</dl>
<p>You can control the locations where files will be installed by
using the <c>--install_path</c> and <c>--installdirs</c> options.
See [mod://Module::Build] for details.</p>
<p>However, this only begins to touch on the portability issues that
can affect a module. By far and away the best option is to get your
module working well on your own system and then upload it to CPAN
where users of other systems can download and test it. See [http://wiki.cpantesters.org/wiki/CPANAuthorNotes|CPAN Author Notes] for more information.</p>
<h5>Quality control testing</h5>
<p>[mod://Module::Build]'s generated <c>Build</c> script also contains
several tools for checking the quality of code, tests, and
documentation. Among them:</p>
<dl>
<dt>skipcheck</dt>
<dd>prints out the files that were omitted based on rules in
<c>MANIFEST.SKIP</c>. You can use this to eyeball the list
of excluded files and verify that nothing was unintentionally
excluded from your distribution by a malformed regex.</dd>
<dt>testpod</dt>
<dd>finds all of the pod files and makes sure that they are well
formed.</dd>
<dt>testcover</dt>
<dd>runs the test action using [mod://Devel::Cover] and generates a
code coverage report. To use this, [mod://Devel::Cover] must be
downloaded from CPAN. It isn't part of the Perl core.</dd>
</dl>
<p>If you are particular excited about quality metrics you might also
want to consider using the [mod://Module::Build::Kwalitee] subclass
of [mod://Module::Build]. For a description of the Kwalitee metrics and why they are important, see [http://cpants.perl.org/kwalitee.html]. Kwalitee metrics are tracked by [http://cpants.perl.org/|CPANTS], an alternate testing service that should not be confused with [http://cpantesters.org/|CPAN testers].</p>
<h4>2.6 Extensions to [mod://Module::Build]</h4>
<p>[mod://Module::Build] was designed for subclassing and fortunately
many developers have taken advantage of that and shared their work.</p>
<p>A number of extensions to [mod://Module::Build] have been created
to handle special application types: applications with embedded C/C++, applications with databases, applications with a web front
end and so on. For a list of available modules, [cpan://Module::Build|search CPAN].</p>
<h3>3. Uploading your package to CPAN</h3>
<p>To upload a module to CPAN, you need an account on
[http://pause.perl.org|PAUSE]. For more information, see
[http://pause.perl.org/pause/query?ACTION=pause_04about|About Pause]
</p>
<h3>4. Alternative distribution channels</h3>
<p>The <c>Build</c> script generated by [mod://Module::Build] also
supports packaging for software distribution channels other than
CPAN:</p>
<ul>
<li>PAR files are the Perl analog to Java's JAR files. The bundle
Perl scrpts with a loader and perl interpreter. See the
'pardist' action in [mod://Module::Build], the
[http://par.perl.org/wiki/Main_Page|PAR wiki] and [http://web.archive.org/web/20050423212123/par.perl.org/index.cgi?Features|Features list from 2005] for more information.</li>
<li>PPM is the package management system for Active state Perl.
For tools to create packages distributed via PPM, see the
'ppmdist' and 'ppd' actions.</li>
<li>Support for distributing modules as.deb packages for Debian Linux is available through [mod://Module::Build::Debian].
</ul>
</readmore>
<p><b>Updates</b>:</p>
<readmore>
<ol>
<li><p>2010-12-29, 7:11am IST: moved section on extensions to [mod://Module::Build] into the section on building modules with [mod://Module::Build] - I plan to add a top level section on [mod://Dist::Zilla] recommended by several below so this doesn't make sense as a top level section.</p></li>
<li><p>2010-12-29, 12:30pm IST: added subsection numbers to section 1; replace "the CPAN client" with "a CPAN client" (there is more than one); removed the word "inherently" from the phrase "inherently less portable" in section 1.3 (Build.PL vs. Makefile.PM); Fixed wording in section on packaging tools (1.4) and added mention of [mod://Module::Install] and [mod://Dist::Zilla].</p></li>
<li><p>2010-12-29, 3:00pm IST: updating discussion of development releases to include [moritz]'s comments on development release [id://879516|below].</li>
<li><p>2010-12-29, 5:15pm IST: added links to [doc://perlmodinstall] in 1.3 (what a CPAN client does), as an example of installing modules without the benefit of a client and another link to a document that explains the Qwalitee metrics mentioned in the section on additional testing.</li>
</ol>
</readmore>