Dist::Zilla::Tutorial(3pm)

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 6.012
10

SYNOPSIS

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

BUILDING YOUR DIST

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

HOW BUILDS GET BUILT

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

RELEASING YOUR DIST

119       By running "dzil release", you'll test your distribution, build a
120       tarball of it, and upload it to the CPAN.  Plugins are able to do
121       things like check your version control system to make sure you're
122       releasing a new version and that you tag the version you've just
123       uploaded.  It can also update your Changelog file, too, making sure
124       that you don't need to know what your next version number will be
125       before releasing.
126
127       The final CPAN release process is implemented by the UploadToCPAN
128       plugin. However you can replace it by your own to match your own
129       (company?) process.
130

AUTHOR

135       Ricardo SIGNES 😏 <rjbs@cpan.org>
136

COPYRIGHT AND LICENSE

138       This software is copyright (c) 2018 by Ricardo SIGNES.
139
140       This is free software; you can redistribute it and/or modify it under
141       the same terms as the Perl 5 programming language system itself.
142
143
144
145perl v5.30.0                      2019-07-26          Dist::Zilla::Tutorial(3)