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