/ 
Zilla-Dist-0.0.170
River stage zero No dependents
/ Zilla::Dist

NAME

Zilla::Dist - Dist::Zilla Mixed Up

zilla-dist-pm zilla-dist-pm

SYNOPSIS

> zild
> # Edit the Meta file.
> make release

DESCRIPTION

This module is a formalization of a Perl package directory layout and release process that I have been evolving for some time. I use the same layout for Bash, Ruby, Python and Node.js package publishing.

Zilla::Dist provides a Makefile and set of scripts that take a modern code layout and transform it into something that looks like a standard old Perl distribution. Under the hood zild generates everything that Dist::Zilla wants and lets dzil do the heavy lifting, but you never need to interact with Dist::Zilla stuff directly.

Directory Layout

A fully stacked top level CPAN package repository might look like this:

Changes         # History in YAML
Contributing    # A generated instruction file for contributing
Makefile        # Automation of test, dist, publish, etc
Meta            # Meta info for all metadata needs (including dzil)
ReadMe.pod      # Generated from `doc/Module.swim`
bin/            # Scripts
doc/            # Swim docs
ext/            # External repos (subrepos)
eg/             # Examples
lib/            # Perl `.pm` code
pkg/            # Packaging related files
note/           # Project notes, todo lists, ideas, specs, etc
share/          # Shared files to distribute
test/           # Test suite
.travis.yml     # Travis file (generated)

Note a few things:

  • Sane/Readable names

  • Directories are lowercase. Never plural

  • Files are TitleCase

  • No file extensions (if possible)

  • No extra meta files like dist.ini, .travis.yml, bower.json etc

These are the best of from all the package systems I've used. They make me happy, and not tied to poor legacy standards.

Zilla::Dist

Zilla::Dist provides a Makefile to do everything. You get a new Makefile with:

> zild [setup]

And you can refresh it later with:

> make update

Run make help to get a list of all the targets. Here are the most important targets:

make release

Build the dist, then cpan-upload it.

make test

Run the test suite.

make install

Build and install the software. Same as install from CPAN.

make prereqs

Install the prereqs from CPAN that are listed in the Meta file's requires: field.

make cpan

Turn repo into a Dist::Zilla ready subdirectory called ./cpan/. This directory has a dist.ini file.

make dist

Basically the same as make cpan; cd cpan; dzil build.

USAGE

Start by running:

zild

and you'll get a Makefile and a Meta file template. You need to customize the Meta file and leave the Makefile alone.

To do a release, just set a new version in the Meta file and add a Changes section using the same version. Then run:

make release

This will:

  • Make sure things are ready for release.

  • Make a dzil ready directory of your stuff called ./cpan/.

  • Call dzil build.

  • Call cpan-upload to send the dist to CPAN.

  • Tag the git repo with the version string.

  • git push the repo and tag upstream.

Release in Depth

This section lists all the things that actually happen during the make release step.

…to be completed…

RATIONALE RANTING

I've published a lot of packages in a lot of programming languages. I like taking the best ideas and spreading them around. I like reusing ideas and code and tools as much as possible between these packages.

I trust dzil to DTRT with regard to the CPAN release process. I use almost the exact same dist.ini for some 50 CPAN packages that I've converted so far.

I don't like cluttered repos and adding new metadata files for each new tool that needs one. The dist.ini file is not bad, but I can generate it from metadata easily. So I do.

As much as these great new ideas differ from the norm, I want my CPAN publishings to be normal to normal mongers (if there's such a thing). The make releasse process does just that. End users would have to look hard to know this wasn't a "normal" dzil release.

I'm packaging this packaging process as Zilla::Dist for others to use. It's also a decent example of a CPAN package packaged with itself.

NOTES

Unlike dzil, the only zild command you ever use is zild (with no arguments) to get the Zilla::Dist Makefile and Meta file. After that, all Zilla::Dist commands are make targets.

Some of the tools in Zilla::Dist are Bash, some are Perl. I'm doing a lot in the area of Bash Package packaging. See http://bpan.org.

I use the term Package where CPAN people have used the term Distribution. Perl is the only language (in my packaging experience) to do so.

The name t/ is another outlier. The most common is test/ followed by tests/.

I don't like plural directory names. Try singular. I think you'll like it too.

ALLCAPSFILENAMES ARE TOO LOUD! ChillOut.

Commiting Generated Code/Files

People think that committing generated code/files is a bad idea and in general I concur, but there are exceptions.

Sometimes tools like Travis-CI require you to commit a config file. Zilla::Dist generates these files from metadata, which is a whole lot easier than maintaining them yourself, but you end up commiting generated code.

The dist.ini file is only needed locally, however, during dist build time, so no need to commit that.

In general, when an external tool requires files, and it's easiest to generate those files, it's OK to commit generated code.

SEE ALSO

Modules Published to CPAN w/ zild

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2014. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html