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

COPYRIGHT AND LICENSE

431       This software is copyright (c) 2020 by Ricardo SIGNES.
432
433       This is free software; you can redistribute it and/or modify it under
434       the same terms as the Perl 5 programming language system itself.
435
436
437
438perl v5.30.1                      2020-03-03                    Dist::Zilla(3)