/ 
Dist-Zilla-Plugin-Manifest-Write-v0.8.1
River stage one • 1 direct dependent • 1 total dependent
++
/ Dist::Zilla::Plugin::Manifest::Write::Manual

NAME

Dist::Zilla::Plugin::Manifest::Write::Manual - Manifest::Write plugin user manual

VERSION

Version v0.8.1, released on 2015-09-15 21:00 UTC.

WHAT?

Manifest::Write is a plugin for Dist::Zilla, a replacement for standard plugin Manifest. Manifest::Write writes annotated MANIFEST: each filename is followed by a comment, explaining origin of the file, whether it is part of software, meta information, or 3rd party file.

This is Manifest::Write plugin user manual. Read this if you want to have annotated MANIFEST in your distribution.

If you are going to hack or extend Manifest::Write, read the module documentation. General topics like getting source, building, installing, bug reporting and some others are covered in the README.

SYNOPSIS

In your dist.ini:

    …
    [GatherDir]         ; Plugin which adds source files to distribution.
                        ; You may use other plugins, like GatherFromManifest.
    [Manifest::Write]
        source_providers = GatherDir
    …

DESCRIPTION

Manifest::Write is a replacement for standard plugin Manifest. To use Manifest::Write, you should replace line

    [Manifest]

with

    [Manifest::Write]

in your dist.ini file, and specify one or more source providers, see source_providers option below.

OPTIONS

manifest

Name of manifest file to write. Default value is MANIFEST. It is unlikely you will need to change the default value.

It could be used, though, to generate standard and annotated manifest, e. g.:

    [Manifest]          ; Writes 'MANIFEST'.
    [Manifest::Write]   ; Writes 'Manifest.new'.
        manifest = Manifest.new

source_providers

Names of plugins which add source files to distribution. Option may be specified several times, each value may include several space-separated plugin names, e. g.:

    source_providers = GatherDir GatherDir::Template
    source_providers = GenerateFile

There are no default source file providers.

Note: source files term does not mean exactly Perl sources. Source files are your files, in contrast to ("3rd party") files added to the distribution by various Dist::Zilla plugins. Sources may include Perl modules, scripts, POD files, tests, and any other files composing your software.

You will likely want to specify GatherDir, GatherFromManifest and similar plugins, like GatherDir::Template or GenerateFile.

metainfo_providers

Names of plugins which add meta information files to the distribution. Option may be specified several times, each value may include several space-separated plugin names, e. g.:

    metainfo_providers = MetaYAML MetaJSON Manifest
    metainfo_providers = Manifest::Write

Default meta info providers are MetaYAML, MetaJSON, Manifest, and Manifest::Write itself. It seems these metainfo providers should satisfy most of the users (if any).

Note: Specifying any metainfo provider (even empty one) cancels all the default metainfo providers:

    [Manifest::Write]
        metainfo_providers =

strict

Let us consider an example:

    [Manifest::Write]
        metainfo_providers = MetaYML

At the first glance it may look ok, but there is a mistake: correct plugin name is MetaYAML, not MetaYML. Left unnoticed, such a typo may cause bad manifest: files may be classified incorrectly.

To avoid such mistakes Manifest::Write checks plugin names specified in source_providers and metainfo_providers options. Any name specified in these options must be a name of Dist::Zilla plugin consumed FileInjector role (or FileGatherer, which is a kind of FileInjector). If not, Manifest::Write will issue error message and abort build process.

This behaviour may be modified by strict option, which sets the level of strictness. Level 1 behaviour is described above (strict checks, any mistake is fatal), this is default. At level -1 Manifest::Write does not check provider names at all. At level 0 some mistakes are fatal, some are not. Using a plugin which is not a FileInjector is fatal error. Using a string which is not a (loaded) plugin name is not fatal (because it may be a name of FileInjector plugin which is not loaded, e. g. commented out):

    ; [MetaYAML]
    [Manifest::Write]
        metainfo_providers = MetaYAML
        ;   MetaYAML is a correct name of not loaded plugin,
        ;   but Manifest::Write cannot verify it easily.
        strict = 0
        ;   Print a message but do not abort build.

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
    lib/Foo.pm
    t/00-compile.t
    xt/author/eol.t
    xt/author/no-tabs.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/Assa.pm could be such file). Some of these files may be processed by various filters (like PodWeaver).

  2. Some files contain distribution metainformation (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).

Sometimes you may want (or have) to trace an origin of a file: whether this file created by author or automatically added, if the file was processed or added as-is. With a typical manifest you have to guess origin of each file, because distribution build tool, Dist-Zilla, throws this information away. Manifest::Write saves this information in comments:

    Build.PL            # 3rd party file added by ModuleBuildTiny
    COPYING             #       Foo file added by GatherFromManifest
    Changes             #       Foo file added by GatherFromManifest
    MANIFEST            #  metainfo file built by Manifest::Write
    META.yml            #  metainfo file built by MetaYAML
    README              #       Foo file added by GatherFromManifest
    lib/Foo.pm          #       Foo file added by GatherFromManifest and modified by PkgVersion
    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 the example above "Foo" is name of manifested distribution.)

With such annotated manifest there is no need to guess, you just know.

SEE ALSO

Dist::Zilla
Dist::Zilla::Plugin::Manifest
Dist::Zilla::Role::FileInjector
Dist::Zilla::Role::FileGatherer
Dist::Zilla::Plugin::Manifest::Write

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.

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 <http://www.gnu.org/licenses/>.