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.031
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 <https://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 <https://dzil.org/> has several valuable
202       resources for learning to use Dist::Zilla.
203

AUTHOR

221       Ricardo SIGNES 😏 <cpan@semiotic.systems>
222

CONTRIBUTORS

224       •   Ævar Arnfjörð Bjarmason <avarab@gmail.com>
225
226       •   Alastair McGowan-Douglas <alastair.mcgowan@opusvl.com>
227
228       •   Alceu Rodrigues de Freitas Junior <glasswalk3r@yahoo.com.br>
229
230       •   Alexei Znamensky <russoz@cpan.org>
231
232       •   Alex Vandiver <alexmv@mit.edu>
233
234       •   ambs <ambs@cpan.org>
235
236       •   Andrew Rodland <andrew@hbslabs.com>
237
238       •   Andy Jack <andyjack@cpan.org>
239
240       •   Apocalypse <APOCAL@cpan.org>
241
242       •   ben hengst <ben.hengst@gmail.com>
243
244       •   Bernardo Rechea <brbpub@gmail.com>
245
246       •   Branislav Zahradník <happy.barney@gmail.com>
247
248       •   Brian Fraser <fraserbn@gmail.com>
249
250       •   Caleb Cushing <xenoterracide@gmail.com>
251
252       •   Chase Whitener <cwhitener@gmail.com>
253
254       •   Chisel <chisel@chizography.net>
255
256       •   Christian Walde <walde.christian@googlemail.com>
257
258       •   Christopher Bottoms <molecules@users.noreply.github.com>
259
260       •   Christopher J. Madsen <cjm@cjmweb.net>
261
262       •   Chris Weyl <cweyl@alumni.drew.edu>
263
264       •   Cory G Watson <gphat@onemogin.com>
265
266       •   csjewell <perl@csjewell.fastmail.us>
267
268       •   Curtis Brandt <curtisjbrandt@gmail.com>
269
270       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
271
272       •   Damien KRotkine <dkrotkine@booking.com>
273
274       •   Dan Book <grinnz@gmail.com>
275
276       •   Daniel Böhmer <post@daniel-boehmer.de>
277
278       •   Danijel Tasov <dt@korn.shell.la>
279
280       •   Dave Lambley <dave@lambley.me.uk>
281
282       •   Dave O'Neill <dmo@dmo.ca>
283
284       •   Dave Rolsky <autarch@urth.org>
285
286       •   David E. Wheeler <david@justatheory.com>
287
288       •   David Golden <dagolden@cpan.org>
289
290       •   David H. Adler <dha@pobox.com>
291
292       •   David Steinbrunner <dsteinbrunner@pobox.com>
293
294       •   David Zurborg <port@david-zurb.org>
295
296       •   Davor Cubranic <cubranic@stat.ubc.ca>
297
298       •   Dimitar Petrov <mitakaa@gmail.com>
299
300       •   Doug Bell <doug@preaction.me>
301
302       •   Doug Bell <madcityzen@gmail.com>
303
304       •   Elvin Aslanov <rwp.primary@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       •   Mark Flickinger <mark.flickinger@grantstreet.com>
379
380       •   Martin McGrath <mcgrath.martin@gmail.com>
381
382       •   Mary Ehlers <regina.verb.ae@gmail.com>
383
384       •   Mateu X Hunter <hunter@missoula.org>
385
386       •   Matthew Horsfall <wolfsage@gmail.com>
387
388       •   mauke <l.mai@web.de>
389
390       •   Michael Conrad <mike@nrdvana.net>
391
392       •   Michael G. Schwern <schwern@pobox.com>
393
394       •   Michael Jemmeson <mjemmeson@cpan.org>
395
396       •   Mickey Nasriachi <mickey@cpan.org>
397
398       •   Mike Doherty <mike@mikedoherty.ca>
399
400       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
401
402       •   Moritz Onken <onken@netcubed.de>
403
404       •   Neil Bowers <neil@bowers.com>
405
406       •   Nickolay Platonov <nickolay@desktop.(none)>
407
408       •   Nick Tonkin <1nickt@users.noreply.github.com>
409
410       •   nperez <nperez@cpan.org>
411
412       •   Olivier Mengué <dolmen@cpan.org>
413
414       •   Paul Cochrane <paul@liekut.de>
415
416       •   Paulo Custodio <pauloscustodio@gmail.com>
417
418       •   Pedro Melo <melo@simplicidade.org>
419
420       •   perlancar (@pc-office) <perlancar@gmail.com>
421
422       •   Philippe Bruhat (BooK) <book@cpan.org>
423
424       •   raf <68724930+rafork@users.noreply.github.com>
425
426       •   Randy Stauner <rwstauner@cpan.org>
427
428       •   reneeb <info@perl-services.de>
429
430       •   Ricardo Signes <rjbs@semiotic.systems>
431
432       •   robertkrimen <robertkrimen@gmail.com>
433
434       •   Rob Hoelz <rob@hoelz.ro>
435
436       •   Robin Smidsrød <robin@smidsrod.no>
437
438       •   Roy Ivy III <rivy@cpan.org>
439
440       •   Shawn M Moore <sartak@gmail.com>
441
442       •   Shlomi Fish <shlomif@shlomifish.org>
443
444       •   Shoichi Kaji <skaji@cpan.org>
445
446       •   Smylers <Smylers@stripey.com>
447
448       •   Steffen Schwigon <ss5@renormalist.net>
449
450       •   Steven Haryanto <stevenharyanto@gmail.com>
451
452       •   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
453
454       •   Upasana Shukla <me@upasana.me>
455
456       •   Van de Bugger <van.de.bugger@gmail.com>
457
458       •   Vyacheslav Matjukhin <mmcleric@yandex-team.ru>
459
460       •   Yanick Champoux <yanick@babyl.dyndns.org>
461
462       •   Yuval Kogman <nothingmuch@woobling.org>
463

COPYRIGHT AND LICENSE

465       This software is copyright (c) 2023 by Ricardo SIGNES.
466
467       This is free software; you can redistribute it and/or modify it under
468       the same terms as the Perl 5 programming language system itself.
469
470
471
472perl v5.36.1                      2023-11-21                    Dist::Zilla(3)