=item *
-Specify pre-requisites in Makefile.PL
+Specify pre-requisites in Makefile.PL or Build.PL
=item *
been done in Perl, and avoid re-inventing the wheel unless you have a
good reason.
+Good places to look for pre-existing modules include
+http://search.cpan.org/ and asking on modules@perl.org
+
If an existing module B<almost> does what you want, consider writing a
patch, writing a subclass, or otherwise extending the existing module
rather than rewriting it.
The level of detail in Perl module documentation generally goes from
less detailed to more detailed. Your SYNOPSIS section should contain a
minimal example of use (perhaps as little as one line of code; skip the
-unusual use cases or or anything not needed by most users); the
+unusual use cases or anything not needed by most users); the
DESCRIPTION should describe your module in broad terms, generally in
just a few paragraphs; more detail of the module's routines or methods,
lengthy code examples, or other in-depth material should be given in
giving pointers to further information (website, author email).
An INSTALL file should be included, and should contain simple installation
-instructions (usually "perl Makefile.PL; make; make install").
+instructions. When using ExtUtils::MakeMaker this will usually be:
+
+=over 4
+
+=item perl Makefile.PL
+
+=item make
+
+=item make test
+
+=item make install
+
+=back
+
+When using Module::Build, this will usually be:
+
+=over 4
+
+=item perl Build.PL
+
+=item perl Build
+
+=item perl Build test
+
+=item perl Build install
+
+=back
Release notes or changelogs should be produced for each release of your
software describing user-visible changes to your module, in terms
perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'
-If you want to release a 'beta' or 'alpha' version of a module but don't
-want CPAN.pm to list it as most recent use an '_' after the regular
-version number followed by at least 2 digits, eg. 1.20_01
+If you want to release a 'beta' or 'alpha' version of a module but
+don't want CPAN.pm to list it as most recent use an '_' after the
+regular version number followed by at least 2 digits, eg. 1.20_01. If
+you do this, the following idiom is recommended:
+
+ $VERSION = "1.12_01";
+ $XS_VERSION = $VERSION; # only needed if you have XS code
+ $VERSION = eval $VERSION;
+
+With that trick MakeMaker will only read the first line and thus read
+the underscore, while the perl interpreter will evaluate the $VERSION
+and convert the string into a number. Later operations that treat
+$VERSION as a number will then be able to do so without provoking a
+warning about $VERSION not being a number.
Never release anything (even a one-word documentation patch) without
incrementing the number. Even a one-word documentation patch should
=back
Specify version requirements for other Perl modules in the
-pre-requisites in your Makefile.PL.
+pre-requisites in your Makefile.PL or Build.PL.
-Be sure to specify Perl version requirements both in Makefile.PL and
-with C<require 5.6.1> or similar.
+Be sure to specify Perl version requirements both in Makefile.PL or
+Build.PL and with C<require 5.6.1> or similar. See the section on
+C<use VERSION> of L<perlfunc/require> for details.
=head2 Testing
-All modules should be tested before distribution (using "make disttest",
+All modules should be tested before distribution (using "make disttest"),
and the tests should also be available to people installing the modules
(using "make test").
+For Module::Build you would use the C<make test> equivalent C<perl Build test>.
The importance of these tests is proportional to the alleged stability of a
module -- a module which purports to be stable or which hopes to achieve wide
Useful modules to help you write tests (with minimum impact on your
development process or your time) include Test::Simple, Carp::Assert
and Test::Inline.
+For more sophisticated test suites there are Test::More and Test::MockObject.
=head2 Packaging
-Modules should be packaged using the standard MakeMaker tools, allowing
-them to be installed in a consistent manner. Use "make dist" to create
-your package.
-
-Tools exist to help you build your module in a MakeMaker-friendly style.
-These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
+Modules should be packaged using one of the standard packaging tools.
+Currently you have the choice between ExtUtils::MakeMaker and the
+more platform independent Module::Build, allowing modules to be installed in a
+consistent manner.
+When using ExtUtils::MakeMaker, you can use "make dist" to create your
+package. Tools exist to help you to build your module in a MakeMaker-friendly
+style. These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
=head2 Licensing
If you don't know what license to use, dual licensing under the GPL
and Artistic licenses (the same as Perl itself) is a good idea.
+See L<perlgpl> and L<perlartistic>.
=head1 COMMON PITFALLS
Verifies your POD's correctness
+=item Packaging Tools
+
+L<ExtUtils::MakeMaker>, L<Module::Build>
+
=item Testing tools
-L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>
+L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
=item http://pause.perl.org/
https://perl5.git.perl.org / perl5.git / blobdiff