Dist::Zilla(3pm)

1Dist::Zilla(3)        User Contributed Perl Documentation       Dist::Zilla(3)
2
3
4

NAME

6       Dist::Zilla - distribution builder; installer not included!
7

VERSION

9       version 6.012
10

DESCRIPTION

12       Dist::Zilla builds distributions of code to be uploaded to the CPAN.
13       In this respect, it is like ExtUtils::MakeMaker, Module::Build, or
14       Module::Install.  Unlike those tools, however, it is not also a system
15       for installing code that has been downloaded from the CPAN.  Since it's
16       only run by authors, and is meant to be run on a repository checkout
17       rather than on published, released code, it can do much more than those
18       tools, and is free to make much more ludicrous demands in terms of
19       prerequisites.
20
21       If you have access to the web, you can learn more and find an
22       interactive tutorial at dzil.org <http://dzil.org/>.  If not, try
23       Dist::Zilla::Tutorial.
24

ATTRIBUTES

26   name
27       The name attribute (which is required) gives the name of the
28       distribution to be built.  This is usually the name of the
29       distribution's main module, with the double colons ("::") replaced with
30       dashes.  For example: "Dist-Zilla".
31
32   version
33       This is the version of the distribution to be created.
34
35   release_status
36       This attribute sets the release status to one of the CPAN::META::Spec
37       <https://metacpan.org/pod/CPAN::Meta::Spec#release_status> values:
38       'stable', 'testing' or 'unstable'.
39
40       If the $ENV{RELEASE_STATUS} environment variable exists, its value will
41       be used as the release status.
42
43       For backwards compatibility, if $ENV{RELEASE_STATUS} does not exist and
44       the $ENV{TRIAL} variable is true, the release status will be 'testing'.
45
46       Otherwise, the release status will be set from a ReleaseStatusProvider,
47       if one has been configured.
48
49       For backwards compatibility, setting "is_trial" true in dist.ini is
50       equivalent to using a "ReleaseStatusProvider".  If "is_trial" is false,
51       it has no effect.
52
53       Only one "ReleaseStatusProvider" may be used.
54
55       If no providers are used, the release status defaults to 'stable'
56       unless there is an "_" character in the version, in which case, it
57       defaults to 'testing'.
58
59   abstract
60       This is a one-line summary of the distribution.  If none is given, one
61       will be looked for in the "main_module" of the dist.
62
63   main_module
64       This is the module where Dist::Zilla might look for various defaults,
65       like the distribution abstract.  By default, it's derived from the
66       distribution name.  If your distribution is Foo-Bar, and lib/Foo/Bar.pm
67       exists, that's the main_module.  Otherwise, it's the shortest-named
68       module in the distribution.  This may change!
69
70       You can override the default by specifying the file path explicitly,
71       ie:
72
73         main_module = lib/Foo/Bar.pm
74
75   license
76       This is the Software::License object for this dist's license and
77       copyright.
78
79       It will be created automatically, if possible, with the
80       "copyright_holder" and "copyright_year" attributes.  If necessary, it
81       will try to guess the license from the POD of the dist's main module.
82
83       A better option is to set the "license" name in the dist's config to
84       something understandable, like "Perl_5".
85
86   authors
87       This is an arrayref of author strings, like this:
88
89         [
90           'Ricardo Signes <rjbs@cpan.org>',
91           'X. Ample, Jr <example@example.biz>',
92         ]
93
94       This is likely to change at some point in the near future.
95
96   files
97       This is an arrayref of objects implementing Dist::Zilla::Role::File
98       that will, if left in this arrayref, be built into the dist.
99
100       Non-core code should avoid altering this arrayref, but sometimes there
101       is not other way to change the list of files.  In the future, the
102       representation used for storing files will be changed.
103
104   root
105       This is the root directory of the dist, as a Path::Tiny.  It will
106       nearly always be the current working directory in which "dzil" was run.
107
108   is_trial
109       This attribute tells us whether or not the dist will be a trial
110       release, i.e. whether it has "release_status" 'testing' or 'unstable'.
111
112       Do not set this directly, it will be derived from "release_status".
113
114   plugins
115       This is an arrayref of plugins that have been plugged into this
116       Dist::Zilla object.
117
118       Non-core code must not alter this arrayref.  Public access to this
119       attribute may go away in the future.
120
121   distmeta
122       This is a hashref containing the metadata about this distribution that
123       will be stored in META.yml or META.json.  You should not alter the
124       metadata in this hash; use a MetaProvider plugin instead.
125
126   prereqs
127       This is a Dist::Zilla::Prereqs object, which is a thin layer atop
128       CPAN::Meta::Prereqs, and describes the distribution's prerequisites.
129
130   logger
131       This attribute stores a Log::Dispatchouli::Proxy object, used to log
132       messages.  By default, a proxy to the dist's Chrome is taken.
133
134       The following methods are delegated from the Dist::Zilla object to the
135       logger:
136
137       ·   log
138
139       ·   log_debug
140
141       ·   log_fatal
142

