local-lib5/man/man3/ExtUtils::Manifest.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "inc::ExtUtils::Manifest 3"
 132 .TH inc::ExtUtils::Manifest 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::Manifest \- utilities to write and check a MANIFEST file
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use ExtUtils::Manifest qw(...funcs to import...);
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    mkmanifest();
 143 .Ve
 144 .PP
 145 .Vb 4
 146 \&    my @missing_files    = manicheck;
 147 \&    my @skipped          = skipcheck;
 148 \&    my @extra_files      = filecheck;
 149 \&    my($missing, $extra) = fullcheck;
 150 .Ve
 151 .PP
 152 .Vb 1
 153 \&    my $found    = manifind();
 154 .Ve
 155 .PP
 156 .Vb 1
 157 \&    my $manifest = maniread();
 158 .Ve
 159 .PP
 160 .Vb 1
 161 \&    manicopy($read,$target);
 162 .Ve
 163 .PP
 164 .Vb 1
 165 \&    maniadd({$file => $comment, ...});
 166 .Ve
 167 .SH "DESCRIPTION"
 168 .IX Header "DESCRIPTION"
 169 .Sh "Functions"
 170 .IX Subsection "Functions"
 171 ExtUtils::Manifest exports no functions by default.  The following are
 172 exported on request
 173 .IP "mkmanifest" 4
 174 .IX Item "mkmanifest"
 175 .Vb 1
 176 \&    mkmanifest();
 177 .Ve
 178 .Sp
 179 Writes all files in and below the current directory to your \fI\s-1MANIFEST\s0\fR.
 180 It works similar to the result of the Unix command
 181 .Sp
 182 .Vb 1
 183 \&    find . > MANIFEST
 184 .Ve
 185 .Sp
 186 All files that match any regular expression in a file \fI\s-1MANIFEST\s0.SKIP\fR
 187 (if it exists) are ignored.
 188 .Sp
 189 Any existing \fI\s-1MANIFEST\s0\fR file will be saved as \fI\s-1MANIFEST\s0.bak\fR.
 190 .IP "manifind" 4
 191 .IX Item "manifind"
 192 .Vb 1
 193 \&    my $found = manifind();
 194 .Ve
 195 .Sp
 196 returns a hash reference. The keys of the hash are the files found
 197 below the current directory.
 198 .IP "manicheck" 4
 199 .IX Item "manicheck"
 200 .Vb 1
 201 \&    my @missing_files = manicheck();
 202 .Ve
 203 .Sp
 204 checks if all the files within a \f(CW\*(C`MANIFEST\*(C'\fR in the current directory
 205 really do exist. If \f(CW\*(C`MANIFEST\*(C'\fR and the tree below the current
 206 directory are in sync it silently returns an empty list.
 207 Otherwise it returns a list of files which are listed in the
 208 \&\f(CW\*(C`MANIFEST\*(C'\fR but missing from the directory, and by default also
 209 outputs these names to \s-1STDERR\s0.
 210 .IP "filecheck" 4
 211 .IX Item "filecheck"
 212 .Vb 1
 213 \&    my @extra_files = filecheck();
 214 .Ve
 215 .Sp
 216 finds files below the current directory that are not mentioned in the
 217 \&\f(CW\*(C`MANIFEST\*(C'\fR file. An optional file \f(CW\*(C`MANIFEST.SKIP\*(C'\fR will be
 218 consulted. Any file matching a regular expression in such a file will
 219 not be reported as missing in the \f(CW\*(C`MANIFEST\*(C'\fR file. The list of any
 220 extraneous files found is returned, and by default also reported to
 221 \&\s-1STDERR\s0.
 222 .IP "fullcheck" 4
 223 .IX Item "fullcheck"
 224 .Vb 1
 225 \&    my($missing, $extra) = fullcheck();
 226 .Ve
 227 .Sp
 228 does both a \fImanicheck()\fR and a \fIfilecheck()\fR, returning then as two array
 229 refs.
 230 .IP "skipcheck" 4
 231 .IX Item "skipcheck"
 232 .Vb 1
 233 \&    my @skipped = skipcheck();
 234 .Ve
 235 .Sp
 236 lists all the files that are skipped due to your \f(CW\*(C`MANIFEST.SKIP\*(C'\fR
 237 file.
 238 .IP "maniread" 4
 239 .IX Item "maniread"
 240 .Vb 2
 241 \&    my $manifest = maniread();
 242 \&    my $manifest = maniread($manifest_file);
 243 .Ve
 244 .Sp
 245 reads a named \f(CW\*(C`MANIFEST\*(C'\fR file (defaults to \f(CW\*(C`MANIFEST\*(C'\fR in the current
 246 directory) and returns a \s-1HASH\s0 reference with files being the keys and
 247 comments being the values of the \s-1HASH\s0.  Blank lines and lines which
 248 start with \f(CW\*(C`#\*(C'\fR in the \f(CW\*(C`MANIFEST\*(C'\fR file are discarded.
 249 .IP "maniskip" 4
 250 .IX Item "maniskip"
 251 .Vb 2
 252 \&    my $skipchk = maniskip();
 253 \&    my $skipchk = maniskip($manifest_skip_file);
 254 .Ve
 255 .Sp
 256 .Vb 1
 257 \&    if ($skipchk\->($file)) { .. }
 258 .Ve
 259 .Sp
 260 reads a named \f(CW\*(C`MANIFEST.SKIP\*(C'\fR file (defaults to \f(CW\*(C`MANIFEST.SKIP\*(C'\fR in
 261 the current directory) and returns a \s-1CODE\s0 reference that tests whether
 262 a given filename should be skipped.
 263 .IP "manicopy" 4
 264 .IX Item "manicopy"
 265 .Vb 2
 266 \&    manicopy(\e%src, $dest_dir);
 267 \&    manicopy(\e%src, $dest_dir, $how);
 268 .Ve
 269 .Sp
 270 Copies the files that are the keys in \f(CW%src\fR to the \f(CW$dest_dir\fR.  \f(CW%src\fR is
 271 typically returned by the \fImaniread()\fR function.
 272 .Sp
 273 .Vb 1
 274 \&    manicopy( maniread(), $dest_dir );
 275 .Ve
 276 .Sp
 277 This function is useful for producing a directory tree identical to the
 278 intended distribution tree.
 279 .Sp
 280 $how can be used to specify a different methods of \*(L"copying\*(R".  Valid
 281 values are \f(CW\*(C`cp\*(C'\fR, which actually copies the files, \f(CW\*(C`ln\*(C'\fR which creates
 282 hard links, and \f(CW\*(C`best\*(C'\fR which mostly links the files but copies any
 283 symbolic link to make a tree without any symbolic link.  \f(CW\*(C`cp\*(C'\fR is the
 284 default.
 285 .IP "maniadd" 4
 286 .IX Item "maniadd"
 287 .Vb 1
 288 \&  maniadd({ $file => $comment, ...});
 289 .Ve
 290 .Sp
 291 Adds an entry to an existing \fI\s-1MANIFEST\s0\fR unless its already there.
 292 .Sp
 293 $file will be normalized (ie. Unixified).  \fB\s-1UNIMPLEMENTED\s0\fR
 294 .Sh "\s-1MANIFEST\s0"
 295 .IX Subsection "MANIFEST"
 296 A list of files in the distribution, one file per line.  The \s-1MANIFEST\s0
 297 always uses Unix filepath conventions even if you're not on Unix.  This
 298 means \fIfoo/bar\fR style not \fIfoo\ebar\fR.
 299 .PP
 300 Anything between white space and an end of line within a \f(CW\*(C`MANIFEST\*(C'\fR
 301 file is considered to be a comment.  Any line beginning with # is also
 302 a comment. Beginning with ExtUtils::Manifest 1.52, a filename may
 303 contain whitespace characters if it is enclosed in single quotes; single
 304 quotes or backslashes in that filename must be backslash\-escaped.
 305 .PP
 306 .Vb 4
 307 \&    # this a comment
 308 \&    some/file
 309 \&    some/other/file            comment about some/file
 310 \&    'some/third file'          comment
 311 .Ve
 312 .Sh "\s-1MANIFEST\s0.SKIP"
 313 .IX Subsection "MANIFEST.SKIP"
 314 The file \s-1MANIFEST\s0.SKIP may contain regular expressions of files that
 315 should be ignored by \fImkmanifest()\fR and \fIfilecheck()\fR. The regular
 316 expressions should appear one on each line. Blank lines and lines
 317 which start with \f(CW\*(C`#\*(C'\fR are skipped.  Use \f(CW\*(C`\e#\*(C'\fR if you need a regular
 318 expression to start with a \f(CW\*(C`#\*(C'\fR.
 319 .PP
 320 For example:
 321 .PP
 322 .Vb 5
 323 \&    # Version control files and dirs.
 324 \&    \ebRCS\eb
 325 \&    \ebCVS\eb
 326 \&    ,v$
 327 \&    \eB\e.svn\eb
 328 .Ve
 329 .PP
 330 .Vb 5
 331 \&    # Makemaker generated files and dirs.
 332 \&    ^MANIFEST\e.
 333 \&    ^Makefile$
 334 \&    ^blib/
 335 \&    ^MakeMaker\-\ed
 336 .Ve
 337 .PP
 338 .Vb 5
 339 \&    # Temp, old and emacs backup files.
 340 \&    ~$
 341 \&    \e.old$
 342 \&    ^#.*#$
 343 \&    ^\e.#
 344 .Ve
 345 .PP
 346 If no \s-1MANIFEST\s0.SKIP file is found, a default set of skips will be
 347 used, similar to the example above.  If you want nothing skipped,
 348 simply make an empty \s-1MANIFEST\s0.SKIP file.
 349 .PP
 350 In one's own \s-1MANIFEST\s0.SKIP file, certain directives
 351 can be used to include the contents of other \s-1MANIFEST\s0.SKIP
 352 files. At present two such directives are recognized.
 353 .IP "#!include_default" 4
 354 .IX Item "#!include_default"
 355 This inserts the contents of the default \s-1MANIFEST\s0.SKIP file
 356 .IP "#!include /Path/to/another/manifest.skip" 4
 357 .IX Item "#!include /Path/to/another/manifest.skip"
 358 This inserts the contents of the specified external file
 359 .PP
 360 The included contents will be inserted into the \s-1MANIFEST\s0.SKIP
 361 file in between \fI#!start included /path/to/manifest.skip\fR
 362 and \fI#!end included /path/to/manifest.skip\fR markers.
 363 The original \s-1MANIFEST\s0.SKIP is saved as \s-1MANIFEST\s0.SKIP.bak.
 364 .Sh "\s-1EXPORT_OK\s0"
 365 .IX Subsection "EXPORT_OK"
 366 \&\f(CW&mkmanifest\fR, \f(CW&manicheck\fR, \f(CW&filecheck\fR, \f(CW&fullcheck\fR,
 367 \&\f(CW&maniread\fR, and \f(CW&manicopy\fR are exportable.
 368 .Sh "\s-1GLOBAL\s0 \s-1VARIABLES\s0"
 369 .IX Subsection "GLOBAL VARIABLES"
 370 \&\f(CW$ExtUtils::Manifest::MANIFEST\fR defaults to \f(CW\*(C`MANIFEST\*(C'\fR. Changing it
 371 results in both a different \f(CW\*(C`MANIFEST\*(C'\fR and a different
 372 \&\f(CW\*(C`MANIFEST.SKIP\*(C'\fR file. This is useful if you want to maintain
 373 different distributions for different audiences (say a user version
 374 and a developer version including \s-1RCS\s0).
 375 .PP
 376 \&\f(CW$ExtUtils::Manifest::Quiet\fR defaults to 0. If set to a true value,
 377 all functions act silently.
 378 .PP
 379 \&\f(CW$ExtUtils::Manifest::Debug\fR defaults to 0.  If set to a true value,
 380 or if \s-1PERL_MM_MANIFEST_DEBUG\s0 is true, debugging output will be
 381 produced.
 382 .SH "DIAGNOSTICS"
 383 .IX Header "DIAGNOSTICS"
 384 All diagnostic output is sent to \f(CW\*(C`STDERR\*(C'\fR.
 385 .ie n .IP """Not in MANIFEST:""\fR \fIfile" 4
 386 .el .IP "\f(CWNot in MANIFEST:\fR \fIfile\fR" 4
 387 .IX Item "Not in MANIFEST: file"
 388 is reported if a file is found which is not in \f(CW\*(C`MANIFEST\*(C'\fR.
 389 .ie n .IP """Skipping""\fR \fIfile" 4
 390 .el .IP "\f(CWSkipping\fR \fIfile\fR" 4
 391 .IX Item "Skipping file"
 392 is reported if a file is skipped due to an entry in \f(CW\*(C`MANIFEST.SKIP\*(C'\fR.
 393 .ie n .IP """No such file:""\fR \fIfile" 4
 394 .el .IP "\f(CWNo such file:\fR \fIfile\fR" 4
 395 .IX Item "No such file: file"
 396 is reported if a file mentioned in a \f(CW\*(C`MANIFEST\*(C'\fR file does not
 397 exist.
 398 .ie n .IP """MANIFEST:""\fR \fI$!" 4
 399 .el .IP "\f(CWMANIFEST:\fR \fI$!\fR" 4
 400 .IX Item "MANIFEST: $!"
 401 is reported if \f(CW\*(C`MANIFEST\*(C'\fR could not be opened.
 402 .ie n .IP """Added to MANIFEST:""\fR \fIfile" 4
 403 .el .IP "\f(CWAdded to MANIFEST:\fR \fIfile\fR" 4
 404 .IX Item "Added to MANIFEST: file"
 405 is reported by \fImkmanifest()\fR if \f(CW$Verbose\fR is set and a file is added
 406 to \s-1MANIFEST\s0. \f(CW$Verbose\fR is set to 1 by default.
 407 .SH "ENVIRONMENT"
 408 .IX Header "ENVIRONMENT"
 409 .IP "\fB\s-1PERL_MM_MANIFEST_DEBUG\s0\fR" 4
 410 .IX Item "PERL_MM_MANIFEST_DEBUG"
 411 Turns on debugging
 412 .SH "SEE ALSO"
 413 .IX Header "SEE ALSO"
 414 ExtUtils::MakeMaker which has handy targets for most of the functionality.
 415 .SH "AUTHOR"
 416 .IX Header "AUTHOR"
 417 Andreas Koenig \f(CW\*(C`andreas.koenig@anima.de\*(C'\fR
 418 .PP
 419 Maintained by Michael G Schwern \f(CW\*(C`schwern@pobox.com\*(C'\fR within the
 420 ExtUtils-MakeMaker package and, as a separate \s-1CPAN\s0 package, by
 421 Randy Kobes \f(CW\*(C`r.kobes@uwinnipeg.ca\*(C'\fR.