perltutorial tachyon h2xs CPAN makefile <p>OK so you have learnt a bit of perl and have a great idea for a module. Here is how you go about making a distribution fit to go on CPAN. For background see [Simple Module Tutorial] and [A Guide to Installing Modules] Simon Cozens has a good overview of the process at <a href="http://www.perldoc.com/perl5.6.1/pod/perlnewmod.html">perlnewmod</a>. This tutorial is more hands on nitty gritty. <p>So you're all fired up to make your new widget module. Before you start it may be worthwhile to have a look at what already exists. You have many options open to you: <readmore> <ul> <li><a href="http://cpan.org">http://cpan.org</a> <li><a href="http://cpan.org/misc/cpan-faq.html">CPAN FAQ</a> <li><a href="http://search.cpan.org">http://search.cpan.org</a> <li>the newsgroups comp.lang.perl.misc et al <li>Post here on [Meditations] </ul> <p>It should be pretty simple to see if it has already been done. If it has you can reinvent the wheel, modify the existing codebase, or add functionality to the existing modules. Alright your mind is made up, so let's get stuck into it. <h3>Building a single module distribution Foo::Bar</h3> <p>Generally speaking you will be writting a module that fits below one of the base CPAN descriptions so lets presume you want to make a distro called <tt>Foo::Bar</tt> Typically you will start like this: <code> $ h2xs -AX Foo::Bar </code> <p><tt>h2xs</tt> should be available if you have perl on *nix or Win32. This will write module stubs for you automatically. You will get the following dir/files written into your current directory: <code> Foo/Bar/Makefile.PL Foo/Bar/Bar.pm Foo/Bar/Changes Foo/Bar/test.pl Foo/Bar/MANIFEST Foo/Bar/README </code> <p><tt>h2xs</tt> even writes you the stubs of your code which you can then just edit (a lot!). Once you have your basic structure you should then rename the Bar directory Foo-Bar-0.01 if you want to follow the accepted norms. <code> $ mv Bar Foo-Bar-0.01 </code> <p>By default the syntax in this tute is for *nix. On Win32 you will need to read and use \ instead of /. The Win32 equivalent of <tt>mv</tt> is <tt>rn</tt> or <tt>rename</tt>. If you are unfamiliar with shell commands see <a href="http://tachyon.perlmonk.org/tutorials/behind_the_gui_lives_the_shell.htm">Behind the GUI lives the Shell</a> for a just the facts overview. <p>Note that you just throw away the Foo dir :-) To avoid generating the extra directory you just <tt>h2xs -AX Bar</tt> but you will have to edit your Makefile.PL After this command it will have: <code> 'NAME' => 'Bar' # but you need 'NAME' => 'Foo::Bar' # so fix it! </code> <p>You should now have a proto-distro that looks like this: <code> Foo-Bar-0.01/Bar.pm Foo-Bar-0.01/Makefile.PL Foo-Bar-0.01/MANIFEST Foo-Bar-0.01/Changes Foo-Bar-0.01/test.pl Foo-Bar-0.01/README </code> <h3>Building a multi-module distribution</h3> <p>If you want to build a distribution that contains two modules like: <code> Foo::Bar # will install in Foo/Bar.pm Foo::Bar::Baz # will install in Foo/Bar/Baz.pm </code> <p>Then all you need is this structure (which you can't instantly get from h2xs): <code> Foo-Bar-0.01/Bar.pm Foo-Bar-0.01/Makefile.PL Foo-Bar-0.01/MANIFEST Foo-Bar-0.01/Changes Foo-Bar-0.01/test.pl Foo-Bar-0.01/README Foo-Bar-0.01/Bar/Baz.pm # in Bar.pm package Foo::Bar; # in Baz.pm package Foo::Bar::Baz; # in Makefile.PL WriteMakefile( 'NAME' => 'Foo::Bar', </code> <p>So as you can see all you need to do is make a <tt>Bar/</tt> directory in your root dir and place <tt>Baz.pm</tt> in this. If you want <tt>h2xs</tt> to write the <tt>Baz.pm</tt> stub.....don't bother! Simply do this: <code> $ cd Foo-Bar-0.01 $ mkdir Bar $ cp Bar.pm ./Bar/Baz.pm $ cd Bar $ perl -pi.bak -e 's/Foo::Bar/Foo::Bar::Baz/g' Baz.pm $ rm Baz.pm.bak </code> <p>As you can see all we have done is make a new directory called <tt>Bar/</tt> then copy Bar.pm into it renaming it on the fly to Baz.pm. We then use perl to do a quick inplace edit of the package name and voila. Of course you could use an editor but you do know perl right? On Win32 use <tt>mkdir</tt> and <tt>copy</tt> and <tt>del</tt> You also need to use " instead of ' for command line perl under Win32 which is a right royal pain as you have to \ your " if you want them in the script. <h3>[cpan://ExtUtils::ModuleMaker] or [cpan://Module::Starter] can replace h2xs</h3> These modules can replace the use of [h2xs] for pure perl modules and do a lot of the 'hard' work for you. See a review of [ExtUtils::ModuleMaker] by [simonflk] for details and a rather nifty script. [cpan://Module::Starter] installs a script that you use like: <code> module-starter --module=Foo::Bar,Foo::Bat \ --author="Andy Lester" --email=andy@petdance.com </code> <p>See its docs for more details. <h3>Tests</h3> <p>OK so you have written your modules. What about some unit tests. Tests are great because every time you modify you module you may break something ;-) If you write some good tests for the API then all you have to do after each edit is run the tests - if you have not broken anything all should be well. If you have broken something you can fix it before you embarass yourself publicly!. I find [Test] is quite adequate. If you want you can bundle a copy of [Test::More] or even [Test::Lincoln::Stein] in your distro to avoid this problem. Asking permission for [Test::More] would be politic. See the [CGI] distribution to see Lincoln Stein roll his own test suite and include it. If you want complex tests you can still have them just using [Test] (which is part of the standard distro so you don't have to bundle it): <code> use Test; BEGIN { plan tests => 42 } use Widget; ok(1) # module loaded OK my $w = new Widget; $reply = $w->method; @reply = $w->method; ok( $reply ); ok( @reply ); ok( $reply =~ m/something/ ); ok( $reply eq 'some string' ); ok( scalar @reply == 42 ); ok( join '', @reply eq 'some list of stuff' ); </code> <p>You have two choices with tests. You can have all the tests in one file called <tt>test.pl</tt> in the root dir of your package (the h2xs default) or you can place test in the <tt>t/</tt> dir. These test need to be called <tt>*.t</tt> for example you might have: <code> Foo-Bar-0.01/t/some_test.t Foo-Bar-0.01/t/test_this.t Foo-Bar-0.01/t/test_that.t </code> <p>You can make this structure from the standard <tt>h2xs</tt> output like this: <code> $ cd Foo-Bar-0.01 $ md t $ cp test.pl ./t/some_test.t $ cp test.pl ./t/other_test.t $ rm test.pl </code> <p>On Win32 you use <tt>del</tt> instead of <tt>rm</tt>. <h3>Packaging your Masterpiece</h3> <p>You will need a tar(1) prgram and gzip(1). You should have them on *nix. On Win32 the <a href="http://cygwin.com/">CYGWIN</a> distribution effectively gives you a UNIX console window (like the MSDOS console windows) with all the standard unix tools like tar and gzip. You package your distro like this: <code> $ tar -czf Foo-Bar-0.01.tar.gz Foo-Bar-0.01 # using CYGWIN you need to do it in two steps as the tar -z # option (which uses the tar gzip) produces broken distros # at least with my version of CYGWIN $ tar -cf Foo-Bar-0.01.tar Foo-Bar-0.01 $ gzip Foo-Bar-0.01.tar </code> <p>You can also <tt>make clean</tt> <tt>make distcheck</tt> <tt>make manifest</tt> and <tt>make dist</tt> to achieve a similar result. See <A HREF="http://www.perldoc.com/perl5.6.1/lib/ExtUtils/MakeMaker.html#Distribution-Support">ExtUtils::MakeMaker Distribution Support</A> for more details. I have problems with these under Win32 and <tt>nmake</tt> Anyway you are now the proud owner of <tt>Foo-Bar-0.01.tar.gz</tt> Test that all is ok like this: <code> $ tar -xzvf Foo-Bar-0.01.tar.gz $ cd Foo-Bar-0.01 $ perl Makefile.PL $ make $ make test $ make install </code> <p>When you call <tt>make test</tt> (or nmake on Win32) make looks for any tests to run. Both <tt>test.pl</tt> and all the <tt>t/*.t</tt> tests will run. Generally you have one or the other. [Test::Harness] is called by <tt>make</tt> to run all the <tt>t/*.t</tt> tests. <h3>make_manifest.pl</h3> <p>You will find that when you are playing with your distro you will repeat a number of steps over and over. I have a little custom script called <tt>make_manifest.pl</tt> which does a whole lot of things like: <ul> <li>clean out blib/ and all the other Makefile and make crap <li>remove any temp files like .bak files (or any other extensions like .pbp ~ etc) <li>cleans Win32 line endings to *nix standard (otherwise you will have install nightmares) <li>writes HTML files into html/ for all the pod (with CSS support) using Pod::HTML <li>writes a current MANIFEST </ul>You can get a copy of the script from the [cpan://CGI::Simple] distro (it expects to be in the <tt>misc/</tt> dir which is where you will find it. Don't forget the CSS if you use this script. <h3>Win32</h3> <p>I do most of my work on Win32 (some on Redhat and FreeBSD). You will need tar and gzip from somewhere to make your distributions. As noted the <a href="http://cygwin.com/">CYGWIN</a> distribution effectively gives you a UNIX console window (like the MSDOS console windows) with all the standard unix tools like tar and gzip. <p>Windows line endings and perl distributions are a bad combination. You will need to ensure that all the files in your distro have regular \n line endings not \r\n. I use my make_manifest.pl script to do this but you could write a little [File::Find] script to process your dirs. <p><tt>nmake()</tt> can be replaced by [cpan://Make.pm] which is a pure perl version of <tt>make()</tt>. I have not used this personally. You can install it <tt>ppm install make</tt> and [RTFM] if you want. <h3>Notes</h3> <p>Finally there are a few practical points. <ul> <li>If no one knows how to use it no one will. If there are no docs then I will have to RTFS to work out how to use it. Most people probably won't bother <li>Don't contaminate your user's namspace by Exporting ANYTHING by default (without good reason). Let them ask for the functions they want. Better still go OO. <li>Do write some decent tests <li>Do use some sort of CVS system to keep track of your distro as it develops. You may end up with Foo::Bar packages everywhere and have trouble finding the latest one. Worse you may patch old versions, etc, etc. Just zipping the distro up periodically with the date in the name can be invaluable ie Foo-Bar-0.01-01012002.tar.gz <li><tt>use Carp;</tt> [Carp|see Carp for why] and use the <tt>carp()</tt> and <tt>croak()</tt> methods instead of <tt>warn()</tt> and <tt>die()</tt> which will put these messages in the perspective of the caller rather than the module. <li><tt>use strict;</tt> and test with warnings <tt>use warnings; # 5.6 and up</tt> or <tt>$^W = 1</tt>. Don't leave $^W = 1 in you distro (your users may not appreciate your module telling them how bad their code is via its activation of gloabal warnings) <li>Remember to update $VERSION <li>Do write some pod. When you write the module Even you may forget how the API works given a little time </ul> <h3>Please sir, can I have some more</h3> <p>Sure Oliver, here you go: <ul> <li><a href="http://www.perldoc.com/perl5.6.1/pod/perlnewmod.html">perlnewmod</a> <li><A HREF="http://www.perldoc.com/perl5.6.1/pod/perlmod.html">perlmod</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/pod/perlmodlib.html">perlmodlib</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/pod/perlmodinstall.html">perlmodinstall</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/bin/h2xs.html">h2xs</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/lib/strict.html">strict</A>, <A HREF="Carp.html">Carp</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/lib/Exporter.html">Exporter</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/pod/perlpod.html">perlpod</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/lib/Test.html">Test</A> <li><A HREF="http://www.perldoc.com/perl5.6.1/lib/ExtUtils/MakeMaker.html">ExtUtils::MakeMaker</A> </ul> <p>Good luck, enjoy and share. <p>Thanks to [Juerd] for correcting a Win32 error <tt>s/md/mkdir/g</tt> and noting my CYGWIN tar -czf workaround. Added <tt>make dist</tt> thanks to [jmcnamara]. Added note on research at start thanks to [ybiC] Added [perlnewmod] thanks to [simonflk] (I had forgotten what it was called). R&D links from [perlnewmod] in true web style :-)