Test::DistManifest(3pm)

1Test::DistManifest(3) User Contributed Perl DocumentationTest::DistManifest(3)
2
3
4

NAME

6       Test::DistManifest - Author test that validates a package MANIFEST
7

VERSION

9       version 1.014
10

SYNOPSIS

12       This is the common idiom for author test modules like this, but see the
13       full example in examples/checkmanifest.t and, more importantly, Adam
14       Kennedy's article:
15       <http://use.perl.org/use.perl.org/_Alias/journal/38822.html>
16
17         use Test::More;
18         eval 'use Test::DistManifest';
19         if ($@) {
20           plan skip_all => 'Test::DistManifest required to test MANIFEST';
21         }
22
23         manifest_ok('MANIFEST', 'MANIFEST.SKIP'); # Default options
24
25         manifest_ok(); # Functionally equivalent to above
26

DESCRIPTION

28       This module provides a simple method of testing that a MANIFEST matches
29       the distribution.
30
31       It tests three things:
32

EXPORTS

34       By default, this module exports the following functions:
35
36       •   manifest_ok
37
38       1.  Everything in MANIFEST exists
39
40       2.  Everything in the package is listed in MANIFEST, or subsequently
41           matches a regular expression mask in MANIFEST.SKIP
42
43       3.  Nothing exists in MANIFEST that also matches a mask in
44           MANIFEST.SKIP, so as to avoid an unsatisfiable dependency
45           conditions
46
47       If there is no MANIFEST.SKIP included in your distribution, this module
48       will replicate the toolchain behaviour of using the default system-wide
49       MANIFEST.SKIP file. To view the contents of this file, use the command:
50
51         $ perldoc -m ExtUtils::MANIFEST.SKIP
52

FUNCTIONS

54   manifest_ok
55         manifest_ok( $manifest, $skipfile )
56
57       This subroutine checks the manifest list contained in $manifest by
58       using "Module::Manifest" to determine the list of files and then
59       checking for the existence of all such files. Then, it checks if there
60       are any files in the distribution that were not specified in the
61       $manifest file but do not match any regular expressions provided in the
62       $skipfile exclusion file.
63
64       If your MANIFEST file is generated by a module installation toolchain
65       system such as ExtUtils::MakeMaker, Module::Build or Module::Install,
66       then you shouldn't have any problems with these files. It's just a
67       helpful test to remind you to update these files, using:
68
69         $ make manifest # For ExtUtils::MakeMaker
70         $ ./Build manifest # For Module::Build
71

NON-FATAL ERRORS

73       By default, errors in the MANIFEST or MANIFEST.SKIP files are treated
74       as fatal, which really is the purpose of using "Test::DistManifest" as
75       part of your author test suite.
76
77       In some cases this is not desirable behaviour, such as with the Debian
78       Perl Group, which runs all tests - including author tests - as part of
79       its module packaging process. This wreaks havoc because Debian adds its
80       control files in "debian/" downstream, and that directory or its files
81       are generally not in MANIFEST.SKIP.
82
83       By setting the environment variable MANIFEST_WARN_ONLY to a true value,
84       errors will be non-fatal - they show up as diagnostic messages only,
85       but all tests pass from the perspective of "Test::Harness".
86
87       This can be used in a test script as:
88
89         $ENV{MANIFEST_WARN_ONLY} = 1;
90
91       or from other shell scripts as:
92
93         export MANIFEST_WARN_ONLY=1
94
95       Note that parsing errors in MANIFEST and circular dependencies will
96       always be considered fatal. The author is not aware of any cases where
97       other behaviour would be useful.
98

GUTS

100       This module internally plans four tests:
101
102       1.  MANIFEST can be parsed by "Module::Manifest"
103
104       2.  Check which files exist in the distribution directory that do not
105           match an existing regular expression in MANIFEST.SKIP and not
106           listed in the MANIFEST file. These files should either be excluded
107           from the test by addition of a mask in MANIFEST.SKIP (in the case
108           of temporary development or test files) or should be included in
109           the MANIFEST.
110
111       3.  Check which files are specified in MANIFEST but do not exist on the
112           disk.  This usually occurs when one deletes a test or similar
113           script from the distribution, or accidentally moves it.
114
115       4.  Check which files are specified in both MANIFEST and MANIFEST.SKIP.
116           This is clearly an unsatisfiable condition, since the file in
117           question cannot be expected to be included while also
118           simultaneously ignored.
119
120       If you want to run tests on multiple different MANIFEST files, you can
121       simply pass 'no_plan' to the import function, like so:
122
123         use Test::DistManifest 'no_plan';
124
125         # Multiple tests work properly now
126         manifest_ok('MANIFEST', 'MANIFEST.SKIP');
127         manifest_ok();
128         manifest_ok('MANIFEST.OTHER', 'MANIFEST.SKIP');
129
130       I doubt this will be useful to users of this module. However, this is
131       used internally for testing and it might be helpful to you. You can
132       also plan more tests, but keep in mind that the idea of "3 internal
133       tests" may change in the future.
134
135       Example code:
136
137         use Test::DistManifest tests => 5;
138         manifest_ok(); # 4 tests
139         ok(1, 'is 1 true?');
140

ACKNOWLEDGEMENTS

142       •   Thanks to Adam Kennedy for developing Module::Manifest, which
143           provides much of the core functionality for these tests.
144
145       •   Thanks to Apocalypse <apocal@cpan.org>, for helping me track down
146           an obscure bug caused by circular dependencies: when files are
147           expected by MANIFEST but explicitly skipped by MANIFEST.SKIP.
148

CAVEATS

159       •   There is currently no way to test a MANIFEST/MANIFEST.SKIP without
160           having the files actually exist on disk. I am planning for this to
161           change in the future.
162
163       •   This module has not been tested very thoroughly with Unicode.
164
165       •   This module does not produce any useful diagnostic messages in
166           terms of how to correct the situation. Hopefully this will be
167           obvious for anybody using the module; the emphasis should be on
168           generating helpful error messages.
169

AUTHOR

171       Jonathan Yu <jawnsy@cpan.org>
172

COPYRIGHT AND LICENSE

174       This software is copyright (c) 2008 by Jonathan Yu <jawnsy@cpan.org>.
175
176       This is free software; you can redistribute it and/or modify it under
177       the same terms as the Perl 5 programming language system itself.
178

CONTRIBUTOR

180       Karen Etheridge <ether@cpan.org>
181
182
183
184perl v5.36.0                      2023-01-20             Test::DistManifest(3)