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
  
  [@Basic]
  [InstallGuide]
  [MetaJSON]
  
  [MetaResources]
  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
  ;[PodWeaver]
  ;[NoTabsTests]
  ;[EOLTests]
  ;[Signature]
  ;[CheckChangeLog]
  
  [Prereq]
  ;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
  ;[@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… :-)