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.024
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

PERL VERSION

73       This module should work on any version of perl still receiving updates
74       from the Perl 5 Porters.  This means it should work on any version of
75       perl released in the last two to three years.  (That is, if the most
76       recently released version is v5.40, then this module should work on
77       both v5.40 and v5.38.)
78
79       Although it may work on older versions of perl, no guarantee is made
80       that the minimum required version will not be increased.  The version
81       may be increased for any reason, and there is no promise that patches
82       will be accepted to lower the minimum required perl.
83

BUILDING YOUR DIST

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

HOW BUILDS GET BUILT

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

RELEASING YOUR DIST

131       By running "dzil release", you'll test your distribution, build a
132       tarball of it, and upload it to the CPAN.  Plugins are able to do
133       things like check your version control system to make sure you're
134       releasing a new version and that you tag the version you've just
135       uploaded.  It can also update your Changelog file, too, making sure
136       that you don't need to know what your next version number will be
137       before releasing.
138
139       The final CPAN release process is implemented by the UploadToCPAN
140       plugin. However you can replace it by your own to match your own
141       (company?) process.
142

SEE ALSO

144       dzil
145

AUTHOR

147       Ricardo SIGNES 😏 <rjbs@semiotic.systems>
148
150       This software is copyright (c) 2021 by Ricardo SIGNES.
151
152       This is free software; you can redistribute it and/or modify it under
153       the same terms as the Perl 5 programming language system itself.
154
155
156
157perl v5.34.0                      2022-01-21          Dist::Zilla::Tutorial(3)
Impressum