Maintaining Debian Packages of Perl Modules with dh-dist-zilla //at 03:59 //by abe

Maintaining Debian packages of Perl modules usually can be done with the common git-buildpackage (aka gbp) workflow with its three git branches master (or debian), upstream and pristine-tar:

• upstream contains the upstream code as imported from upstream’s release tar-balls.
• pristine-tar contains the binary diffs between the contents of the upstream branch and the original tar-ball. This mostly contains meta-data (timestamps, permissions, file owners, etc.) as git doesn’t store them.
• master (or debian) which contains upstream plus packaging.

This also works more or less fine for Perl modules, where the Debian package maintainer is also the upstream developer. In that case mostly the upstream branch is used (and then maybe called master while the Debian packaging branch is then called debian).

But the files needed for a proper so called “CPAN distribution” of a Perl module often contain redundant information (version numbers, required modules, etc.) which needs to be maintained. And for that, many people prefer Don’t Repeat Yourself (DRY) as a principle.

Dist::Zilla

One nice and common tool for that is Dist::Zilla or short dzil. It generates most redundant but required data out of a central source, e.g. Dist::Zilla’s dist.ini or the contained .pm files, etc. dzil build creates tar ball which contains all files necessary by CPAN.

But now we have a dilemma: Debian expects those generated files inside the upstream branch while the files are only generated from other files in that branch. There are multiple solutions, but all of them involve committing generated files to the git repository:

• Commit them into the upstream branch. Disadvantage: You’ll likely later forget which files were generated and which weren’t.
• Commit the generated files into a separated branch, e.g. use master (original code), upstream (original code + stuff generated by dzil build, maybe imported with git-import-orig), pristine-tar and a debian (based on upstream) branches.

librun-parts-perl aka Run::Parts (a Perl wrapper around and a pure-perl implementation of Debian’s run-parts tool) was initially maintained in the latter way.

But especially in cases where we just need a Perl module packaged as .deb without uploading it to CPAN (e.g. project-internal modules), this is a tedious workflow and overkill. It would be much nicer if debhelper would just call dzil to generate all the stuff it needs to build the package.

dh-dist-zilla

Well, you can do that now, at least with Debian Jessie. This is what dh-dist-zilla does: It is a debhelper sequence plugin which calls dzil build and dzil clean in the right moment and takes care that all dh_auto_* commands look in the directory with the generated files instead of the rather clean project root directory.

To use dh-dist-zilla, you just need to add a build-dependency on it and the Dist::Zilla plugins you use, and add --with dist-zilla to your minimal dh-style debian/rules file:

#!/usr/bin/make -f

%:
	dh $@ --with dist-zilla

That’s it.

With regards to workflow and git branches, you may still want to use separate branches for upstream work and debian work, and you may want to continue to use pristine-tar, but you don’t have to commit generated files to git anymore and you can maintain a clean master branch with nearly no redundancy.

And if you need to generate to final upstream tar ball for you debian package, just call dh get-orig-source or maybe easier to use with tab completion dh_dist_zilla_origtar.

This is how the librun-parts-perl package is maintained nowadays. There’s otherwise not much difference to the old, classically maintained versions.

More DRY

Next step in the DRY evolution is to reduce redundancies between upstream (Dist::Zilla based) packaging and the Debian packaging. There are a few tools available, partially brand new, partially not yet packaged:

• dh-dist-zilla’s dh-dzil-refresh which combines dh-make-perl’s “refresh” subcommand with Dist::Zilla.
• Enrico Zini’s debdry, which aims to be a front-end to all the language specific packaging automation tools like dh-make-perl and gem2deb.
• The not yet packaged Perl module distribution Dist-Zilla-Deb which beyond others contains the (slightly under-documented) Perl module Dist::Zilla::Plugin::Deb::VersionFromChangelog to use the version from Debian’s changelog as the primary source for the version of the module. (Source code is on GitHub.)
• And then there is Dist::Zilla::App::Command::authordebs aka libdist-zilla-app-command-authordebs-perl by Dominque Dumont which lists or installs Dist::Zilla authors dependencies as Debian packages. (Source code is on GitHub, too.)

I wouldn’t be surprised if there’s more to come in this area.

P.S.: I actually started this blog posting in September 2014 and never finished it until now. Had to kick out some already outdated again stuff, but also could add some more recent things.