Dist-Zilla-Plugin-Hook (or just Hook) is a set of Dist-Zilla plugins. Every
plugin executes Perl code inlined into dist.ini at particular stage of build


There is Dist::Zilla::Plugin::Run on CPAN which allows to run Perl code from
within dist.ini, why I wrote one more? Let us consider two examples.

The first one executes external commands:

    $cat dist.ini
    name     = RunShell
    abstract = RunShell demo
    version  = 0.001_001
        run            = echo "1. begin"
        run_if_release = echo "2. release"
        run_no_release = echo "3. not release"
        run_if_trial   = echo "4. trial"
        run_no_trial   = echo "5. not trial"
        run            = echo "6. end"
        filename = lib/Assa.pm
        content  = package Assa; 1;

    $ dzil build
    [Run::BeforeBuild] executing: echo "1. begin"
    [Run::BeforeBuild] 1. begin
    [Run::BeforeBuild] executing: echo "6. end"
    [Run::BeforeBuild] 6. end
    [Run::BeforeBuild] executing: echo "5. not trial"
    [Run::BeforeBuild] 5. not trial
    [Run::BeforeBuild] executing: echo "3. not release"
    [Run::BeforeBuild] 3. not release
    [DZ] beginning to build RunShell
    [DZ] writing RunShell in RunShell-0.001_001
    [DZ] building archive with Archive::Tar::Wrapper
    [DZ] writing archive to RunShell-0.001_001-TRIAL.tar.gz
    [DZ] built in RunShell-0.001_001

Execution order is err… non-linear. Of course there is an explanation why
command were executed in this particular order, but when you are looking at
dist.ini it is not obvious. (It is also unclear why Run consider the build is
*not* trial, but it may be just a bug.)

Another example executes Perl code:

    $cat dist.ini
    name     = RunPerl
    abstract = RunPerl demo
    version  = 0.001_001
        eval = my $self = shift( @_ );
        eval = my $dist = $self->zilla;
        eval = $self->log( [ '%s v%s', $dist->name, $dist->version ] );
        filename = lib/Assa.pm
        content  = package Assa; 1;

    $ dzil build
    [Run::BeforeBuild] evaluating: my $self = shift( @_ );
    [Run::BeforeBuild] my $dist = $self->zilla;
    [Run::BeforeBuild] $self->log( [ '0.001_001 v', $dist->name, $dist->version ] );
    [Run::BeforeBuild] 0.001_001 v
    [DZ] beginning to build RunPerl
    [DZ] writing RunPerl in RunPerl-0.001_001
    [DZ] building archive with Archive::Tar::Wrapper
    [DZ] writing archive to RunPerl-0.001_001-TRIAL.tar.gz
    [DZ] built in RunPerl-0.001_001

Look at the last message from Run::BeforeBuild plugin. Surprising? Where is the
distribution name? Why is the character "v" printed after version number? Ah! %s
is a special conversion specifier which was replaced with "something retained
for backward compatibility". There is a bunch of other conversion specifiers:
%a, %d, %n,%p, %t, %v, %x,… That effectively means I cannot use printf-like
functions and hashes, because every percent will be replaced with something or
cause error "unknown conversion".

Ok, I can. There is (undocumented!) method to avoid it — every percent sign
should be doubled:

    eval = $self->log( [ '%%s v%%s', $dist->name, $dist->version ] );


    eval = my %%meta = %%{ $dist->distmeta };

It is simple, but… this is err… not quite Perl. I cannot just cut-n-paste code
from a plugin to dist.ini and back.

Let me cite a part of "Philosophy" section of the great Text::Template module:

    When people make a template module like this one, they almost always start
    by inventing a special syntax for substitutions. For example, they build it
    so that a string like %%VAR%% is replaced with the value of $VAR. Then they
    realize the need extra formatting, so they put in some special syntax for
    formatting. Then they need a loop, so they invent a loop syntax. Pretty soon
    they have a new little template language.

    This approach has two problems: First, their little language is crippled. If
    you need to do something the author hasn't thought of, you lose. Second: Who
    wants to learn another language? You already know Perl, so why not use it?

