Dist::Zilla, cpanhacker, do you use it??!

Dist::Zilla, cpan hacker, do you use it?

If not, you should. Full stop.

So I've been reading about Dist::Zilla (dzil) for a while now. The first articles didn't really convince me too much. Yes, it's a nice tool, but why would I want to use it? Ok, to save time. Right. But how do I use it the first time? I need a config file. Ok where do I get (a sane) one?

Then I read a clear walk-through example of a Dist::Zilla config by Dave Rolsky. So, the quick start route was clear. Copy/paste the dist.ini file and try it.

Except, the file in that blog post contains so much stuff (read: additional plugins required) that is not practical to use as a first dist.ini config.

Basic premise

It's that you have to have a module/class that you want to upload to the CPAN, and you want to save yourself all the "package-wrapping" activities that a CPAN distribution needs. That is were dzil shines.

Start-using-Dist::Zilla-in-2-minutes guide

Good, you're on your way to spend countless hours less on maintaining your CPAN stuff.

  • First things first: write the thing that you want to package and upload to CPAN. Fatto? Bene.
  • So you probably have a lib folder with your class and a t folder with the test scripts for your class. Good.
  • Then, usually if you want to package everything for CPAN, you need to add a MANIFEST, a README, INSTALL, Changes, possibly a LICENSE, etc… Forget about those!
  • Copy paste the following into a dist.ini file:
    ; Everything starting with ';' is a comment
    name    = Your-Awesome-Module
    author  = Joe J. Hacker <jjhacker@example.org>
    license = Perl_5
    copyright_holder = Joe J. Hacker
    copyright_year   = 2010
    version = 0.01
    bugtracker.web    = http://rt.cpan.org/NoAuth/Bugs.html?Dist=Your-Awesome-Module
    bugtracker.mailto = bug-your-awesome-module@rt.cpan.org
    ; If you have a repository...
    ;repository.url    = git://github.com/jjhacker/your-awesome-module.git
    ;repository.web    = http://github.com/jjhacker/your-awesome-module
    ;repository.type   = git
    ; You have to have Dist::Zilla::Plugin::<Name> for these to work
    ;DBI = 1.600
    ;SomeOtherModule = 0
    [Prereq / TestRequires]
    Test::More = 0
    ; If you're using git, this is interesting
    ; You need to install Dist::Zilla::PluginBundle::Git
  • Add the following line at the top of your main class (.pm) file:
    # ABSTRACT: Supercool generator of twisty little passages, all alike
  • Run dzil build

That's it! The build command will do everything for you. When I realized how quick this tool makes my CPAN activities, I decided I had to try to convince some more people out there. Until I didn't really try it, I wasn't convinced 100%. Now I definitely am. Life's just too short. Use DZIL.

There's also a release command, that will also send your generated distribution archive to the CPAN directly. I couldn't get that to work. I remember there was some kind of dot file I had to write my credentials to before I could release, but I couldn't find the details today. If anyone knows, please comment here… :-)

Leave a Reply

Your email address will not be published. Required fields are marked *