Unix/Linux Go Back    


CentOS 7.0 - man page for test::distmanifest (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Test::DistManifest(3)	       User Contributed Perl Documentation	    Test::DistManifest(3)

NAME
       Test::DistManifest - Author test that validates a package MANIFEST

VERSION
       version 1.012

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

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

EXPORTS
       By default, this module exports the following functions:

       o   manifest_ok

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?');

ACKNOWLEDGEMENTS
       o   Thanks to Adam Kennedy for developing Module::Manifest, which provides much of the
	   core functionality for these tests.

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

SEE ALSO
       Test::CheckManifest, a module providing similar functionality

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

       o   This module has not been tested very thoroughly with Unicode.

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

BUGS
       Please report any bugs or feature requests on the bugtracker website
       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-DistManifest

       When submitting a bug or request, please include a test-file or a patch to an existing
       test-file that illustrates the bug or desired feature.

AUTHOR
       Jonathan Yu <jawnsy@cpan.org>

COPYRIGHT AND LICENSE
       This software is copyright (c) 2012 by Jonathan Yu <jawnsy@cpan.org>.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

perl v5.16.3				    2012-04-22			    Test::DistManifest(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:00 PM.