METHODS

144   register_prereqs
145       Allows registration of prerequisites; delegates to "register_prereqs"
146       in Dist::Zilla::Prereqs via our "prereqs" attribute.
147
148   plugin_named
149         my $plugin = $zilla->plugin_named( $plugin_name );
150
151   plugins_with
152         my $roles = $zilla->plugins_with( -SomeRole );
153
154       This method returns an arrayref containing all the Dist::Zilla object's
155       plugins that perform the named role.  If the given role name begins
156       with a dash, the dash is replaced with "Dist::Zilla::Role::"
157
158   find_files
159         my $files = $zilla->find_files( $finder_name );
160
161       This method will look for a FileFinder-performing plugin with the given
162       name and return the result of calling "find_files" on it.  If no plugin
163       can be found, an exception will be raised.
164
165   stash_named
166         my $stash = $zilla->stash_named( $name );
167
168       This method will return the stash with the given name, or undef if none
169       exists.  It looks for a local stash (for this dist) first, then falls
170       back to a global stash (from the user's global configuration).
171

STABILITY PROMISE

173       None.
174
175       I will try not to break things within any major release.  Minor
176       releases are not extensively tested before release.  In major releases,
177       anything goes, although I will try to publish a complete list of known
178       breaking changes in any major release.
179
180       If Dist::Zilla was a tool, it would have yellow and black stripes and
181       there would be no UL certification
182       <https://en.wikipedia.org/wiki/UL_(safety_organization)> on it.  It is
183       nasty, brutish, and large.
184

SUPPORT

186       There are usually people on "irc.perl.org" in "#distzilla", even if
187       they're idling.
188
189       The Dist::Zilla website <http://dzil.org/> has several valuable
190       resources for learning to use Dist::Zilla.
191
192       There is a mailing list to discuss Dist::Zilla.  You can join the list
193       <http://www.listbox.com/subscribe/?list_id=139292> or browse the
194       archives <http://listbox.com/member/archive/139292>.
195

AUTHOR

213       Ricardo SIGNES 😏 <rjbs@cpan.org>
214

CONTRIBUTORS

216       ·   Ævar Arnfjörð Bjarmason <avarab@gmail.com>
217
218       ·   Alastair McGowan-Douglas <alastair.mcgowan@opusvl.com>
219
220       ·   Alceu Rodrigues de Freitas Junior <glasswalk3r@yahoo.com.br>
221
222       ·   Alexei Znamensky <russoz@cpan.org>
223
224       ·   Alex Vandiver <alexmv@mit.edu>
225
226       ·   ambs <ambs@cpan.org>
227
228       ·   Andrew Rodland <andrew@hbslabs.com>
229
230       ·   Andy Jack <andyjack@cpan.org>
231
232       ·   Apocalypse <APOCAL@cpan.org>
233
234       ·   ben hengst <ben.hengst@gmail.com>
235
236       ·   Bernardo Rechea <brbpub@gmail.com>
237
238       ·   Brian Fraser <fraserbn@gmail.com>
239
240       ·   Caleb Cushing <xenoterracide@gmail.com>
241
242       ·   Chase Whitener <cwhitener@gmail.com>
243
244       ·   Chisel <chisel@chizography.net>
245
246       ·   Christian Walde <walde.christian@googlemail.com>
247
248       ·   Christopher J. Madsen <cjm@cjmweb.net>
249
250       ·   Chris Weyl <cweyl@alumni.drew.edu>
251
252       ·   Cory G Watson <gphat@onemogin.com>
253
254       ·   csjewell <perl@csjewell.fastmail.us>
255
256       ·   Curtis Brandt <curtisjbrandt@gmail.com>
257
258       ·   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
259
260       ·   Damien KRotkine <dkrotkine@booking.com>
261
262       ·   Danijel Tasov <dt@korn.shell.la>
263
264       ·   Dave O'Neill <dmo@dmo.ca>
265
266       ·   Dave Rolsky <autarch@urth.org>
267
268       ·   David E. Wheeler <david@justatheory.com>
269
270       ·   David Golden <dagolden@cpan.org>
271
272       ·   David H. Adler <dha@pobox.com>
273
274       ·   David Steinbrunner <dsteinbrunner@pobox.com>
275
276       ·   David Zurborg <port@david-zurb.org>
277
278       ·   Davor Cubranic <cubranic@stat.ubc.ca>
279
280       ·   Dimitar Petrov <mitakaa@gmail.com>
281
282       ·   Doug Bell <madcityzen@gmail.com>
283
284       ·   Erik Carlsson <info@code301.com>
285
286       ·   Fayland Lam <fayland@gmail.com>
287
288       ·   Florian Ragwitz <rafl@debian.org>
289
290       ·   Fred Moyer <fred@redhotpenguin.com>
291
292       ·   fREW Schmidt <frioux@gmail.com>
293
294       ·   gardnerm <gardnerm@gsicommerce.com>
295
296       ·   Gianni Ceccarelli <gianni.ceccarelli@net-a-porter.com>
297
298       ·   Graham Barr <gbarr@pobox.com>
299
300       ·   Graham Knop <haarg@haarg.org>
301
302       ·   Graham Ollis <perl@wdlabs.com>
303
304       ·   Graham Ollis <plicease@cpan.org>
305
306       ·   Grzegorz Rożniecki <xaerxess@gmail.com>
307
308       ·   Hans Dieter Pearcey <hdp@weftsoar.net>
309
310       ·   Hunter McMillen <mcmillhj@gmail.com>
311
312       ·   Ivan Bessarabov <ivan@bessarabov.ru>
313
314       ·   Jakob Voss <jakob@nichtich.de>
315
316       ·   jantore <jantore@32k.org>
317
318       ·   Jérôme Quelin <jquelin@gmail.com>
319
320       ·   Jesse Luehrs <doy@tozt.net>
321
322       ·   Jesse Vincent <jesse@bestpractical.com>
323
324       ·   JJ Merelo <jjmerelo@gmail.com>
325
326       ·   John Napiorkowski <jjnapiork@cpan.org>
327
328       ·   jonasbn <jonasbn@gmail.com>
329
330       ·   Jonathan C. Otsuka <djgoku@gmail.com>
331
332       ·   Jonathan Rockway <jrockway@cpan.org>
333
334       ·   Jonathan Scott Duff <duff@pobox.com>
335
336       ·   Jonathan Yu <jawnsy@cpan.org>
337
338       ·   Karen Etheridge <ether@cpan.org>
339
340       ·   Kent Fredric <kentfredric@gmail.com>
341
342       ·   Leon Timmermans <fawaka@gmail.com>
343
344       ·   Lucas Theisen <lucastheisen@pastdev.com>
345
346       ·   Luc St-Louis <lucs@pobox.com>
347
348       ·   Marcel Gruenauer <hanekomu@gmail.com>
349
350       ·   Martin McGrath <mcgrath.martin@gmail.com>
351
352       ·   Mary Ehlers <regina.verb.ae@gmail.com>
353
354       ·   Mateu X Hunter <hunter@missoula.org>
355
356       ·   Matthew Horsfall <wolfsage@gmail.com>
357
358       ·   mauke <l.mai@web.de>
359
360       ·   Michael G. Schwern <schwern@pobox.com>
361
362       ·   Michael Jemmeson <mjemmeson@cpan.org>
363
364       ·   Mickey Nasriachi <mickey@cpan.org>
365
366       ·   Mike Doherty <mike@mikedoherty.ca>
367
368       ·   Mohammad S Anwar <mohammad.anwar@yahoo.com>
369
370       ·   Moritz Onken <onken@netcubed.de>
371
372       ·   Neil Bowers <neil@bowers.com>
373
374       ·   Nickolay Platonov <nickolay@desktop.(none)>
375
376       ·   Nick Tonkin <1nickt@users.noreply.github.com>
377
378       ·   nperez <nperez@cpan.org>
379
380       ·   Olivier Mengué <dolmen@cpan.org>
381
382       ·   Paul Cochrane <paul@liekut.de>
383
384       ·   Pedro Melo <melo@simplicidade.org>
385
386       ·   Philippe Bruhat (BooK) <book@cpan.org>
387
388       ·   Randy Stauner <rwstauner@cpan.org>
389
390       ·   robertkrimen <robertkrimen@gmail.com>
391
392       ·   Rob Hoelz <rob@hoelz.ro>
393
394       ·   Robin Smidsrød <robin@smidsrod.no>
395
396       ·   Roy Ivy III <rivy@cpan.org>
397
398       ·   Shawn M Moore <sartak@gmail.com>
399
400       ·   Smylers <Smylers@stripey.com>
401
402       ·   Steffen Schwigon <ss5@renormalist.net>
403
404       ·   Steven Haryanto <stevenharyanto@gmail.com>
405
406       ·   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
407
408       ·   Upasana Shukla <me@upasana.me>
409
410       ·   Vyacheslav Matjukhin <mmcleric@yandex-team.ru>
411
412       ·   Yanick Champoux <yanick@babyl.dyndns.org>
413
414       ·   Yuval Kogman <nothingmuch@woobling.org>
415

COPYRIGHT AND LICENSE

417       This software is copyright (c) 2018 by Ricardo SIGNES.
418
419       This is free software; you can redistribute it and/or modify it under
420       the same terms as the Perl 5 programming language system itself.
421
422
423
424perl v5.28.1                      2018-04-21                    Dist::Zilla(3)