Dist::Zilla (dzil) is a program for creating Perl distributions. While the documentation for dzil is complete, it is not geared towards a beginner that has never created a Perl distribution before. This article provides a brief introduction to Dist::Zilla geared towards users that know little about Perl distributions in general.
What is a Perl distribution?
A Perl distribution is an archive of files that includes a Perl module. There are no official rules on what non-module files must be included in a distribution, but they often include (among other things) test scripts, a Makefile.PL, documentation, and the license. These distributions are commonly uploaded to CPAN, which is a place for Perl programmers to upload their Perl distributions for the purpose of sharing their code.
Why Dist::Zilla?
You may think that bundling together a Perl module with some other files is simple, but there are many things that need to be accounted for, and are prone to human error. There are also many possibilities for what somebody may want to include in a distribution, and how they want to include it. Dist::Zilla exists to be a one-stop solution to every possible problem involved in creating a Perl distribution.
Using Dist::Zilla
When you install Dist::Zilla, you will be provided with an executable named dzil. The most important command that dzil provides is build, which - when run in the projects root directory - outputs a distribution tarball. Other commands such as test and release are also provided, but when getting started with Dist::Zilla you will only need the build command.
The "dist.ini" File
Dist::Zilla is configured on a per-project basis through a file named dist.ini, which should be located at the root of the project's directory tree.
The beginning of a dist.ini file specifies required settings that every distribution should have. These settings include name, version, abstract, copyright_holder, and license. (There is also author, which isn't required but you probably want to add it as well.)
Here is an example:
name = App-Foo
version = 1.0
author = Jane Doe
copyright_holder = Jane Doe
license = Perl_5
abstract = the best software ever
After you specify these required settings, you can then configure your distribution by specifying what plugins you wish to use. Plugins are the mechanism that Dist::Zilla uses for providing features to your Perl distribution. If you have a dist.ini that doesn't specify any plugins, Dist::Zilla will produce an empty distribution with no files.
Let's look at example of the plugins that a simple distribution might use, then go over what a few of the plugins actually do:
[MetaResources]
homepage = https://github.com/JaneDoe/App-Foo
bugtracker.web = https://github.com/JaneDoe/App-Foo/issues
repository.url = https://github.com/JaneDoe/App-Foo.git
[GatherDir]
[PruneCruft]
[ManifestSkip]
[MetaYAML]
[License]
[ExecDir]
[MakeMaker]
[Manifest]
[AutoPrereqs]
[TestRelease]
The MetaResources plugin adds resource entries to the distribution's metadata. MetaCPAN can use this information to provide useful links to the distribution's page.
The GatherDir and PruneCruft plugins tell Dist::Zilla that you want to include all the files in your project's directory into the distribution, excluding the ones you certainly don't want. The files you certainly don't want include build artifacts introduced by recent invocations of Dist::Zilla. The combination of these two plugins is used in almost every Dist::Zilla project.
The MakeMaker plugin will tell Dist::Zilla to produce an ExtUtils::MakeMaker-powered Makefile.PL. Dist::Zilla will deal with everything required to create a proper Makefile.PL, so you do not need to know anything about ExtUtils::MakeMaker. Unless you are doing something special, you almost certainly want to use this plugin.
The UploadToCPAN plugin will allow you to use the dzil release command to upload your distribution to CPAN.
It is important to note that each plugin takes effect in the order the plugins are specified in your dist.ini.
There are many plugins available for Dist::Zilla - over 1,200 thus far - so you will probably find one that can do just about anything you could possibly need for creating a distribution. Here is a link for a metacpan query for "Dist::Zilla::Plugin", that can be used to explore the Dist::Zilla plugin ecosystem.
Here are links to the documentation for the plugins in the example dist.ini that I did not explain:
Synopsis
Dist::Zilla can seem daunting at first, but it is actually quite straightforward and easy to use once you figure it out. The only difficult thing is figuring out what plugins you want to use.
Top comments (0)