Switching to Dist::Zilla - a usage report

For a while there has been a problem in one of my modules - the tests for Postscript::TextDecode make use of Test::Most which it turned out most CPAN testers don't use by default. That's fair. It was on my list of things to fix, but never with high priority.

Shortly after YAPC::EU::2010 I received a RT request from Andreas Koenig alerting me to the issue. At YAPC I had heard about this utility called Dist::Zilla which was supposed to make the managing of distributions a lot easier.

Off to CPAN. D::Z took a while to install but the install itself had no problems. I started reading the CPAN page and read Dist::Zilla::Tutorial. Since this was however limited, I directed my attention to the tutorial on dzil.org.

This tutorial has the style of a 'make your own adventure' children's book which was amusing. I found out that I could either start anew or switch my current distrubution over.

I decided to start anew and ran

$ dzil setup

to configure dzil (the Dist::Zilla::App commandline utility) - it creates ~/dzil.ini.
followed by

$ dzil new Postscript-TextDecode

which created the Postscript-TextDecode directory for me, with in it dzil.ini and lib/Postscript/TextDecode.pm.

After that I pasted my existing code into TextDecode.pm and created t/Postscript-TextDecode.t. I could remove $VERSION since I now define that in dist.ini.

After some fiddling, $ dzil test did the testing and $ dzil release uploaded a gzipped tarball onto the PAUSE server.

In between all this, I encountered the following hurdles:

  • dzil test and dzil build won't work without [@Classic] in the dist.ini. I do not know why.
  • the documentation on dzil.org seems...incomplete, or at least appears to assume the reader has in-depth knowledge of the distribution creation process, while I am relatively new to this

Still, it did not cost me huge amounts of time and in the long run this utility should really simplify the creation and maintenance of new modules. Not bad at all. And from what I've seen on CPAN, it's very easy to extend.

If I've missed obvious things, please direct me so I may learn.


You can't build and test without @Basic because Dist::Zilla is highly pluggable and does pretty much *nothing* by default.

The basic plugin does things like gathering files in your directory, including MakeMaker etc. These things are required for having any distro at all, you can't build and test without something like that.

But because of that pluggability you can replace pretty much anything in dzil, e.g. I replace the MakeMaker step in some of my distros.

I think the documentation could be a little bit clearer as well. I had to do some digging around and eventually, as I got started, I just did so by copying someone else's dist.ini and tweaking it from there.

Having said that, it has saved me so much time in other ways, that I've found the investment in time to be well worth it.

Yes, that documentation should be on the CPAN, not just on the website. This has been pointed out a lot, and I think rjbs has some plan to move it there.

In general the docs are confusing, at least they were when I last read them.

Leave a comment

About Job van Achterberg

user-pic A small cog in the Perl machine, I'm a happy Perl developer and have some CPAN modules here and there.