/ 
Dist-Zilla-Plugin-Manifest-Read-v0.5.0
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.5.0, released on 2016-11-21 19:18 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 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/:AllFiles ;   all *your* files.
[Test::EOL]                              ; Check line endings are consistent
    finder = Manifest::Read/:TestFiles   ;   in *your* test files.
[Test::NoTabs]                           ; Ensure there are no tabs
    finder = Manifest::Read/:ExecFiles   ;   in *your* exec 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 - and directories marked with / should exist, but they are not added to the distribution.

Manifest::Read also provides a bunch of FileFinders, which can be used by other plugins, see "File Finders" section below.

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

File Finders

Manifest::Read provides bunch of file finders:

Manifest::Read/:AllFiles
Manifest::Read/:ExecFiles
Manifest::Read/:ExtraTestFiles
Manifest::Read/:IncModules
Manifest::Read/:InstallModules
Manifest::Read/:NoFiles
Manifest::Read/:PerlExecFiles
Manifest::Read/:ShareFiles
Manifest::Read/:TestFiles

You can pass them to any plugin expecting FileFinder (see "EXAMPLES").

Each of these finders returns the list of files read from the manifest, added to the distribution, not pruned, and falling to the specified category. Strictly speaking, a file finder Manifest::Read/:X returns intersection of two sets: (1) files listed in the source manifest and (2) files found by standard :X file finder (see "default_finders" in Dist::Zilla::Role::FileFinderUser for the list of the standard file finders).

Manifest::Read itself returns the complete list of the files read from the manifest. It includes the files which are not added to the distribution. It also includes pruned files, if any.

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.source
[Manifest::Write]

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

EXAMPLES

Test::EOL and Test::NoTabs tests

By default, Test::EOL and Test::NoTabs are applied to all install modules, executable files, and test files (i. e. to the files returned by the :InstallModules, :ExecFiles, :TestFiles standard finders). Some of these files may be out of your control. For example, t/00-compile.t test is generated by Test::Compile. There is no point in testing t/00-compile.t: even if the test fails you cannot fix it (at least, easily). At the same time you may want to apply these tests to other your files, like README or Changes. To apply the tests to all your files:

[Manifest::Read]
[Test::EOL]
    finder = Manifest::Read/:AllFiles
[Test::NoTabs]
    finder = Manifest::Read/:AllFiles

Test::Version test

By default, Test::Version is applied to all the Perl modules in the lib/ directory. Some of these files may be out of your control. For example, Inline.pm file is generated by InlineModule plugin. This file does not have $VERSION assignment and so fails the test. Applying the test to your modules only solves the problem:

[Manifest::Read]
[Test::Version]
    finder = Manifest::Read/:InstallModules

NOTES

File Finder Names

When Manifest::Read is passed to another plugin as a file finder, you should pass plugin name, not moniker:

[Manifest::Read/MR]             ; Plugin name is MR.
[Test::EOL]
    finder = MR/AllFiles        ; *Not* Manifest::Read/AllFiles!
[Test::Version]
    finder = MR/InstallModules  ; *Not* Manifest::Read/InstallModules!

Source Manifest Can Enlist Itself

Source manifest can enlist itself but normally it should be excluded from distribution:

...
MANIFEST        - Source manifest, this file.
#              ^^^ *Not* +!
...

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 (if created manually), 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 the distribution. However, risk to grab unwanted files remains.

There is another (better to my taste) approach: grab only the files explicitly listed in the 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 the 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 file.

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::Plugin::Test::EOL
Dist::Zilla::Plugin::Test::NoTabs
Dist::Zilla::Plugin::Test::Version
Dist::Zilla::Role::FileFinder
Dist::Zilla::Role::FileGatherer
Dist::Zilla::Role::FilePruner

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015, 2016 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.