Provided by: libtest-distmanifest-perl_1.009-1_all 
NAME
Test::DistManifest - Author test that validates a package MANIFEST
VERSION
Version 1.009 ($Id: DistManifest.pm 10671 2009-12-29 01:49:23Z FREQUENCY@cpan.org $)
EXPORTS
By default, this module exports the following functions:
• manifest_ok
DESCRIPTION
This module provides a simple method of testing that a MANIFEST matches the distribution.
It tests three things:
1. Everything in MANIFEST exists
2. Everything in the package is listed in MANIFEST, or subsequently matches a regular
expression mask in MANIFEST.SKIP
3. Nothing exists in MANIFEST that also matches a mask in MANIFEST.SKIP, so as to avoid
an unsatisfiable dependency conditions
If there is no MANIFEST.SKIP included in your distribution, this module will replicate the
toolchain behaviour of using the default system-wide MANIFEST.SKIP file. To view the
contents of this file, use the command:
$ perldoc -m ExtUtils::MANIFEST.SKIP
SYNOPSIS
use Test::More;
# This is the common idiom for author test modules like this, but see
# the full example in examples/checkmanifest.t and, more importantly,
# Adam Kennedy's article: http://use.perl.org/~Alias/journal/38822
eval 'use Test::DistManifest';
if ($@) {
plan skip_all => 'Test::DistManifest required to test MANIFEST';
}
manifest_ok('MANIFEST', 'MANIFEST.SKIP'); # Default options
manifest_ok(); # Functionally equivalent to above
COMPATIBILITY
This module was tested under Perl 5.10.0, using Debian Linux. However, because it's Pure
Perl and doesn't do anything too obscure, it should be compatible with any version of Perl
that supports its prerequisite modules.
If you encounter any problems on a different version or architecture, please contact the
maintainer.
FUNCTIONS
manifest_ok
manifest_ok( $manifest, $skipfile )
This subroutine checks the manifest list contained in $manifest by using
"Module::Manifest" to determine the list of files and then checking for the existence of
all such files. Then, it checks if there are any files in the distribution that were not
specified in the $manifest file but do not match any regular expressions provided in the
$skipfile exclusion file.
If your MANIFEST file is generated by a module installation toolchain system such as
ExtUtils::MakeMaker, Module::Build or Module::Install, then you shouldn't have any
problems with these files. It's just a helpful test to remind you to update these files,
using:
$ make manifest # For ExtUtils::MakeMaker
$ ./Build manifest # For Module::Build
Non-Fatal Errors
By default, errors in the MANIFEST or MANIFEST.SKIP files are treated as fatal, which
really is the purpose of using "Test::DistManifest" as part of your author test suite.
In some cases this is not desirable behaviour, such as with the Debian Perl Group, which
runs all tests - including author tests - as part of its module packaging process. This
wreaks havoc because Debian adds its control files in "debian/" downstream, and that
directory or its files are generally not in MANIFEST.SKIP.
By setting the environment variable MANIFEST_WARN_ONLY to a true value, errors will be
non-fatal - they show up as diagnostic messages only, but all tests pass from the
perspective of "Test::Harness".
This can be used in a test script as:
$ENV{MANIFEST_WARN_ONLY} = 1;
or from other shell scripts as:
export MANIFEST_WARN_ONLY=1
Note that parsing errors in MANIFEST and circular dependencies will always be considered
fatal. The author is not aware of any cases where other behaviour would be useful.
GUTS
This module internally plans 4 tests:
1. MANIFEST can be parsed by "Module::Manifest"
2. Check which files exist in the distribution directory that do not match an existing
regular expression in MANIFEST.SKIP and not listed in the MANIFEST file. These files
should either be excluded from the test by addition of a mask in MANIFEST.SKIP (in the
case of temporary development or test files) or should be included in the MANIFEST.
3. Check which files are specified in MANIFEST but do not exist on the disk. This
usually occurs when one deletes a test or similar script from the distribution, or
accidentally moves it.
4. Check which files are specified in both MANIFEST and MANIFEST.SKIP. This is clearly
an unsatisfiable condition, since the file in question cannot be expected to be
included while also simultaneously ignored.
If you want to run tests on multiple different MANIFEST files, you can simply pass
'no_plan' to the import function, like so:
use Test::DistManifest 'no_plan';
# Multiple tests work properly now
manifest_ok('MANIFEST', 'MANIFEST.SKIP');
manifest_ok();
manifest_ok('MANIFEST.OTHER', 'MANIFEST.SKIP');
I doubt this will be useful to users of this module. However, this is used internally for
testing and it might be helpful to you. You can also plan more tests, but keep in mind
that the idea of "3 internal tests" may change in the future.
Example code:
use Test::DistManifest tests => 5;
manifest_ok(); # 4 tests
ok(1, 'is 1 true?');
AUTHOR
Jonathan Yu <jawnsy@cpan.org>
CONTRIBUTORS
Your name here ;-)
ACKNOWLEDGEMENTS
• Thanks to Adam Kennedy for developing Module::Manifest, which provides much of the
core functionality for these tests.
• Thanks to Apocalypse <apocal@cpan.org>, for helping me track down an obscure bug
caused by circular dependencies: when files are expected by MANIFEST but explictly
skipped by MANIFEST.SKIP.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Test::DistManifest
You can also look for information at:
• AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Test-Dist-Manifest>
• CPAN Ratings
<http://cpanratings.perl.org/d/Test-Dist-Manifest>
• Search CPAN
<http://search.cpan.org/dist/Test-Dist-Manifest>
• CPAN Request Tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Dist-Manifest>
• CPAN Testing Service (Kwalitee Tests)
<http://cpants.perl.org/dist/overview/Test-DistManifest>
REPOSITORY
You can access the most recent development version of this module at:
<http://svn.ali.as/cpan/trunk/Test-DistManifest>
If you are a CPAN developer and would like to make modifications to the code base, please
contact Adam Kennedy <adamk@cpan.org>, the repository administrator. I only ask that you
contact me first to discuss the changes you wish to make to the distribution.
FEEDBACK
Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer
noted above.
If you have a bug report or feature request, please file them on the CPAN Request Tracker
at <http://rt.cpan.org>. If you are able to submit your bug report in the form of failing
unit tests, you are strongly encouraged to do so.
SEE ALSO
Test::CheckManifest, a module providing similar functionality
CAVEATS
KNOWN BUGS
There are no known bugs as of this release.
LIMITATIONS
• There is currently no way to test a MANIFEST/MANIFEST.SKIP without having the files
actually exist on disk. I am planning for this to change in the future.
• This module has not been tested very thoroughly with Unicode.
• This module does not produce any useful diagnostic messages in terms of how to correct
the situation. Hopefully this will be obvious for anybody using the module; the
emphasis should be on generating helpful error messages.
QUALITY ASSURANCE METRICS
TEST COVERAGE
File stmt bran cond sub pod total
----------------------- ------ ------ ------ ------ ------ ------
Test/DistManifest.pm 96.1 95.8 100.0 100.0 100.0 96.8
LICENSE
Copyright 2008-2009 by Jonathan Yu <jawnsy@cpan.org>
This package is distributed under the same terms as Perl itself. Please see the LICENSE
file included in this distribution for full details of these terms.
DISCLAIMER OF WARRANTY
This software is provided by the copyright holders and contributors "AS IS" and ANY
EXPRESS OR IMPLIED WARRANTIES, including, but not limited to, the IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
In no event shall the copyright owner or contributors be liable for any direct, indirect,
incidental, special, exemplary or consequential damages (including, but not limited to,
procurement of substitute goods or services; loss of use, data or profits; or business
interruption) however caused and on any theory of liability, whether in contract, strict
liability or tort (including negligence or otherwise) arising in any way out of the use of
this software, even if advised of the possibility of such damage.