Zilla::Dist - Dist::Zilla Mixed Up
> zild setup > # Edit the Meta file. > make publish
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.
zild
dzil
Dist::Zilla
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:
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
dist.ini
.travis.yml
bower.json
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 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
prove -lv test
make install
Do a dzil install.
make doc
Make the ReadMe.pod and other stuff.
ReadMe.pod
make cpan
Turn repo into a Dist::Zilla ready subdirectory called ./cpan/. This directory has a dist.ini file.
./cpan/
make dist
Basically the same as make cpan; cd cpan; dzil build.
make cpan; cd cpan; dzil build
make distdir
Unzip the dist, for inspection.
make publish
Have dzil build a dist, then cpan-upload it.
cpan-upload
make publish-dryrun
Yep.
make upgrade
Upgrade the Zilla::Dist Makefile.
Makefile
make help
Show documentation for all targets.
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.
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.
Meta
To do a release, just set the version in the Meta file and add a Changes section using the same version. Then run:
version
Changes
This will:
Make sure things are ready for release.
Make a dzil ready directory of your stuff called ./cpan/.
Call dzil build.
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.
git push
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.
make
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.
Package
Distribution
The name t/ is another outlier. The most common is test/ followed by tests/.
t/
test/
tests/
I don't like plural directory names. Try singular. I think you'll like it too.
ALLCAPSFILENAMES ARE TOO LOUD! ChillOut.
https://github.com/ingydotnet/zilla-dist-pm !!
https://github.com/ingydotnet/pegex-pm
https://github.com/ingydotnet/testml-pm
https://github.com/ingydotnet/kwim-pm
https://github.com/ingydotnet/file-share-pm
Ingy döt Net <ingy@cpan.org>
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
To install Zilla::Dist, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Zilla::Dist
CPAN shell
perl -MCPAN -e shell install Zilla::Dist
For more information on module installation, please visit the detailed CPAN module installation guide.