.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Test::DistManifest 3pm" .TH Test::DistManifest 3pm "2009-12-29" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::DistManifest \- Author test that validates a package MANIFEST .SH "VERSION" .IX Header "VERSION" Version 1.009 ($Id: DistManifest.pm 10671 2009\-12\-29 01:49:23Z FREQUENCY@cpan.org $) .SH "EXPORTS" .IX Header "EXPORTS" By default, this module exports the following functions: .IP "\(bu" 4 manifest_ok .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a simple method of testing that a \s-1MANIFEST\s0 matches the distribution. .PP It tests three things: .IP "1." 4 Everything in \fB\s-1MANIFEST\s0\fR exists .IP "2." 4 Everything in the package is listed in \fB\s-1MANIFEST\s0\fR, or subsequently matches a regular expression mask in \fB\s-1MANIFEST\s0.SKIP\fR .IP "3." 4 Nothing exists in \fB\s-1MANIFEST\s0\fR that also matches a mask in \fB\s-1MANIFEST\s0.SKIP\fR, so as to avoid an unsatisfiable dependency conditions .PP If there is no \fB\s-1MANIFEST\s0.SKIP\fR included in your distribution, this module will replicate the toolchain behaviour of using the default system-wide \&\s-1MANIFEST\s0.SKIP file. To view the contents of this file, use the command: .PP .Vb 1 \& $ perldoc \-m ExtUtils::MANIFEST.SKIP .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\*(Aqs article: http://use.perl.org/~Alias/journal/38822 \& eval \*(Aquse Test::DistManifest\*(Aq; \& if ($@) { \& plan skip_all => \*(AqTest::DistManifest required to test MANIFEST\*(Aq; \& } \& \& manifest_ok(\*(AqMANIFEST\*(Aq, \*(AqMANIFEST.SKIP\*(Aq); # Default options \& \& manifest_ok(); # Functionally equivalent to above .Ve .SH "COMPATIBILITY" .IX Header "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. .PP If you encounter any problems on a different version or architecture, please contact the maintainer. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "manifest_ok" .IX Subsection "manifest_ok" .Vb 1 \& manifest_ok( $manifest, $skipfile ) .Ve .PP This subroutine checks the manifest list contained in \f(CW$manifest\fR by using \&\f(CW\*(C`Module::Manifest\*(C'\fR 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 \f(CW$manifest\fR file but do not match any regular expressions provided in the \f(CW$skipfile\fR exclusion file. .PP If your \s-1MANIFEST\s0 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: .PP .Vb 2 \& $ make manifest # For ExtUtils::MakeMaker \& $ ./Build manifest # For Module::Build .Ve .SS "Non-Fatal Errors" .IX Subsection "Non-Fatal Errors" By default, errors in the \fB\s-1MANIFEST\s0\fR or \fB\s-1MANIFEST\s0.SKIP\fR files are treated as fatal, which really is the purpose of using \f(CW\*(C`Test::DistManifest\*(C'\fR as part of your author test suite. .PP 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 \f(CW\*(C`debian/\*(C'\fR downstream, and that directory or its files are generally not in \fB\s-1MANIFEST\s0.SKIP\fR. .PP By setting the environment variable \fB\s-1MANIFEST_WARN_ONLY\s0\fR to a true value, errors will be non-fatal \- they show up as diagnostic messages only, but all tests pass from the perspective of \f(CW\*(C`Test::Harness\*(C'\fR. .PP This can be used in a test script as: .PP .Vb 1 \& $ENV{MANIFEST_WARN_ONLY} = 1; .Ve .PP or from other shell scripts as: .PP .Vb 1 \& export MANIFEST_WARN_ONLY=1 .Ve .PP Note that parsing errors in \fB\s-1MANIFEST\s0\fR and circular dependencies will always be considered fatal. The author is not aware of any cases where other behaviour would be useful. .SH "GUTS" .IX Header "GUTS" This module internally plans 4 tests: .IP "1." 4 \&\fB\s-1MANIFEST\s0\fR can be parsed by \f(CW\*(C`Module::Manifest\*(C'\fR .IP "2." 4 Check which files exist in the distribution directory that do not match an existing regular expression in \fB\s-1MANIFEST\s0.SKIP\fR and not listed in the \&\fB\s-1MANIFEST\s0\fR file. These files should either be excluded from the test by addition of a mask in \s-1MANIFEST\s0.SKIP (in the case of temporary development or test files) or should be included in the \s-1MANIFEST\s0. .IP "3." 4 Check which files are specified in \fB\s-1MANIFEST\s0\fR 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. .IP "4." 4 Check which files are specified in both \fB\s-1MANIFEST\s0\fR and \fB\s-1MANIFEST\s0.SKIP\fR. This is clearly an unsatisfiable condition, since the file in question cannot be expected to be included while also simultaneously ignored. .PP If you want to run tests on multiple different \s-1MANIFEST\s0 files, you can simply pass 'no_plan' to the import function, like so: .PP .Vb 1 \& use Test::DistManifest \*(Aqno_plan\*(Aq; \& \& # Multiple tests work properly now \& manifest_ok(\*(AqMANIFEST\*(Aq, \*(AqMANIFEST.SKIP\*(Aq); \& manifest_ok(); \& manifest_ok(\*(AqMANIFEST.OTHER\*(Aq, \*(AqMANIFEST.SKIP\*(Aq); .Ve .PP 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 \*(L"3 internal tests\*(R" may change in the future. .PP Example code: .PP .Vb 3 \& use Test::DistManifest tests => 5; \& manifest_ok(); # 4 tests \& ok(1, \*(Aqis 1 true?\*(Aq); .Ve .SH "AUTHOR" .IX Header "AUTHOR" Jonathan Yu .SS "\s-1CONTRIBUTORS\s0" .IX Subsection "CONTRIBUTORS" Your name here ;\-) .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" .IP "\(bu" 4 Thanks to Adam Kennedy for developing Module::Manifest, which provides much of the core functionality for these tests. .IP "\(bu" 4 Thanks to Apocalypse , for helping me track down an obscure bug caused by circular dependencies: when files are expected by \&\s-1MANIFEST\s0 but explictly skipped by \s-1MANIFEST\s0.SKIP. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Test::DistManifest .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Request Tracker .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testing Service (Kwalitee Tests) .Sp .SH "REPOSITORY" .IX Header "REPOSITORY" You can access the most recent development version of this module at: .PP .PP If you are a \s-1CPAN\s0 developer and would like to make modifications to the code base, please contact Adam Kennedy , the repository administrator. I only ask that you contact me first to discuss the changes you wish to make to the distribution. .SH "FEEDBACK" .IX Header "FEEDBACK" Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer noted above. .PP If you have a bug report or feature request, please file them on the \s-1CPAN\s0 Request Tracker at . If you are able to submit your bug report in the form of failing unit tests, you are \fBstrongly\fR encouraged to do so. .SH "SEE ALSO" .IX Header "SEE ALSO" Test::CheckManifest, a module providing similar functionality .SH "CAVEATS" .IX Header "CAVEATS" .SS "\s-1KNOWN\s0 \s-1BUGS\s0" .IX Subsection "KNOWN BUGS" There are no known bugs as of this release. .SS "\s-1LIMITATIONS\s0" .IX Subsection "LIMITATIONS" .IP "\(bu" 4 There is currently no way to test a \s-1MANIFEST/MANIFEST\s0.SKIP without having the files actually exist on disk. I am planning for this to change in the future. .IP "\(bu" 4 This module has not been tested very thoroughly with Unicode. .IP "\(bu" 4 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. .SH "QUALITY ASSURANCE METRICS" .IX Header "QUALITY ASSURANCE METRICS" .SS "\s-1TEST\s0 \s-1COVERAGE\s0" .IX Subsection "TEST COVERAGE" .Vb 3 \& File stmt bran cond sub pod total \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \& Test/DistManifest.pm 96.1 95.8 100.0 100.0 100.0 96.8 .Ve .SH "LICENSE" .IX Header "LICENSE" Copyright 2008\-2009 by Jonathan Yu .PP This package is distributed under the same terms as Perl itself. Please see the \fI\s-1LICENSE\s0\fR file included in this distribution for full details of these terms. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" This software is provided by the copyright holders and contributors \&\*(L"\s-1AS\s0 \s-1IS\s0\*(R" and \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0, including, but not limited to, the \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1ARE\s0 \s-1DISCLAIMED\s0. .PP 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.