WHAT?
Test-Dist-Zilla is a set of Test::Routine-based roles for testing Dist::Ziilla
and its plugins.
WHY?
TODO
NAMING
perl-Test-Dist-Zilla 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 Test-Dist-Zilla. In
the rest of the documentation shortened name Test-Dist-Zilla is used as synonym
for full name perl-Test-Dist-Zilla. We are in the Perl world, aren't we?
You may notice that name may be spelled with dashes (Test-Dist-Zilla) or with
double colons (Test::Dist::Zilla). 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 Test-Dist-Zilla in *source* or *distribution* forms.
If you are going to test your Dist::Zilla plugin, you will likely be interested
in *using* Test-Dist-Zilla *distribution*. If you are going to *develop* (or
*hack*) the Test-Dist-Zilla 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. Test-Dist-Zilla),
while name of distribution does (e. g. Test-Dist-Zilla-v0.7.1).
SOURCE
Test-Dist-Zilla source is in Mercurial repository hosted on fedorapeople.org. To
clone the entire repository:
$ hg clone https://vandebugger.fedorapeople.org/hg/perl-Test-Dist-Zilla
Source Files
Test-Dist-Zilla source files usually include a comment near the top of the file:
This file is part of perl-Test-Dist-Zilla.
Not all source files are included into distribution. Some source files are used
at distribution build time only, and not required for installation.
DISTRIBUTION
Test-Dist-Zilla 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 Test-Dist-Zilla 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 Test-Dist-Zilla source, and Test-Dist-Zilla 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 Test::Dist::Zilla
To install a specific version (e. g. *v0.7.1*) from CPAN:
$ cpanm Test::Dist::Zilla@v0.7.1
To install locally available distribution (e. g. previously downloaded from CPAN
or built from sources):
$ cpanm ./Test-Dist-Zilla-v0.7.1.tar.gz
To uninstall the distribution:
$ cpanm -U Test::Dist::Zilla
Manually
To install distribution tarball manually (let us assume you have version
*v0.7.1* of the distribution):
$ tar xaf Test-Dist-Zilla-v0.7.1.tar.gz
$ cd Test-Dist-Zilla-v0.7.1
$ perl Build.PL
$ ./Build build
$ ./Build test
$ ./Build install
See Also
How to install CPAN modules
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-Test-Dist-Zilla
$ cd perl-Test-Dist-Zilla
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
or
$ cpanm ./Test-Dist-Zilla-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 Test::Dist::Zilla::Manual
$ perldoc Test::Dist::Zilla
Built from Source
Build Test-Dist-Zilla first (see "HACKING"), then:
$ cd Test-Dist-Zilla-VERSION
$ perldoc Test::Dist::Zilla::Manual
$ perldoc Test::Dist::Zilla
where *VERSION* is a version of built distribution.
FEEDBACK
CPAN Request Tracker
The quickest way to report a bug in Test-Dist-Zilla is by sending email to
bug-Test-Dist-Zilla [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 .
Please start message subject with "perl-Test-Dist-Zilla:".
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
.