/ 
Dist-Zilla-Plugin-Manifest-Read-v0.4.2
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.4.2, released on 2015-11-05 14:08 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          ;   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 itself does FileFinder role, providing the list of files read from the manifest, so you can pass Manifest::Read to any plugin expecting FileFinder (see "EXAMPLES").

Manifest::Read itself is not the only file finder, it also provides a bunch of (sub)finders:

Manifest::Read/AllFiles
Manifest::Read/ExecFiles
Manifest::Read/ExtraTestFiles
Manifest::Read/InstallModules
Manifest::Read/PerlExecFiles
Manifest::Read/TestFiles

Each of these finders returns the list of files read from the manifest, not pruned, and falling to the specified category. For example, Manifest::Read/InstallModules returns the list of your install modules (*.pm and *.pod files from lib/ directory), Manifest::Read/TestFiles returns the list of your test files (all files from t/ directory), etc. Strictly speaking, a file finder Manifest::Read/X returns intersection of two sets: (1) files returned by Manifest::Read and (2) files found by standard :X file finder (see "default_finders" in Dist::Zilla::Role::FileFinderUser for list of standard finders).

Note: Files marked with - and directories are not included into distribution and so never reported by any of Manifest::Read finders.

Also note a subtle difference between Manifest::Read and other file (sub)finders (especially Manifest::Read/AllFiles): the result of the first one is not affected by FilePruners, while result of others are. However, in normal conditions the difference should not appear: there is no point in manifesting a file just to prune it.

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 files returned by :InstallModules, :ExecFiles, :TestFiles standard finders). Some of these files may be out of your control, for example, t/00-compile.t generated by Test::Compile. There is no point in testing such files: even if the test fails, you cannot fix the generated file (at least, easily). At the same time, you may want to apply these tests to other your files, like README. To apply the tests to all your files:

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

Test::Version test

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

[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                 ; *Not* Manifest::Read!
[Test::Version]
    finder = MR/InstallModules  ; *Not* Manifest::Read!

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