WHAT?
perl-Dist-Zilla-Plugin-Manifest-Write is a plugin for Dist-Zilla, a replacement
for standard plugin Manifest. perl-Dist-Zilla-Plugin-Manifest-Write writes
annotated MANIFEST: each file followed by a comment, explaining origin of the
file, whether it is part of software, meta information, or 3rd party file.
perl-Dist-Zilla-Plugin-Manifest-Write is free software.
NAMING
perl-Dist-Zilla-Plugin-Manifest-Write 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-Manifest-Write. In the rest of the documentation shortened
name Dist-Zilla-Plugin-Manifest-Write is used as synonym for full name
perl-Dist-Zilla-Plugin-Manifest-Write. We are in the Perl world, aren't we?
You may notice that name may be spelled with dashes
(Dist-Zilla-Plugin-Manifest-Write) or with double colons
(Dist::Zilla::Plugin::Manifest::Write). 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.
WHY?
Typical MANIFEST file included into a Perl distribution is plain list of all
distribution files, a filename per line, e. g.:
Build.PL
COPYING
Changes
MANIFEST
META.yml
README
lib/Foo.pm
t/00-compile.t
xt/author/eol.t
xt/author/no-tabs.t
However, files have different origin:
1. Some files created by software author (in the example above, lib/Assa.pm
*could* be such file).
2. Some files contain distribution meta information (META.yml and MANIFEST
itself).
3. Some files may be generated by a tool from third party templates (Dist-Zilla
and its plugins can generate a lot of various files, in the example above
all the tests *could* be generated, as well as Build.PL, COPYING, and even
Changes).
File origin may be important. For example, if you want to copy a file from a
distribution, you have to check the terms of the license first. However, the
distribution license covers only files from category #1. Obviously, distribution
license is not applicable to files from category #3. So, you have to *guess*
whether a file is from category #1 or #3. I do not like guessing. To me it would
be much better if MANIFEST clearly states origin of each file (Foo is name of
manifested software):
Build.PL # 3rd party file added by ModuleBuildTiny
COPYING # Foo file added by GatherFromManifest
Changes # Foo file added by GatherFromManifest
MANIFEST # metainfo file generated by Manifest::Write
META.yml # metainfo file generated by MetaYAML
README # Foo file added by GatherFromManifest
lib/Foo.pm # Foo file added by GatherFromManifest and modified by OurPkgVersion
t/00-compile.t # 3rd party file added by Test::Compile
xt/author/eol.t # 3rd party file added by Test::EOL
xt/author/no-tabs.t # 3rd party file added by Test::NoTabs
In such a case you *know* which files are covered by COPYING.
Dist-Zilla-Plugin-Manifest-Write creates such annotated manifests.
FORMS
You may face Dist-Zilla-Plugin-Manifest-Write in *source* or *distribution*
forms.
If you are going to have annotated MANIFEST in your distribution, you will
likely be interested in *using* Dist-Zilla-Plugin-Manifest-Write *distribution*.
If you are going to *develop* (or *hack*) the Dist-Zilla-Plugin-Manifest-Write
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-Manifest-Write), while name of distribution does (e. g.
Dist-Zilla-Plugin-Manifest-Write-0.007).
SOURCE
Dist-Zilla-Plugin-Manifest-Write 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-Manifest-Write
Source files
Dist-Zilla-Plugin-Manifest-Write source files usually include a comment near the
top of the file:
This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.
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-Manifest-Write 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-Manifest-Write
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-Manifest-Write source, and
Dist-Zilla-Plugin-Manifest-Write 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::Manifest::Write
To install a specific version (e. g. *0.007*) from CPAN:
$ cpanm Dist::Zilla::Plugin::Manifest::Write@0.007
To install locally available distribution (e. g. previously downloaded from CPAN
or built from sources):
$ cpanm ./Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz
To uninstall the distribution:
$ cpanm -U Dist::Zilla::Plugin::Manifest::Write
Manually
To install distribution tarball manually (let us assume you have version *0.007*
of the distribution):
$ tar xaf Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz
$ cd Dist-Zilla-Plugin-Manifest-Write-0.007
$ 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-Dist-Zilla-Plugin-Manifest-Write
$ cd perl-Dist-Zilla-Plugin-Manifest-Write
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
or
$ cpanm ./Dist-Zilla-Plugin-Manifest-Write-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::Manifest::Write::ReadMe
$ perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
$ perldoc Dist::Zilla::Plugin::Manifest::Write
Built from source
Build Dist-Zilla-Plugin-Manifest-Write first (see "HACKING"), then:
$ PERL5LIB=Dist-Zilla-Plugin-Manifest-Write-VERSION/lib:$PERL5LIB perldoc Dist::Zilla::Plugin::Manifest::Write::ReadMe
$ PERL5LIB=Dist-Zilla-Plugin-Manifest-Write-VERSION/lib:$PERL5LIB perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
$ PERL5LIB=Dist-Zilla-Plugin-Manifest-Write-VERSION/lib:$PERL5LIB perldoc Dist::Zilla::Plugin::Manifest::Write
where *VERSION* is a version of built distribution.
BUGS
CPAN request tracker
The quickest way to report a bug in Dist-Zilla-Plugin-Manifest-Write is by
sending email to bug-Dist-Zilla-Plugin-Manifest-Write [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.)
Email to author
As a last resort, send email to author: Van de Bugger .
Please start message subject with "Dist-Zilla-Plugin-Manifest-Write:".
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
.
COPYRIGHT AND LICENSE
Copyright © 2015 Van de Bugger
perl-Dist-Zilla-Plugin-Manifest-Write 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-Manifest-Write 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-Manifest-Write. If not, see
.
perl-Dist-Zilla-Plugin-Manifest-Write *distribution* may contain files generated
by Dist-Zilla and/or its plugins from third-party templates; copyright and
license specified above are *not* applicable to that files.
SEE ALSO
Dist::Zilla — distribution builder; installer not included!
Dist::Zilla::Plugin::Manifest — build a MANIFEST file