Overview and Motivation

You are working on a Perl module in git and want to build Debian packages from the same git working copy.

This is where dh-dist-zilla jumps in and tells debhelper how to use Dist::Zilla to generate on-the-fly at build-time the files it needs.

A Closer Look at Dist::Zilla

Dist::Zilla is "Don’t Repeat Yourself" (DRY) for Perl module authors.

Dist::Zilla generates all these files by gathering information from your Perl module code plus a single minimal configuration file called dist.ini.

Dist::Zilla’s command is dzil and it knows subcommands like git:

authordeps: list your distribution's author dependencies
     build: build your dist
     clean: clean up after build, test, or install
     cover: code coverage metrics for your distribution
   install: install your dist
  listdeps: print your distribution's prerequisites
   release: release your dist
       run: run stuff in a dir where your dist is built
     smoke: smoke your dist
      test: test your dist

Maintaining Debian Packages of Your Own Dist::Zilla based Perl Modules

Typical VCS-Workflow for Building .deb Packages from Your Own Perl Module

  1. Build CPAN tar-ball from master branch with dzil build
  2. Switch to the upstream branch
  3. Import the contents of the tar-ball destined for CPAN into VCS
  4. Merge the upstream branch into the debian branch
  5. Update packaging (debian/changelog, etc.)
  6. Build .deb package

What we want

  • Building the .deb directly from a VCS checkout
  • Skip manual tar-ball generation and reimport
  • Don’t commit generated files to VCS



  • dh-make-perl (for bootstrapping the Debian packaging) needs CPAN meta data.
    • Solution: Run dh-make-perl once manually inside the dzil-generated build directory, copy debian/ subdirectory back into the project root directory.
  • debhelper (dh) only knows about the generated Build.PL and Makefile.PL, not about dist.ini. Solved by dh-dist-zilla.

Debhelper Sequence Modification

  • Generate build directory before debhelper looks for the existing of Build.PL or Makefile.PL.
    • Call dzil build before dh_auto_configure
    • Ignore generated tar ball
  • Build package inside the generated build directory
    • Pass build directory option -D to dh_auto_configure, dh_auto_build, dh_auto_test and dh_auto_install.
  • Easy cleanup: Just delete the build directory.
    • Call dzil clean before dh_auto_clean.

How do I use dh-dist-zilla in my Debian package?

It’s as simple as this debian/rules file:

#!/usr/bin/make -f
      dh $@ --with dist-zilla

Additionally, a build-dependency on dh-dist-zilla is needed.

Untypical Workflow

Expected / Traditional

  • VCS → dzil build → CPAN tar-ball ∈ Debian Source Package → Debian Binary Package


  • VCS → dzil build → CPAN tar-ball
  • VCS = Debian Source Package → Debian Binary Package

The .orig.tar.xz tar ball for the Debian source package can be generated from the git working copy using dh_dist_zilla_origtar.


  • CPAN tar ball and .orig.tar tar ball for Debian differ.

Example Modules/Packages