Look: Run plugin introduced a bunch of dist.ini options: run_if_trial,
run_no_trial (BTW, why not run_if_not_trial?), run_if_release, run_no_release,
eval, censor_commands, fatal_errors, quiet; a bunch of "conversion specifiers":
%a, %d, %n, %p, %v, %t, %x, %s; and bunch of poorly documented rules. It's "a
little crippled language", isn't it?

Compared to Run, Hook is designed to be minimalistic: It provides only one
option, and it executes only Perl. Of course, when writing a hook you have to
keep in mind many rules, but these are well documented Perl rules and (not so
well) Dist::Zilla rules, not rules introduced by Hook.

All Run features can be easily implemented with hooks in Perl, for example:

Running external commands:

    . = system( … );

Making errors in external commands fatal:

    . = use autodie ':all';
    . = system( … );

Making errors in Perl code non-fatal:

    . = use Try::Tiny;
    . = try { … };

Checking trial status:

    . = if ( $dist->is_trial ) { … };

Checking release build:

    . = if ( $ENV{ DZIL_RELEASING } ) { … };

The code is a little bit longer than Run counterparts, but it is well-known
full-featured Perl.

What if you need to pass to an external command something the Run authors have
not thought of? For example, abstract or licence name. There are no conversion
specifiers for it, so you lose. But with Hook it is trivial:

    . = system( …, $dist->abstract, …, $dist->license->name, … );

BTW, there are two minor (at the first look) Hook features:

These bring a new quality: with Hook you can write inline plugins. For example,
a plugin which reads distribution version from an external file:

        . = use Path::Tiny; path( 'VERSION' )->slurp;

(Actually, every hook is an inline plugin.) See more in "EXAMPLES" in


perl-Dist-Zilla-Plugin-Hook is official software name.

However, in Perl world prefix "perl-" is redundant and not used. For example, on
meta::cpan <https://metacpan.org/> this software is named as
Dist-Zilla-Plugin-Hook. In the rest of the documentation shortened name
Dist-Zilla-Plugin-Hook is used as synonym for full name
perl-Dist-Zilla-Plugin-Hook. We are in the Perl world, aren't we?

You may notice that name may be spelled with dashes (Dist-Zilla-Plugin-Hook) or
with double colons (Dist::Zilla::Plugin::Hook). Strictly speaking, there is
difference: the first one is software name, while the second is name of Perl
package, but often these names are interchangeable especially if software
consists of single package.


You may face Dist-Zilla-Plugin-Hook in *source* or *distribution* forms.

If you are going to write Dist::Zilla plugin directly in dist.ini, you will
likely be interested in *using* Dist-Zilla-Plugin-Hook *distribution*. If you
are going to *develop* (or *hack*) the Dist-Zilla-Plugin-Hook itself, you will
likely need the *source*, not distribution.

Since Perl is an interpreting language, modules in the distribution *look* like
sources. Actually, they are Perl source files. But they are not *actual*
sources, because they are *built* (preprocessed or generated) by Dist-Zilla.

How to distinguish source and distribution:

*   Source may contain Mercurial files and directories .hgignore, .hgtags, .hg/,
    while distribution should not.

*   Source should contain dist.ini file, while distribution may not.

*   Source should *not* contain xt/ directory, while distribution should.

