<B>BEFORE YOU GET STARTEDB>: Maybe you should be looking at the web-based
tutorial instead. Its more complete. <http://dzil.org/tutorial/start.html>
Dist::Zilla builds distributions to be uploaded to the CPAN. That means that
the first thing youll need is some code.
Once youve got that, youll need to configure Dist::Zilla. Heres a simple
name = Carbon-Dating
version = 0.003
author = Alan Smithee <email@example.com>
license = Perl_5
copyright_holder = Alan Smithee
App::Cmd = 0.013
Number::Nary = 0
Sub::Exporter = 0.981
The topmost section configures Dist::Zilla itself. Here are some of the
entries it expects:
name - (required) the name of the dist being built
version - (required) the version of the dist
abstract - (required) a short description of the dist
author - (optional) the dist author (you may have multiple entries for this)
license - (required) the dist license; must be a Software::License::* name
copyright_holder - (required) the entity holding copyright on the dist
Some of the required values above may actually be provided by means other than
the top-level section of the config. For example,
VersionProvider plugins can
set the version, and a line like this in the main module of the dist will set
# ABSTRACT: a totally cool way to do totally great stuff
The main modules is the module that shares the same name as the dist, in
Named sections load plugins, with the following rules:
If a section name begins with an equals sign (=), the rest of the section
name is left intact and not expanded. If the section name begins with an at
sign (@), it is prepended with Dist::Zilla::PluginBundle::. Otherwise,
it is prepended with Dist::Zilla::Plugin::.
The values inside a section are given as configuration to the plugin. Consult
each plugins documentation for more information.
The Basic bundle, seen above, builds a fairly normal distribution. It
rewrites tests from ./xt, adds some information to POD, and builds a
Makefile.PL. For more information, you can look at the docs for
@Basic and see the plugins it includes.
Maybe were getting ahead of ourselves, here. Configuring a bunch of plugins
wont do you a lot of good unless you know how to use them to build your dist.
Dist::Zilla ships with a command called dzil that will get installed by
default. While it can be extended to offer more commands, there are two really
$ dzil build
The build command will build the distribution. Say youre using the
configuration in the SYNOPSIS above. Youll end up with a file called
Carbon-Dating-0.004.tar.gz. As long as youve done everything right, it
will be suitable for uploading to the CPAN.
Of course, you should really test it out first. You can test the dist youd be
building by running another dzil command:
$ dzil test
This will build a new copy of your distribution and run its tests, so youll
know whether the dist that build would build is worth releasing!
This is really more of a sketchy overview than a spec.
First, all the plugins that perform the
BeforeBuild perform their before_build
The build root (where the dist is being built) is made.
The FileGatherers gather and inject files
into the distribution, then the FilePruners
remove some of them.
All the FileMungers get a chance to muck about
with each file, possibly changing its name, content, or installability.
Now that the distribution is basically set up, it needs an install tool, like a
Makefile.PL. All the
InstallTool-performing plugins are used to
do whatever is needed to make the dist installable.
Everything is just about done. The files are all written out to disk and the
AfterBuild plugins do their thing.