Ingy döt Net > Zilla-Dist-0.0.11 > Zilla::Dist

Download:
Zilla-Dist-0.0.11.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.0.11   Source   Latest Release: Zilla-Dist-0.0.163

NAME ^

Zilla::Dist - Dist::Zilla Mixed Up

SYNOPSIS ^

    > zild setup
    > # Edit the Meta file.
    > make publish

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
    Makefile        # Automation of test, dist, publish, etc
    Meta            # Meta info for all metadata needs (including dzil)
    ReadMe.pod      # Generated from `doc/Module.kwim`
    bin/            # Scripts
    doc/            # Kwim docs
    eg/             # Examples
    lib/            # Perl `.pm` code
    share/          # Shared files
    test/           # Test suite

Note a few things:

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

The Makefile has these targets:

make test

Use prove -lv test

make install

Do a dzil install.

make doc

Make the ReadMe.pod and other stuff.

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.

make distdir

Unzip the dist, for inspection.

make publish

Have dzil build a dist, then cpan-upload it.

make publish-dryrun

Yep.

make upgrade

Upgrade the Zilla::Dist Makefile.

make help

Show documentation for all targets.

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 20 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 publish 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.

USAGE ^

Start by running:

    zild setup

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 the version in the Meta file and add a Changes section using the same version. Then run:

    make publish

This will:

NOTES ^

Unlike dzil, the only zild command you ever use is zild setup to get the Zilla::Dist Makefile. 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.

SEE ALSO ^

Modules Published to CPAN w/ `zild`

AUTHOR ^

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

COPYRIGHT AND LICENSE ^

Copyright (c) 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

syntax highlighting: