1Dist::Zilla::Tutorial(3U)ser Contributed Perl DocumentatiDoinst::Zilla::Tutorial(3)
2
3
4

NAME

6       Dist::Zilla::Tutorial - how to use this "Dist::Zilla" thing
7

VERSION

9       version 4.300002
10

SYNOPSIS

12       Dist::Zilla builds distributions to be uploaded to the CPAN.  That
13       means that the first thing you'll need is some code.
14
15       Once you've got that, you'll need to configure Dist::Zilla.  Here's a
16       simple dist.ini:
17
18         name    = Carbon-Dating
19         version = 0.003
20         author  = Alan Smithee <asmithee@example.org>
21         license = Perl_5
22         copyright_holder = Alan Smithee
23
24         [@Classic]
25
26         [Prereq]
27         App::Cmd          = 0.013
28         Number::Nary      = 0
29         Sub::Exporter     = 0.981
30
31       The topmost section configures Dist::Zilla itself.  Here are some of
32       the entries it expects:
33
34         name     - (required) the name of the dist being built
35         version  - (required) the version of the dist
36         abstract - (required) a short description of the dist
37         author   - (optional) the dist author (you may have multiple entries for this)
38         license  - (required) the dist license; must be a Software::License::* name
39
40         copyright_holder - (required) the entity holding copyright on the dist
41
42       Some of the required values above may actually be provided by means
43       other than the top-level section of the config.  For example,
44       VersionProvider plugins can set the version, and a line like this in
45       the "main module" of the dist will set the abstract:
46
47         # ABSTRACT: a totally cool way to do totally great stuff
48
49       The main modules is the module that shares the same name as the dist,
50       in general.
51
52       Named sections load plugins, with the following rules:
53
54       If a section name begins with an equals sign, the rest of the section
55       name is left intact and not expanded.  If the section name begins with
56       an at sign, it is prepended with 'Dist::Zilla::PluginBundle::'.
57       Otherwise, it is prepended with 'Dist::Zilla::Plugin::'.
58
59       The values inside a section are given as configuration to the plugin.
60       Consult each plugin's documentation for more information.
61
62       The "Classic" bundle, seen above, builds a fairly normal distribution.
63       It rewrites tests from ./xt, adds some information to POD, and builds a
64       Makefile.PL.  For more information, you can look at the docs for
65       Dist::Zilla::PluginBundle::Classic and see the plugins it includes.
66

BUILDING YOUR DIST

68       Maybe we're getting ahead of ourselves, here.  Configuring a bunch of
69       plugins won't do you a lot of good unless you know how to use them to
70       build your dist.
71
72       Dist::Zilla ships with a command called dzil that will get installed by
73       default.  While it can be extended to offer more commands, there are
74       two really useful ones:
75
76         $ dzil build
77
78       The "build" command will build the distribution.  Say you're using the
79       configuration in the SYNOPSIS above.  You'll end up with a file called
80       Carbon-Dating-0.004.tar.gz.  As long as you've done everything right,
81       it will be suitable for uploading to the CPAN.
82
83       Of course, you should really test it out first.  You can test the dist
84       you'd be building by running another dzil command:
85
86         $ dzil test
87
88       This will build a new copy of your distribution and run its tests, so
89       you'll know whether the dist that "build" would build is worth
90       releasing!
91

HOW BUILDS GET BUILT

93       This is really more of a sketchy overview than a spec.
94
95       First, all the plugins that perform the BeforeBuild perform their
96       "before_build" tasks.
97
98       The build root (where the dist is being built) is made.
99
100       The FileGatherers gather and inject files into the distribution, then
101       the FilePruners remove some of them.
102
103       All the FileMungers get a chance to muck about with each file, possibly
104       changing its name, content, or installability.
105
106       Now that the distribution is basically set up, it needs an install
107       tool, like a Makefile.PL.  All the InstallTool-performing plugins are
108       used to do whatever is needed to make the dist installable.
109
110       Everything is just about done.  The files are all written out to disk
111       and the AfterBuild plugins do their thing.
112

THE GLORIOUS FUTURE

114       In the glorious future of Dist::Zilla, another phase in the process
115       will exist: "release".  By running "dzil release", you'll be able to
116       test your distribution, build a tarball of it, and upload it to the
117       CPAN.  Plugins will be able to do things like check your version
118       control system to make sure you're releasing a new version and that you
119       tag the version you've just uploaded.  It will update your Changelog
120       file, too, making sure that you don't need to know what your next
121       version number will be before releasing.
122

AUTHOR

124       Ricardo SIGNES <rjbs@cpan.org>
125

127       This software is copyright (c) 2011 by Ricardo SIGNES.
128
129       This is free software; you can redistribute it and/or modify it under
130       the same terms as the Perl 5 programming language system itself.
131
132
133
134perl v5.12.4                      2011-09-22          Dist::Zilla::Tutorial(3)
Impressum