> dzil

How CPAN Distributions Work

First off, let's just acknowledge that there are lots of wacky edge cases and weird things that go on. It's Perl, so there are lots of crazy people doing crazy things. This summary is just an overview of the simplest case.

A CPAN distribution is a gzipped tar archive with a filename in the form

  Distribution-Name-1.234.tar.gz

Distribution-Name is the name of the distribution, which is usually just the name of its most important module with the "::" replaced with a dash. The "1.234" is the version number. Extracted, the tarball's contents will look something like:

  Distribution-Name-1.234/Changes
  Distribution-Name-1.234/LICENSE
  Distribution-Name-1.234/MANIFEST
  Distribution-Name-1.234/META.yml
  Distribution-Name-1.234/Makefile.PL
  Distribution-Name-1.234/README
  Distribution-Name-1.234/bin/dist-program
  Distribution-Name-1.234/lib/Distribution/Name.pm
  Distribution-Name-1.234/lib/Distribution/Name/Helper.pm
  Distribution-Name-1.234/t/00-compile.t
  Distribution-Name-1.234/t/blowfish-tests.t
  Distribution-Name-1.234/t/monkfish-tests.t
  Distribution-Name-1.234/t/octopode-tests.t
  Distribution-Name-1.234/xt/release/pod-syntax.t

Some of these files serve an obvious purpose, like the LICENSE file, the Changes file, or the README. They're found in software distributions everywhere. CPAN doesn't require them, but they help downstream packagers (people who package Perl for OS-level package managers, for example). Other files are the actual code: the files under lib are the libraries you're shipping. The files under bin are executables to be installed into the user's $PATH. The files in t and xt are automated tests, run before releasing or before installing the library.

That just leaves a few CPAN packaging related files to mention:

MANIFEST

This file lists all the files in the archive. Some tools use it to sanity-check the distribution.

Makefile.PL and/or Build.PL

One or both of these files may appear. They're programs that the installing user runs to configure, build, test, and install the distribution. Traditionally, they've also been used by the distribution's packager to build the tarball -- but with Dist::Zilla, that's no longer the case. Dist::Zilla replaces these files for packaging the archive, but not for installing.

META.yml and/or META.json

These files describes the distribution so that installers, indexers, and other programs can get an idea what the distribution contains. They report the dist's name, version, authors, and license. They'll often tell you what packages the distribution provides, what packages must be present for it to work, and some other metadata about the distribution.

How does Dist::Zilla help?

When packaging with the traditional distribution building tools, almost all of the files in the distribution had to be managed by the author. The author had to maintain the manifest, provide the correct license file, update the "stock" tests that he shipped in all his distributions, and so on. Some build tools could take care of some of these, but Dist::Zilla tries to take care of all of them. Instead of tracking all the dist's files in your repository, Dist::Zilla lets you focus on the ones you care about:

  bin/dist-program
  lib/Distribution/Name.pm
  lib/Distribution/Name/Helper.pm
  t/blowfish-tests.t
  t/monkfish-tests.t
  t/octopode-tests.t

...and then dist.ini or another Dist::Zilla configuration file.

When you're ready to build a complete distribution, you run dzil build and Dist::Zilla runs through its build mechanism, using your plugins to add needed files (like LICENSE and META.yml) and to add boilerplate to existing files (like versions and copyright statements to your code files).