Dist::Zilla(3)

πŸ“¦
version 6.040 Β· 9 versions
, in fedora 44

🌸 NAME 🌸

Dist::Zilla β€” distribution builder; installer not included! πŸ’… (yes bestie, that's literally the whole tagline, and it's iconic)

πŸ”₯ VERSION πŸ”₯

version 6.040

✨ DESCRIPTION ✨

So Dist::Zilla builds distributions of code that you upload to the CPAN. In that specific lane, it's like ExtUtils::MakeMaker, Module::Build, or Module::Install. 🫢

But here's the plot twist: unlike those tools, it is NOT also a system for installing code that's been downloaded from the CPAN. Nope. It gets run by authors only, on a repository checkout, not on published/released code β€” so it can do way more than those tools, and it's free to make much more ludicrous demands in terms of prerequisites. And it does. 😌

If you have access to the web, you can learn more and find an interactive tutorial at dzil.org <https://dzil.org/>. If not, try Dist::Zilla::Tutorial.

πŸͺ PERL VERSION πŸͺ

This module should work on any version of perl still receiving updates from the Perl 5 Porters. Translation: any version of perl released in the last two to three years. (So like, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.) πŸ’–

And yeah, it may work on older versions of perl, but no guarantee is made that the minimum required version won't get increased. The version may be increased for any reason, and there's no promise that patches will be accepted to lower the minimum required perl. Periodt. πŸ™ˆ

πŸ‘‘ ATTRIBUTES πŸ‘‘

πŸ’« name

The name attribute (which is required, bestie, you cannot skip it) gives the name of the distribution to be built. Usually it's the name of the dist's main module, with the double colons (::) swapped out for dashes. For example: Dist-Zilla. ✨

πŸ’« version

This is the version of the distribution to be created.

πŸ’« release_status

This attribute sets the release status to one of the CPAN::META::Spec <https://metacpan.org/pod/CPAN::Meta::Spec#release_status> values: 'stable', 'testing' or 'unstable'.

Here's the priority order, pay attention:

  • If the $ENV{RELEASE_STATUS} environment variable exists, its value gets used as the release status.
  • For backwards compatibility, if $ENV{RELEASE_STATUS} does not exist and the $ENV{TRIAL} variable is true, the release status will be 'testing'.
  • Otherwise, the release status gets set from a ReleaseStatusProvider, if one has been configured.
  • For backwards compatibility, setting is_trial true in dist.ini is equivalent to using a ReleaseStatusProvider. If is_trial is false, it has no effect.
  • Only one ReleaseStatusProvider may be used. One. That's it.
  • If no providers are used, the release status defaults to 'stable' unless there is an _ character in the version, in which case it defaults to 'testing'.

πŸ’« abstract

A one-line summary of the distribution. If none is given, one will be looked for in the main_module of the dist. πŸŽ€

πŸ’« main_module

This is the module where Dist::Zilla might look for various defaults, like the distribution abstract. By default it's derived from the distribution name. So if your distribution is Foo-Bar, and lib/Foo/Bar.pm exists, that's the main_module. Otherwise, it's the shortest-named module in the distribution. This may change!

You can override the default by specifying the file path explicitly, ie:

main_module = lib/Foo/Bar.pm

πŸ’« license

This is the Software::License object for this dist's license and copyright. πŸ“œ

It gets created automatically, if possible, with the copyright_holder and copyright_year attributes. If necessary, it will try to guess the license from the POD of the dist's main module.

A better option is to set the license name in the dist's config to something understandable, like Perl_5. πŸ’…

If copyright_year is not given, the current year is used. If it is given, it's used as a string, so a range like 2008 - 2012 is totally fine. The string $this_year, wherever it appears in copyright_year, gets replaced with the current year when the license is built β€” so 2008 - $this_year would become 2008 - 2026 when built in 2026. πŸ¦‹

πŸ’« authors

This is an arrayref of author strings, like this:

[
  'Ricardo Signes <rjbs@cpan.org>',
  'X. Ample, Jr <example@example.biz>',
]

This is likely to change at some point in the near future. πŸ‘€

πŸ’« files

