X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmodstyle.pod;h=a5e332e533b101e017795a8497264a2c57141bd9;hb=a5365663f59d38ce50a53f9b46b25daa36d5ab17;hp=4da7311f7aa30e563ff13951abddc730f873faa7;hpb=f67486beba48c3146946f5320d63fa647944efb5;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index 4da7311..a5e332e 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -137,7 +137,7 @@ Provide links to further information (URL, email) =item * -Specify pre-requisites in Makefile.PL +Specify pre-requisites in Makefile.PL or Build.PL =item * @@ -177,6 +177,9 @@ You may not even need to write the module. Check whether it's already 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 does what you want, consider writing a patch, writing a subclass, or otherwise extending the existing module rather than rewriting it. @@ -498,7 +501,7 @@ A contact email address for the author/maintainer 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 @@ -560,7 +563,33 @@ Your module should also include a README file describing the module and 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 @@ -588,9 +617,20 @@ using 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 @@ -625,16 +665,18 @@ Modules not available from CPAN =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 or similar. +Be sure to specify Perl version requirements both in Makefile.PL or +Build.PL and with C or similar. See the section on +C of L 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 equivalent C. 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 @@ -643,15 +685,17 @@ 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. +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. =head2 Licensing @@ -661,6 +705,7 @@ of the license don't require you to include it). 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 and L. =head1 COMMON PITFALLS @@ -712,9 +757,13 @@ POD documentation Verifies your POD's correctness +=item Packaging Tools + +L, L + =item Testing tools -L, L, L +L, L, L, L, L =item http://pause.perl.org/