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.017
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 Bottoms <molecules@users.noreply.github.com>
249
250       •   Christopher J. Madsen <cjm@cjmweb.net>
251
252       •   Chris Weyl <cweyl@alumni.drew.edu>
253
254       •   Cory G Watson <gphat@onemogin.com>
255
256       •   csjewell <perl@csjewell.fastmail.us>
257
258       •   Curtis Brandt <curtisjbrandt@gmail.com>
259
260       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
261
262       •   Damien KRotkine <dkrotkine@booking.com>
263
264       •   Dan Book <grinnz@gmail.com>
265
266       •   Daniel Böhmer <post@daniel-boehmer.de>
267
268       •   Danijel Tasov <dt@korn.shell.la>
269
270       •   Dave Lambley <dave@lambley.me.uk>
271
272       •   Dave O'Neill <dmo@dmo.ca>
273
274       •   Dave Rolsky <autarch@urth.org>
275
276       •   David E. Wheeler <david@justatheory.com>
277
278       •   David Golden <dagolden@cpan.org>
279
280       •   David H. Adler <dha@pobox.com>
281
282       •   David Steinbrunner <dsteinbrunner@pobox.com>
283
284       •   David Zurborg <port@david-zurb.org>
285
286       •   Davor Cubranic <cubranic@stat.ubc.ca>
287
288       •   Dimitar Petrov <mitakaa@gmail.com>
289
290       •   Doug Bell <doug@preaction.me>
291
292       •   Doug Bell <madcityzen@gmail.com>
293
294       •   Erik Carlsson <info@code301.com>
295
296       •   Fayland Lam <fayland@gmail.com>
297
298       •   Felix Ostmann <felix.ostmann@gmail.com>
299
300       •   Florian Ragwitz <rafl@debian.org>
301
302       •   Fred Moyer <fred@redhotpenguin.com>
303
304       •   fREW Schmidt <frioux@gmail.com>
305
306       •   gardnerm <gardnerm@gsicommerce.com>
307
308       •   Gianni Ceccarelli <gianni.ceccarelli@net-a-porter.com>
309
310       •   Graham Barr <gbarr@pobox.com>
311
312       •   Graham Knop <haarg@haarg.org>
313
314       •   Graham Ollis <perl@wdlabs.com>
315
316       •   Graham Ollis <plicease@cpan.org>
317
318       •   Grzegorz Rożniecki <xaerxess@gmail.com>
319
320       •   Håkon Hægland <hakon.hagland@gmail.com>
321
322       •   Hans Dieter Pearcey <hdp@weftsoar.net>
323
324       •   Hunter McMillen <mcmillhj@gmail.com>
325
326       •   Ivan Bessarabov <ivan@bessarabov.ru>
327
328       •   Jakob Voss <jakob@nichtich.de>
329
330       •   jantore <jantore@32k.org>
331
332       •   Jérôme Quelin <jquelin@gmail.com>
333
334       •   Jesse Luehrs <doy@tozt.net>
335
336       •   Jesse Vincent <jesse@bestpractical.com>
337
338       •   JJ Merelo <jjmerelo@gmail.com>
339
340       •   John Napiorkowski <jjnapiork@cpan.org>
341
342       •   jonasbn <jonasbn@gmail.com>
343
344       •   Jonathan C. Otsuka <djgoku@gmail.com>
345
346       •   Jonathan Rockway <jrockway@cpan.org>
347
348       •   Jonathan Scott Duff <duff@pobox.com>
349
350       •   Jonathan Yu <jawnsy@cpan.org>
351
352       •   Karen Etheridge <ether@cpan.org>
353
354       •   Kent Fredric <kentfredric@gmail.com>
355
356       •   Kent Fredric <kentnl@gentoo.org>
357
358       •   Leon Timmermans <fawaka@gmail.com>
359
360       •   Lucas Theisen <lucastheisen@pastdev.com>
361
362       •   Luc St-Louis <lucs@pobox.com>
363
364       •   Marcel Gruenauer <hanekomu@gmail.com>
365
366       •   Martin McGrath <mcgrath.martin@gmail.com>
367
368       •   Mary Ehlers <regina.verb.ae@gmail.com>
369
370       •   Mateu X Hunter <hunter@missoula.org>
371
372       •   Matthew Horsfall <wolfsage@gmail.com>
373
374       •   mauke <l.mai@web.de>
375
376       •   Michael Conrad <mike@nrdvana.net>
377
378       •   Michael G. Schwern <schwern@pobox.com>
379
380       •   Michael Jemmeson <mjemmeson@cpan.org>
381
382       •   Mickey Nasriachi <mickey@cpan.org>
383
384       •   Mike Doherty <mike@mikedoherty.ca>
385
386       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
387
388       •   Moritz Onken <onken@netcubed.de>
389
390       •   Neil Bowers <neil@bowers.com>
391
392       •   Nickolay Platonov <nickolay@desktop.(none)>
393
394       •   Nick Tonkin <1nickt@users.noreply.github.com>
395
396       •   nperez <nperez@cpan.org>
397
398       •   Olivier Mengué <dolmen@cpan.org>
399
400       •   Paul Cochrane <paul@liekut.de>
401
402       •   Pedro Melo <melo@simplicidade.org>
403
404       •   perlancar (@pc-office) <perlancar@gmail.com>
405
406       •   Philippe Bruhat (BooK) <book@cpan.org>
407
408       •   Randy Stauner <rwstauner@cpan.org>
409
410       •   Ricardo Signes <rjbs@semiotic.systems>
411
412       •   robertkrimen <robertkrimen@gmail.com>
413
414       •   Rob Hoelz <rob@hoelz.ro>
415
416       •   Robin Smidsrød <robin@smidsrod.no>
417
418       •   Roy Ivy III <rivy@cpan.org>
419
420       •   Shawn M Moore <sartak@gmail.com>
421
422       •   Shlomi Fish <shlomif@shlomifish.org>
423
424       •   Smylers <Smylers@stripey.com>
425
426       •   Steffen Schwigon <ss5@renormalist.net>
427
428       •   Steven Haryanto <stevenharyanto@gmail.com>
429
430       •   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
431
432       •   Upasana Shukla <me@upasana.me>
433
434       •   Vyacheslav Matjukhin <mmcleric@yandex-team.ru>
435
436       •   Yanick Champoux <yanick@babyl.dyndns.org>
437
438       •   Yuval Kogman <nothingmuch@woobling.org>
439

COPYRIGHT AND LICENSE

441       This software is copyright (c) 2020 by Ricardo SIGNES.
442
443       This is free software; you can redistribute it and/or modify it under
444       the same terms as the Perl 5 programming language system itself.
445
446
447
448perl v5.32.1                      2021-01-27                    Dist::Zilla(3)