Section 19.3. Preparing Your Distribution


19.3. Preparing Your Distribution

Once you've gotten your module name settled and you've tested your module with its new name (if needed), you should ensure your distribution is ready for prime time. While this is similar to releasing a distribution in-house, as described in Chapter 16, you might want to ensure a few additional things about your distribution:

  • Create a README file. This file is automatically extracted to a separate file on the CPAN archives and lets someone view or download just the key facts about your distribution before fetching or unpacking the rest.

  • Make and test your Makefile.PL or Build.PL. Modules without a Makefile.PL are accepted via PAUSE to go into the CPAN but usually get a grimace from those of us who download your stuff, because we might have to figure out how to build and install your distribution.

  • Bring your MANIFEST up to date. If you add files that should be part of the distribution, they also need to be in the MANIFEST. One quick trick is to clean things up as you would want them in the distribution, and then invoke make manifest, which updates the MANIFEST file to be exactly what you are holding at the moment.[*]

    [*] If make manifest adds too many files, you can create a MANIFEST.SKIP file that has a set of Perl regular expressions that tells make manifest which files to ignore. Once you have that file, make manifest will remove from MANIFEST files that match those patterns.

  • Have a logical distribution version number. The Makefile.PL file should specify either a VERSION value or a VERSION_FROM value. If you have a single module (such as a .pm file) in your distribution, it's usually best to grab the version number from there with VERSION_FROM. If you have multiple files, either designate one of them as the one you'll always update just before a new release or use the VERSION within the Makefile.PL instead. Also keep in mind that your version number must always increase numerically for newer versions of your distribution. (After Version 1.9, the next release can't be Version 1.10, because even if you're calling it "version one point ten," it's still merely 1.1 to the tools that compare version numbers.)

  • Have tests! Reread Chapter 17 if you must. There's nothing that builds more confidence in an installed distribution than at least a few dozen tests that are run during the installation phase. If you're not adding a test for each bug that you find, how do you know the bug is fixed?

  • Invoke make disttest , which builds a distribution archive of everything in MANIFEST, unpacks the archive into a separate directory, and then runs the tests on your distribution. If that doesn't work for you, you can't expect it to work for anyone else who downloads your distribution from the CPAN.




Intermediate Perl
Intermediate Perl
ISBN: 0596102062
EAN: 2147483647
Year: N/A
Pages: 238

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net