What tools should you use to create a CPAN distribution?

Reading time: 3 minutes

Recently, I answered a question on the module-authors mailing list about the best tool for building a CPAN distribution. Whole generations of tools have come and gone since I first read Writing Perl Modules for CPAN and the state of the art slash best practices slash fads have changed.

Since I first released a distribution to CPAN in the early 2000’s, I’ve gotten familiar with the gory details of most of the toolchain. I maintain Module::Build, I’ve contributed to Dist::Zilla, and I know the guts of ExtUtils::MakeMaker (pretty well) and Module::Install (at least a little). Based on that experience, I think I can offer a (hopefully) objective view of the tradeoffs in using these different tools.

  • ExtUtils::MakeMaker (aka EU::MM) – this is the “standard” but it is annoying to work with and tricky to customize (unless you are a Makefile expert). Prolific CPAN authors seem to prefer Module::Install or Dist::Zilla to avoid dealing with EU::MM directly.
  • Module::Build (aka M::B) – this is the ‘pure perl’ alternative. It is very easy to customize compared to EU::MM but you can’t always rely on users having a new enough M::B for any given feature unless you target Perl 5.10.1 (which added the ability for CPAN/CPANPLUS to bootstrap tools you need *before* running Build.PL)
  • Module::Install (aka M::I) – this gives a nicer API than EU::MM, but it uses EU::MM behind the scenes to do the work. It is different in that it bundles itself with the distribution, avoiding bootstrap problems. This is viewed as a benefit by some and as a burden or design defect by others. If existing M::I plugins don’t meet your needs, it is a bit harder to understand how to customize M::I compared to M::B.
  • Dist::Zilla (aka D::Z) – this is a complete distribution management tool, not just a builder. It tries to let authors write as little repetitive scaffolding and documentation as possible and then generates a “release ready” distribution from templates and other configuration. Think of it as a “distribution compiler”. In the generation process, it will create your Makefile.PL (EU::MM) or your Build.PL (M::B) for you. (It’s your choice which one you prefer.)

The original question was about “creating CPAN packages”. All four tools will let you “create” a distribution tarball that you can upload to CPAN. For the first three, you have to create a Makefile.PL or Build.PL and then use the tool you select to create the tarball. With D::Z, you create a “dist.ini” file and D::Z creates the tarball itself (generating the Makefile.PL or Build.PL) without relying on EU::MM or M::B to do the work.

D::Z also can create a new “boilerplate” distribution, similar to Module::Starter or h2xs (or any of various other distribution boilerplate tools on CPAN). The other three do not.

I have switched to Dist::Zilla and many other prolific CPAN authors have as well. (It was written by RJBS, the most prolific CPAN author of all, so he has some perspective on what is the easiest thing for managing CPAN distributions). If you are interested in learning Dist::Zilla, the online tutorial is the way to go.

If you don’t want a complete solution, the question is how much customization do you need (to the test process, distribution packaging process, etc.)? If the answer is “a lot”, then I would recommend M::B. If the answer is “very little”, then I would recommend M::I. Avoid direct use of EU::MM entirely.

•      •      •

If you enjoyed this or have feedback, please let me know by or