- RATIONALE RANTING
- COPYRIGHT AND LICENSE
Zilla::Dist - Dist::Zilla Mixed Up
This document describes Zilla::Dist version 0.1.5.
> zild Meta > # Edit the Meta file. > zild release
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.
A fully stacked top level CPAN package repository might look like this:
Changes # History in YAML Contributing # A generated instruction file for contributing Meta # Meta info for all metadata needs (including dzil) ReadMe.pod # Generated from `doc/Module.swim` .travis.yml # Travis file (generated) 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
Note a few things:
Directories are lowercase. Never plural
Files are TitleCase
No file extensions (if possible)
No extra meta files like
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 uses a Makefile to do everything, but you never see it. You run commands like:
zild make test
zild make help to get a list of all the targets.
The most common targets don't require you to type
make. For instance, you can simply:
Here are the most important targets:
Build the dist, then
Run the test suite.
Build and install the software. Same as install from CPAN.
Rebuild the ReadMe.pod and other generated files.
Install the prereqs from CPAN that are listed in the
Turn repo into a
Dist::Zillaready subdirectory called
./cpan/. This directory has a
Basically the same as
zild cpan; cd cpan; dzil build.
Start by running:
cp `zild sharedir`/Meta .
and you'll get a
Meta file template. You need to customize the
Meta file with information specific to your project.
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 sure things are ready for release.
Update the modules with
$VERSIONto the new version.
Make a dzil ready directory of your stuff called
cpan-uploadto send the dist to CPAN.
Tag the git repo with the version string.
git pushthe repo and tag upstream.
This section lists all the things that actually happen during the
zild release step.
…to be completed…
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
zild release 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.
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.
t/ is another outlier. The most common is
test/ followed by
I don't like plural directory names. Try singular. I think you'll like it too.
ALLCAPSFILENAMES ARE TOO LOUD! ChillOut.
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.
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.
Ingy döt Net <firstname.lastname@example.org>
Copyright 2014-2020. Ingy döt Net.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.