/ 
Dist-Zilla-Plugin-Manifest-Read-v0.3.1
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::Manifest::Read::Manual

NAME

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

VERSION

Version v0.3.1, released on 2015-09-23 11:45 UTC.

WHAT?

Dist-Zilla-Plugin-Manifest-Read is a Dist::Zilla plugin. It reads MANIFEST file, checks existence of all listed files and directories, and adds marked files to the distribution. Dist-Zilla-Plugin-Manifest-Read also does FileFinder role, providing list of added files for latter use.

This is Manifest::Read plugin user manual. Read this if you want to have annotated manifest in your source.

If you are going to hack or extend Manifest::Read, 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:

# Manifest::Read is a FileGatherer:
[Manifest::Read]        # Read source MANIFEST,
                        # add files to the distribution.
…
[Manifest]              # Write distribution MANIFEST.
# or [Manifest::Write] to write annotated MANIFEST.
…
# Manifest::Read is a FileFinder:
[Test::EOL]
    # Check eols only in your source files,
    # ignore automatically genenared files.
    finder = Manifest::Read

In your source MANIFEST:

# Files marked with "+" will be included into distribution,
# files marked with "-" will *not* be included into distribution,
# but all the files regardless of marker must be present on disk.
# Entries marked with "/" are directories,
# they serve for documentation purposes.

Changes             + Release history log.
COPYING             + License.
MANIFEST            - Exclude *source* manifest.
dist.ini            - Exclude Dist-Zilla config.
weaver.ini          - Exclude PodWeaver config.

lib/                / Modules to install:
lib/Foo.pm          + Perl module
lib/Foo/Manual.pod  + and user manual.

DESCRIPTION

Manifest::Read reads the source manifest. Default manifest name is MANIFEST, but it may be changed with manifest option.

Manifest enlists all the source files and directories. Manifest::Read ensures all the manifested files and directories exist, and adds files marked with + to the distribution. Files marked with - marker and directories (must be marked with /) should exist, but they are not added to the distribution.

File Format

Manifest is a plain text file in UTF-8 encoding. Empty and whitespace-only lines are ignored. Comment line should have hash (#) as the first non-whitespace character, comment lines are ignored too. Other lines must meet the format:

^ \s* filename ( \s+ marker ( \s+ comment )? )? \s* $

(^, \s*, etc. are Perl regular expressions.)

filename

Filename should be Perl single-quoted string, or should not contain whitespaces, start with hash or apostrophe:

lib/Assa.pm
'/Program Files/Common Files/Dummy File.txt'
'That\'s all, folks!'

Within single-quoted string \\ denotes backslash, \' denotes apostrophe, all other characters are treated literally: \n denotes two characters \ and n, not newline (i. e. regular Perl rules work).

marker

Marker should be either plus (+) or minus (-) sign, or slash (/). Plus sign is also used as default marker if no marker is explicitly specified.

comment

Comment is arbitrary text.

OPTIONS

manifest

Name of manifest file to read. Default value is MANIFEST.

The option may be used if you want to differentiate source and distribution manifest, e. g.:

[Manifest::Read]
    manifest = Manifest.lst
[Manifest::Write]

In such a case the source manifest has name Manifest.lst, while distribution manifest has default name MANIFEST.

WHY?

Dist::Zilla advertises using GatherDir plugin to populate the distribution. However, GatherDir has disadvantage: it grabs really all the files from the source directory, including files which are not meant to be added to distribution, like previously built distribution tarball. You have to use either GatherDir parameters or dedicated plugins (e. g. PruneCruft) to exclude unwanted files from distribution. However, risk to grab unwanted files remains.

There is another (better to my taste) approach: grab only files explicitly listed in MANIFEST file. This is implemented by nice GatherFromManifest plugin.

However I want a bit more. I also want to specify (and document) files which should not be included into distribution, but expected to be in the source tree, and directories, for example:

Changes         + Release history log.
COPYING         + License.
README          - Source documentation.
TODO            - Plans and ideas.
VERSION         +

lib/            / Modules to install.
lib/Assa.pm     + The primary module.

t/              / Tests.
t/basic.t       +
t/advanced.t    +

SEE ALSO

Dist::Zilla
Dist::Zilla::Plugin::GatherDir
Dist::Zilla::Plugin::GatherFromManifest

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

perl-Dist-Zilla-Plugin-Manifest-Read 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-Read 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-Read. If not, see <http://www.gnu.org/licenses/>.