This is an arrayref of objects implementing Dist::Zilla::Role::File that will, if left in this arrayref, be built into the dist.

Non-core code should avoid altering this arrayref, but sometimes there is no other way to change the list of files. In the future, the representation used for storing files will be changed. 😭

πŸ’« root

This is the root directory of the dist, as a Path::Tiny. It will nearly always be the current working directory in which dzil was run. πŸ“‚

πŸ’« is_trial

This attribute tells us whether or not the dist will be a trial release, i.e. whether it has release_status 'testing' or 'unstable'.

Do not set this directly, bestie β€” it will be derived from release_status. πŸ™…β€β™€οΈ

πŸ’« plugins

This is an arrayref of plugins that have been plugged into this Dist::Zilla object.

Non-core code must not alter this arrayref. Public access to this attribute may go away in the future. πŸ’€

πŸ’« distmeta

This is a hashref containing the metadata about this distribution that will be stored in META.yml or META.json.

You should not alter the metadata in this hash; use a MetaProvider plugin instead. 🫢

πŸ’« prereqs

This is a Dist::Zilla::Prereqs object, which is a thin layer atop CPAN::Meta::Prereqs, and it describes the distribution's prerequisites. 🌈

πŸ’« logger

This attribute stores a Log::Dispatchouli::Proxy object, used to log messages. By default, a proxy to the dist's Chrome is taken. πŸŽ€

The following methods are delegated from the Dist::Zilla object to the logger:

  • log
  • log_debug
  • log_fatal

🧚 METHODS 🧚

πŸ’œ register_prereqs

Allows registration of prerequisites; delegates to register_prereqs in Dist::Zilla::Prereqs via our prereqs attribute.

πŸ’œ plugin_named

my $plugin = $zilla->plugin_named( $plugin_name );

πŸ’œ plugins_with

my $roles = $zilla->plugins_with( -SomeRole );

This method returns an arrayref containing all the Dist::Zilla object's plugins that perform the named role. If the given role name begins with a dash, the dash is replaced with Dist::Zilla::Role:: πŸ’«

πŸ’œ find_files

my $files = $zilla->find_files( $finder_name );

This method will look for a FileFinder-performing plugin with the given name and return the result of calling find_files on it. If no plugin can be found, an exception will be raised. 😭

πŸ’œ stash_named

my $stash = $zilla->stash_named( $name );

