> dzil

Choose Your Own Tutorial

page source | index | page 13

Building a Dist from Scratch

Starting a distribution with Dist::Zilla is easy. It provides a system for "minting" new distributions, much like `h2xs`, Module::Starter, or other similar tools. Unlike those, it is extremely customizable and can be made to do much more than just build a bunch of files for you to edit.

Install Dist::Zilla

For the tasks below, you'll want to:

The rest of this document assumes that you haven't made a custom minting profile, meaning that you haven't got anything in ~/.dzil/profiles. If you do, and the behavior you see isn't what's described below, you might want to move that directory out of the way, or read more about how minting profiles work.

Run dzil new

It's easy:

  $ dzil new Your::Library
  [DZ] making target dir ./Your-Library
  [DZ] writing files to /Users/rjbs/tmp/Your-Library
  [DZ] dist minted in ./Your-Library

If you haven't set up any special minting configuration, you'll have two files.

./Your-Library/dist.ini:

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
9: 
 
name = Your-Library
author = E. Xavier Ample <example@cpan.org>
license = Perl_5
copyright_holder = E. Xavier Ample <example@cpan.org>
copyright_year = 2010

version = 0.001

[@Basic]
 

./Your-Library/lib/Your/Library.pm

1: 
2: 
3: 
4: 
5: 
 
use strict;
use warnings;
package Your::Library;

1;
 

There isn't a lot of other boilerplate, because the default minter assumes that you're going to go whole hog and use lots of plugins to build everything else you might need. It doesn't add those plugins to your dist.ini for you, though. The only plugins it does add are the ones in the Basic bundle, so that the other dzil commands work. You'll have to choose the other plugins yourself.

It's crucial that you understand what's in that "@Basic" bundle. That is almost the entire configuration that will be used to build your distribution. If you add more plugins that conflict with the ones in the basic bundle, but you had no idea what was in "@Basic", you will be confused.

Write some code and some tests

This bit is just like it would be with anything else: do the hard work that will make releasing the dist worthwhile. Dist::Zilla, sadly, will not write your code or your code's tests for you.

You'll also want to write documentation, of course, but Dist::Zilla can help make that less painful. Choose an appropriate set of plugins, test, and release!

You can fork and improve this documentation on GitHub!