433a8dd7a31db7b63255c4977498e1f9b92efac5
[perl.git] / cpan / ExtUtils-MakeMaker / lib / ExtUtils / MM_Any.pm
1 package ExtUtils::MM_Any;
2
3 use strict;
4 our $VERSION = '7.24';
5 $VERSION = eval $VERSION;
6
7 use Carp;
8 use File::Spec;
9 use File::Basename;
10 BEGIN { our @ISA = qw(File::Spec); }
11
12 # We need $Verbose
13 use ExtUtils::MakeMaker qw($Verbose neatvalue _sprintf562);
14
15 use ExtUtils::MakeMaker::Config;
16
17
18 # So we don't have to keep calling the methods over and over again,
19 # we have these globals to cache the values.  Faster and shrtr.
20 my $Curdir  = __PACKAGE__->curdir;
21 #my $Updir   = __PACKAGE__->updir;
22
23 my $METASPEC_URL = 'https://metacpan.org/pod/CPAN::Meta::Spec';
24 my $METASPEC_V = 2;
25
26 =head1 NAME
27
28 ExtUtils::MM_Any - Platform-agnostic MM methods
29
30 =head1 SYNOPSIS
31
32   FOR INTERNAL USE ONLY!
33
34   package ExtUtils::MM_SomeOS;
35
36   # Temporarily, you have to subclass both.  Put MM_Any first.
37   require ExtUtils::MM_Any;
38   require ExtUtils::MM_Unix;
39   @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
40
41 =head1 DESCRIPTION
42
43 B<FOR INTERNAL USE ONLY!>
44
45 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
46 modules.  It contains methods which are either inherently
47 cross-platform or are written in a cross-platform manner.
48
49 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix.  This is a
50 temporary solution.
51
52 B<THIS MAY BE TEMPORARY!>
53
54
55 =head1 METHODS
56
57 Any methods marked I<Abstract> must be implemented by subclasses.
58
59
60 =head2 Cross-platform helper methods
61
62 These are methods which help writing cross-platform code.
63
64
65
66 =head3 os_flavor  I<Abstract>
67
68     my @os_flavor = $mm->os_flavor;
69
70 @os_flavor is the style of operating system this is, usually
71 corresponding to the MM_*.pm file we're using.
72
73 The first element of @os_flavor is the major family (ie. Unix,
74 Windows, VMS, OS/2, etc...) and the rest are sub families.
75
76 Some examples:
77
78     Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
79     Windows        ('Win32')
80     Win98          ('Win32', 'Win9x')
81     Linux          ('Unix',  'Linux')
82     MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
83     OS/2           ('OS/2')
84
85 This is used to write code for styles of operating system.
86 See os_flavor_is() for use.
87
88
89 =head3 os_flavor_is
90
91     my $is_this_flavor = $mm->os_flavor_is($this_flavor);
92     my $is_this_flavor = $mm->os_flavor_is(@one_of_these_flavors);
93
94 Checks to see if the current operating system is one of the given flavors.
95
96 This is useful for code like:
97
98     if( $mm->os_flavor_is('Unix') ) {
99         $out = `foo 2>&1`;
100     }
101     else {
102         $out = `foo`;
103     }
104
105 =cut
106
107 sub os_flavor_is {
108     my $self = shift;
109     my %flavors = map { ($_ => 1) } $self->os_flavor;
110     return (grep { $flavors{$_} } @_) ? 1 : 0;
111 }
112
113
114 =head3 can_load_xs
115
116     my $can_load_xs = $self->can_load_xs;
117
118 Returns true if we have the ability to load XS.
119
120 This is important because miniperl, used to build XS modules in the
121 core, can not load XS.
122
123 =cut
124
125 sub can_load_xs {
126     return defined &DynaLoader::boot_DynaLoader ? 1 : 0;
127 }
128
129
130 =head3 can_run
131
132   use ExtUtils::MM;
133   my $runnable = MM->can_run($Config{make});
134
135 If called in a scalar context it will return the full path to the binary
136 you asked for if it was found, or C<undef> if it was not.
137
138 If called in a list context, it will return a list of the full paths to instances
139 of the binary where found in C<PATH>, or an empty list if it was not found.
140
141 Copied from L<IPC::Cmd|IPC::Cmd/"$path = can_run( PROGRAM );">, but modified into
142 a method (and removed C<$INSTANCES> capability).
143
144 =cut
145
146 sub can_run {
147     my ($self, $command) = @_;
148
149     # a lot of VMS executables have a symbol defined
150     # check those first
151     if ( $^O eq 'VMS' ) {
152         require VMS::DCLsym;
153         my $syms = VMS::DCLsym->new;
154         return $command if scalar $syms->getsym( uc $command );
155     }
156
157     my @possibles;
158
159     if( File::Spec->file_name_is_absolute($command) ) {
160         return $self->maybe_command($command);
161
162     } else {
163         for my $dir (
164             File::Spec->path,
165             File::Spec->curdir
166         ) {
167             next if ! $dir || ! -d $dir;
168             my $abs = File::Spec->catfile($self->os_flavor_is('Win32') ? Win32::GetShortPathName( $dir ) : $dir, $command);
169             push @possibles, $abs if $abs = $self->maybe_command($abs);
170         }
171     }
172     return @possibles if wantarray;
173     return shift @possibles;
174 }
175
176
177 =head3 can_redirect_error
178
179   $useredirect = MM->can_redirect_error;
180
181 True if on an OS where qx operator (or backticks) can redirect C<STDERR>
182 onto C<STDOUT>.
183
184 =cut
185
186 sub can_redirect_error {
187   my $self = shift;
188   $self->os_flavor_is('Unix')
189       or ($self->os_flavor_is('Win32') and !$self->os_flavor_is('Win9x'))
190       or $self->os_flavor_is('OS/2')
191 }
192
193
194 =head3 is_make_type
195
196     my $is_dmake = $self->is_make_type('dmake');
197
198 Returns true if C<<$self->make>> is the given type; possibilities are:
199
200   gmake    GNU make
201   dmake
202   nmake
203   bsdmake  BSD pmake-derived
204
205 =cut
206
207 my %maketype2true;
208 # undocumented - so t/cd.t can still do its thing
209 sub _clear_maketype_cache { %maketype2true = () }
210
211 sub is_make_type {
212     my($self, $type) = @_;
213     return $maketype2true{$type} if defined $maketype2true{$type};
214     (undef, undef, my $make_basename) = $self->splitpath($self->make);
215     return $maketype2true{$type} = 1
216         if $make_basename =~ /\b$type\b/i; # executable's filename
217     return $maketype2true{$type} = 0
218         if $make_basename =~ /\b[gdn]make\b/i; # Never fall through for dmake/nmake/gmake
219     # now have to run with "-v" and guess
220     my $redirect = $self->can_redirect_error ? '2>&1' : '';
221     my $make = $self->make || $self->{MAKE};
222     my $minus_v = `"$make" -v $redirect`;
223     return $maketype2true{$type} = 1
224         if $type eq 'gmake' and $minus_v =~ /GNU make/i;
225     return $maketype2true{$type} = 1
226         if $type eq 'bsdmake'
227       and $minus_v =~ /^usage: make \[-BeikNnqrstWwX\]/im;
228     $maketype2true{$type} = 0; # it wasn't whatever you asked
229 }
230
231
232 =head3 can_dep_space
233
234     my $can_dep_space = $self->can_dep_space;
235
236 Returns true if C<make> can handle (probably by quoting)
237 dependencies that contain a space. Currently known true for GNU make,
238 false for BSD pmake derivative.
239
240 =cut
241
242 my $cached_dep_space;
243 sub can_dep_space {
244     my $self = shift;
245     return $cached_dep_space if defined $cached_dep_space;
246     return $cached_dep_space = 1 if $self->is_make_type('gmake');
247     return $cached_dep_space = 0 if $self->is_make_type('dmake'); # only on W32
248     return $cached_dep_space = 0 if $self->is_make_type('bsdmake');
249     return $cached_dep_space = 0; # assume no
250 }
251
252
253 =head3 quote_dep
254
255   $text = $mm->quote_dep($text);
256
257 Method that protects Makefile single-value constants (mainly filenames),
258 so that make will still treat them as single values even if they
259 inconveniently have spaces in. If the make program being used cannot
260 achieve such protection and the given text would need it, throws an
261 exception.
262
263 =cut
264
265 sub quote_dep {
266     my ($self, $arg) = @_;
267     die <<EOF if $arg =~ / / and not $self->can_dep_space;
268 Tried to use make dependency with space for make that can't:
269   '$arg'
270 EOF
271     $arg =~ s/( )/\\$1/g; # how GNU make does it
272     return $arg;
273 }
274
275
276 =head3 split_command
277
278     my @cmds = $MM->split_command($cmd, @args);
279
280 Most OS have a maximum command length they can execute at once.  Large
281 modules can easily generate commands well past that limit.  Its
282 necessary to split long commands up into a series of shorter commands.
283
284 C<split_command> will return a series of @cmds each processing part of
285 the args.  Collectively they will process all the arguments.  Each
286 individual line in @cmds will not be longer than the
287 $self->max_exec_len being careful to take into account macro expansion.
288
289 $cmd should include any switches and repeated initial arguments.
290
291 If no @args are given, no @cmds will be returned.
292
293 Pairs of arguments will always be preserved in a single command, this
294 is a heuristic for things like pm_to_blib and pod2man which work on
295 pairs of arguments.  This makes things like this safe:
296
297     $self->split_command($cmd, %pod2man);
298
299
300 =cut
301
302 sub split_command {
303     my($self, $cmd, @args) = @_;
304
305     my @cmds = ();
306     return(@cmds) unless @args;
307
308     # If the command was given as a here-doc, there's probably a trailing
309     # newline.
310     chomp $cmd;
311
312     # set aside 30% for macro expansion.
313     my $len_left = int($self->max_exec_len * 0.70);
314     $len_left -= length $self->_expand_macros($cmd);
315
316     do {
317         my $arg_str = '';
318         my @next_args;
319         while( @next_args = splice(@args, 0, 2) ) {
320             # Two at a time to preserve pairs.
321             my $next_arg_str = "\t  ". join ' ', @next_args, "\n";
322
323             if( !length $arg_str ) {
324                 $arg_str .= $next_arg_str
325             }
326             elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
327                 unshift @args, @next_args;
328                 last;
329             }
330             else {
331                 $arg_str .= $next_arg_str;
332             }
333         }
334         chop $arg_str;
335
336         push @cmds, $self->escape_newlines("$cmd \n$arg_str");
337     } while @args;
338
339     return @cmds;
340 }
341
342
343 sub _expand_macros {
344     my($self, $cmd) = @_;
345
346     $cmd =~ s{\$\((\w+)\)}{
347         defined $self->{$1} ? $self->{$1} : "\$($1)"
348     }e;
349     return $cmd;
350 }
351
352
353 =head3 make_type
354
355 Returns a suitable string describing the type of makefile being written.
356
357 =cut
358
359 # override if this isn't suitable!
360 sub make_type { return 'Unix-style'; }
361
362
363 =head3 stashmeta
364
365     my @recipelines = $MM->stashmeta($text, $file);
366
367 Generates a set of C<@recipelines> which will result in the literal
368 C<$text> ending up in literal C<$file> when the recipe is executed. Call
369 it once, with all the text you want in C<$file>. Make macros will not
370 be expanded, so the locations will be fixed at configure-time, not
371 at build-time.
372
373 =cut
374
375 sub stashmeta {
376     my($self, $text, $file) = @_;
377     $self->echo($text, $file, { allow_variables => 0, append => 0 });
378 }
379
380
381 =head3 echo
382
383     my @commands = $MM->echo($text);
384     my @commands = $MM->echo($text, $file);
385     my @commands = $MM->echo($text, $file, \%opts);
386
387 Generates a set of @commands which print the $text to a $file.
388
389 If $file is not given, output goes to STDOUT.
390
391 If $opts{append} is true the $file will be appended to rather than
392 overwritten.  Default is to overwrite.
393
394 If $opts{allow_variables} is true, make variables of the form
395 C<$(...)> will not be escaped.  Other C<$> will.  Default is to escape
396 all C<$>.
397
398 Example of use:
399
400     my $make = join '', map "\t$_\n", $MM->echo($text, $file);
401
402 =cut
403
404 sub echo {
405     my($self, $text, $file, $opts) = @_;
406
407     # Compatibility with old options
408     if( !ref $opts ) {
409         my $append = $opts;
410         $opts = { append => $append || 0 };
411     }
412     $opts->{allow_variables} = 0 unless defined $opts->{allow_variables};
413
414     my $ql_opts = { allow_variables => $opts->{allow_variables} };
415     my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_, $ql_opts) }
416                split /\n/, $text;
417     if( $file ) {
418         my $redirect = $opts->{append} ? '>>' : '>';
419         $cmds[0] .= " $redirect $file";
420         $_ .= " >> $file" foreach @cmds[1..$#cmds];
421     }
422
423     return @cmds;
424 }
425
426
427 =head3 wraplist
428
429   my $args = $mm->wraplist(@list);
430
431 Takes an array of items and turns them into a well-formatted list of
432 arguments.  In most cases this is simply something like:
433
434     FOO \
435     BAR \
436     BAZ
437
438 =cut
439
440 sub wraplist {
441     my $self = shift;
442     return join " \\\n\t", @_;
443 }
444
445
446 =head3 maketext_filter
447
448     my $filter_make_text = $mm->maketext_filter($make_text);
449
450 The text of the Makefile is run through this method before writing to
451 disk.  It allows systems a chance to make portability fixes to the
452 Makefile.
453
454 By default it does nothing.
455
456 This method is protected and not intended to be called outside of
457 MakeMaker.
458
459 =cut
460
461 sub maketext_filter { return $_[1] }
462
463
464 =head3 cd  I<Abstract>
465
466   my $subdir_cmd = $MM->cd($subdir, @cmds);
467
468 This will generate a make fragment which runs the @cmds in the given
469 $dir.  The rough equivalent to this, except cross platform.
470
471   cd $subdir && $cmd
472
473 Currently $dir can only go down one level.  "foo" is fine.  "foo/bar" is
474 not.  "../foo" is right out.
475
476 The resulting $subdir_cmd has no leading tab nor trailing newline.  This
477 makes it easier to embed in a make string.  For example.
478
479       my $make = sprintf <<'CODE', $subdir_cmd;
480   foo :
481       $(ECHO) what
482       %s
483       $(ECHO) mouche
484   CODE
485
486
487 =head3 oneliner  I<Abstract>
488
489   my $oneliner = $MM->oneliner($perl_code);
490   my $oneliner = $MM->oneliner($perl_code, \@switches);
491
492 This will generate a perl one-liner safe for the particular platform
493 you're on based on the given $perl_code and @switches (a -e is
494 assumed) suitable for using in a make target.  It will use the proper
495 shell quoting and escapes.
496
497 $(PERLRUN) will be used as perl.
498
499 Any newlines in $perl_code will be escaped.  Leading and trailing
500 newlines will be stripped.  Makes this idiom much easier:
501
502     my $code = $MM->oneliner(<<'CODE', [...switches...]);
503 some code here
504 another line here
505 CODE
506
507 Usage might be something like:
508
509     # an echo emulation
510     $oneliner = $MM->oneliner('print "Foo\n"');
511     $make = '$oneliner > somefile';
512
513 Dollar signs in the $perl_code will be protected from make using the
514 C<quote_literal> method, unless they are recognised as being a make
515 variable, C<$(varname)>, in which case they will be left for make
516 to expand. Remember to quote make macros else it might be used as a
517 bareword. For example:
518
519     # Assign the value of the $(VERSION_FROM) make macro to $vf.
520     $oneliner = $MM->oneliner('$vf = "$(VERSION_FROM)"');
521
522 Its currently very simple and may be expanded sometime in the figure
523 to include more flexible code and switches.
524
525
526 =head3 quote_literal  I<Abstract>
527
528     my $safe_text = $MM->quote_literal($text);
529     my $safe_text = $MM->quote_literal($text, \%options);
530
531 This will quote $text so it is interpreted literally in the shell.
532
533 For example, on Unix this would escape any single-quotes in $text and
534 put single-quotes around the whole thing.
535
536 If $options{allow_variables} is true it will leave C<'$(FOO)'> make
537 variables untouched.  If false they will be escaped like any other
538 C<$>.  Defaults to true.
539
540 =head3 escape_dollarsigns
541
542     my $escaped_text = $MM->escape_dollarsigns($text);
543
544 Escapes stray C<$> so they are not interpreted as make variables.
545
546 It lets by C<$(...)>.
547
548 =cut
549
550 sub escape_dollarsigns {
551     my($self, $text) = @_;
552
553     # Escape dollar signs which are not starting a variable
554     $text =~ s{\$ (?!\() }{\$\$}gx;
555
556     return $text;
557 }
558
559
560 =head3 escape_all_dollarsigns
561
562     my $escaped_text = $MM->escape_all_dollarsigns($text);
563
564 Escapes all C<$> so they are not interpreted as make variables.
565
566 =cut
567
568 sub escape_all_dollarsigns {
569     my($self, $text) = @_;
570
571     # Escape dollar signs
572     $text =~ s{\$}{\$\$}gx;
573
574     return $text;
575 }
576
577
578 =head3 escape_newlines  I<Abstract>
579
580     my $escaped_text = $MM->escape_newlines($text);
581
582 Shell escapes newlines in $text.
583
584
585 =head3 max_exec_len  I<Abstract>
586
587     my $max_exec_len = $MM->max_exec_len;
588
589 Calculates the maximum command size the OS can exec.  Effectively,
590 this is the max size of a shell command line.
591
592 =for _private
593 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
594
595
596 =head3 make
597
598     my $make = $MM->make;
599
600 Returns the make variant we're generating the Makefile for.  This attempts
601 to do some normalization on the information from %Config or the user.
602
603 =cut
604
605 sub make {
606     my $self = shift;
607
608     my $make = lc $self->{MAKE};
609
610     # Truncate anything like foomake6 to just foomake.
611     $make =~ s/^(\w+make).*/$1/;
612
613     # Turn gnumake into gmake.
614     $make =~ s/^gnu/g/;
615
616     return $make;
617 }
618
619
620 =head2 Targets
621
622 These are methods which produce make targets.
623
624
625 =head3 all_target
626
627 Generate the default target 'all'.
628
629 =cut
630
631 sub all_target {
632     my $self = shift;
633
634     return <<'MAKE_EXT';
635 all :: pure_all
636         $(NOECHO) $(NOOP)
637 MAKE_EXT
638
639 }
640
641
642 =head3 blibdirs_target
643
644     my $make_frag = $mm->blibdirs_target;
645
646 Creates the blibdirs target which creates all the directories we use
647 in blib/.
648
649 The blibdirs.ts target is deprecated.  Depend on blibdirs instead.
650
651
652 =cut
653
654 sub _xs_list_basenames {
655     my ($self) = @_;
656     map { (my $b = $_) =~ s/\.xs$//; $b } sort keys %{ $self->{XS} };
657 }
658
659 sub blibdirs_target {
660     my $self = shift;
661
662     my @dirs = map { uc "\$(INST_$_)" } qw(libdir archlib
663                                            autodir archautodir
664                                            bin script
665                                            man1dir man3dir
666                                           );
667     if ($self->{XSMULTI}) {
668         for my $ext ($self->_xs_list_basenames) {
669             my ($v, $d, $f) = File::Spec->splitpath($ext);
670             my @d = File::Spec->splitdir($d);
671             shift @d if $d[0] eq 'lib';
672             push @dirs, $self->catdir('$(INST_ARCHLIB)', 'auto', @d, $f);
673         }
674     }
675
676     my @exists = map { $_.'$(DFSEP).exists' } @dirs;
677
678     my $make = sprintf <<'MAKE', join(' ', @exists);
679 blibdirs : %s
680         $(NOECHO) $(NOOP)
681
682 # Backwards compat with 6.18 through 6.25
683 blibdirs.ts : blibdirs
684         $(NOECHO) $(NOOP)
685
686 MAKE
687
688     $make .= $self->dir_target(@dirs);
689
690     return $make;
691 }
692
693
694 =head3 clean (o)
695
696 Defines the clean target.
697
698 =cut
699
700 sub clean {
701 # --- Cleanup and Distribution Sections ---
702
703     my($self, %attribs) = @_;
704     my @m;
705     push(@m, '
706 # Delete temporary files but do not touch installed files. We don\'t delete
707 # the Makefile here so a later make realclean still has a makefile to use.
708
709 clean :: clean_subdirs
710 ');
711
712     my @files = sort values %{$self->{XS}}; # .c files from *.xs files
713     push @files, map {
714         my $file = $_;
715         map { $file.$_ } $self->{OBJ_EXT}, qw(.def _def.old .bs .bso .exp .base);
716     } $self->_xs_list_basenames;
717     my @dirs  = qw(blib);
718
719     # Normally these are all under blib but they might have been
720     # redefined.
721     # XXX normally this would be a good idea, but the Perl core sets
722     # INST_LIB = ../../lib rather than actually installing the files.
723     # So a "make clean" in an ext/ directory would blow away lib.
724     # Until the core is adjusted let's leave this out.
725 #     push @dirs, qw($(INST_ARCHLIB) $(INST_LIB)
726 #                    $(INST_BIN) $(INST_SCRIPT)
727 #                    $(INST_MAN1DIR) $(INST_MAN3DIR)
728 #                    $(INST_LIBDIR) $(INST_ARCHLIBDIR) $(INST_AUTODIR)
729 #                    $(INST_STATIC) $(INST_DYNAMIC)
730 #                 );
731
732
733     if( $attribs{FILES} ) {
734         # Use @dirs because we don't know what's in here.
735         push @dirs, ref $attribs{FILES}                ?
736                         @{$attribs{FILES}}             :
737                         split /\s+/, $attribs{FILES}   ;
738     }
739
740     push(@files, qw[$(MAKE_APERL_FILE)
741                     MYMETA.json MYMETA.yml perlmain.c tmon.out mon.out so_locations
742                     blibdirs.ts pm_to_blib pm_to_blib.ts
743                     *$(OBJ_EXT) *$(LIB_EXT) perl.exe perl perl$(EXE_EXT)
744                     $(BOOTSTRAP) $(BASEEXT).bso
745                     $(BASEEXT).def lib$(BASEEXT).def
746                     $(BASEEXT).exp $(BASEEXT).x
747                    ]);
748
749     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.all'));
750     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.ld'));
751
752     # core files
753     if ($^O eq 'vos') {
754         push(@files, qw[perl*.kp]);
755     }
756     else {
757         push(@files, qw[core core.*perl.*.? *perl.core]);
758     }
759
760     push(@files, map { "core." . "[0-9]"x$_ } (1..5));
761
762     # OS specific things to clean up.  Use @dirs since we don't know
763     # what might be in here.
764     push @dirs, $self->extra_clean_files;
765
766     # Occasionally files are repeated several times from different sources
767     { my(%f) = map { ($_ => 1) } @files; @files = sort keys %f; }
768     { my(%d) = map { ($_ => 1) } @dirs;  @dirs  = sort keys %d; }
769
770     push @m, map "\t$_\n", $self->split_command('- $(RM_F)',  @files);
771     push @m, map "\t$_\n", $self->split_command('- $(RM_RF)', @dirs);
772
773     # Leave Makefile.old around for realclean
774     push @m, <<'MAKE';
775           $(NOECHO) $(RM_F) $(MAKEFILE_OLD)
776         - $(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD) $(DEV_NULL)
777 MAKE
778
779     push(@m, "\t$attribs{POSTOP}\n")   if $attribs{POSTOP};
780
781     join("", @m);
782 }
783
784
785 =head3 clean_subdirs_target
786
787   my $make_frag = $MM->clean_subdirs_target;
788
789 Returns the clean_subdirs target.  This is used by the clean target to
790 call clean on any subdirectories which contain Makefiles.
791
792 =cut
793
794 sub clean_subdirs_target {
795     my($self) = shift;
796
797     # No subdirectories, no cleaning.
798     return <<'NOOP_FRAG' unless @{$self->{DIR}};
799 clean_subdirs :
800         $(NOECHO) $(NOOP)
801 NOOP_FRAG
802
803
804     my $clean = "clean_subdirs :\n";
805
806     for my $dir (@{$self->{DIR}}) {
807         my $subclean = $self->oneliner(sprintf <<'CODE', $dir);
808 exit 0 unless chdir '%s';  system '$(MAKE) clean' if -f '$(FIRST_MAKEFILE)';
809 CODE
810
811         $clean .= "\t$subclean\n";
812     }
813
814     return $clean;
815 }
816
817
818 =head3 dir_target
819
820     my $make_frag = $mm->dir_target(@directories);
821
822 Generates targets to create the specified directories and set its
823 permission to PERM_DIR.
824
825 Because depending on a directory to just ensure it exists doesn't work
826 too well (the modified time changes too often) dir_target() creates a
827 .exists file in the created directory.  It is this you should depend on.
828 For portability purposes you should use the $(DIRFILESEP) macro rather
829 than a '/' to separate the directory from the file.
830
831     yourdirectory$(DIRFILESEP).exists
832
833 =cut
834
835 sub dir_target {
836     my($self, @dirs) = @_;
837
838     my $make = '';
839     foreach my $dir (@dirs) {
840         $make .= sprintf <<'MAKE', ($dir) x 4;
841 %s$(DFSEP).exists :: Makefile.PL
842         $(NOECHO) $(MKPATH) %s
843         $(NOECHO) $(CHMOD) $(PERM_DIR) %s
844         $(NOECHO) $(TOUCH) %s$(DFSEP).exists
845
846 MAKE
847
848     }
849
850     return $make;
851 }
852
853
854 =head3 distdir
855
856 Defines the scratch directory target that will hold the distribution
857 before tar-ing (or shar-ing).
858
859 =cut
860
861 # For backwards compatibility.
862 *dist_dir = *distdir;
863
864 sub distdir {
865     my($self) = shift;
866
867     my $meta_target = $self->{NO_META} ? '' : 'distmeta';
868     my $sign_target = !$self->{SIGN}   ? '' : 'distsignature';
869
870     return sprintf <<'MAKE_FRAG', $meta_target, $sign_target;
871 create_distdir :
872         $(RM_RF) $(DISTVNAME)
873         $(PERLRUN) "-MExtUtils::Manifest=manicopy,maniread" \
874                 -e "manicopy(maniread(),'$(DISTVNAME)', '$(DIST_CP)');"
875
876 distdir : create_distdir %s %s
877         $(NOECHO) $(NOOP)
878
879 MAKE_FRAG
880
881 }
882
883
884 =head3 dist_test
885
886 Defines a target that produces the distribution in the
887 scratch directory, and runs 'perl Makefile.PL; make ;make test' in that
888 subdirectory.
889
890 =cut
891
892 sub dist_test {
893     my($self) = shift;
894
895     my $mpl_args = join " ", map qq["$_"], @ARGV;
896
897     my $test = $self->cd('$(DISTVNAME)',
898                          '$(ABSPERLRUN) Makefile.PL '.$mpl_args,
899                          '$(MAKE) $(PASTHRU)',
900                          '$(MAKE) test $(PASTHRU)'
901                         );
902
903     return sprintf <<'MAKE_FRAG', $test;
904 disttest : distdir
905         %s
906
907 MAKE_FRAG
908
909
910 }
911
912
913 =head3 xs_dlsyms_ext
914
915 Returns file-extension for C<xs_make_dlsyms> method's output file,
916 including any "." character.
917
918 =cut
919
920 sub xs_dlsyms_ext {
921     die "Pure virtual method";
922 }
923
924 =head3 xs_dlsyms_extra
925
926 Returns any extra text to be prepended to the C<$extra> argument of
927 C<xs_make_dlsyms>.
928
929 =cut
930
931 sub xs_dlsyms_extra {
932     '';
933 }
934
935 =head3 xs_dlsyms_iterator
936
937 Iterates over necessary shared objects, calling C<xs_make_dlsyms> method
938 for each with appropriate arguments.
939
940 =cut
941
942 sub xs_dlsyms_iterator {
943     my ($self, $attribs) = @_;
944     if ($self->{XSMULTI}) {
945         my @m;
946         for my $ext ($self->_xs_list_basenames) {
947             my @parts = File::Spec->splitdir($ext);
948             shift @parts if $parts[0] eq 'lib';
949             my $name = join '::', @parts;
950             push @m, $self->xs_make_dlsyms(
951                 $attribs,
952                 $ext . $self->xs_dlsyms_ext,
953                 "$ext.xs",
954                 $name,
955                 $parts[-1],
956                 {}, [], {}, [],
957                 $self->xs_dlsyms_extra . q!, 'FILE' => ! . neatvalue($ext),
958             );
959         }
960         return join "\n", @m;
961     } else {
962         return $self->xs_make_dlsyms(
963             $attribs,
964             $self->{BASEEXT} . $self->xs_dlsyms_ext,
965             'Makefile.PL',
966             $self->{NAME},
967             $self->{DLBASE},
968             $attribs->{DL_FUNCS} || $self->{DL_FUNCS} || {},
969             $attribs->{FUNCLIST} || $self->{FUNCLIST} || [],
970             $attribs->{IMPORTS} || $self->{IMPORTS} || {},
971             $attribs->{DL_VARS} || $self->{DL_VARS} || [],
972             $self->xs_dlsyms_extra,
973         );
974     }
975 }
976
977 =head3 xs_make_dlsyms
978
979     $self->xs_make_dlsyms(
980         \%attribs, # hashref from %attribs in caller
981         "$self->{BASEEXT}.def", # output file for Makefile target
982         'Makefile.PL', # dependency
983         $self->{NAME}, # shared object's "name"
984         $self->{DLBASE}, # last ::-separated part of name
985         $attribs{DL_FUNCS} || $self->{DL_FUNCS} || {}, # various params
986         $attribs{FUNCLIST} || $self->{FUNCLIST} || [],
987         $attribs{IMPORTS} || $self->{IMPORTS} || {},
988         $attribs{DL_VARS} || $self->{DL_VARS} || [],
989         # optional extra param that will be added as param to Mksymlists
990     );
991
992 Utility method that returns Makefile snippet to call C<Mksymlists>.
993
994 =cut
995
996 sub xs_make_dlsyms {
997     my ($self, $attribs, $target, $dep, $name, $dlbase, $funcs, $funclist, $imports, $vars, $extra) = @_;
998     my @m = (
999      "\n$target: $dep\n",
1000      q! $(PERLRUN) -MExtUtils::Mksymlists \\
1001      -e "Mksymlists('NAME'=>\"!, $name,
1002      q!\", 'DLBASE' => '!,$dlbase,
1003      # The above two lines quoted differently to work around
1004      # a bug in the 4DOS/4NT command line interpreter.  The visible
1005      # result of the bug was files named q('extension_name',) *with the
1006      # single quotes and the comma* in the extension build directories.
1007      q!', 'DL_FUNCS' => !,neatvalue($funcs),
1008      q!, 'FUNCLIST' => !,neatvalue($funclist),
1009      q!, 'IMPORTS' => !,neatvalue($imports),
1010      q!, 'DL_VARS' => !, neatvalue($vars)
1011     );
1012     push @m, $extra if defined $extra;
1013     push @m, qq!);"\n!;
1014     join '', @m;
1015 }
1016
1017 =head3 dynamic (o)
1018
1019 Defines the dynamic target.
1020
1021 =cut
1022
1023 sub dynamic {
1024 # --- Dynamic Loading Sections ---
1025
1026     my($self) = shift;
1027     '
1028 dynamic :: $(FIRST_MAKEFILE) config $(INST_BOOT) $(INST_DYNAMIC)
1029         $(NOECHO) $(NOOP)
1030 ';
1031 }
1032
1033
1034 =head3 makemakerdflt_target
1035
1036   my $make_frag = $mm->makemakerdflt_target
1037
1038 Returns a make fragment with the makemakerdeflt_target specified.
1039 This target is the first target in the Makefile, is the default target
1040 and simply points off to 'all' just in case any make variant gets
1041 confused or something gets snuck in before the real 'all' target.
1042
1043 =cut
1044
1045 sub makemakerdflt_target {
1046     return <<'MAKE_FRAG';
1047 makemakerdflt : all
1048         $(NOECHO) $(NOOP)
1049 MAKE_FRAG
1050
1051 }
1052
1053
1054 =head3 manifypods_target
1055
1056   my $manifypods_target = $self->manifypods_target;
1057
1058 Generates the manifypods target.  This target generates man pages from
1059 all POD files in MAN1PODS and MAN3PODS.
1060
1061 =cut
1062
1063 sub manifypods_target {
1064     my($self) = shift;
1065
1066     my $man1pods      = '';
1067     my $man3pods      = '';
1068     my $dependencies  = '';
1069
1070     # populate manXpods & dependencies:
1071     foreach my $name (sort keys %{$self->{MAN1PODS}}, sort keys %{$self->{MAN3PODS}}) {
1072         $dependencies .= " \\\n\t$name";
1073     }
1074
1075     my $manify = <<END;
1076 manifypods : pure_all config $dependencies
1077 END
1078
1079     my @man_cmds;
1080     foreach my $section (qw(1 3)) {
1081         my $pods = $self->{"MAN${section}PODS"};
1082         my $p2m = sprintf <<'CMD', $section, $] > 5.008 ? " -u" : "";
1083         $(NOECHO) $(POD2MAN) --section=%s --perm_rw=$(PERM_RW)%s
1084 CMD
1085         push @man_cmds, $self->split_command($p2m, map {($_,$pods->{$_})} sort keys %$pods);
1086     }
1087
1088     $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
1089     $manify .= join '', map { "$_\n" } @man_cmds;
1090
1091     return $manify;
1092 }
1093
1094 {
1095     my $has_cpan_meta;
1096     sub _has_cpan_meta {
1097         return $has_cpan_meta if defined $has_cpan_meta;
1098         return $has_cpan_meta = !!eval {
1099             require CPAN::Meta;
1100             CPAN::Meta->VERSION(2.112150);
1101             1;
1102         };
1103     }
1104 }
1105
1106 =head3 metafile_target
1107
1108     my $target = $mm->metafile_target;
1109
1110 Generate the metafile target.
1111
1112 Writes the file META.yml (YAML encoded meta-data) and META.json
1113 (JSON encoded meta-data) about the module in the distdir.
1114 The format follows Module::Build's as closely as possible.
1115
1116 =cut
1117
1118 sub metafile_target {
1119     my $self = shift;
1120     return <<'MAKE_FRAG' if $self->{NO_META} or ! _has_cpan_meta();
1121 metafile :
1122         $(NOECHO) $(NOOP)
1123 MAKE_FRAG
1124
1125     my $metadata   = $self->metafile_data(
1126         $self->{META_ADD}   || {},
1127         $self->{META_MERGE} || {},
1128     );
1129
1130     my $meta = $self->_fix_metadata_before_conversion( $metadata );
1131
1132     my @write_metayml = $self->stashmeta(
1133       $meta->as_string({version => "1.4"}), 'META_new.yml'
1134     );
1135     my @write_metajson = $self->stashmeta(
1136       $meta->as_string({version => "2.0"}), 'META_new.json'
1137     );
1138
1139     my $metayml = join("\n\t", @write_metayml);
1140     my $metajson = join("\n\t", @write_metajson);
1141     return sprintf <<'MAKE_FRAG', $metayml, $metajson;
1142 metafile : create_distdir
1143         $(NOECHO) $(ECHO) Generating META.yml
1144         %s
1145         -$(NOECHO) $(MV) META_new.yml $(DISTVNAME)/META.yml
1146         $(NOECHO) $(ECHO) Generating META.json
1147         %s
1148         -$(NOECHO) $(MV) META_new.json $(DISTVNAME)/META.json
1149 MAKE_FRAG
1150
1151 }
1152
1153 =begin private
1154
1155 =head3 _fix_metadata_before_conversion
1156
1157     $mm->_fix_metadata_before_conversion( \%metadata );
1158
1159 Fixes errors in the metadata before it's handed off to CPAN::Meta for
1160 conversion. This hopefully results in something that can be used further
1161 on, no guarantee is made though.
1162
1163 =end private
1164
1165 =cut
1166
1167 sub _fix_metadata_before_conversion {
1168     my ( $self, $metadata ) = @_;
1169
1170     # we should never be called unless this already passed but
1171     # prefer to be defensive in case somebody else calls this
1172
1173     return unless _has_cpan_meta;
1174
1175     my $bad_version = $metadata->{version} &&
1176                       !CPAN::Meta::Validator->new->version( 'version', $metadata->{version} );
1177     # just delete all invalid versions
1178     if( $bad_version ) {
1179         warn "Can't parse version '$metadata->{version}'\n";
1180         $metadata->{version} = '';
1181     }
1182
1183     my $validator2 = CPAN::Meta::Validator->new( $metadata );
1184     my @errors;
1185     push @errors, $validator2->errors if !$validator2->is_valid;
1186     my $validator14 = CPAN::Meta::Validator->new(
1187         {
1188             %$metadata,
1189             'meta-spec' => { version => 1.4 },
1190         }
1191     );
1192     push @errors, $validator14->errors if !$validator14->is_valid;
1193     # fix non-camelcase custom resource keys (only other trick we know)
1194     for my $error ( @errors ) {
1195         my ( $key ) = ( $error =~ /Custom resource '(.*)' must be in CamelCase./ );
1196         next if !$key;
1197
1198         # first try to remove all non-alphabetic chars
1199         ( my $new_key = $key ) =~ s/[^_a-zA-Z]//g;
1200
1201         # if that doesn't work, uppercase first one
1202         $new_key = ucfirst $new_key if !$validator14->custom_1( $new_key );
1203
1204         # copy to new key if that worked
1205         $metadata->{resources}{$new_key} = $metadata->{resources}{$key}
1206           if $validator14->custom_1( $new_key );
1207
1208         # and delete old one in any case
1209         delete $metadata->{resources}{$key};
1210     }
1211
1212     # paper over validation issues, but still complain, necessary because
1213     # there's no guarantee that the above will fix ALL errors
1214     my $meta = eval { CPAN::Meta->create( $metadata, { lazy_validation => 1 } ) };
1215     warn $@ if $@ and
1216                $@ !~ /encountered CODE.*, but JSON can only represent references to arrays or hashes/;
1217
1218     # use the original metadata straight if the conversion failed
1219     # or if it can't be stringified.
1220     if( !$meta                                                  ||
1221         !eval { $meta->as_string( { version => $METASPEC_V } ) }      ||
1222         !eval { $meta->as_string }
1223     ) {
1224         $meta = bless $metadata, 'CPAN::Meta';
1225     }
1226
1227     my $now_license = $meta->as_struct({ version => 2 })->{license};
1228     if ($self->{LICENSE} and $self->{LICENSE} ne 'unknown' and
1229         @{$now_license} == 1 and $now_license->[0] eq 'unknown'
1230     ) {
1231         warn "Invalid LICENSE value '$self->{LICENSE}' ignored\n";
1232     }
1233
1234     $meta;
1235 }
1236
1237
1238 =begin private
1239
1240 =head3 _sort_pairs
1241
1242     my @pairs = _sort_pairs($sort_sub, \%hash);
1243
1244 Sorts the pairs of a hash based on keys ordered according
1245 to C<$sort_sub>.
1246
1247 =end private
1248
1249 =cut
1250
1251 sub _sort_pairs {
1252     my $sort  = shift;
1253     my $pairs = shift;
1254     return map  { $_ => $pairs->{$_} }
1255            sort $sort
1256            keys %$pairs;
1257 }
1258
1259
1260 # Taken from Module::Build::Base
1261 sub _hash_merge {
1262     my ($self, $h, $k, $v) = @_;
1263     if (ref $h->{$k} eq 'ARRAY') {
1264         push @{$h->{$k}}, ref $v ? @$v : $v;
1265     } elsif (ref $h->{$k} eq 'HASH') {
1266         $self->_hash_merge($h->{$k}, $_, $v->{$_}) foreach keys %$v;
1267     } else {
1268         $h->{$k} = $v;
1269     }
1270 }
1271
1272
1273 =head3 metafile_data
1274
1275     my $metadata_hashref = $mm->metafile_data(\%meta_add, \%meta_merge);
1276
1277 Returns the data which MakeMaker turns into the META.yml file 
1278 and the META.json file. It is always in version 2.0 of the format.
1279
1280 Values of %meta_add will overwrite any existing metadata in those
1281 keys.  %meta_merge will be merged with them.
1282
1283 =cut
1284
1285 sub metafile_data {
1286     my $self = shift;
1287     my($meta_add, $meta_merge) = @_;
1288
1289     $meta_add ||= {};
1290     $meta_merge ||= {};
1291
1292     my $version = _normalize_version($self->{VERSION});
1293     my $release_status = ($version =~ /_/) ? 'unstable' : 'stable';
1294     my %meta = (
1295         # required
1296         abstract     => $self->{ABSTRACT} || 'unknown',
1297         author       => defined($self->{AUTHOR}) ? $self->{AUTHOR} : ['unknown'],
1298         dynamic_config => 1,
1299         generated_by => "ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION",
1300         license      => [ $self->{LICENSE} || 'unknown' ],
1301         'meta-spec'  => {
1302             url         => $METASPEC_URL,
1303             version     => $METASPEC_V,
1304         },
1305         name         => $self->{DISTNAME},
1306         release_status => $release_status,
1307         version      => $version,
1308
1309         # optional
1310         no_index     => { directory => [qw(t inc)] },
1311     );
1312     $self->_add_requirements_to_meta(\%meta);
1313
1314     if (!eval { require JSON::PP; require CPAN::Meta::Converter; CPAN::Meta::Converter->VERSION(2.141170) }) {
1315       return \%meta;
1316     }
1317
1318     # needs to be based on the original version
1319     my $v1_add = _metaspec_version($meta_add) !~ /^2/;
1320
1321     for my $frag ($meta_add, $meta_merge) {
1322         $frag = CPAN::Meta::Converter->new($frag, default_version => "1.4")->upgrade_fragment;
1323     }
1324
1325     # if we upgraded a 1.x _ADD fragment, we gave it a prereqs key that
1326     # will override all prereqs, which is more than the user asked for;
1327     # instead, we'll go inside the prereqs and override all those
1328     while( my($key, $val) = each %$meta_add ) {
1329         if ($v1_add and $key eq 'prereqs') {
1330             $meta{$key}{$_} = $val->{$_} for keys %$val;
1331         } elsif ($key ne 'meta-spec') {
1332             $meta{$key} = $val;
1333         }
1334     }
1335
1336     while( my($key, $val) = each %$meta_merge ) {
1337         next if $key eq 'meta-spec';
1338         $self->_hash_merge(\%meta, $key, $val);
1339     }
1340
1341     return \%meta;
1342 }
1343
1344
1345 =begin private
1346
1347 =cut
1348
1349 sub _add_requirements_to_meta {
1350     my ( $self, $meta ) = @_;
1351     # Check the original args so we can tell between the user setting it
1352     # to an empty hash and it just being initialized.
1353     $meta->{prereqs}{configure}{requires} = $self->{ARGS}{CONFIGURE_REQUIRES}
1354         ? $self->{CONFIGURE_REQUIRES}
1355         : { 'ExtUtils::MakeMaker' => 0, };
1356     $meta->{prereqs}{build}{requires} = $self->{ARGS}{BUILD_REQUIRES}
1357         ? $self->{BUILD_REQUIRES}
1358         : { 'ExtUtils::MakeMaker' => 0, };
1359     $meta->{prereqs}{test}{requires} = $self->{TEST_REQUIRES}
1360         if $self->{ARGS}{TEST_REQUIRES};
1361     $meta->{prereqs}{runtime}{requires} = $self->{PREREQ_PM}
1362         if $self->{ARGS}{PREREQ_PM};
1363     $meta->{prereqs}{runtime}{requires}{perl} = _normalize_version($self->{MIN_PERL_VERSION})
1364         if $self->{MIN_PERL_VERSION};
1365 }
1366
1367 # spec version of given fragment - if not given, assume 1.4
1368 sub _metaspec_version {
1369   my ( $meta ) = @_;
1370   return $meta->{'meta-spec'}->{version}
1371     if defined $meta->{'meta-spec'}
1372        and defined $meta->{'meta-spec'}->{version};
1373   return '1.4';
1374 }
1375
1376 sub _add_requirements_to_meta_v1_4 {
1377     my ( $self, $meta ) = @_;
1378     # Check the original args so we can tell between the user setting it
1379     # to an empty hash and it just being initialized.
1380     if( $self->{ARGS}{CONFIGURE_REQUIRES} ) {
1381         $meta->{configure_requires} = $self->{CONFIGURE_REQUIRES};
1382     } else {
1383         $meta->{configure_requires} = {
1384             'ExtUtils::MakeMaker'       => 0,
1385         };
1386     }
1387     if( $self->{ARGS}{BUILD_REQUIRES} ) {
1388         $meta->{build_requires} = $self->{BUILD_REQUIRES};
1389     } else {
1390         $meta->{build_requires} = {
1391             'ExtUtils::MakeMaker'       => 0,
1392         };
1393     }
1394     if( $self->{ARGS}{TEST_REQUIRES} ) {
1395         $meta->{build_requires} = {
1396           %{ $meta->{build_requires} },
1397           %{ $self->{TEST_REQUIRES} },
1398         };
1399     }
1400     $meta->{requires} = $self->{PREREQ_PM}
1401         if defined $self->{PREREQ_PM};
1402     $meta->{requires}{perl} = _normalize_version($self->{MIN_PERL_VERSION})
1403         if $self->{MIN_PERL_VERSION};
1404 }
1405
1406 # Adapted from Module::Build::Base
1407 sub _normalize_version {
1408   my ($version) = @_;
1409   $version = 0 unless defined $version;
1410
1411   if ( ref $version eq 'version' ) { # version objects
1412     $version = $version->stringify;
1413   }
1414   elsif ( $version =~ /^[^v][^.]*\.[^.]+\./ ) { # no leading v, multiple dots
1415     # normalize string tuples without "v": "1.2.3" -> "v1.2.3"
1416     $version = "v$version";
1417   }
1418   else {
1419     # leave alone
1420   }
1421   return $version;
1422 }
1423
1424 =head3 _dump_hash
1425
1426     $yaml = _dump_hash(\%options, %hash);
1427
1428 Implements a fake YAML dumper for a hash given
1429 as a list of pairs. No quoting/escaping is done. Keys
1430 are supposed to be strings. Values are undef, strings,
1431 hash refs or array refs of strings.
1432
1433 Supported options are:
1434
1435     delta => STR - indentation delta
1436     use_header => BOOL - whether to include a YAML header
1437     indent => STR - a string of spaces
1438           default: ''
1439
1440     max_key_length => INT - maximum key length used to align
1441         keys and values of the same hash
1442         default: 20
1443     key_sort => CODE - a sort sub
1444             It may be undef, which means no sorting by keys
1445         default: sub { lc $a cmp lc $b }
1446
1447     customs => HASH - special options for certain keys
1448            (whose values are hashes themselves)
1449         may contain: max_key_length, key_sort, customs
1450
1451 =end private
1452
1453 =cut
1454
1455 sub _dump_hash {
1456     croak "first argument should be a hash ref" unless ref $_[0] eq 'HASH';
1457     my $options = shift;
1458     my %hash = @_;
1459
1460     # Use a list to preserve order.
1461     my @pairs;
1462
1463     my $k_sort
1464         = exists $options->{key_sort} ? $options->{key_sort}
1465                                       : sub { lc $a cmp lc $b };
1466     if ($k_sort) {
1467         croak "'key_sort' should be a coderef" unless ref $k_sort eq 'CODE';
1468         @pairs = _sort_pairs($k_sort, \%hash);
1469     } else { # list of pairs, no sorting
1470         @pairs = @_;
1471     }
1472
1473     my $yaml     = $options->{use_header} ? "--- #YAML:1.0\n" : '';
1474     my $indent   = $options->{indent} || '';
1475     my $k_length = min(
1476         ($options->{max_key_length} || 20),
1477         max(map { length($_) + 1 } grep { !ref $hash{$_} } keys %hash)
1478     );
1479     my $customs  = $options->{customs} || {};
1480
1481     # printf format for key
1482     my $k_format = "%-${k_length}s";
1483
1484     while( @pairs ) {
1485         my($key, $val) = splice @pairs, 0, 2;
1486         $val = '~' unless defined $val;
1487         if(ref $val eq 'HASH') {
1488             if ( keys %$val ) {
1489                 my %k_options = ( # options for recursive call
1490                     delta => $options->{delta},
1491                     use_header => 0,
1492                     indent => $indent . $options->{delta},
1493                 );
1494                 if (exists $customs->{$key}) {
1495                     my %k_custom = %{$customs->{$key}};
1496                     foreach my $k (qw(key_sort max_key_length customs)) {
1497                         $k_options{$k} = $k_custom{$k} if exists $k_custom{$k};
1498                     }
1499                 }
1500                 $yaml .= $indent . "$key:\n"
1501                   . _dump_hash(\%k_options, %$val);
1502             }
1503             else {
1504                 $yaml .= $indent . "$key:  {}\n";
1505             }
1506         }
1507         elsif (ref $val eq 'ARRAY') {
1508             if( @$val ) {
1509                 $yaml .= $indent . "$key:\n";
1510
1511                 for (@$val) {
1512                     croak "only nested arrays of non-refs are supported" if ref $_;
1513                     $yaml .= $indent . $options->{delta} . "- $_\n";
1514                 }
1515             }
1516             else {
1517                 $yaml .= $indent . "$key:  []\n";
1518             }
1519         }
1520         elsif( ref $val and !blessed($val) ) {
1521             croak "only nested hashes, arrays and objects are supported";
1522         }
1523         else {  # if it's an object, just stringify it
1524             $yaml .= $indent . sprintf "$k_format  %s\n", "$key:", $val;
1525         }
1526     };
1527
1528     return $yaml;
1529
1530 }
1531
1532 sub blessed {
1533     return eval { $_[0]->isa("UNIVERSAL"); };
1534 }
1535
1536 sub max {
1537     return (sort { $b <=> $a } @_)[0];
1538 }
1539
1540 sub min {
1541     return (sort { $a <=> $b } @_)[0];
1542 }
1543
1544 =head3 metafile_file
1545
1546     my $meta_yml = $mm->metafile_file(@metadata_pairs);
1547
1548 Turns the @metadata_pairs into YAML.
1549
1550 This method does not implement a complete YAML dumper, being limited
1551 to dump a hash with values which are strings, undef's or nested hashes
1552 and arrays of strings. No quoting/escaping is done.
1553
1554 =cut
1555
1556 sub metafile_file {
1557     my $self = shift;
1558
1559     my %dump_options = (
1560         use_header => 1,
1561         delta      => ' ' x 4,
1562         key_sort   => undef,
1563     );
1564     return _dump_hash(\%dump_options, @_);
1565
1566 }
1567
1568
1569 =head3 distmeta_target
1570
1571     my $make_frag = $mm->distmeta_target;
1572
1573 Generates the distmeta target to add META.yml and META.json to the MANIFEST
1574 in the distdir.
1575
1576 =cut
1577
1578 sub distmeta_target {
1579     my $self = shift;
1580
1581     my @add_meta = (
1582       $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']),
1583 exit unless -e q{META.yml};
1584 eval { maniadd({q{META.yml} => q{Module YAML meta-data (added by MakeMaker)}}) }
1585     or die "Could not add META.yml to MANIFEST: ${'@'}"
1586 CODE
1587       $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd'])
1588 exit unless -f q{META.json};
1589 eval { maniadd({q{META.json} => q{Module JSON meta-data (added by MakeMaker)}}) }
1590     or die "Could not add META.json to MANIFEST: ${'@'}"
1591 CODE
1592     );
1593
1594     my @add_meta_to_distdir = map { $self->cd('$(DISTVNAME)', $_) } @add_meta;
1595
1596     return sprintf <<'MAKE', @add_meta_to_distdir;
1597 distmeta : create_distdir metafile
1598         $(NOECHO) %s
1599         $(NOECHO) %s
1600
1601 MAKE
1602
1603 }
1604
1605
1606 =head3 mymeta
1607
1608     my $mymeta = $mm->mymeta;
1609
1610 Generate MYMETA information as a hash either from an existing CPAN Meta file
1611 (META.json or META.yml) or from internal data.
1612
1613 =cut
1614
1615 sub mymeta {
1616     my $self = shift;
1617     my $file = shift || ''; # for testing
1618
1619     my $mymeta = $self->_mymeta_from_meta($file);
1620     my $v2 = 1;
1621
1622     unless ( $mymeta ) {
1623         $mymeta = $self->metafile_data(
1624             $self->{META_ADD}   || {},
1625             $self->{META_MERGE} || {},
1626         );
1627         $v2 = 0;
1628     }
1629
1630     # Overwrite the non-configure dependency hashes
1631     $self->_add_requirements_to_meta($mymeta);
1632
1633     $mymeta->{dynamic_config} = 0;
1634
1635     return $mymeta;
1636 }
1637
1638
1639 sub _mymeta_from_meta {
1640     my $self = shift;
1641     my $metafile = shift || ''; # for testing
1642
1643     return unless _has_cpan_meta();
1644
1645     my $meta;
1646     for my $file ( $metafile, "META.json", "META.yml" ) {
1647       next unless -e $file;
1648       eval {
1649           $meta = CPAN::Meta->load_file($file)->as_struct( { version => 2 } );
1650       };
1651       last if $meta;
1652     }
1653     return unless $meta;
1654
1655     # META.yml before 6.25_01 cannot be trusted.  META.yml lived in the source directory.
1656     # There was a good chance the author accidentally uploaded a stale META.yml if they
1657     # rolled their own tarball rather than using "make dist".
1658     if ($meta->{generated_by} &&
1659         $meta->{generated_by} =~ /ExtUtils::MakeMaker version ([\d\._]+)/) {
1660         my $eummv = do { local $^W = 0; $1+0; };
1661         if ($eummv < 6.2501) {
1662             return;
1663         }
1664     }
1665
1666     return $meta;
1667 }
1668
1669 =head3 write_mymeta
1670
1671     $self->write_mymeta( $mymeta );
1672
1673 Write MYMETA information to MYMETA.json and MYMETA.yml.
1674
1675 =cut
1676
1677 sub write_mymeta {
1678     my $self = shift;
1679     my $mymeta = shift;
1680
1681     return unless _has_cpan_meta();
1682
1683     my $meta_obj = $self->_fix_metadata_before_conversion( $mymeta );
1684
1685     $meta_obj->save( 'MYMETA.json', { version => "2.0" } );
1686     $meta_obj->save( 'MYMETA.yml', { version => "1.4" } );
1687     return 1;
1688 }
1689
1690 =head3 realclean (o)
1691
1692 Defines the realclean target.
1693
1694 =cut
1695
1696 sub realclean {
1697     my($self, %attribs) = @_;
1698
1699     my @dirs  = qw($(DISTVNAME));
1700     my @files = qw($(FIRST_MAKEFILE) $(MAKEFILE_OLD));
1701
1702     # Special exception for the perl core where INST_* is not in blib.
1703     # This cleans up the files built from the ext/ directory (all XS).
1704     if( $self->{PERL_CORE} ) {
1705         push @dirs, qw($(INST_AUTODIR) $(INST_ARCHAUTODIR));
1706         push @files, values %{$self->{PM}};
1707     }
1708
1709     if( $self->has_link_code ){
1710         push @files, qw($(OBJECT));
1711     }
1712
1713     if( $attribs{FILES} ) {
1714         if( ref $attribs{FILES} ) {
1715             push @dirs, @{ $attribs{FILES} };
1716         }
1717         else {
1718             push @dirs, split /\s+/, $attribs{FILES};
1719         }
1720     }
1721
1722     # Occasionally files are repeated several times from different sources
1723     { my(%f) = map { ($_ => 1) } @files;  @files = sort keys %f; }
1724     { my(%d) = map { ($_ => 1) } @dirs;   @dirs  = sort keys %d; }
1725
1726     my $rm_cmd  = join "\n\t", map { "$_" }
1727                     $self->split_command('- $(RM_F)',  @files);
1728     my $rmf_cmd = join "\n\t", map { "$_" }
1729                     $self->split_command('- $(RM_RF)', @dirs);
1730
1731     my $m = sprintf <<'MAKE', $rm_cmd, $rmf_cmd;
1732 # Delete temporary files (via clean) and also delete dist files
1733 realclean purge :: realclean_subdirs
1734         %s
1735         %s
1736 MAKE
1737
1738     $m .= "\t$attribs{POSTOP}\n" if $attribs{POSTOP};
1739
1740     return $m;
1741 }
1742
1743
1744 =head3 realclean_subdirs_target
1745
1746   my $make_frag = $MM->realclean_subdirs_target;
1747
1748 Returns the realclean_subdirs target.  This is used by the realclean
1749 target to call realclean on any subdirectories which contain Makefiles.
1750
1751 =cut
1752
1753 sub realclean_subdirs_target {
1754     my $self = shift;
1755     my @m = <<'EOF';
1756 # so clean is forced to complete before realclean_subdirs runs
1757 realclean_subdirs : clean
1758 EOF
1759     return join '', @m, "\t\$(NOECHO) \$(NOOP)\n" unless @{$self->{DIR}};
1760     foreach my $dir (@{$self->{DIR}}) {
1761         foreach my $makefile ('$(MAKEFILE_OLD)', '$(FIRST_MAKEFILE)' ) {
1762             my $subrclean .= $self->oneliner(_sprintf562 <<'CODE', $dir, $makefile);
1763 chdir '%1$s';  system '$(MAKE) $(USEMAKEFILE) %2$s realclean' if -f '%2$s';
1764 CODE
1765             push @m, "\t- $subrclean\n";
1766         }
1767     }
1768     return join '', @m;
1769 }
1770
1771
1772 =head3 signature_target
1773
1774     my $target = $mm->signature_target;
1775
1776 Generate the signature target.
1777
1778 Writes the file SIGNATURE with "cpansign -s".
1779
1780 =cut
1781
1782 sub signature_target {
1783     my $self = shift;
1784
1785     return <<'MAKE_FRAG';
1786 signature :
1787         cpansign -s
1788 MAKE_FRAG
1789
1790 }
1791
1792
1793 =head3 distsignature_target
1794
1795     my $make_frag = $mm->distsignature_target;
1796
1797 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
1798 distdir.
1799
1800 =cut
1801
1802 sub distsignature_target {
1803     my $self = shift;
1804
1805     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1806 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
1807     or die "Could not add SIGNATURE to MANIFEST: ${'@'}"
1808 CODE
1809
1810     my $sign_dist        = $self->cd('$(DISTVNAME)' => 'cpansign -s');
1811
1812     # cpansign -s complains if SIGNATURE is in the MANIFEST yet does not
1813     # exist
1814     my $touch_sig        = $self->cd('$(DISTVNAME)' => '$(TOUCH) SIGNATURE');
1815     my $add_sign_to_dist = $self->cd('$(DISTVNAME)' => $add_sign );
1816
1817     return sprintf <<'MAKE', $add_sign_to_dist, $touch_sig, $sign_dist
1818 distsignature : distmeta
1819         $(NOECHO) %s
1820         $(NOECHO) %s
1821         %s
1822
1823 MAKE
1824
1825 }
1826
1827
1828 =head3 special_targets
1829
1830   my $make_frag = $mm->special_targets
1831
1832 Returns a make fragment containing any targets which have special
1833 meaning to make.  For example, .SUFFIXES and .PHONY.
1834
1835 =cut
1836
1837 sub special_targets {
1838     my $make_frag = <<'MAKE_FRAG';
1839 .SUFFIXES : .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
1840
1841 .PHONY: all config static dynamic test linkext manifest blibdirs clean realclean disttest distdir pure_all subdirs clean_subdirs makemakerdflt manifypods realclean_subdirs subdirs_dynamic subdirs_pure_nolink subdirs_static subdirs-test_dynamic subdirs-test_static test_dynamic test_static
1842
1843 MAKE_FRAG
1844
1845     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
1846 .NO_CONFIG_REC: Makefile
1847
1848 MAKE_FRAG
1849
1850     return $make_frag;
1851 }
1852
1853
1854
1855
1856 =head2 Init methods
1857
1858 Methods which help initialize the MakeMaker object and macros.
1859
1860
1861 =head3 init_ABSTRACT
1862
1863     $mm->init_ABSTRACT
1864
1865 =cut
1866
1867 sub init_ABSTRACT {
1868     my $self = shift;
1869
1870     if( $self->{ABSTRACT_FROM} and $self->{ABSTRACT} ) {
1871         warn "Both ABSTRACT_FROM and ABSTRACT are set.  ".
1872              "Ignoring ABSTRACT_FROM.\n";
1873         return;
1874     }
1875
1876     if ($self->{ABSTRACT_FROM}){
1877         $self->{ABSTRACT} = $self->parse_abstract($self->{ABSTRACT_FROM}) or
1878             carp "WARNING: Setting ABSTRACT via file ".
1879                  "'$self->{ABSTRACT_FROM}' failed\n";
1880     }
1881
1882     if ($self->{ABSTRACT} && $self->{ABSTRACT} =~ m![[:cntrl:]]+!) {
1883             warn "WARNING: ABSTRACT contains control character(s),".
1884                  " they will be removed\n";
1885             $self->{ABSTRACT} =~ s![[:cntrl:]]+!!g;
1886             return;
1887     }
1888 }
1889
1890 =head3 init_INST
1891
1892     $mm->init_INST;
1893
1894 Called by init_main.  Sets up all INST_* variables except those related
1895 to XS code.  Those are handled in init_xs.
1896
1897 =cut
1898
1899 sub init_INST {
1900     my($self) = shift;
1901
1902     $self->{INST_ARCHLIB} ||= $self->catdir($Curdir,"blib","arch");
1903     $self->{INST_BIN}     ||= $self->catdir($Curdir,'blib','bin');
1904
1905     # INST_LIB typically pre-set if building an extension after
1906     # perl has been built and installed. Setting INST_LIB allows
1907     # you to build directly into, say $Config{privlibexp}.
1908     unless ($self->{INST_LIB}){
1909         if ($self->{PERL_CORE}) {
1910             $self->{INST_LIB} = $self->{INST_ARCHLIB} = $self->{PERL_LIB};
1911         } else {
1912             $self->{INST_LIB} = $self->catdir($Curdir,"blib","lib");
1913         }
1914     }
1915
1916     my @parentdir = split(/::/, $self->{PARENT_NAME});
1917     $self->{INST_LIBDIR}      = $self->catdir('$(INST_LIB)',     @parentdir);
1918     $self->{INST_ARCHLIBDIR}  = $self->catdir('$(INST_ARCHLIB)', @parentdir);
1919     $self->{INST_AUTODIR}     = $self->catdir('$(INST_LIB)', 'auto',
1920                                               '$(FULLEXT)');
1921     $self->{INST_ARCHAUTODIR} = $self->catdir('$(INST_ARCHLIB)', 'auto',
1922                                               '$(FULLEXT)');
1923
1924     $self->{INST_SCRIPT}  ||= $self->catdir($Curdir,'blib','script');
1925
1926     $self->{INST_MAN1DIR} ||= $self->catdir($Curdir,'blib','man1');
1927     $self->{INST_MAN3DIR} ||= $self->catdir($Curdir,'blib','man3');
1928
1929     return 1;
1930 }
1931
1932
1933 =head3 init_INSTALL
1934
1935     $mm->init_INSTALL;
1936
1937 Called by init_main.  Sets up all INSTALL_* variables (except
1938 INSTALLDIRS) and *PREFIX.
1939
1940 =cut
1941
1942 sub init_INSTALL {
1943     my($self) = shift;
1944
1945     if( $self->{ARGS}{INSTALL_BASE} and $self->{ARGS}{PREFIX} ) {
1946         die "Only one of PREFIX or INSTALL_BASE can be given.  Not both.\n";
1947     }
1948
1949     if( $self->{ARGS}{INSTALL_BASE} ) {
1950         $self->init_INSTALL_from_INSTALL_BASE;
1951     }
1952     else {
1953         $self->init_INSTALL_from_PREFIX;
1954     }
1955 }
1956
1957
1958 =head3 init_INSTALL_from_PREFIX
1959
1960   $mm->init_INSTALL_from_PREFIX;
1961
1962 =cut
1963
1964 sub init_INSTALL_from_PREFIX {
1965     my $self = shift;
1966
1967     $self->init_lib2arch;
1968
1969     # There are often no Config.pm defaults for these new man variables so
1970     # we fall back to the old behavior which is to use installman*dir
1971     foreach my $num (1, 3) {
1972         my $k = 'installsiteman'.$num.'dir';
1973
1974         $self->{uc $k} ||= uc "\$(installman${num}dir)"
1975           unless $Config{$k};
1976     }
1977
1978     foreach my $num (1, 3) {
1979         my $k = 'installvendorman'.$num.'dir';
1980
1981         unless( $Config{$k} ) {
1982             $self->{uc $k}  ||= $Config{usevendorprefix}
1983                               ? uc "\$(installman${num}dir)"
1984                               : '';
1985         }
1986     }
1987
1988     $self->{INSTALLSITEBIN} ||= '$(INSTALLBIN)'
1989       unless $Config{installsitebin};
1990     $self->{INSTALLSITESCRIPT} ||= '$(INSTALLSCRIPT)'
1991       unless $Config{installsitescript};
1992
1993     unless( $Config{installvendorbin} ) {
1994         $self->{INSTALLVENDORBIN} ||= $Config{usevendorprefix}
1995                                     ? $Config{installbin}
1996                                     : '';
1997     }
1998     unless( $Config{installvendorscript} ) {
1999         $self->{INSTALLVENDORSCRIPT} ||= $Config{usevendorprefix}
2000                                        ? $Config{installscript}
2001                                        : '';
2002     }
2003
2004
2005     my $iprefix = $Config{installprefixexp} || $Config{installprefix} ||
2006                   $Config{prefixexp}        || $Config{prefix} || '';
2007     my $vprefix = $Config{usevendorprefix}  ? $Config{vendorprefixexp} : '';
2008     my $sprefix = $Config{siteprefixexp}    || '';
2009
2010     # 5.005_03 doesn't have a siteprefix.
2011     $sprefix = $iprefix unless $sprefix;
2012
2013
2014     $self->{PREFIX}       ||= '';
2015
2016     if( $self->{PREFIX} ) {
2017         @{$self}{qw(PERLPREFIX SITEPREFIX VENDORPREFIX)} =
2018           ('$(PREFIX)') x 3;
2019     }
2020     else {
2021         $self->{PERLPREFIX}   ||= $iprefix;
2022         $self->{SITEPREFIX}   ||= $sprefix;
2023         $self->{VENDORPREFIX} ||= $vprefix;
2024
2025         # Lots of MM extension authors like to use $(PREFIX) so we
2026         # put something sensible in there no matter what.
2027         $self->{PREFIX} = '$('.uc $self->{INSTALLDIRS}.'PREFIX)';
2028     }
2029
2030     my $arch    = $Config{archname};
2031     my $version = $Config{version};
2032
2033     # default style
2034     my $libstyle = $Config{installstyle} || 'lib/perl5';
2035     my $manstyle = '';
2036
2037     if( $self->{LIBSTYLE} ) {
2038         $libstyle = $self->{LIBSTYLE};
2039         $manstyle = $self->{LIBSTYLE} eq 'lib/perl5' ? 'lib/perl5' : '';
2040     }
2041
2042     # Some systems, like VOS, set installman*dir to '' if they can't
2043     # read man pages.
2044     for my $num (1, 3) {
2045         $self->{'INSTALLMAN'.$num.'DIR'} ||= 'none'
2046           unless $Config{'installman'.$num.'dir'};
2047     }
2048
2049     my %bin_layouts =
2050     (
2051         bin         => { s => $iprefix,
2052                          t => 'perl',
2053                          d => 'bin' },
2054         vendorbin   => { s => $vprefix,
2055                          t => 'vendor',
2056                          d => 'bin' },
2057         sitebin     => { s => $sprefix,
2058                          t => 'site',
2059                          d => 'bin' },
2060         script      => { s => $iprefix,
2061                          t => 'perl',
2062                          d => 'bin' },
2063         vendorscript=> { s => $vprefix,
2064                          t => 'vendor',
2065                          d => 'bin' },
2066         sitescript  => { s => $sprefix,
2067                          t => 'site',
2068                          d => 'bin' },
2069     );
2070
2071     my %man_layouts =
2072     (
2073         man1dir         => { s => $iprefix,
2074                              t => 'perl',
2075                              d => 'man/man1',
2076                              style => $manstyle, },
2077         siteman1dir     => { s => $sprefix,
2078                              t => 'site',
2079                              d => 'man/man1',
2080                              style => $manstyle, },
2081         vendorman1dir   => { s => $vprefix,
2082                              t => 'vendor',
2083                              d => 'man/man1',
2084                              style => $manstyle, },
2085
2086         man3dir         => { s => $iprefix,
2087                              t => 'perl',
2088                              d => 'man/man3',
2089                              style => $manstyle, },
2090         siteman3dir     => { s => $sprefix,
2091                              t => 'site',
2092                              d => 'man/man3',
2093                              style => $manstyle, },
2094         vendorman3dir   => { s => $vprefix,
2095                              t => 'vendor',
2096                              d => 'man/man3',
2097                              style => $manstyle, },
2098     );
2099
2100     my %lib_layouts =
2101     (
2102         privlib     => { s => $iprefix,
2103                          t => 'perl',
2104                          d => '',
2105                          style => $libstyle, },
2106         vendorlib   => { s => $vprefix,
2107                          t => 'vendor',
2108                          d => '',
2109                          style => $libstyle, },
2110         sitelib     => { s => $sprefix,
2111                          t => 'site',
2112                          d => 'site_perl',
2113                          style => $libstyle, },
2114
2115         archlib     => { s => $iprefix,
2116                          t => 'perl',
2117                          d => "$version/$arch",
2118                          style => $libstyle },
2119         vendorarch  => { s => $vprefix,
2120                          t => 'vendor',
2121                          d => "$version/$arch",
2122                          style => $libstyle },
2123         sitearch    => { s => $sprefix,
2124                          t => 'site',
2125                          d => "site_perl/$version/$arch",
2126                          style => $libstyle },
2127     );
2128
2129
2130     # Special case for LIB.
2131     if( $self->{LIB} ) {
2132         foreach my $var (keys %lib_layouts) {
2133             my $Installvar = uc "install$var";
2134
2135             if( $var =~ /arch/ ) {
2136                 $self->{$Installvar} ||=
2137                   $self->catdir($self->{LIB}, $Config{archname});
2138             }
2139             else {
2140                 $self->{$Installvar} ||= $self->{LIB};
2141             }
2142         }
2143     }
2144
2145     my %type2prefix = ( perl    => 'PERLPREFIX',
2146                         site    => 'SITEPREFIX',
2147                         vendor  => 'VENDORPREFIX'
2148                       );
2149
2150     my %layouts = (%bin_layouts, %man_layouts, %lib_layouts);
2151     while( my($var, $layout) = each(%layouts) ) {
2152         my($s, $t, $d, $style) = @{$layout}{qw(s t d style)};
2153         my $r = '$('.$type2prefix{$t}.')';
2154
2155         warn "Prefixing $var\n" if $Verbose >= 2;
2156
2157         my $installvar = "install$var";
2158         my $Installvar = uc $installvar;
2159         next if $self->{$Installvar};
2160
2161         $d = "$style/$d" if $style;
2162         $self->prefixify($installvar, $s, $r, $d);
2163
2164         warn "  $Installvar == $self->{$Installvar}\n"
2165           if $Verbose >= 2;
2166     }
2167
2168     # Generate these if they weren't figured out.
2169     $self->{VENDORARCHEXP} ||= $self->{INSTALLVENDORARCH};
2170     $self->{VENDORLIBEXP}  ||= $self->{INSTALLVENDORLIB};
2171
2172     return 1;
2173 }
2174
2175
2176 =head3 init_from_INSTALL_BASE
2177
2178     $mm->init_from_INSTALL_BASE
2179
2180 =cut
2181
2182 my %map = (
2183            lib      => [qw(lib perl5)],
2184            arch     => [('lib', 'perl5', $Config{archname})],
2185            bin      => [qw(bin)],
2186            man1dir  => [qw(man man1)],
2187            man3dir  => [qw(man man3)]
2188           );
2189 $map{script} = $map{bin};
2190
2191 sub init_INSTALL_from_INSTALL_BASE {
2192     my $self = shift;
2193
2194     @{$self}{qw(PREFIX VENDORPREFIX SITEPREFIX PERLPREFIX)} =
2195                                                          '$(INSTALL_BASE)';
2196
2197     my %install;
2198     foreach my $thing (keys %map) {
2199         foreach my $dir (('', 'SITE', 'VENDOR')) {
2200             my $uc_thing = uc $thing;
2201             my $key = "INSTALL".$dir.$uc_thing;
2202
2203             $install{$key} ||=
2204               $self->catdir('$(INSTALL_BASE)', @{$map{$thing}});
2205         }
2206     }
2207
2208     # Adjust for variable quirks.
2209     $install{INSTALLARCHLIB} ||= delete $install{INSTALLARCH};
2210     $install{INSTALLPRIVLIB} ||= delete $install{INSTALLLIB};
2211
2212     foreach my $key (keys %install) {
2213         $self->{$key} ||= $install{$key};
2214     }
2215
2216     return 1;
2217 }
2218
2219
2220 =head3 init_VERSION  I<Abstract>
2221
2222     $mm->init_VERSION
2223
2224 Initialize macros representing versions of MakeMaker and other tools
2225
2226 MAKEMAKER: path to the MakeMaker module.
2227
2228 MM_VERSION: ExtUtils::MakeMaker Version
2229
2230 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
2231              compat)
2232
2233 VERSION: version of your module
2234
2235 VERSION_MACRO: which macro represents the version (usually 'VERSION')
2236
2237 VERSION_SYM: like version but safe for use as an RCS revision number
2238
2239 DEFINE_VERSION: -D line to set the module version when compiling
2240
2241 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
2242
2243 XS_VERSION_MACRO: which macro represents the XS version.
2244
2245 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
2246
2247 Called by init_main.
2248
2249 =cut
2250
2251 sub init_VERSION {
2252     my($self) = shift;
2253
2254     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
2255     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
2256     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
2257     $self->{VERSION_FROM} ||= '';
2258
2259     if ($self->{VERSION_FROM}){
2260         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
2261         if( $self->{VERSION} eq 'undef' ) {
2262             carp("WARNING: Setting VERSION via file ".
2263                  "'$self->{VERSION_FROM}' failed\n");
2264         }
2265     }
2266
2267     if (defined $self->{VERSION}) {
2268         if ( $self->{VERSION} !~ /^\s*v?[\d_\.]+\s*$/ ) {
2269           require version;
2270           my $normal = eval { version->new( $self->{VERSION} ) };
2271           $self->{VERSION} = $normal if defined $normal;
2272         }
2273         $self->{VERSION} =~ s/^\s+//;
2274         $self->{VERSION} =~ s/\s+$//;
2275     }
2276     else {
2277         $self->{VERSION} = '';
2278     }
2279
2280
2281     $self->{VERSION_MACRO}  = 'VERSION';
2282     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
2283     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
2284
2285
2286     # Graham Barr and Paul Marquess had some ideas how to ensure
2287     # version compatibility between the *.pm file and the
2288     # corresponding *.xs file. The bottom line was, that we need an
2289     # XS_VERSION macro that defaults to VERSION:
2290     $self->{XS_VERSION} ||= $self->{VERSION};
2291
2292     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
2293     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
2294
2295 }
2296
2297
2298 =head3 init_tools
2299
2300     $MM->init_tools();
2301
2302 Initializes the simple macro definitions used by tools_other() and
2303 places them in the $MM object.  These use conservative cross platform
2304 versions and should be overridden with platform specific versions for
2305 performance.
2306
2307 Defines at least these macros.
2308
2309   Macro             Description
2310
2311   NOOP              Do nothing
2312   NOECHO            Tell make not to display the command itself
2313
2314   SHELL             Program used to run shell commands
2315
2316   ECHO              Print text adding a newline on the end
2317   RM_F              Remove a file
2318   RM_RF             Remove a directory
2319   TOUCH             Update a file's timestamp
2320   TEST_F            Test for a file's existence
2321   TEST_S            Test the size of a file
2322   CP                Copy a file
2323   CP_NONEMPTY       Copy a file if it is not empty
2324   MV                Move a file
2325   CHMOD             Change permissions on a file
2326   FALSE             Exit with non-zero
2327   TRUE              Exit with zero
2328
2329   UMASK_NULL        Nullify umask
2330   DEV_NULL          Suppress all command output
2331
2332 =cut
2333
2334 sub init_tools {
2335     my $self = shift;
2336
2337     $self->{ECHO}     ||= $self->oneliner('binmode STDOUT, qq{:raw}; print qq{@ARGV}', ['-l']);
2338     $self->{ECHO_N}   ||= $self->oneliner('print qq{@ARGV}');
2339
2340     $self->{TOUCH}    ||= $self->oneliner('touch', ["-MExtUtils::Command"]);
2341     $self->{CHMOD}    ||= $self->oneliner('chmod', ["-MExtUtils::Command"]);
2342     $self->{RM_F}     ||= $self->oneliner('rm_f',  ["-MExtUtils::Command"]);
2343     $self->{RM_RF}    ||= $self->oneliner('rm_rf', ["-MExtUtils::Command"]);
2344     $self->{TEST_F}   ||= $self->oneliner('test_f', ["-MExtUtils::Command"]);
2345     $self->{TEST_S}   ||= $self->oneliner('test_s', ["-MExtUtils::Command::MM"]);
2346     $self->{CP_NONEMPTY} ||= $self->oneliner('cp_nonempty', ["-MExtUtils::Command::MM"]);
2347     $self->{FALSE}    ||= $self->oneliner('exit 1');
2348     $self->{TRUE}     ||= $self->oneliner('exit 0');
2349
2350     $self->{MKPATH}   ||= $self->oneliner('mkpath', ["-MExtUtils::Command"]);
2351
2352     $self->{CP}       ||= $self->oneliner('cp', ["-MExtUtils::Command"]);
2353     $self->{MV}       ||= $self->oneliner('mv', ["-MExtUtils::Command"]);
2354
2355     $self->{MOD_INSTALL} ||=
2356       $self->oneliner(<<'CODE', ['-MExtUtils::Install']);
2357 install([ from_to => {@ARGV}, verbose => '$(VERBINST)', uninstall_shadows => '$(UNINST)', dir_mode => '$(PERM_DIR)' ]);
2358 CODE
2359     $self->{DOC_INSTALL} ||= $self->oneliner('perllocal_install', ["-MExtUtils::Command::MM"]);
2360     $self->{UNINSTALL}   ||= $self->oneliner('uninstall', ["-MExtUtils::Command::MM"]);
2361     $self->{WARN_IF_OLD_PACKLIST} ||=
2362       $self->oneliner('warn_if_old_packlist', ["-MExtUtils::Command::MM"]);
2363     $self->{FIXIN}       ||= $self->oneliner('MY->fixin(shift)', ["-MExtUtils::MY"]);
2364     $self->{EQUALIZE_TIMESTAMP} ||= $self->oneliner('eqtime', ["-MExtUtils::Command"]);
2365
2366     $self->{UNINST}     ||= 0;
2367     $self->{VERBINST}   ||= 0;
2368
2369     $self->{SHELL}              ||= $Config{sh};
2370
2371     # UMASK_NULL is not used by MakeMaker but some CPAN modules
2372     # make use of it.
2373     $self->{UMASK_NULL}         ||= "umask 0";
2374
2375     # Not the greatest default, but its something.
2376     $self->{DEV_NULL}           ||= "> /dev/null 2>&1";
2377
2378     $self->{NOOP}               ||= '$(TRUE)';
2379     $self->{NOECHO}             = '@' unless defined $self->{NOECHO};
2380
2381     $self->{FIRST_MAKEFILE}     ||= $self->{MAKEFILE} || 'Makefile';
2382     $self->{MAKEFILE}           ||= $self->{FIRST_MAKEFILE};
2383     $self->{MAKEFILE_OLD}       ||= $self->{MAKEFILE}.'.old';
2384     $self->{MAKE_APERL_FILE}    ||= $self->{MAKEFILE}.'.aperl';
2385
2386     # Not everybody uses -f to indicate "use this Makefile instead"
2387     $self->{USEMAKEFILE}        ||= '-f';
2388
2389     # Some makes require a wrapper around macros passed in on the command
2390     # line.
2391     $self->{MACROSTART}         ||= '';
2392     $self->{MACROEND}           ||= '';
2393
2394     return;
2395 }
2396
2397
2398 =head3 init_others
2399
2400     $MM->init_others();
2401
2402 Initializes the macro definitions having to do with compiling and
2403 linking used by tools_other() and places them in the $MM object.
2404
2405 If there is no description, its the same as the parameter to
2406 WriteMakefile() documented in ExtUtils::MakeMaker.
2407
2408 =cut
2409
2410 sub init_others {
2411     my $self = shift;
2412
2413     $self->{LD_RUN_PATH} = "";
2414
2415     $self->{LIBS} = $self->_fix_libs($self->{LIBS});
2416
2417     # Compute EXTRALIBS, BSLOADLIBS and LDLOADLIBS from $self->{LIBS}
2418     foreach my $libs ( @{$self->{LIBS}} ){
2419         $libs =~ s/^\s*(.*\S)\s*$/$1/; # remove leading and trailing whitespace
2420         my(@libs) = $self->extliblist($libs);
2421         if ($libs[0] or $libs[1] or $libs[2]){
2422             # LD_RUN_PATH now computed by ExtUtils::Liblist
2423             ($self->{EXTRALIBS},  $self->{BSLOADLIBS},
2424              $self->{LDLOADLIBS}, $self->{LD_RUN_PATH}) = @libs;
2425             last;
2426         }
2427     }
2428
2429     if ( $self->{OBJECT} ) {
2430         $self->{OBJECT} = join(" ", @{$self->{OBJECT}}) if ref $self->{OBJECT};
2431         $self->{OBJECT} =~ s!\.o(bj)?\b!\$(OBJ_EXT)!g;
2432     } elsif ( ($self->{MAGICXS} || $self->{XSMULTI}) && @{$self->{O_FILES}||[]} ) {
2433         $self->{OBJECT} = join(" ", @{$self->{O_FILES}});
2434         $self->{OBJECT} =~ s!\.o(bj)?\b!\$(OBJ_EXT)!g;
2435     } else {
2436         # init_dirscan should have found out, if we have C files
2437         $self->{OBJECT} = "";
2438         $self->{OBJECT} = '$(BASEEXT)$(OBJ_EXT)' if @{$self->{C}||[]};
2439     }
2440     $self->{OBJECT} =~ s/\n+/ \\\n\t/g;
2441
2442     $self->{BOOTDEP}  = (-f "$self->{BASEEXT}_BS") ? "$self->{BASEEXT}_BS" : "";
2443     $self->{PERLMAINCC} ||= '$(CC)';
2444     $self->{LDFROM} = '$(OBJECT)' unless $self->{LDFROM};
2445
2446     # Sanity check: don't define LINKTYPE = dynamic if we're skipping
2447     # the 'dynamic' section of MM.  We don't have this problem with
2448     # 'static', since we either must use it (%Config says we can't
2449     # use dynamic loading) or the caller asked for it explicitly.
2450     if (!$self->{LINKTYPE}) {
2451        $self->{LINKTYPE} = $self->{SKIPHASH}{'dynamic'}
2452                         ? 'static'
2453                         : ($Config{usedl} ? 'dynamic' : 'static');
2454     }
2455
2456     return;
2457 }
2458
2459
2460 # Lets look at $self->{LIBS} carefully: It may be an anon array, a string or
2461 # undefined. In any case we turn it into an anon array
2462 sub _fix_libs {
2463     my($self, $libs) = @_;
2464
2465     return !defined $libs       ? ['']          :
2466            !ref $libs           ? [$libs]       :
2467            !defined $libs->[0]  ? ['']          :
2468                                   $libs         ;
2469 }
2470
2471
2472 =head3 tools_other
2473
2474     my $make_frag = $MM->tools_other;
2475
2476 Returns a make fragment containing definitions for the macros init_others()
2477 initializes.
2478
2479 =cut
2480
2481 sub tools_other {
2482     my($self) = shift;
2483     my @m;
2484
2485     # We set PM_FILTER as late as possible so it can see all the earlier
2486     # on macro-order sensitive makes such as nmake.
2487     for my $tool (qw{ SHELL CHMOD CP MV NOOP NOECHO RM_F RM_RF TEST_F TOUCH
2488                       UMASK_NULL DEV_NULL MKPATH EQUALIZE_TIMESTAMP
2489                       FALSE TRUE
2490                       ECHO ECHO_N
2491                       UNINST VERBINST
2492                       MOD_INSTALL DOC_INSTALL UNINSTALL
2493                       WARN_IF_OLD_PACKLIST
2494                       MACROSTART MACROEND
2495                       USEMAKEFILE
2496                       PM_FILTER
2497                       FIXIN
2498                       CP_NONEMPTY
2499                     } )
2500     {
2501         next unless defined $self->{$tool};
2502         push @m, "$tool = $self->{$tool}\n";
2503     }
2504
2505     return join "", @m;
2506 }
2507
2508
2509 =head3 init_DIRFILESEP  I<Abstract>
2510
2511   $MM->init_DIRFILESEP;
2512   my $dirfilesep = $MM->{DIRFILESEP};
2513
2514 Initializes the DIRFILESEP macro which is the separator between the
2515 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
2516 nothing on VMS.
2517
2518 For example:
2519
2520     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
2521     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
2522
2523 Something of a hack but it prevents a lot of code duplication between
2524 MM_* variants.
2525
2526 Do not use this as a separator between directories.  Some operating
2527 systems use different separators between subdirectories as between
2528 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
2529
2530 =head3 init_linker  I<Abstract>
2531
2532     $mm->init_linker;
2533
2534 Initialize macros which have to do with linking.
2535
2536 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
2537 extensions.
2538
2539 PERL_ARCHIVE_AFTER: path to a library which should be put on the
2540 linker command line I<after> the external libraries to be linked to
2541 dynamic extensions.  This may be needed if the linker is one-pass, and
2542 Perl includes some overrides for C RTL functions, such as malloc().
2543
2544 EXPORT_LIST: name of a file that is passed to linker to define symbols
2545 to be exported.
2546
2547 Some OSes do not need these in which case leave it blank.
2548
2549
2550 =head3 init_platform
2551
2552     $mm->init_platform
2553
2554 Initialize any macros which are for platform specific use only.
2555
2556 A typical one is the version number of your OS specific module.
2557 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
2558
2559 =cut
2560
2561 sub init_platform {
2562     return '';
2563 }
2564
2565
2566 =head3 init_MAKE
2567
2568     $mm->init_MAKE
2569
2570 Initialize MAKE from either a MAKE environment variable or $Config{make}.
2571
2572 =cut
2573
2574 sub init_MAKE {
2575     my $self = shift;
2576
2577     $self->{MAKE} ||= $ENV{MAKE} || $Config{make};
2578 }
2579
2580
2581 =head2 Tools
2582
2583 A grab bag of methods to generate specific macros and commands.
2584
2585
2586
2587 =head3 manifypods
2588
2589 Defines targets and routines to translate the pods into manpages and
2590 put them into the INST_* directories.
2591
2592 =cut
2593
2594 sub manifypods {
2595     my $self          = shift;
2596
2597     my $POD2MAN_macro = $self->POD2MAN_macro();
2598     my $manifypods_target = $self->manifypods_target();
2599
2600     return <<END_OF_TARGET;
2601
2602 $POD2MAN_macro
2603
2604 $manifypods_target
2605
2606 END_OF_TARGET
2607
2608 }
2609
2610
2611 =head3 POD2MAN_macro
2612
2613   my $pod2man_macro = $self->POD2MAN_macro
2614
2615 Returns a definition for the POD2MAN macro.  This is a program
2616 which emulates the pod2man utility.  You can add more switches to the
2617 command by simply appending them on the macro.
2618
2619 Typical usage:
2620
2621     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
2622
2623 =cut
2624
2625 sub POD2MAN_macro {
2626     my $self = shift;
2627
2628 # Need the trailing '--' so perl stops gobbling arguments and - happens
2629 # to be an alternative end of line separator on VMS so we quote it
2630     return <<'END_OF_DEF';
2631 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
2632 POD2MAN = $(POD2MAN_EXE)
2633 END_OF_DEF
2634 }
2635
2636
2637 =head3 test_via_harness
2638
2639   my $command = $mm->test_via_harness($perl, $tests);
2640
2641 Returns a $command line which runs the given set of $tests with
2642 Test::Harness and the given $perl.
2643
2644 Used on the t/*.t files.
2645
2646 =cut
2647
2648 sub test_via_harness {
2649     my($self, $perl, $tests) = @_;
2650
2651     return qq{\t$perl "-MExtUtils::Command::MM" "-MTest::Harness" }.
2652            qq{"-e" "undef *Test::Harness::Switches; test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
2653 }
2654
2655 =head3 test_via_script
2656
2657   my $command = $mm->test_via_script($perl, $script);
2658
2659 Returns a $command line which just runs a single test without
2660 Test::Harness.  No checks are done on the results, they're just
2661 printed.
2662
2663 Used for test.pl, since they don't always follow Test::Harness
2664 formatting.
2665
2666 =cut
2667
2668 sub test_via_script {
2669     my($self, $perl, $script) = @_;
2670     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
2671 }
2672
2673
2674 =head3 tool_autosplit
2675
2676 Defines a simple perl call that runs autosplit. May be deprecated by
2677 pm_to_blib soon.
2678
2679 =cut
2680
2681 sub tool_autosplit {
2682     my($self, %attribs) = @_;
2683
2684     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
2685                                   : '';
2686
2687     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
2688 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
2689 PERL_CODE
2690
2691     return sprintf <<'MAKE_FRAG', $asplit;
2692 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
2693 AUTOSPLITFILE = %s
2694
2695 MAKE_FRAG
2696
2697 }
2698
2699
2700 =head3 arch_check
2701
2702     my $arch_ok = $mm->arch_check(
2703         $INC{"Config.pm"},
2704         File::Spec->catfile($Config{archlibexp}, "Config.pm")
2705     );
2706
2707 A sanity check that what Perl thinks the architecture is and what
2708 Config thinks the architecture is are the same.  If they're not it
2709 will return false and show a diagnostic message.
2710
2711 When building Perl it will always return true, as nothing is installed
2712 yet.
2713
2714 The interface is a bit odd because this is the result of a
2715 quick refactoring.  Don't rely on it.
2716
2717 =cut
2718
2719 sub arch_check {
2720     my $self = shift;
2721     my($pconfig, $cconfig) = @_;
2722
2723     return 1 if $self->{PERL_SRC};
2724
2725     my($pvol, $pthinks) = $self->splitpath($pconfig);
2726     my($cvol, $cthinks) = $self->splitpath($cconfig);
2727
2728     $pthinks = $self->canonpath($pthinks);
2729     $cthinks = $self->canonpath($cthinks);
2730
2731     my $ret = 1;
2732     if ($pthinks ne $cthinks) {
2733         print "Have $pthinks\n";
2734         print "Want $cthinks\n";
2735
2736         $ret = 0;
2737
2738         my $arch = (grep length, $self->splitdir($pthinks))[-1];
2739
2740         print <<END unless $self->{UNINSTALLED_PERL};
2741 Your perl and your Config.pm seem to have different ideas about the
2742 architecture they are running on.
2743 Perl thinks: [$arch]
2744 Config says: [$Config{archname}]
2745 This may or may not cause problems. Please check your installation of perl
2746 if you have problems building this extension.
2747 END
2748     }
2749
2750     return $ret;
2751 }
2752
2753
2754
2755 =head2 File::Spec wrappers
2756
2757 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
2758 override File::Spec.
2759
2760
2761
2762 =head3 catfile
2763
2764 File::Spec <= 0.83 has a bug where the file part of catfile is not
2765 canonicalized.  This override fixes that bug.
2766
2767 =cut
2768
2769 sub catfile {
2770     my $self = shift;
2771     return $self->canonpath($self->SUPER::catfile(@_));
2772 }
2773
2774
2775
2776 =head2 Misc
2777
2778 Methods I can't really figure out where they should go yet.
2779
2780
2781 =head3 find_tests
2782
2783   my $test = $mm->find_tests;
2784
2785 Returns a string suitable for feeding to the shell to return all
2786 tests in t/*.t.
2787
2788 =cut
2789
2790 sub find_tests {
2791     my($self) = shift;
2792     return -d 't' ? 't/*.t' : '';
2793 }
2794
2795 =head3 find_tests_recursive
2796
2797   my $tests = $mm->find_tests_recursive;
2798
2799 Returns a string suitable for feeding to the shell to return all
2800 tests in t/ but recursively. Equivalent to
2801
2802   my $tests = $mm->find_tests_recursive_in('t');
2803
2804 =cut
2805
2806 sub find_tests_recursive {
2807     my $self = shift;
2808     return $self->find_tests_recursive_in('t');
2809 }
2810
2811 =head3 find_tests_recursive_in
2812
2813   my $tests = $mm->find_tests_recursive_in($dir);
2814
2815 Returns a string suitable for feeding to the shell to return all
2816 tests in $dir recursively.
2817
2818 =cut
2819
2820 sub find_tests_recursive_in {
2821     my($self, $dir) = @_;
2822     return '' unless -d $dir;
2823
2824     require File::Find;
2825
2826     my $base_depth = grep { $_ ne '' } File::Spec->splitdir( (File::Spec->splitpath($dir))[1] );
2827     my %depths;
2828
2829     my $wanted = sub {
2830         return unless m!\.t$!;
2831         my ($volume,$directories,$file) =
2832             File::Spec->splitpath( $File::Find::name  );
2833         my $depth = grep { $_ ne '' } File::Spec->splitdir( $directories );
2834         $depth -= $base_depth;
2835         $depths{ $depth } = 1;
2836     };
2837
2838     File::Find::find( $wanted, $dir );
2839
2840     return join ' ',
2841         map { $dir . '/*' x $_ . '.t' }
2842         sort { $a <=> $b }
2843         keys %depths;
2844 }
2845
2846 =head3 extra_clean_files
2847
2848     my @files_to_clean = $MM->extra_clean_files;
2849
2850 Returns a list of OS specific files to be removed in the clean target in
2851 addition to the usual set.
2852
2853 =cut
2854
2855 # An empty method here tickled a perl 5.8.1 bug and would return its object.
2856 sub extra_clean_files {
2857     return;
2858 }
2859
2860
2861 =head3 installvars
2862
2863     my @installvars = $mm->installvars;
2864
2865 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
2866 for iteration or building related variable sets.
2867
2868 =cut
2869
2870 sub installvars {
2871     return qw(PRIVLIB SITELIB  VENDORLIB
2872               ARCHLIB SITEARCH VENDORARCH
2873               BIN     SITEBIN  VENDORBIN
2874               SCRIPT  SITESCRIPT  VENDORSCRIPT
2875               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
2876               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
2877              );
2878 }
2879
2880
2881 =head3 libscan
2882
2883   my $wanted = $self->libscan($path);
2884
2885 Takes a path to a file or dir and returns an empty string if we don't
2886 want to include this file in the library.  Otherwise it returns the
2887 the $path unchanged.
2888
2889 Mainly used to exclude version control administrative directories from
2890 installation.
2891
2892 =cut
2893
2894 sub libscan {
2895     my($self,$path) = @_;
2896     my($dirs,$file) = ($self->splitpath($path))[1,2];
2897     return '' if grep /^(?:RCS|CVS|SCCS|\.svn|_darcs)$/,
2898                      $self->splitdir($dirs), $file;
2899
2900     return $path;
2901 }
2902
2903
2904 =head3 platform_constants
2905
2906     my $make_frag = $mm->platform_constants
2907
2908 Returns a make fragment defining all the macros initialized in
2909 init_platform() rather than put them in constants().
2910
2911 =cut
2912
2913 sub platform_constants {
2914     return '';
2915 }
2916
2917 =head3 post_constants (o)
2918
2919 Returns an empty string per default. Dedicated to overrides from
2920 within Makefile.PL after all constants have been defined.
2921
2922 =cut
2923
2924 sub post_constants {
2925     "";
2926 }
2927
2928 =head3 post_initialize (o)
2929
2930 Returns an empty string per default. Used in Makefile.PLs to add some
2931 chunk of text to the Makefile after the object is initialized.
2932
2933 =cut
2934
2935 sub post_initialize {
2936     "";
2937 }
2938
2939 =head3 postamble (o)
2940
2941 Returns an empty string. Can be used in Makefile.PLs to write some
2942 text to the Makefile at the end.
2943
2944 =cut
2945
2946 sub postamble {
2947     "";
2948 }
2949
2950 =begin private
2951
2952 =head3 _PREREQ_PRINT
2953
2954     $self->_PREREQ_PRINT;
2955
2956 Implements PREREQ_PRINT.
2957
2958 Refactored out of MakeMaker->new().
2959
2960 =end private
2961
2962 =cut
2963
2964 sub _PREREQ_PRINT {
2965     my $self = shift;
2966
2967     require Data::Dumper;
2968     my @what = ('PREREQ_PM');
2969     push @what, 'MIN_PERL_VERSION' if $self->{MIN_PERL_VERSION};
2970     push @what, 'BUILD_REQUIRES'   if $self->{BUILD_REQUIRES};
2971     print Data::Dumper->Dump([@{$self}{@what}], \@what);
2972     exit 0;
2973 }
2974
2975
2976 =begin private
2977
2978 =head3 _PRINT_PREREQ
2979
2980   $mm->_PRINT_PREREQ;
2981
2982 Implements PRINT_PREREQ, a slightly different version of PREREQ_PRINT
2983 added by Redhat to, I think, support generating RPMs from Perl modules.
2984
2985 Should not include BUILD_REQUIRES as RPMs do not include them.
2986
2987 Refactored out of MakeMaker->new().
2988
2989 =end private
2990
2991 =cut
2992
2993 sub _PRINT_PREREQ {
2994     my $self = shift;
2995
2996     my $prereqs= $self->{PREREQ_PM};
2997     my @prereq = map { [$_, $prereqs->{$_}] } keys %$prereqs;
2998
2999     if ( $self->{MIN_PERL_VERSION} ) {
3000         push @prereq, ['perl' => $self->{MIN_PERL_VERSION}];
3001     }
3002
3003     print join(" ", map { "perl($_->[0])>=$_->[1] " }
3004                  sort { $a->[0] cmp $b->[0] } @prereq), "\n";
3005     exit 0;
3006 }
3007
3008
3009 =begin private
3010
3011 =head3 _perl_header_files
3012
3013   my $perl_header_files= $self->_perl_header_files;
3014
3015 returns a sorted list of header files as found in PERL_SRC or $archlibexp/CORE.
3016
3017 Used by perldepend() in MM_Unix and MM_VMS via _perl_header_files_fragment()
3018
3019 =end private
3020
3021 =cut
3022
3023 sub _perl_header_files {
3024     my $self = shift;
3025
3026     my $header_dir = $self->{PERL_SRC} || $ENV{PERL_SRC} || $self->catdir($Config{archlibexp}, 'CORE');
3027     opendir my $dh, $header_dir
3028         or die "Failed to opendir '$header_dir' to find header files: $!";
3029
3030     # we need to use a temporary here as the sort in scalar context would have undefined results.
3031     my @perl_headers= sort grep { /\.h\z/ } readdir($dh);
3032
3033     closedir $dh;
3034
3035     return @perl_headers;
3036 }
3037
3038 =begin private
3039
3040 =head3 _perl_header_files_fragment ($o, $separator)
3041
3042   my $perl_header_files_fragment= $self->_perl_header_files_fragment("/");
3043
3044 return a Makefile fragment which holds the list of perl header files which
3045 XS code depends on $(PERL_INC), and sets up the dependency for the $(OBJECT) file.
3046
3047 The $separator argument defaults to "". MM_VMS will set it to "" and MM_UNIX to "/"
3048 in perldepend(). This reason child subclasses need to control this is that in
3049 VMS the $(PERL_INC) directory will already have delimiters in it, but in
3050 UNIX $(PERL_INC) will need a slash between it an the filename. Hypothetically
3051 win32 could use "\\" (but it doesn't need to).
3052
3053 =end private
3054
3055 =cut
3056
3057 sub _perl_header_files_fragment {
3058     my ($self, $separator)= @_;
3059     $separator ||= "";
3060     return join("\\\n",
3061                 "PERL_HDRS = ",
3062                 map {
3063                     sprintf( "        \$(PERL_INCDEP)%s%s            ", $separator, $_ )
3064                 } $self->_perl_header_files()
3065            ) . "\n\n"
3066            . "\$(OBJECT) : \$(PERL_HDRS)\n";
3067 }
3068
3069
3070 =head1 AUTHOR
3071
3072 Michael G Schwern <schwern@pobox.com> and the denizens of
3073 makemaker@perl.org with code from ExtUtils::MM_Unix and
3074 ExtUtils::MM_Win32.
3075
3076
3077 =cut
3078
3079 1;