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.
A small cog in the Perl machine, I'm a happy Perl developer and have some CPAN modules here and there.
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.
Thank you for clarifying that. I actually made a mistake - it was [@Classic]. I've corrected this in my post.
What puzzles me, is that this requirement is not mentioned on dzil.org, just in Dist::Zilla::Tutorial on CPAN. If one would not read the tutorial, but instead relies on the documentation provided on dzil.org (like me), one would not be aware.
I might be nitpicking here but I hope to be the only one encountering this problem.
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.