NAME

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

VERSION

Version v0.9.0, released on 2015-10-02 20:00 UTC.

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.

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

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
                    ; or Manifest::Read.
[Manifest::Write]
    source_provider = 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, e. g.:

[Manifest::Write]
    source_provider = GatherDir

(See source_provider option below for details.)

Manifest File Format

If the first non-whitespace character of a line is hash character (#), such line is a comment.

Other lines in annotated manifest follows the format:

NAME # DEED file BREED by ADDER [ and munged by MUNGER,… ]

Square brackets denote optional part, ellipsis denotes repeatable part, hash (#), file, by, and munged by are literals.

NAME

Just a file name. If file name contains spaces, apostrophes ('), backslashes (\), or hashes (#) it is formatted as Perl single-quoted string literal, otherwise it is written as-is.

#

Technically, hash character is not required because everything after a file name is a comment, hash just visually emphasises it.

DEED

File "deed" is file ownership: if the file (1) belongs to the project, is (2) a meta information, or (3) third-party file. In the first case "deed" is project (distribution) name, in the second — metainfo, in the third — 3rd party. (So, do not name your project "metainfo" to avoid confusion.)

BREED

File "breed" explains how the file appeared in the distribution — was it added (copied as-is from the project sources) or built (generated).

ADDER

File "adder" is a moniker of plugin (see "Plugin moniker") brought (either added or built, see "BREED") the file into the distribution.

Plugins bringing files to distribution do FileInjector or FileGatherer roles. Some plugins add existing files to distribution (e. g. GatherDir, Manifest::Read), others generate new files (e. g. Test::EOL, Test::NoTabs).

MUNGER

File "munger" is a plugin changed the file during build.

Plugins modifying files in distribution do FileMunger role. Some plugins may touch files slightly (for example, PkgVersion changes a single line in Perl modules), others may rewrite them heavily (PodWeaver removes or comments out all existing POD and generates new POD at the end).

The same file may be changed several times during build. For example, Perl module may be processed by both PkgVersion and PodWeaver.

Quite often the same plugin appears as both adder and munger. Many plugins add a generic template to the distribution first, then tune the template to meet the distribution needs.

If a file was not changed after its addition to the distribution, annotation will not show any mungers for this file, obviously. Also, all munger nay be forcibly hidden by show_mungers option.

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 both standard and annotated manifests (for testing, comparison, etc):

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

source_provider

This is a multi-value option, i. e. option may be specified several times. Every option value is a name of plugin (see "Plugin name") which adds source files to distribution.

source_provider = GatherDir
source_provider = GatherDir::Template
source_provider = GenerateFile

There are no default source file providers. You will likely want to specify GatherDir, GatherFromManifest and similar plugins as source providers.

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

source_providers

The option splits its value into plugin names using whitespaces as separators, so

source_providers = GatherDir GatherDir::Template GenerateFile

is just a shortcut for

source_provider = GatherDir
source_provider = GatherDir::Template
source_provider = GenerateFile

metainfo_provider

This is multi-value option too. Every value is a name of plugin (see "Plugin name") which adds meta information files to the distribution:

metainfo_provider = MetaYAML
metainfo_provider = MetaJSON
metainfo_provider = Manifest

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

Specifying any metainfo_provider or metainfo_providers option (even with empty value) cancels all the default metainfo providers:

metainfo_provider =     ; Cancel default metainfo providers.

metainfo_providers

The option allows to specify several source providers in single line:

metainfo_providers = MetaYAML MetaJSON Manifest

The option splits its value to separate plugin names, using whitespaces as separators. If plugin names contain spaces, use metainfo_provider option.

strict

Let us consider an example:

[Manifest::Write]
    metainfo_provider = MetaYML

At the first glance it may look ok, but there is a mistake: correct plugin name is MetaYAML, not MetaYML (assumed the plugin was not explicitly (re)named). Left unnoticed, such a typo may cause bad manifest: files may have incorrect "deed" classification.

To avoid such mistakes Manifest::Write checks plugin names specified in source_provider and metainfo_provider 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 issues error message and aborts 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 does not do FileInjector role is fatal error. Using a string which is not a (loaded) plugin name is not fatal (because it may be a name proper plugin which is not loaded, e. g. commented out):

; [MetaYAML]
[Manifest::Write]
    metainfo_provider = 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.

show_mungers

If set to 1, information about file mungers (if any) is included into file annotation. If 0, file mungers is not shown completely. Default value is 0. See "File Mungers".

NOTES

Plugin Identification

Every Dist:Zilla plugin has (at least) two attributes: moniker and name. Both are used for plugin identification, but these terms are not explained well in Dist::Zilla documentation. Often plugin moniker equals to the plugin name (and so they are interchangeable), but sometimes not. The difference is important enough to be explained.

Plugin moniker

In order to load plugin, Dist::Zilla should know plugin package. Great majority of plugin packages start with Dist::Zilla::Plugin:: prefix. Using full package names in dist.ini file looks ugly:

[Dist::Zilla::Plugin::GatherDir]
[Dist::Zilla::Plugin::PruneCruft]
[Dist::Zilla::Plugin::Manifest]
[Dist::Zilla::Plugin::MetaYAML]
[Dist::Zilla::Plugin::MetaJSON]

So Dist::Zilla uses plugin monikers instead of plugin package names. Moniker is a plugin package name with the common prefix stripped down:

[GatherDir]
[PruneCruft]
[Manifest]
[MetaYAML]
[MetaJSON]

Dist::Zilla prepends a plugin moniker with the common prefix to get plugin package name.

In rare cases when plugin package does not start with the common prefix, plugin moniker must start with = to let Dist::Zilla know the common prefix should not be used:

[=MyPrivatePlugin]

Since moniker is a part of package name, it cannot include characters not valid for package names.

Plugin name

Someone may want to use the same plugin more than once. To differentiate plugins with the same moniker, Dist::Zilla introduces plugin names. Name is unique string that identifies plugin in dist.ini. Plugin name is specified in dist.ini after plugin moniker and separated from moniker by slash:

[GenerateFile/Copying]
    filename = COPYING
    content  = ...
[GenerateFile/ReadMe]
    filename = README
    content  = ...

If plugin name is not specified explicitly, the plugin gets automatically assigned name, which is the same as the plugin moniker:

[Manifest]  ; plugin named "Manifest"

Actually, it is just short form of

[Manifest/Manifest]  ; plugin named "Manifest"

All the plugins in dist.ini must have unique names.

Since name is just a string, it may include arbitrary characters, probably with few exceptions like square brackets and newlines.

Thus, a plugin name is a string identifier assigned to the plugin by distribution author. Plugin names are unique within dist.ini, but they are also "local" within dist.ini because nobody except the distribution author takes care about plugin names used in the dist.ini. (dist.ini file may even be excluded from distribution.)

In contrast, a plugin moniker is based on the plugin package name, and so "assigned" by plugin author. If plugin is published on CPAN (which is quite common), plugin moniker becomes a "global" entity.

So, in dist.ini file, source_provider and metainfo_provider options accept plugin names because names unambiguously identify plugins in dist.ini. However, in manifest file, plugin monikers are used because plugin names have little or no meaning for distribution users, while plugin monikers are still valuable.

File Mungers

Dist::Zilla records each file operation (adding, content modification, etc) in a history log attached to every file (see added_by attribute declared in Dist::Zilla::Role::File).

File adder is recorded properly.

Unfortunately, (in Dist::Zilla 5.039) subsequent file modifications are recorded not too accurate: Dist::Zilla guesses the plugin that changed the file. When guessing, it uses heuristic which works correctly only in trivial cases. In non-trivial cases recorded information is not fully correct (this is a soft form to say "incorrect"). "Non-trivial case" does not mean something overcomplicated: consuming a role or extending a class are non-trivial cases. So, file history log may have records that file was modified by a role (actually the file was modified by the plugin consumed the role) or a plugin's parent class (actual modifier was the plugin itself).

Thus, all but the first records in file history log are unreliable.

Manifest::Write uses file history logs to generate file annotations. So file annotations in manifest are inaccurate too. A file adder is quite reliable, but file mungers are not.

This is reason why show_mungers option is set to 0 by default.

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

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).
Some files contain distribution meta information (META.yml and MANIFEST itself).
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.8.1_01
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
xt/author/eol.t     # 3rd party file built by Test::EOL
xt/author/no-tabs.t # 3rd party file built by Test::NoTabs

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

AUTHOR

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

COPYRIGHT AND LICENSE

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

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

cpanm

cpanm Dist::Zilla::Plugin::Manifest::Write

CPAN shell

perl -MCPAN -e shell
install Dist::Zilla::Plugin::Manifest::Write

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)