This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update ExtUtils-Manifest to CPAN version 1.65
[perl5.git] / cpan / ExtUtils-Manifest / lib / ExtUtils / Manifest.pm
1 package ExtUtils::Manifest;
2
3 require Exporter;
4 use Config;
5 use File::Basename;
6 use File::Copy 'copy';
7 use File::Find;
8 use File::Spec;
9 use Carp;
10 use strict;
11 use warnings;
12
13 our $VERSION = '1.65';
14 our @ISA = ('Exporter');
15 our @EXPORT_OK = qw(mkmanifest
16                 manicheck  filecheck  fullcheck  skipcheck
17                 manifind   maniread   manicopy   maniadd
18                 maniskip
19                );
20
21 our $Is_MacOS = $^O eq 'MacOS';
22 our $Is_VMS   = $^O eq 'VMS';
23 our $Is_VMS_mode = 0;
24 our $Is_VMS_lc = 0;
25 our $Is_VMS_nodot = 0;  # No dots in dir names or double dots in files
26
27 if ($Is_VMS) {
28     require VMS::Filespec if $Is_VMS;
29     my $vms_unix_rpt;
30     my $vms_efs;
31     my $vms_case;
32
33     $Is_VMS_mode = 1;
34     $Is_VMS_lc = 1;
35     $Is_VMS_nodot = 1;
36     if (eval { local $SIG{__DIE__}; require VMS::Feature; }) {
37         $vms_unix_rpt = VMS::Feature::current("filename_unix_report");
38         $vms_efs = VMS::Feature::current("efs_charset");
39         $vms_case = VMS::Feature::current("efs_case_preserve");
40     } else {
41         my $unix_rpt = $ENV{'DECC$FILENAME_UNIX_REPORT'} || '';
42         my $efs_charset = $ENV{'DECC$EFS_CHARSET'} || '';
43         my $efs_case = $ENV{'DECC$EFS_CASE_PRESERVE'} || '';
44         $vms_unix_rpt = $unix_rpt =~ /^[ET1]/i;
45         $vms_efs = $efs_charset =~ /^[ET1]/i;
46         $vms_case = $efs_case =~ /^[ET1]/i;
47     }
48     $Is_VMS_lc = 0 if ($vms_case);
49     $Is_VMS_mode = 0 if ($vms_unix_rpt);
50     $Is_VMS_nodot = 0 if ($vms_efs);
51 }
52
53 our $Debug   = $ENV{PERL_MM_MANIFEST_DEBUG} || 0;
54 our $Verbose = defined $ENV{PERL_MM_MANIFEST_VERBOSE} ?
55                    $ENV{PERL_MM_MANIFEST_VERBOSE} : 1;
56 our $Quiet = 0;
57 our $MANIFEST = 'MANIFEST';
58
59 our $DEFAULT_MSKIP = File::Spec->catfile( dirname(__FILE__), "$MANIFEST.SKIP" );
60
61
62 =head1 NAME
63
64 ExtUtils::Manifest - utilities to write and check a MANIFEST file
65
66 =head1 SYNOPSIS
67
68     use ExtUtils::Manifest qw(...funcs to import...);
69
70     mkmanifest();
71
72     my @missing_files    = manicheck;
73     my @skipped          = skipcheck;
74     my @extra_files      = filecheck;
75     my($missing, $extra) = fullcheck;
76
77     my $found    = manifind();
78
79     my $manifest = maniread();
80
81     manicopy($read,$target);
82
83     maniadd({$file => $comment, ...});
84
85
86 =head1 DESCRIPTION
87
88 =head2 Functions
89
90 ExtUtils::Manifest exports no functions by default.  The following are
91 exported on request
92
93 =over 4
94
95 =item mkmanifest
96
97     mkmanifest();
98
99 Writes all files in and below the current directory to your F<MANIFEST>.
100 It works similar to the result of the Unix command
101
102     find . > MANIFEST
103
104 All files that match any regular expression in a file F<MANIFEST.SKIP>
105 (if it exists) are ignored.
106
107 Any existing F<MANIFEST> file will be saved as F<MANIFEST.bak>.
108
109 =cut
110
111 sub _sort {
112     return sort { lc $a cmp lc $b } @_;
113 }
114
115 sub mkmanifest {
116     my $manimiss = 0;
117     my $read = (-r 'MANIFEST' && maniread()) or $manimiss++;
118     $read = {} if $manimiss;
119     local *M;
120     my $bakbase = $MANIFEST;
121     $bakbase =~ s/\./_/g if $Is_VMS_nodot; # avoid double dots
122     rename $MANIFEST, "$bakbase.bak" unless $manimiss;
123     open M, "> $MANIFEST" or die "Could not open $MANIFEST: $!";
124     binmode M, ':raw';
125     my $skip = maniskip();
126     my $found = manifind();
127     my($key,$val,$file,%all);
128     %all = (%$found, %$read);
129     $all{$MANIFEST} = ($Is_VMS_mode ? "$MANIFEST\t\t" : '') .
130                      'This list of files'
131         if $manimiss; # add new MANIFEST to known file list
132     foreach $file (_sort keys %all) {
133         if ($skip->($file)) {
134             # Policy: only remove files if they're listed in MANIFEST.SKIP.
135             # Don't remove files just because they don't exist.
136             warn "Removed from $MANIFEST: $file\n" if $Verbose and exists $read->{$file};
137             next;
138         }
139         if ($Verbose){
140             warn "Added to $MANIFEST: $file\n" unless exists $read->{$file};
141         }
142         my $text = $all{$file};
143         $file = _unmacify($file);
144         my $tabs = (5 - (length($file)+1)/8);
145         $tabs = 1 if $tabs < 1;
146         $tabs = 0 unless $text;
147         if ($file =~ /\s/) {
148             $file =~ s/([\\'])/\\$1/g;
149             $file = "'$file'";
150         }
151         print M $file, "\t" x $tabs, $text, "\n";
152     }
153     close M;
154 }
155
156 # Geez, shouldn't this use File::Spec or File::Basename or something?
157 # Why so careful about dependencies?
158 sub clean_up_filename {
159   my $filename = shift;
160   $filename =~ s|^\./||;
161   $filename =~ s/^:([^:]+)$/$1/ if $Is_MacOS;
162   if ( $Is_VMS ) {
163       $filename =~ s/\.$//;                           # trim trailing dot
164       $filename = VMS::Filespec::unixify($filename);  # unescape spaces, etc.
165       if( $Is_VMS_lc ) {
166           $filename = lc($filename);
167           $filename = uc($filename) if $filename =~ /^MANIFEST(\.SKIP)?$/i;
168       }
169   }
170   return $filename;
171 }
172
173
174 =item manifind
175
176     my $found = manifind();
177
178 returns a hash reference. The keys of the hash are the files found
179 below the current directory.
180
181 =cut
182
183 sub manifind {
184     my $p = shift || {};
185     my $found = {};
186
187     my $wanted = sub {
188         my $name = clean_up_filename($File::Find::name);
189         warn "Debug: diskfile $name\n" if $Debug;
190         return if -d $_;
191         $found->{$name} = "";
192     };
193
194     # We have to use "$File::Find::dir/$_" in preprocess, because
195     # $File::Find::name is unavailable.
196     # Also, it's okay to use / here, because MANIFEST files use Unix-style
197     # paths.
198     find({wanted => $wanted},
199          $Is_MacOS ? ":" : ".");
200
201     return $found;
202 }
203
204
205 =item manicheck
206
207     my @missing_files = manicheck();
208
209 checks if all the files within a C<MANIFEST> in the current directory
210 really do exist. If C<MANIFEST> and the tree below the current
211 directory are in sync it silently returns an empty list.
212 Otherwise it returns a list of files which are listed in the
213 C<MANIFEST> but missing from the directory, and by default also
214 outputs these names to STDERR.
215
216 =cut
217
218 sub manicheck {
219     return _check_files();
220 }
221
222
223 =item filecheck
224
225     my @extra_files = filecheck();
226
227 finds files below the current directory that are not mentioned in the
228 C<MANIFEST> file. An optional file C<MANIFEST.SKIP> will be
229 consulted. Any file matching a regular expression in such a file will
230 not be reported as missing in the C<MANIFEST> file. The list of any
231 extraneous files found is returned, and by default also reported to
232 STDERR.
233
234 =cut
235
236 sub filecheck {
237     return _check_manifest();
238 }
239
240
241 =item fullcheck
242
243     my($missing, $extra) = fullcheck();
244
245 does both a manicheck() and a filecheck(), returning then as two array
246 refs.
247
248 =cut
249
250 sub fullcheck {
251     return [_check_files()], [_check_manifest()];
252 }
253
254
255 =item skipcheck
256
257     my @skipped = skipcheck();
258
259 lists all the files that are skipped due to your C<MANIFEST.SKIP>
260 file.
261
262 =cut
263
264 sub skipcheck {
265     my($p) = @_;
266     my $found = manifind();
267     my $matches = maniskip();
268
269     my @skipped = ();
270     foreach my $file (_sort keys %$found){
271         if (&$matches($file)){
272             warn "Skipping $file\n" unless $Quiet;
273             push @skipped, $file;
274             next;
275         }
276     }
277
278     return @skipped;
279 }
280
281
282 sub _check_files {
283     my $p = shift;
284     my $dosnames=(defined(&Dos::UseLFN) && Dos::UseLFN()==0);
285     my $read = maniread() || {};
286     my $found = manifind($p);
287
288     my(@missfile) = ();
289     foreach my $file (_sort keys %$read){
290         warn "Debug: manicheck checking from $MANIFEST $file\n" if $Debug;
291         if ($dosnames){
292             $file = lc $file;
293             $file =~ s=(\.(\w|-)+)=substr ($1,0,4)=ge;
294             $file =~ s=((\w|-)+)=substr ($1,0,8)=ge;
295         }
296         unless ( exists $found->{$file} ) {
297             warn "No such file: $file\n" unless $Quiet;
298             push @missfile, $file;
299         }
300     }
301
302     return @missfile;
303 }
304
305
306 sub _check_manifest {
307     my($p) = @_;
308     my $read = maniread() || {};
309     my $found = manifind($p);
310     my $skip  = maniskip();
311
312     my @missentry = ();
313     foreach my $file (_sort keys %$found){
314         next if $skip->($file);
315         warn "Debug: manicheck checking from disk $file\n" if $Debug;
316         unless ( exists $read->{$file} ) {
317             my $canon = $Is_MacOS ? "\t" . _unmacify($file) : '';
318             warn "Not in $MANIFEST: $file$canon\n" unless $Quiet;
319             push @missentry, $file;
320         }
321     }
322
323     return @missentry;
324 }
325
326
327 =item maniread
328
329     my $manifest = maniread();
330     my $manifest = maniread($manifest_file);
331
332 reads a named C<MANIFEST> file (defaults to C<MANIFEST> in the current
333 directory) and returns a HASH reference with files being the keys and
334 comments being the values of the HASH.  Blank lines and lines which
335 start with C<#> in the C<MANIFEST> file are discarded.
336
337 =cut
338
339 sub maniread {
340     my ($mfile) = @_;
341     $mfile ||= $MANIFEST;
342     my $read = {};
343     local *M;
344     unless (open M, "< $mfile"){
345         warn "Problem opening $mfile: $!";
346         return $read;
347     }
348     local $_;
349     while (<M>){
350         chomp;
351         next if /^\s*#/;
352
353         my($file, $comment);
354
355         # filename may contain spaces if enclosed in ''
356         # (in which case, \\ and \' are escapes)
357         if (($file, $comment) = /^'(\\[\\']|.+)+'\s*(.*)/) {
358             $file =~ s/\\([\\'])/$1/g;
359         }
360         else {
361             ($file, $comment) = /^(\S+)\s*(.*)/;
362         }
363         next unless $file;
364
365         if ($Is_MacOS) {
366             $file = _macify($file);
367             $file =~ s/\\([0-3][0-7][0-7])/sprintf("%c", oct($1))/ge;
368         }
369         elsif ($Is_VMS_mode) {
370             require File::Basename;
371             my($base,$dir) = File::Basename::fileparse($file);
372             # Resolve illegal file specifications in the same way as tar
373             if ($Is_VMS_nodot) {
374                 $dir =~ tr/./_/;
375                 my(@pieces) = split(/\./,$base);
376                 if (@pieces > 2)
377                     { $base = shift(@pieces) . '.' . join('_',@pieces); }
378                 my $okfile = "$dir$base";
379                 warn "Debug: Illegal name $file changed to $okfile\n" if $Debug;
380                 $file = $okfile;
381             }
382             if( $Is_VMS_lc ) {
383                 $file = lc($file);
384                 $file = uc($file) if $file =~ /^MANIFEST(\.SKIP)?$/i;
385             }
386         }
387
388         $read->{$file} = $comment;
389     }
390     close M;
391     $read;
392 }
393
394 =item maniskip
395
396     my $skipchk = maniskip();
397     my $skipchk = maniskip($manifest_skip_file);
398
399     if ($skipchk->($file)) { .. }
400
401 reads a named C<MANIFEST.SKIP> file (defaults to C<MANIFEST.SKIP> in
402 the current directory) and returns a CODE reference that tests whether
403 a given filename should be skipped.
404
405 =cut
406
407 # returns an anonymous sub that decides if an argument matches
408 sub maniskip {
409     my @skip ;
410     my $mfile = shift || "$MANIFEST.SKIP";
411     _check_mskip_directives($mfile) if -f $mfile;
412     local(*M, $_);
413     open M, "< $mfile" or open M, "< $DEFAULT_MSKIP" or return sub {0};
414     while (<M>){
415       chomp;
416       s/\r//;
417       $_ =~ qr{^\s*(?:(?:'([^\\']*(?:\\.[^\\']*)*)')|([^#\s]\S*))?(?:(?:\s*)|(?:\s+(.*?)\s*))$};
418       #my $comment = $3;
419       my $filename = $2;
420       if ( defined($1) ) {
421         $filename = $1;
422         $filename =~ s/\\(['\\])/$1/g;
423       }
424       next if (not defined($filename) or not $filename);
425       push @skip, _macify($filename);
426     }
427     close M;
428     return sub {0} unless (scalar @skip > 0);
429
430     my $opts = $Is_VMS_mode ? '(?i)' : '';
431
432     # Make sure each entry is isolated in its own parentheses, in case
433     # any of them contain alternations
434     my $regex = join '|', map "(?:$_)", @skip;
435
436     return sub { $_[0] =~ qr{$opts$regex} };
437 }
438
439 # checks for the special directives
440 #   #!include_default
441 #   #!include /path/to/some/manifest.skip
442 # in a custom MANIFEST.SKIP for, for including
443 # the content of, respectively, the default MANIFEST.SKIP
444 # and an external manifest.skip file
445 sub _check_mskip_directives {
446     my $mfile = shift;
447     local (*M, $_);
448     my @lines = ();
449     my $flag = 0;
450     unless (open M, "< $mfile") {
451         warn "Problem opening $mfile: $!";
452         return;
453     }
454     while (<M>) {
455         if (/^#!include_default\s*$/) {
456             if (my @default = _include_mskip_file()) {
457                 push @lines, @default;
458                 warn "Debug: Including default MANIFEST.SKIP\n" if $Debug;
459                 $flag++;
460             }
461             next;
462         }
463         if (/^#!include\s+(.*)\s*$/) {
464             my $external_file = $1;
465             if (my @external = _include_mskip_file($external_file)) {
466                 push @lines, @external;
467                 warn "Debug: Including external $external_file\n" if $Debug;
468                 $flag++;
469             }
470             next;
471         }
472         push @lines, $_;
473     }
474     close M;
475     return unless $flag;
476     my $bakbase = $mfile;
477     $bakbase =~ s/\./_/g if $Is_VMS_nodot;  # avoid double dots
478     rename $mfile, "$bakbase.bak";
479     warn "Debug: Saving original $mfile as $bakbase.bak\n" if $Debug;
480     unless (open M, "> $mfile") {
481         warn "Problem opening $mfile: $!";
482         return;
483     }
484     binmode M, ':raw';
485     print M $_ for (@lines);
486     close M;
487     return;
488 }
489
490 # returns an array containing the lines of an external
491 # manifest.skip file, if given, or $DEFAULT_MSKIP
492 sub _include_mskip_file {
493     my $mskip = shift || $DEFAULT_MSKIP;
494     unless (-f $mskip) {
495         warn qq{Included file "$mskip" not found - skipping};
496         return;
497     }
498     local (*M, $_);
499     unless (open M, "< $mskip") {
500         warn "Problem opening $mskip: $!";
501         return;
502     }
503     my @lines = ();
504     push @lines, "\n#!start included $mskip\n";
505     push @lines, $_ while <M>;
506     close M;
507     push @lines, "#!end included $mskip\n\n";
508     return @lines;
509 }
510
511 =item manicopy
512
513     manicopy(\%src, $dest_dir);
514     manicopy(\%src, $dest_dir, $how);
515
516 Copies the files that are the keys in %src to the $dest_dir.  %src is
517 typically returned by the maniread() function.
518
519     manicopy( maniread(), $dest_dir );
520
521 This function is useful for producing a directory tree identical to the
522 intended distribution tree.
523
524 $how can be used to specify a different methods of "copying".  Valid
525 values are C<cp>, which actually copies the files, C<ln> which creates
526 hard links, and C<best> which mostly links the files but copies any
527 symbolic link to make a tree without any symbolic link.  C<cp> is the
528 default.
529
530 =cut
531
532 sub manicopy {
533     my($read,$target,$how)=@_;
534     croak "manicopy() called without target argument" unless defined $target;
535     $how ||= 'cp';
536     require File::Path;
537     require File::Basename;
538
539     $target = VMS::Filespec::unixify($target) if $Is_VMS_mode;
540     File::Path::mkpath([ $target ],! $Quiet,$Is_VMS ? undef : 0755);
541     foreach my $file (keys %$read){
542         if ($Is_MacOS) {
543             if ($file =~ m!:!) {
544                 my $dir = _maccat($target, $file);
545                 $dir =~ s/[^:]+$//;
546                 File::Path::mkpath($dir,1,0755);
547             }
548             cp_if_diff($file, _maccat($target, $file), $how);
549         } else {
550             $file = VMS::Filespec::unixify($file) if $Is_VMS_mode;
551             if ($file =~ m!/!) { # Ilya, that hurts, I fear, or maybe not?
552                 my $dir = File::Basename::dirname($file);
553                 $dir = VMS::Filespec::unixify($dir) if $Is_VMS_mode;
554                 File::Path::mkpath(["$target/$dir"],! $Quiet,$Is_VMS ? undef : 0755);
555             }
556             cp_if_diff($file, "$target/$file", $how);
557         }
558     }
559 }
560
561 sub cp_if_diff {
562     my($from, $to, $how)=@_;
563     if (! -f $from) {
564         carp "$from not found";
565         return;
566     }
567     my($diff) = 0;
568     local(*F,*T);
569     open(F,"< $from\0") or die "Can't read $from: $!\n";
570     if (open(T,"< $to\0")) {
571         local $_;
572         while (<F>) { $diff++,last if $_ ne <T>; }
573         $diff++ unless eof(T);
574         close T;
575     }
576     else { $diff++; }
577     close F;
578     if ($diff) {
579         if (-e $to) {
580             unlink($to) or confess "unlink $to: $!";
581         }
582         STRICT_SWITCH: {
583             best($from,$to), last STRICT_SWITCH if $how eq 'best';
584             cp($from,$to), last STRICT_SWITCH if $how eq 'cp';
585             ln($from,$to), last STRICT_SWITCH if $how eq 'ln';
586             croak("ExtUtils::Manifest::cp_if_diff " .
587                   "called with illegal how argument [$how]. " .
588                   "Legal values are 'best', 'cp', and 'ln'.");
589         }
590     }
591 }
592
593 sub cp {
594     my ($srcFile, $dstFile) = @_;
595     my ($access,$mod) = (stat $srcFile)[8,9];
596
597     copy($srcFile,$dstFile);
598     utime $access, $mod + ($Is_VMS ? 1 : 0), $dstFile;
599     _manicopy_chmod($srcFile, $dstFile);
600 }
601
602
603 sub ln {
604     my ($srcFile, $dstFile) = @_;
605     # Fix-me - VMS can support links.
606     return &cp if $Is_VMS or ($^O eq 'MSWin32' and Win32::IsWin95());
607     link($srcFile, $dstFile);
608
609     unless( _manicopy_chmod($srcFile, $dstFile) ) {
610         unlink $dstFile;
611         return;
612     }
613     1;
614 }
615
616 # 1) Strip off all group and world permissions.
617 # 2) Let everyone read it.
618 # 3) If the owner can execute it, everyone can.
619 sub _manicopy_chmod {
620     my($srcFile, $dstFile) = @_;
621
622     my $perm = 0444 | (stat $srcFile)[2] & 0700;
623     chmod( $perm | ( $perm & 0100 ? 0111 : 0 ), $dstFile );
624 }
625
626 # Files that are often modified in the distdir.  Don't hard link them.
627 my @Exceptions = qw(MANIFEST META.yml SIGNATURE);
628 sub best {
629     my ($srcFile, $dstFile) = @_;
630
631     my $is_exception = grep $srcFile =~ /$_/, @Exceptions;
632     if ($is_exception or !$Config{d_link} or -l $srcFile) {
633         cp($srcFile, $dstFile);
634     } else {
635         ln($srcFile, $dstFile) or cp($srcFile, $dstFile);
636     }
637 }
638
639 sub _macify {
640     my($file) = @_;
641
642     return $file unless $Is_MacOS;
643
644     $file =~ s|^\./||;
645     if ($file =~ m|/|) {
646         $file =~ s|/+|:|g;
647         $file = ":$file";
648     }
649
650     $file;
651 }
652
653 sub _maccat {
654     my($f1, $f2) = @_;
655
656     return "$f1/$f2" unless $Is_MacOS;
657
658     $f1 .= ":$f2";
659     $f1 =~ s/([^:]:):/$1/g;
660     return $f1;
661 }
662
663 sub _unmacify {
664     my($file) = @_;
665
666     return $file unless $Is_MacOS;
667
668     $file =~ s|^:||;
669     $file =~ s|([/ \n])|sprintf("\\%03o", unpack("c", $1))|ge;
670     $file =~ y|:|/|;
671
672     $file;
673 }
674
675
676 =item maniadd
677
678   maniadd({ $file => $comment, ...});
679
680 Adds an entry to an existing F<MANIFEST> unless its already there.
681
682 $file will be normalized (ie. Unixified).  B<UNIMPLEMENTED>
683
684 =cut
685
686 sub maniadd {
687     my($additions) = shift;
688
689     _normalize($additions);
690     _fix_manifest($MANIFEST);
691
692     my $manifest = maniread();
693     my @needed = grep { !exists $manifest->{$_} } keys %$additions;
694     return 1 unless @needed;
695
696     open(MANIFEST, ">>$MANIFEST") or
697       die "maniadd() could not open $MANIFEST: $!";
698     binmode MANIFEST, ':raw';
699
700     foreach my $file (_sort @needed) {
701         my $comment = $additions->{$file} || '';
702         if ($file =~ /\s/) {
703             $file =~ s/([\\'])/\\$1/g;
704             $file = "'$file'";
705         }
706         printf MANIFEST "%-40s %s\n", $file, $comment;
707     }
708     close MANIFEST or die "Error closing $MANIFEST: $!";
709
710     return 1;
711 }
712
713
714 # Make sure this MANIFEST is consistently written with native
715 # newlines and has a terminal newline.
716 sub _fix_manifest {
717     my $manifest_file = shift;
718
719     open MANIFEST, $MANIFEST or die "Could not open $MANIFEST: $!";
720     local $/;
721     my @manifest = split /(\015\012|\012|\015)/, <MANIFEST>, -1;
722     close MANIFEST;
723     my $must_rewrite = "";
724     if ($manifest[-1] eq ""){
725         # sane case: last line had a terminal newline
726         pop @manifest;
727         for (my $i=1; $i<=$#manifest; $i+=2) {
728             unless ($manifest[$i] eq "\n") {
729                 $must_rewrite = "not a newline at pos $i";
730                 last;
731             }
732         }
733     } else {
734         $must_rewrite = "last line without newline";
735     }
736
737     if ( $must_rewrite ) {
738         1 while unlink $MANIFEST; # avoid multiple versions on VMS
739         open MANIFEST, ">", $MANIFEST or die "(must_rewrite=$must_rewrite) Could not open >$MANIFEST: $!";
740         binmode MANIFEST, ':raw';
741         for (my $i=0; $i<=$#manifest; $i+=2) {
742             print MANIFEST "$manifest[$i]\n";
743         }
744         close MANIFEST or die "could not write $MANIFEST: $!";
745     }
746 }
747
748
749 # UNIMPLEMENTED
750 sub _normalize {
751     return;
752 }
753
754
755 =back
756
757 =head2 MANIFEST
758
759 A list of files in the distribution, one file per line.  The MANIFEST
760 always uses Unix filepath conventions even if you're not on Unix.  This
761 means F<foo/bar> style not F<foo\bar>.
762
763 Anything between white space and an end of line within a C<MANIFEST>
764 file is considered to be a comment.  Any line beginning with # is also
765 a comment. Beginning with ExtUtils::Manifest 1.52, a filename may
766 contain whitespace characters if it is enclosed in single quotes; single
767 quotes or backslashes in that filename must be backslash-escaped.
768
769     # this a comment
770     some/file
771     some/other/file            comment about some/file
772     'some/third file'          comment
773
774
775 =head2 MANIFEST.SKIP
776
777 The file MANIFEST.SKIP may contain regular expressions of files that
778 should be ignored by mkmanifest() and filecheck(). The regular
779 expressions should appear one on each line. Blank lines and lines
780 which start with C<#> are skipped.  Use C<\#> if you need a regular
781 expression to start with a C<#>.
782
783 For example:
784
785     # Version control files and dirs.
786     \bRCS\b
787     \bCVS\b
788     ,v$
789     \B\.svn\b
790
791     # Makemaker generated files and dirs.
792     ^MANIFEST\.
793     ^Makefile$
794     ^blib/
795     ^MakeMaker-\d
796
797     # Temp, old and emacs backup files.
798     ~$
799     \.old$
800     ^#.*#$
801     ^\.#
802
803 If no MANIFEST.SKIP file is found, a default set of skips will be
804 used, similar to the example above.  If you want nothing skipped,
805 simply make an empty MANIFEST.SKIP file.
806
807 In one's own MANIFEST.SKIP file, certain directives
808 can be used to include the contents of other MANIFEST.SKIP
809 files. At present two such directives are recognized.
810
811 =over 4
812
813 =item #!include_default
814
815 This inserts the contents of the default MANIFEST.SKIP file
816
817 =item #!include /Path/to/another/manifest.skip
818
819 This inserts the contents of the specified external file
820
821 =back
822
823 The included contents will be inserted into the MANIFEST.SKIP
824 file in between I<#!start included /path/to/manifest.skip>
825 and I<#!end included /path/to/manifest.skip> markers.
826 The original MANIFEST.SKIP is saved as MANIFEST.SKIP.bak.
827
828 =head2 EXPORT_OK
829
830 C<&mkmanifest>, C<&manicheck>, C<&filecheck>, C<&fullcheck>,
831 C<&maniread>, and C<&manicopy> are exportable.
832
833 =head2 GLOBAL VARIABLES
834
835 C<$ExtUtils::Manifest::MANIFEST> defaults to C<MANIFEST>. Changing it
836 results in both a different C<MANIFEST> and a different
837 C<MANIFEST.SKIP> file. This is useful if you want to maintain
838 different distributions for different audiences (say a user version
839 and a developer version including RCS).
840
841 C<$ExtUtils::Manifest::Quiet> defaults to 0. If set to a true value,
842 all functions act silently.
843
844 C<$ExtUtils::Manifest::Debug> defaults to 0.  If set to a true value,
845 or if PERL_MM_MANIFEST_DEBUG is true, debugging output will be
846 produced.
847
848 =head1 DIAGNOSTICS
849
850 All diagnostic output is sent to C<STDERR>.
851
852 =over 4
853
854 =item C<Not in MANIFEST:> I<file>
855
856 is reported if a file is found which is not in C<MANIFEST>.
857
858 =item C<Skipping> I<file>
859
860 is reported if a file is skipped due to an entry in C<MANIFEST.SKIP>.
861
862 =item C<No such file:> I<file>
863
864 is reported if a file mentioned in a C<MANIFEST> file does not
865 exist.
866
867 =item C<MANIFEST:> I<$!>
868
869 is reported if C<MANIFEST> could not be opened.
870
871 =item C<Added to MANIFEST:> I<file>
872
873 is reported by mkmanifest() if $Verbose is set and a file is added
874 to MANIFEST. $Verbose is set to 1 by default.
875
876 =back
877
878 =head1 ENVIRONMENT
879
880 =over 4
881
882 =item B<PERL_MM_MANIFEST_DEBUG>
883
884 Turns on debugging
885
886 =back
887
888 =head1 SEE ALSO
889
890 L<ExtUtils::MakeMaker> which has handy targets for most of the functionality.
891
892 =head1 AUTHOR
893
894 Andreas Koenig C<andreas.koenig@anima.de>
895
896 Maintained by Michael G Schwern C<schwern@pobox.com> within the
897 ExtUtils-MakeMaker package and, as a separate CPAN package, by
898 Randy Kobes C<r.kobes@uwinnipeg.ca>.
899
900 =cut
901
902 1;