NAME

Dist::Zilla::Plugin::Hook::ReadMe - Dist::Zilla::Plugin::Hook ReadMe

VERSION

Version 0.002, released on 2015-07-23 22:08 UTC.

WHAT?

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 process.

This is Dist-Zilla-Plugin-Hook readme. It covers general topics like getting source, building, installing, bug reporting and some others.

If you want to write Dist::Zilla plugin directly in dist.ini, read the manual. If you are going to hack or extend Dist-Zilla-Plugin-Hook, read the module documentation.

WHY?

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::BeforeBuild]
    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"
[GenerateFile/Assa.pm]
    filename = lib/Assa.pm
    content  = package Assa; 1;
[FakeRelease]

$ 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 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
[Run::BeforeBuild]
    eval = my $self = shift( @_ );
    eval = my $dist = $self->zilla;
    eval = $self->log( [ '%s v%s', $dist->name, $dist->version ] );
[GenerateFile/Assa.pm]
    filename = lib/Assa.pm
    content  = package Assa; 1;
[FakeRelease]

$ 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".

There is (undocumented) method to avoid it — every percent sign should be doubled:

my %%args;

However, this is err… not quite Perl.

Let me cite "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 rather minimalistic: It provides only one option, and it executes only Perl. All other Run features can be easily implemented 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;
; or
. = if ( $dist->is_trial ) { … };

Checking release build:

. = … if $ENV{ DZIL_RELEASING };
; or
. = 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:

Hook passes arguments provided by Dist::Zilla to the code.
Hook passes return value from the code back to Dist::Zilla.

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

[Hook::VersionProvider]
    . = use Path::Tiny; path('VERSION' )->slurp;

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

NAMING

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 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.

FORMS

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 files dist.ini, weaver.ini, 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-0.007).

SOURCE

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.

DISTRIBUTION

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.

INSTALLING

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. 0.007) from CPAN:

$ cpanm Dist::Zilla::Plugin::Hook@0.007

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

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

To uninstall the distribution:

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

Manually

To install distribution tarball manually (let us assume you have version 0.007 of the distribution):

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

HACKING

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, 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:

$ dzil test

To run all the tests, including release tests:

$ dzil test --release

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

DOCUMENTATION

Online

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::ReadMe
$ 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::ReadMe
$ perldoc Dist::Zilla::Plugin::Hook::Manual
$ perldoc Dist::Zilla::Plugin::Hook

where VERSION is a version of built distribution.

FEEDBACK

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 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 providers.)

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:".

GLOSSARY

CPAN: Comprehensive Perl Archive Network, a large collection of Perl software and documentation. See cpan.org, What is CPAN?.
Distribution: 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).
Module: Perl library file, usually with .pm suffix. Usually contains one package. See perlmod.
Package: Perl language construct. See package and perlmod.

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

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

perl-Dist-Zilla-Plugin-Hook is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Plugin-Hook is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Plugin-Hook. If not, see <http://www.gnu.org/licenses/>.

To install Dist::Zilla::Plugin::Hook, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Dist::Zilla::Plugin::Hook

CPAN shell

perl -MCPAN -e shell
install Dist::Zilla::Plugin::Hook

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

WHAT?

WHY?

NAMING

FORMS

SOURCE

Source Files

DISTRIBUTION

Generated Files

INSTALLING

With `cpanm`

Manually

See Also

HACKING

DOCUMENTATION

Online

Locally Installed

Built from Source

FEEDBACK

CPAN Request Tracker

Send Email to Author

GLOSSARY

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

NAME

VERSION

WHAT?

WHY?

NAMING

FORMS

SOURCE

Source Files

DISTRIBUTION

Generated Files

INSTALLING

With cpanm

Manually

See Also

HACKING

DOCUMENTATION

Online

Locally Installed

Built from Source

FEEDBACK

CPAN Request Tracker

Send Email to Author

GLOSSARY

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

With `cpanm`