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

PERL VERSION

26       This module should work on any version of perl still receiving updates
27       from the Perl 5 Porters.  This means it should work on any version of
28       perl released in the last two to three years.  (That is, if the most
29       recently released version is v5.40, then this module should work on
30       both v5.40 and v5.38.)
31
32       Although it may work on older versions of perl, no guarantee is made
33       that the minimum required version will not be increased.  The version
34       may be increased for any reason, and there is no promise that patches
35       will be accepted to lower the minimum required perl.
36

ATTRIBUTES

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

METHODS

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

STABILITY PROMISE

185       None.
186
187       I will try not to break things within any major release.  Minor
188       releases are not extensively tested before release.  In major releases,
189       anything goes, although I will try to publish a complete list of known
190       breaking changes in any major release.
191
192       If Dist::Zilla was a tool, it would have yellow and black stripes and
193       there would be no UL certification
194       <https://en.wikipedia.org/wiki/UL_(safety_organization)> on it.  It is
195       nasty, brutish, and large.
196

SUPPORT

198       There are usually people on "irc.perl.org" in "#distzilla", even if
199       they're idling.
200
201       The Dist::Zilla website <http://dzil.org/> has several valuable
202       resources for learning to use Dist::Zilla.
203
204       There is a mailing list to discuss Dist::Zilla.  You can join the list
205       <http://www.listbox.com/subscribe/?list_id=139292> or browse the
206       archives <http://listbox.com/member/archive/139292>.
207

AUTHOR

225       Ricardo SIGNES 😏 <rjbs@semiotic.systems>
226

CONTRIBUTORS

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

COPYRIGHT AND LICENSE

457       This software is copyright (c) 2022 by Ricardo SIGNES.
458
459       This is free software; you can redistribute it and/or modify it under
460       the same terms as the Perl 5 programming language system itself.
461
462
463
464perl v5.36.0                      2022-09-01                    Dist::Zilla(3)