1Dist::Zilla::Tutorial(3U)ser Contributed Perl DocumentatiDoinst::Zilla::Tutorial(3)
2
6 Dist::Zilla::Tutorial - how to use this "Dist::Zilla" thing
7
9 version 6.023
10
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 Dist::Zilla builds distributions to be uploaded to the CPAN. That
17 means that the first thing you'll need is some code.
18 Once you've got that, you'll need to configure Dist::Zilla. Here's a
20 simple dist.ini:
21 name = Carbon-Dating
23 version = 0.003
24 author = Alan Smithee <asmithee@example.org>
25 license = Perl_5
26 copyright_holder = Alan Smithee
27 [@Basic]
29 [Prereqs]
31 App::Cmd = 0.013
32 Number::Nary = 0
33 Sub::Exporter = 0.981
34 The topmost section configures Dist::Zilla itself. Here are some of
36 the entries it expects:
37 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 copyright_holder - (required) the entity holding copyright on the dist
45 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 # ABSTRACT: a totally cool way to do totally great stuff
52 The main modules is the module that shares the same name as the dist,
54 in general.
55 Named sections load plugins, with the following rules:
57 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 The values inside a section are given as configuration to the plugin.
65 Consult each plugin's documentation for more information.
66 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
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 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
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 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 $ dzil build
94 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 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 $ dzil test
104 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
110 This is really more of a sketchy overview than a spec.
111 First, all the plugins that perform the BeforeBuild perform their
113 "before_build" tasks.
114 The build root (where the dist is being built) is made.
116 The FileGatherers gather and inject files into the distribution, then
118 the FilePruners remove some of them.
119 All the FileMungers get a chance to muck about with each file, possibly
121 changing its name, content, or installability.
122 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 Everything is just about done. The files are all written out to disk
128 and the AfterBuild plugins do their thing.
129
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 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
144 dzil
145
147 Ricardo SIGNES 😏 <rjbs@semiotic.systems>
148
150 This software is copyright (c) 2021 by Ricardo SIGNES.
151 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.
154perl v5.34.0 2021-07-22 Dist::Zilla::Tutorial(3)