This method will return the stash with the given name, or undef if none exists. It looks for a local stash (for this dist) first, then falls back to a global stash (from the user's global configuration). πŸ”

πŸ’€ STABILITY PROMISE πŸ’€

None. 😌

I will try not to break things within any major release. Minor releases are not extensively tested before release. In major releases, anything goes, although I will try to publish a complete list of known breaking changes in any major release.

If Dist::Zilla was a tool, it would have yellow and black stripes and there would be no UL certification <https://en.wikipedia.org/wiki/UL_(safety_organization)> on it. It is nasty, brutish, and large. πŸ”₯

🫢 SUPPORT 🫢

There are usually people on irc.perl.org in #distzilla, even if they're idling. (Idling counts, bestie, it's the group chat vibe.) πŸ’–

The Dist::Zilla website <https://dzil.org/> has several valuable resources for learning to use Dist::Zilla.

🌈 SEE ALSO 🌈

πŸ’œ AUTHOR πŸ’œ

Ricardo SIGNES 😏 <cpan@semiotic.systems>

Okay so before we get into the vibes, quick reminder that these are the actual humans who built this thing, and every single one of them has an email address listed because that's how we say thank you in Perl-land. Scroll respectfully πŸ’–

πŸ’– CONTRIBUTORS πŸ’–

Not one of these is a filler name β€” every single person here touched the code, and they're all listed with the exact contact info from the original, no cap:

  • Γ†var ArnfjΓΆrΓ° Bjarmason β€” <avarab@gmail.com>
  • Alastair McGowan-Douglas β€” <alastair.mcgowan@opusvl.com>
  • Alceu Rodrigues de Freitas Junior β€” <glasswalk3r@yahoo.com.br>
  • Alexei Znamensky β€” <russoz@cpan.org>
  • Alex Vandiver β€” <alexmv@mit.edu>
  • ambs β€” <ambs@cpan.org>
  • Andrew Rodland β€” <andrew@hbslabs.com>
  • Andy Jack β€” <andyjack@cpan.org>
  • Apocalypse β€” <APOCAL@cpan.org>
  • ben hengst β€” <ben.hengst@gmail.com>
  • Bernardo Rechea β€” <brbpub@gmail.com>
  • Branislav ZahradnΓ­k β€” <happy.barney@gmail.com>
  • Brian Fraser β€” <fraserbn@gmail.com>
  • Caleb Cushing β€” <xenoterracide@gmail.com>
  • Chase Whitener β€” <cwhitener@gmail.com>
  • Chisel β€” <chisel@chizography.net>
  • Christian Walde β€” <walde.christian@googlemail.com>
  • Christopher Bottoms β€” <molecules@users.noreply.github.com>
  • Christopher J. Madsen β€” <cjm@cjmweb.net>
  • Chris Weyl β€” <cweyl@alumni.drew.edu>
  • Cory G Watson β€” <gphat@onemogin.com>
  • csjewell β€” <perl@csjewell.fastmail.us>
  • Curtis Brandt β€” <curtisjbrandt@gmail.com>
  • Dagfinn Ilmari MannsΓ₯ker β€” <ilmari@ilmari.org>
  • Damien KRotkine β€” <dkrotkine@booking.com>
  • Dan Book β€” <grinnz@gmail.com>
  • Daniel BΓΆhmer β€” <post@daniel-boehmer.de>
  • Danijel Tasov β€” <dt@korn.shell.la>
  • Dave Lambley β€” <dave@lambley.me.uk>
  • Dave O'Neill β€” <dmo@dmo.ca>
  • Dave Rolsky β€” <autarch@urth.org>
  • David E. Wheeler β€” <david@justatheory.com>
  • David Golden β€” <dagolden@cpan.org>
  • David H. Adler β€” <dha@pobox.com>
  • David Steinbrunner β€” <dsteinbrunner@pobox.com>
  • David Zurborg β€” <port@david-zurb.org>
  • Davor Cubranic β€” <cubranic@stat.ubc.ca>
  • Dimitar Petrov β€” <mitakaa@gmail.com>
  • Doug Bell β€” <doug@preaction.me>
  • Elvin Aslanov β€” <rwp.primary@gmail.com>
  • Erik Carlsson β€” <info@code301.com>
  • Fayland Lam β€” <fayland@gmail.com>
  • Felix Ostmann β€” <felix.ostmann@gmail.com>
  • Florian Ragwitz β€” <rafl@debian.org>
  • Fred Moyer β€” <fred@redhotpenguin.com>
  • fREW Schmidt β€” <frioux@gmail.com>
  • gardnerm β€” <gardnerm@gsicommerce.com>
  • Gianni Ceccarelli β€” <gianni.ceccarelli@net-a-porter.com>
  • Graham Barr β€” <gbarr@pobox.com>
  • Graham Knop β€” <haarg@haarg.org>
  • Graham Ollis β€” <plicease@cpan.org>
  • Grzegorz RoΕΌniecki β€” <xaerxess@gmail.com>
  • HΓ₯kon HΓ¦gland β€” <hakon.hagland@gmail.com>
  • Hans Dieter Pearcey β€” <hdp@weftsoar.net>
  • Hunter McMillen β€” <mcmillhj@gmail.com>
  • Ivan Bessarabov β€” <ivan@bessarabov.ru>
  • Jakob Voss β€” <jakob@nichtich.de>
  • jantore β€” <jantore@32k.org>
  • JΓ©rΓ΄me Quelin β€” <jquelin@gmail.com>
  • Jesse Luehrs β€” <doy@tozt.net>
  • Jesse Vincent β€” <jesse@bestpractical.com>
  • JJ Merelo β€” <jjmerelo@gmail.com>
  • John Napiorkowski β€” <jjnapiork@cpan.org>
  • jonasbn β€” <jonasbn@gmail.com>
  • Jonathan C. Otsuka β€” <djgoku@gmail.com>
  • Jonathan Rockway β€” <jrockway@cpan.org>
  • Jonathan Scott Duff β€” <duff@pobox.com>
  • Jonathan Yu β€” <jawnsy@cpan.org>
  • Karen Etheridge β€” <ether@cpan.org>
  • Kent Fredric β€” <kentfredric@gmail.com>
  • Leon Timmermans β€” <fawaka@gmail.com>
  • Lucas Theisen β€” <lucastheisen@pastdev.com>
  • Luc St-Louis β€” <lucs@pobox.com>
  • Marcel Gruenauer β€” <hanekomu@gmail.com>
  • Mark Flickinger β€” <mark.flickinger@grantstreet.com>
  • Martin McGrath β€” <mcgrath.martin@gmail.com>
  • Mary Ehlers β€” <regina.verb.ae@gmail.com>
  • Mateu X Hunter β€” <hunter@missoula.org>
  • Matthew Horsfall β€” <wolfsage@gmail.com>
  • mauke β€” <l.mai@web.de>
  • Michael Conrad β€” <mike@nrdvana.net>
  • Michael G. Schwern β€” <schwern@pobox.com>
  • Michael Jemmeson β€” <mjemmeson@cpan.org>
  • Mickey Nasriachi β€” <mickey@cpan.org>
  • Mike Doherty β€” <mike@mikedoherty.ca>
  • Mohammad S Anwar β€” <mohammad.anwar@yahoo.com>
  • Moritz Onken β€” <onken@netcubed.de>
  • Neil Bowers β€” <neil@bowers.com>
  • Nickolay Platonov β€” <nickolay@desktop.(none)>
  • Nick Tonkin β€” <1nickt@users.noreply.github.com>
  • nperez β€” <nperez@cpan.org>
  • Olivier MenguΓ© β€” <dolmen@cpan.org>
  • Paul Cochrane β€” <paul@liekut.de>
  • Paulo Custodio β€” <pauloscustodio@gmail.com>
  • Pedro Melo β€” <melo@simplicidade.org>
  • perlancar (@pc-office) β€” <perlancar@gmail.com>
  • Philippe Bruhat (BooK) β€” <book@cpan.org>
  • raf β€” <68724930+rafork@users.noreply.github.com>
  • Randy Stauner β€” <rwstauner@cpan.org>
  • reneeb β€” <info@perl-services.de>
  • Ricardo Signes β€” <rjbs@semiotic.systems>
  • robertkrimen β€” <robertkrimen@gmail.com>
  • Robert Rothenberg β€” <rrwo@cpan.org>
  • Rob Hoelz β€” <rob@hoelz.ro>
  • Robin SmidsrΓΈd β€” <robin@smidsrod.no>
  • Roy Ivy III β€” <rivy@cpan.org>
  • Shawn M Moore β€” <sartak@gmail.com>
  • Shlomi Fish β€” <shlomif@shlomifish.org>
  • Shoichi Kaji β€” <skaji@cpan.org>
  • Smylers β€” <Smylers@stripey.com>
  • Steffen Schwigon β€” <ss5@renormalist.net>
  • Steven Haryanto β€” <stevenharyanto@gmail.com>
  • Tatsuhiko Miyagawa β€” <miyagawa@bulknews.net>
  • Upasana Shukla β€” <me@upasana.me>
  • Van de Bugger β€” <van.de.bugger@gmail.com>
  • Vyacheslav Matjukhin β€” <mmcleric@yandex-team.ru>
  • Yanick Champoux β€” <yanick@babyl.dyndns.org>
  • Yuval Kogman β€” <nothingmuch@woobling.org>

Like, one hundred and eighteen humans. That's not a contributor list, that's a whole community 🫢

The legal bit, and yes bestie you still gotta read it, it's short:

This software is copyright (c) 2026 by Ricardo SIGNES.

It's free software, so you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Like, the actual Perl 5 terms, not some new ones. That's the whole deal. πŸ’…

And that's a wrap on this whole page, fr fr πŸ’– This version of the docs came out of perl v5.42.3 on 2026-10-19, and it's the manual for Dist::Zilla(3), so if you cite it anywhere, that's the sauce. Go build something iconic with it, bestie β€” you got this πŸ‘‘βœ¨

πŸ“¦ where this page comes from