=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
+module. A module which purports to be stable or which hopes to achieve wide
use should adhere to as strict a testing regime as possible.
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/