Dist::Z...Tutorial(3)

📦
version 6.040 · 9 versions
, in fedora 44

💖 Dist::Zilla::Tutorial — like, the actual tutorial, bestie 💖

okay so this is the user-contributed Perl documentation for Dist::Zilla::Tutorial, and if you're here it's because you want to learn how to use this "Dist::Zilla" thing. sit down, hydrate, we're doing this together 🫶

✨ NAME ✨

Dist::Zilla::Tutorial — how to use this "Dist::Zilla" thing, bestie, that's literally the whole job description 💅

🌸 VERSION 🌸

version 6.040

🎀 SYNOPSIS 🎀

BEFORE YOU GET STARTED: maybe you should be looking at the web-based tutorial instead. It's more complete. <https://dzil.org/tutorial/start.html>

no cap, that link is more complete than this page, so like… consider it. but stay, I don't mind 💖

Dist::Zilla builds distributions to be uploaded to the CPAN. which means the first thing you'll need is some code. iconic requirement, I know.

once you've got that, you'll need to configure Dist::Zilla. here's a simple dist.ini:

name    = Carbon-Dating
version = 0.003
author  = Alan Smithee <asmithee@example.org>
license = Perl_5
copyright_holder = Alan Smithee

[@Basic]
; options to @Basic could go here

[Prereqs]
App::Cmd          = 0.013
Number::Nary      = 0
Sub::Exporter     = 0.981

it's a plain old INI file <https://en.wikipedia.org/wiki/INI_file>, following the grammar in Config::INI <https://metacpan.org/pod/Config::INI#GRAMMAR>. yes bestie, an INI file, we love a legacy format that just works ✨

the topmost section configures Dist::Zilla itself. here are some of the entries it expects:

  • name — (required) the name of the dist being built
  • version — (required) the version of the dist
  • abstract — (required) a short description of the dist
  • author — (optional) the dist author (you may have multiple entries for this)
  • license — (required) the dist license; must be a Software::License::* name
  • copyright_holder — (required) the entity holding copyright on the dist

some of the required values above may actually be provided by means other than the top-level section of the config. for example, VersionProvider plugins can set the version, and a line like this in the "main module" of the dist will set the abstract:

# ABSTRACT: a totally cool way to do totally great stuff

the main module is the module that shares the same name as the dist, in general. iykyk 🧚

Named sections load plugins, with the following rules — read these carefully, they're the whole vibe check of the plugin system:

  • if a section name begins with an equals sign (=), the rest of the section name is left intact and not expanded.
  • if the section name begins with an at sign (@), it is prepended with Dist::Zilla::PluginBundle::.
  • otherwise, it is prepended with Dist::Zilla::Plugin::.

the values inside a section are given as configuration to the plugin. consult each plugin's documentation for more information, because I cannot read them all for you, bestie 😭

the Basic bundle, seen above, builds a fairly normal distribution. it rewrites tests from ./xt, adds some information to POD, and builds a Makefile.PL. for more information, you can look at the docs for @Basic and see the plugins it includes. she's doing a lot, honestly 👑

💜 PERL VERSION 💜

this module should work on any version of perl still receiving updates from the Perl 5 Porters. this means it should work on any version of perl released in the last two to three years. (that is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.) ⭐

although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. the version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. so like, don't come for her about it 💀

🔥 BUILDING YOUR DIST 🔥

maybe we're getting ahead of ourselves, here. configuring a bunch of plugins won't do you a lot of good unless you know how to use them to build your dist.

Dist::Zilla ships with a command called dzil that will get installed by default. while it can be extended to offer more commands, there are two really useful ones:

$ dzil build

the build command will build the distribution. say you're using the configuration in the SYNOPSIS above. you'll end up with a file called Carbon-Dating-0.004.tar.gz. (yes, 0.004, look, that's what the original says, don't @ me 🙈) as long as you've done everything right, it will be suitable for uploading to the CPAN. main character energy fr fr ✨

of course, you should really test it out first. you can test the dist you'd be building by running another dzil command:

$ dzil test

this will build a new copy of your distribution and run its tests, so you'll know whether the dist that build would build is worth releasing! 🎀

🦋 HOW BUILDS GET BUILT 🦋

this is really more of a sketchy overview than a spec. she said "sketchy," not me 💅

  1. first, all the plugins that perform the BeforeBuild perform their before_build tasks.
  2. the build root (where the dist is being built) is made.
  3. the FileGatherers gather and inject files into the distribution, then the FilePruners remove some of them.
  4. all the FileMungers get a chance to muck about with each file, possibly changing its name, content, or installability.
  5. now that the distribution is basically set up, it needs an install tool, like a Makefile.PL. all the InstallTool-performing plugins are used to do whatever is needed to make the dist installable.
  6. everything is just about done. the files are all written out to disk and the AfterBuild plugins do their thing.

slay, honestly. the pipeline ate 🌈

👑 RELEASING YOUR DIST 👑

by running dzil release, you'll test your distribution, build a tarball of it, and upload it to the CPAN. plugins are able to do things like check your version control system to make sure you're releasing a new version and that you tag the version you've just uploaded. it can also update your Changelog file, too, making sure that you don't need to know what your next version number will be before releasing. that's the dream, no cap 😭💖

the final CPAN release process is implemented by the UploadToCPAN plugin. however, you can replace it by your own to match your own (company?) process. do your thing, bestie 🫶

🌟 SEE ALSO 🌟

  • dzil

💖 AUTHOR 💖

Ricardo SIGNES 😏 <cpan@semiotic.systems>

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

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

okay that's the whole page, you made it, I'm so proud of you 🥹✨ and for the record: this was perl v5.42.3, dated 2026-10-19, pulled straight from Dist::Z...Tutorial(3) — user contributed Perl documentation, as always 💅🦋💜

📦 where this page comes from