*   Name of source directory does *not* include version (e. g.
    Dist-Zilla-Plugin-Hook), while name of distribution does (e. g.


Dist-Zilla-Plugin-Hook source is in Mercurial repository hosted on
fedorapeople.org. To clone the entire repository:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Hook

Source Files

Dist-Zilla-Plugin-Hook source files usually include a comment near the top of
the file:

    This file is part of perl-Dist-Zilla-Plugin-Hook.

Not all source files are included into distribution. Some source files are used
at distribution build time only, and not required for installation.


Dist-Zilla-Plugin-Hook distributions are published on CPAN

Generated Files

Distribution may contain files preprocessed or generated by Dist-Zilla and its
plugins. Some generated files are made from Dist-Zilla-Plugin-Hook source, but
some are generated from third-party templates. Files generated from third-party
templates usually include a comment near the top of the file:

    This file was generated with NAME

(where *NAME* is a name of the plugin generated the file). Such files are *not*
part of Dist-Zilla-Plugin-Hook source, and Dist-Zilla-Plugin-Hook copyright and
license are not applicable to such files.


With cpanm

cpanm tool is (probably) the easiest way to install distribution. It automates
downloading, building, testing, installing, and uninstalling.

To install the latest version from CPAN:

    $ cpanm Dist::Zilla::Plugin::Hook

To install a specific version (e. g. *v0.7.1*) from CPAN:

    $ cpanm Dist::Zilla::Plugin::Hook@v0.7.1

To install locally available distribution (e. g. previously downloaded from CPAN
or built from sources):

    $ cpanm ./Dist-Zilla-Plugin-Hook-v0.7.1.tar.gz

To uninstall the distribution:

    $ cpanm -U Dist::Zilla::Plugin::Hook


To install distribution tarball manually (let us assume you have version
*v0.7.1* of the distribution):

    $ tar xaf Dist-Zilla-Plugin-Hook-v0.7.1.tar.gz
    $ cd Dist-Zilla-Plugin-Hook-v0.7.1
    $ perl Build.PL
    $ ./Build build
    $ ./Build test
    $ ./Build install

See Also

How to install CPAN modules <http://www.cpan.org/modules/INSTALL.html>


For hacking, you will need Mercurial, Perl interpreter and Dist-Zilla (with some
plugins), and likely cpanm to install missed parts.

Clone the repository first:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Hook
    $ cd perl-Dist-Zilla-Plugin-Hook

To build a distribution from the source, run:

    $ dzil build

If required Dist-Zilla plugins are missed, the dzil tool will warn you and show
the command to install all the required plugins, e. g.:

    Required plugin Dist::Zilla::Plugin::Test::EOL isn't installed.

    Run 'dzil authordeps' to see a list of all required plugins.
    You can pipe the list to your CPAN client to install or update them:

        dzil authordeps --missing | cpanm

To run the tests (to check primary software functionality):

    $ dzil test

To run extended tests (to check source code style, documentation and other
things which are not too important for software end users):

    $ dzil xtest

To install the distribution:

    $ dzil install


    $ cpanm ./Dist-Zilla-Plugin-Hook-VERSION.tar.gz

where *VERSION* is a version of built distribution.

To clean the directory:

    $ dzil clean



The easiest way is browsing the documentation online at meta::cpan

Locally Installed

If you have the distribution installed, use perldoc tool to browse locally
installed documentation:

    $ perldoc Dist::Zilla::Plugin::Hook::Manual
    $ perldoc Dist::Zilla::Plugin::Hook

Built from Source

Build Dist-Zilla-Plugin-Hook first (see "HACKING"), then:

    $ cd Dist-Zilla-Plugin-Hook-VERSION
    $ perldoc Dist::Zilla::Plugin::Hook::Manual
    $ perldoc Dist::Zilla::Plugin::Hook

where *VERSION* is a version of built distribution.


CPAN Request Tracker

The quickest way to report a bug in Dist-Zilla-Plugin-Hook is by sending email
to bug-Dist-Zilla-Plugin-Hook [at] rt.cpan.org.

CPAN request tracker can be used via web interface also:

Browse bugs
    Browsing bugs does not require authentication.

Report bugs
    You need to be a CPAN author, have a BitCard <https://www.bitcard.org/>
    account, or OpenID in order to report bugs via the web interface.

    (On 2015-04-27 I have logged in successfully with my LiveJournal OpenID, but
    my Google OpenID did not work for CPAN. I did not check other OpenID

Send Email to Author

As a last resort, send email to author: Van de Bugger <van.de.bugger@gmail.com>.
Please start message subject with "perl-Dist-Zilla-Plugin-Hook:".


    Comprehensive Perl Archive Network, a large collection of Perl software and
    documentation. See cpan.org <http://www.cpan.org>, What is CPAN?

    Tarball, containing Perl modules and accompanying files (documentation,
    metainfo, tests). Usually distributions are uploaded to CPAN, and can be
    installed with dedicated tools (cpan, cpanm, and others).

    Perl library file, usually with .pm suffix. Usually contains one package.
    See perlmod <http://perldoc.perl.org/perlmod.html#Perl-Modules>.

    Perl language construct. See package
    <http://perldoc.perl.org/functions/package.html> and perlmod