The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dist-Zilla-Plugin-Manifest-Read-v0.3.5
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.5, released on 2015-10-29 22:42 UTC.

WHAT?

Dist-Zilla-Plugin-Manifest-Read (or Manifest::Read for brevity) is a Dist::Zilla plugin. It reads annotated source manifest, checks existence of all listed files and directories, and adds selected files to the distribution. Manifest::Read also does FileFinder role, providing the list of added files for other plugins.

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

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:

    ...
    ; Add files listed in source MANIFEST to the distribution
    ;     (Manifest::Read does FileGatherer role):
    [Manifest::Read]        ; Read *source* MANIFEST
                            ;     and add files to the distribution.
    ...
    [Manifest::Write]       ; Write *distribution* MANIFEST.
        ; or [Manifest]
    ...
    ; Use files listed in source MANIFEST
    ;     (Manifest::Read does FileFinder role):
    [Templates]                     ; Treat as templates
        templates = Manifest::Read  ;     *your* files.
    [Test::EOL]                     ; Check line endings are consistent
        finder = Manifest::Read     ;     in *your* files.
    [Test::NoTabs]                  ; Ensure there are no tabs
        finder = Manifest::Read     ;     in *your* files.
    ...

In your source MANIFEST:

    # Files marked with "+" will be added to distribution.
    # Files marked with "-" will *not* be added to distribution.
    # Entries marked with "/" are directories.
    # All the enlisted entities must exist, regardless of mark.

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

    t/                  / Tests.
    t/basic.t           + Test basic functionality.
    t/extended.t        - Do not include, not ready yet.

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

DESCRIPTION

Manifest::Read reads the annotated 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 - mark and directories 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 match the following regular expression:

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

Filename should be Perl single-quoted string, or should not contain whitespaces. It should not start with hash or apostrophe. Example of valid filenames:

    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 (these are regular Perl rules for single-quoted strings).

mark

Either plus (+) or minus (-) sign, or slash (/). Plus sign is also used as default mark if no mark 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 name differently source and distribution manifests, 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.

NOTES

Source manifest can enlist itself

Source manifest can enlist itself but normally it should not be included to distribution:

    ...
    MANIFEST        - Source manifest, this file.
    ...

because source and distribution manifests (may) have the same name but they are distinctly different files with different content. Source manifest enlists source files and itself is a part of source, while distribution manifest enlists distribution files (including automatically generated files like Build.PL, META.json, META.yml) and itself is a part of distribution. Distribution manifest may be a part of source, but usually it is generated by Manifest (or Manifest::Write) plugin.

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 (and directories) which are part of source, but should not be included to distribution. For example:

    ex/                     / Examples.
    ex/Assa/                / Very basic example.
    ex/Assa/dist.ini        - dzil config file.
    ex/Assa/dzil.out        - dzil output, included into user manual.

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

    t/                      / Tests:
    t/advanced.t            - Not ready yet, do not distribute.
    t/basic.t               + Basic functional test.

    tools/                  / Build tools:
    tools/run-examples.sh   - Run examples, refresh dzil.out files.

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

SEE ALSO

Dist::Zilla
Dist::Zilla::Plugin::GatherDir
Dist::Zilla::Plugin::GatherFromManifest
Dist::Zilla::Role::FileFinder

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015 Van de Bugger

License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.