21 Nov 2016 19:20:17 UTC
- Distribution: Dist-Zilla-Plugin-Manifest-Read
- Source (raw)
- Browse (raw)
- How to Contribute
- Clone hg repository
- Issues (0)
- KwaliteeBus factor: 0
- 94.24% Coverage
- License: gpl_3
- Perl: v5.10.0
- Activity24 month
- Download (35.8KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest versionVDB Van de Buggerand 1 contributors
- Van de Bugger
- SEE ALSO
- COPYRIGHT AND LICENSE
Manifest::Readplugin user manual
Version v0.5.0, released on 2016-11-21 19:18 UTC.
Manifest::Readfor brevity) is a
Dist::Zillaplugin. It reads annotated source manifest, checks existence of all listed files and directories, and adds selected files to the distribution.
FileFinderrole, providing the list of files for other plugins.
Manifest::Readplugin 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.
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.
Manifest::Readreads the annotated source manifest. Default manifest name is MANIFEST, but it may be changed with
Manifest enlists all the source files and directories.
Manifest::Readensures 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::Readalso provides a bunch of
FileFinders, which can be used by other plugins, see "File Finders" section below.
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 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 apostrophe, all other characters are treated literally:
\ndenotes two characters
n, not newline (these are regular Perl rules for single-quoted strings).
Either plus (
+) or minus (
-) sign, or slash (
/). Plus sign is also used as default mark if no mark is explicitly specified.
Comment is arbitrary text.
Manifest::Readprovides bunch of file finders:
You can pass them to any plugin expecting
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/:Xreturns intersection of two sets: (1) files listed in the source manifest and (2) files found by standard
:Xfile finder (see "default_finders" in Dist::Zilla::Role::FileFinderUser for the list of the standard file finders).
Manifest::Readitself 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.
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.
Test::NoTabsare applied to all install modules, executable files, and test files (i. e. to the files returned by the
:TestFilesstandard 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::Versionis 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
InlineModuleplugin. This file does not have
$VERSIONassignment and so fails the test. Applying the test to your modules only solves the problem:
[Manifest::Read] [Test::Version] finder = Manifest::Read/:InstallModules
Manifest::Readis 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 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
GatherDirplugin to populate the distribution. However,
GatherDirhas 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
GatherDirparameters 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
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.
Van de Bugger <firstname.lastname@example.org>
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.
Module Install Instructions
To install Dist::Zilla::Plugin::Manifest::Read, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install Dist::Zilla::Plugin::Manifest::Read
For more information on module installation, please visit the detailed CPAN module installation guide.