|P is for Practical|
On packaging modulesby nothingmuch (Priest)
|on Nov 23, 2004 at 10:39 UTC||Need Help??|
I've been doing two things, recently:
Update: Looking at this again, I'd like to stress that this is not a tutorial or a howto on packaging. It's a number issues that I consider either important or beneficial when incorperated into your packaging workflow.
The toolsThis is not really a step into packaging modules correctly, but a prerequisite. Use Module::Build. It's shiny, it's sexy and it's future proof. It's also backwards compatible, with traditional Makefile.PL generation. If you have a reason, use ExtUtils::MakeMaker instead.
Update: Both Zaxo and Corion expressed concern about my advocation of Module::Build. They explain a problem with the faked Makefile.PL interface to it (which IMHO is sillly - if you make a Makefile at least remove the dependancy from M::B).
Anyway, I sort of take it back. Read their posts, see what they have to say. I bought M::B's story, but I may be an idiot. Ciao!
From here on, unless noted, instances of ./Build or Build.PL are canonical to, and can be replaced by make or Makefile.PL if you went the ExtUtils::MakeMaker way. Keep in mind that Michael Schwern, MakeMaker's maintainer promotes replacing MakeMaker with Module::Build.
What goes in
The first step of properly packaging a module has to do with what goes in, and what stays out.
A confusing aspect of that is that what goes into your src dir is not necessarily what goes into your tarball. This is where we'll start.
Enter ./Build distBoth Module::Build and ExtUtils::MakeMaker provide a tool to construct a properly compressed, well defined, signed, manifested, META.yml'd tar ball for you, based on your MANIFEST file.
Given a proper MANIFEST, run perl Build.PL and then ./Build dist. If you want a SIGNATURE file generated, put the argument sign => 1, in your Build.pl args. If you want a Makefile.PL, put a create_makefile_pl => 'traditional', in there too (but make sure Makefile.PL is mentioned in your MANIFEST!).
MANIFESTSo, what goes into the dist is really what's in the MANIFEST, right? Do we really want to edit that? No.
Instead, write a MANIFEST.SKIP file. My generic one looks like this:
The first line removes the pesky OSX .DS_Store stuff. The next 3 lines take care of skipping build cruft. Any editor backup files are skipped, as are vim swap files. Devel::Cover dirs are also ommitted, and lastly, so is the MANIFEST.SKIP file itself. I sometimes add \.tar\.gz$ to the mess, to make sure that dists are not accidentally added to the manifest too.
Now that we defined what we want out of the manifest, lets get our tool to generate one for us: perl Build.pl; ./Build manifest And now, any file that doesn't match the patterns in MANIFEST.SKIP is mentioned in there.
General KwaliteeAfter we define what goes in, we have to make sure it isn't garbage.
Respect your eldersLets start with the bare essentials. Here is an example Build.PL:
That looks well behaved, right? Lets see what's wrong with it:
Basic sanityTest::Prereq was mentioned earlier. It has some siblings. You can write tests which make sure your packaging, and not only your code, is good.
It should be noted that Test::Prereq might not apply to modules you optionally use in tests. skip_all is often used when these modules aren't available. Test::WithoutModule helps you check if that code works correctly.
TestsNow that we've touched packaging quality of tests, are you writing real tests too? These are more important you know.
cpansmoke will complain if you include no t/ dir. It will send you an email saying "would you please get up off your ass and at least write a tests that does use_ok("Your::Module")".
This has become an integral part of a proper distribution, even if it doesn't really do any real testing. At least try to look like you're trying.
VersioningModule::Build will look in the lib/ dir for a file that implements the module you named in the Build.PL script.
From there the value of $VERSION is extracted, and used as the distribution version.
Versions are important because they imply compatibility, they define dependancies, and so forth. On the CPAN there is a general format.
Summary: Source tree overviewYour tarball, when finished, should make sense. Here is what a proper one looks like, with all the necessariy, desired, and reccommended files in place.
And your source dir should be:
Build dist and friends should also generate:
And ofcourse, there is cruft:
That last part is there, but you shouldn't really care about it. Manipulate your MANIFEST.SKIP if they bother you.
ReferencesModule::Build is the tool to use for your package making needs.
Module::Signature makes cryptographically signed MANIFEST like files.
The CPAN testing service is an experiement to try and measure package quality.
http://testers.cpan.org run tests for you, on many platforms and perls, when you release modules with tests.
http://qa.perl.org is a website concerned with the quality of perl and CPAN in general. It's an interesting starting point.
AddendumI don't believe in h2xs. It's yucky. Test::Tutorial has a nicer way to start out. Aside from that, all that's important is that you have the proper sections in your pods. Test::Pod, and podchecker will both help you with that.
That doesn't mean you shouldn't see what h2xs is outputting, and understand what the mess it makes is.
zz zZ Z Z #!perl