Where can I find a concise guide to converting an existing CPAN module to use Dist::Zilla?

Question

I have read, at various times, both the documentation and a number of blog posts on Dist::Zilla. I have never felt confidence in my understanding of it.

In response to another question, @Ether raised the possibility of converting Crypt-SSLeay to use Dist::Zilla.

So, where can I find a concise guide showing me how to convert an existing CPAN module to use Dist::Zilla? Does the question even make sense?

Update:

The Makefile.PL for Crypt-SSLeay does a lot of work (a lot of it seems unnecessary and I am trying to prune it) to find platform specific include and lib directories, to deduce the version of OpenSSL on the machine where it is being installed. How can I include that functionality if I use Dist::Zilla?

Answer 1

These are the sites I have found the most helpful so far, as I'm in the middle of converting a CPAN distribution I comaintain to use it, as a learning exercise. I'm not there yet, but I haven't hit any super tricky bits so far!

• The official Dist::Zilla site's Choose your own tutorial's guide to Converting an existing distribution
• CPAN Dist::Zilla::Tutorial
• Dave Golden's Why I'm using Dist::Zilla

Also, the #toolchain and #distzilla channels on irc.perl.org are full of helpful people, including the authors for Dist::Zilla and other related tools.

Answer 2

The Dist::Zilla Choose Your Own Tutorial has a page on Converting a Dist to Dist::Zilla. One thing it doesn't mention there is my VersionFromModule plugin, which is useful if you want to replicate the way many people use MakeMaker, with the distribution taking its version number from the main module. (Many people use dzil the other way, with the version in dist.ini and a plugin to stick it into the module, but either way works.)

If I need a more complex Makefile.PL than the one dzil generates, I switch to Module::Build and use my ModuleBuild::Custom plugin, which lets me write my own Build.PL and have dzil drop in metadata like the prerequisites.

The MakeMaker::Awesome plugin lets you do something similar with Makefile.PL, but it wasn't quite what I wanted. Instead, I wrote a MakeMaker::Custom plugin that works much like my ModuleBuild::Custom plugin. The big advantage of MakeMaker::Custom over MakeMaker::Awesome is that it makes it possible to build your dist for testing purposes without having to do dzil build. For an XS module that has to be rebuilt after every minor change, this is a big win.