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