Programming Perl

Programming PerlSearch this book
Previous: 7.2.18 ExtUtils::MakeMaker - Create a Makefile for a Perl ExtensionChapter 7
The Standard Perl Library
Next: 7.2.20 ExtUtils::Miniperl - Write the C Code for perlmain.c
 

7.2.19 ExtUtils::Manifest - Utilities to Write and Check a MANIFEST File

require ExtUtils::Manifest;

ExtUtils::Manifest::mkmanifest();
ExtUtils::Manifest::manicheck();
ExtUtils::Manifest::filecheck();
ExtUtils::Manifest::fullcheck();
ExtUtils::Manifest::skipcheck();
ExtUtild::Manifest::manifind();
ExtUtils::Manifest::maniread($file);
ExtUtils::Manifest::manicopy($read, $target, $how);

These routines automate the maintenance and use of a MANIFEST file. A MANIFEST file is essentially just a list of filenames, one per line, with an optional comment on each line, separated by whitespace (usually one or more tabs). The idea is simply that you can extract the filenames by saying:

awk '{print $1}' MANIFEST

mkmanifest() writes the names of all files in and below the current directory to a file named in the global variable $ExtUtils::Manifest::MANIFEST (which defaults to MANIFEST) in the current directory. As the counterpart to the awk command above, it works much like:

find . -type f -print > MANIFEST

except that it also checks the existing MANIFEST file (if any) and copies over any comments that are found there. Also, all filenames that match any regular expression in a file MANIFEST.SKIP (if such a file exists) are ignored.

manicheck() checks whether all files listed in a MANIFEST file in the current directory really do exist.

filecheck() finds files below the current directory that are not mentioned in the MANIFEST file. An optional MANIFEST.SKIP file will be consulted, and any filename matching a regular expression in such a file will not be reported as missing in the MANIFEST file.

fullcheck() does both a manicheck() and a filecheck().

skipcheck() lists all files that are skipped due to your MANIFEST.SKIP file.

manifind() returns a hash reference. The keys of the hash are the files found below the current directory. The values are null strings, representing all the MANIFEST comments that aren't there.

maniread($file) reads a named MANIFEST file (defaults to MANIFEST in the current directory) and returns a hash reference, the keys of which are the filenames, and the values of which are the comments that are there. Er, which may be null if the comments aren't there....

manicopy($read, $target, $how) copies the files that are the keys in the hash %$read to the named target directory. The hash reference $read is typically returned by the maniread() function. manicopy() is useful for producing a directory tree identical to the intended distribution tree. The third parameter $how can be used to specify a different method of "copying". Valid values are "cp", which actually copies the files, "ln", which creates hard links, and "best", which mostly links the files but copies any symbolic link to make a tree without any symbolic link. "best" is the default, though it may not be the best default.

7.2.19.1 Ignoring files

The MANIFEST.SKIP file may contain regular expressions of files that should be ignored by mkmanifest() and filecheck(). The regular expressions should appear one on each line. A typical example:

\bRCS\b
^MANIFEST\.
(?i)^makefile$
~$
\.html$
\.old$
^blib/
^MakeMaker-\d

7.2.19.2 Exportability

mkmanifest(), manicheck(), filecheck(), fullcheck(), maniread(), and manicopy() are exportable.

7.2.19.3 Global variables

$ExtUtils::Manifest::MANIFEST defaults to MANIFEST. Changing it results in both a different MANIFEST and a different MANIFEST.SKIP file. This is useful if you want to maintain different distributions for different audiences (say a user version and a developer version including RCS).

$ExtUtils::Manifest::Quiet defaults to 0. You can set it to a true value to get all the functions to shutup already.

7.2.19.4 Diagnostics

All diagnostic output is sent to STDERR.

Not in MANIFEST: file

A file excluded by a regular expression in MANIFEST.SKIP was missing from the MANIFEST file.

No such file: file

A file mentioned in a MANIFEST file does not exist.

MANIFEST: $!

The MANIFEST file could not be opened.

Added to MANIFEST: file

Reported by mkmanifest() if $Verbose is set and a file is added to MANIFEST. $Verbose is set to 1 by default.

7.2.19.5 See also

The ExtUtils::MakeMaker library module generates a Makefile with handy targets for most of this functionality.


Previous: 7.2.18 ExtUtils::MakeMaker - Create a Makefile for a Perl ExtensionProgramming PerlNext: 7.2.20 ExtUtils::Miniperl - Write the C Code for perlmain.c
7.2.18 ExtUtils::MakeMaker - Create a Makefile for a Perl ExtensionBook Index7.2.20 ExtUtils::Miniperl - Write the C Code for perlmain.c