WHAT?

Dist-Zilla-Plugin-Manifest-Write (or Manifest::Write for brevity) is a plugin
for Dist::Zilla, a replacement for standard plugin Manifest. Manifest::Write
writes *annotated* distribution manifest: each filename is followed by a comment
explaining origin of the file: if it is a part of software, meta information, or
3rd-party file. Also it can *exclude* built files from distribution, e. g. extra
tests have to be built (to run) but need not be distributed.

WHY?

MANIFEST is a metainfo file, a part of every distribution. It is a plain list of
files included into the distribution. Typical MANIFEST looks like:

    Build.PL
    COPYING
    Changes
    MANIFEST
    META.yml
    README
    dist.ini
    lib/Dummy.pm
    t/00-compile.t

Format of manifest allows comments, but comments are rarely used.

As it noted before, manifest is a plain list of files. However, files included
into a distribution differ:

1.  Some files are created by software author (in the example above,
    lib/Dummy.pm *could* be such file). Some of these files may be processed by
    various filters (like PkgVersion or PodWeaver).

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, Changes,
    and README).

Sometimes you may want (or have) to trace origin of files: whether this or that
file was created by author or automatically generated, if the file was processed
or added as-is. With a standard manifest (built by Manifest plugin) you have to
*guess* this or study the distribution build process: look into dist.ini file,
used plugins and plugin bundles. In contrast to standard Manifest plugin,
Manifest::Write writes *annotated* manifest:

    # This file was generated with Dist::Zilla::Plugin::Manifest::Write v0.9.6.
    Build.PL       # 3rd party file built by ModuleBuildTiny
    COPYING        #     Dummy file added by GatherDir
    Changes        #     Dummy file added by GatherDir
    MANIFEST       #  metainfo file built by Manifest::Write
    META.yml       #  metainfo file built by MetaYAML
    README         #     Dummy file added by GatherDir
    dist.ini       #     Dummy file added by GatherDir
    lib/Dummy.pm   #     Dummy file added by GatherDir
    t/00-compile.t # 3rd party file built by Test::Compile

(In the example above "Dummy" is name of manifested distribution.)

Having such annotated manifest there is no need to *guess* origin of files.
(However, see File Mungers.)

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 <https://metacpan.org/> 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.

FORMS

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

If you are going to have annotated distribution manifest, 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 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-Manifest-Write), while name of distribution does (e. g.
    Dist-Zilla-Plugin-Manifest-Write-v0.7.1).

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
<https://metacpan.org/release/Dist-Zilla-Plugin-Manifest-Write>.

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. *v0.7.1*) from CPAN:

    $ cpanm Dist::Zilla::Plugin::Manifest::Write@v0.7.1

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

    $ cpanm ./Dist-Zilla-Plugin-Manifest-Write-v0.7.1.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
*v0.7.1* of the distribution):

    $ tar xaf Dist-Zilla-Plugin-Manifest-Write-v0.7.1.tar.gz
    $ cd Dist-Zilla-Plugin-Manifest-Write-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>

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, 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 ./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
<https://metacpan.org/release/Dist-Zilla-Plugin-Manifest-Write>.

Locally Installed

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

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

    $ cd Dist-Zilla-Plugin-Manifest-Write-VERSION
    $ perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
    $ perldoc Dist::Zilla::Plugin::Manifest::Write

where *VERSION* is a version of built distribution.

FEEDBACK

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
<https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Manifest-Wr
ite>
    Browsing bugs does not require authentication.

Report bugs
<https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugin-Manifest-Wri
te>
    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
    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-Manifest-Write:".

GLOSSARY

CPAN
    Comprehensive Perl Archive Network, a large collection of Perl software and
    documentation. See cpan.org <http://www.cpan.org>, What is CPAN?
    <http://www.cpan.org/misc/cpan-faq.html#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 <http://perldoc.perl.org/perlmod.html#Perl-Modules>.

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