This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to ExtUtils-MakeMaker-6.47_01
[perl5.git] / lib / ExtUtils / MM_Any.pm
1 package ExtUtils::MM_Any;
2
3 use strict;
4 our $VERSION = '6.47_01';
5
6 use Carp;
7 use File::Spec;
8 BEGIN { our @ISA = qw(File::Spec); }
9
10 # We need $Verbose
11 use ExtUtils::MakeMaker qw($Verbose);
12
13 use ExtUtils::MakeMaker::Config;
14
15
16 # So we don't have to keep calling the methods over and over again,
17 # we have these globals to cache the values.  Faster and shrtr.
18 my $Curdir  = __PACKAGE__->curdir;
19 my $Rootdir = __PACKAGE__->rootdir;
20 my $Updir   = __PACKAGE__->updir;
21
22
23 =head1 NAME
24
25 ExtUtils::MM_Any - Platform-agnostic MM methods
26
27 =head1 SYNOPSIS
28
29   FOR INTERNAL USE ONLY!
30
31   package ExtUtils::MM_SomeOS;
32
33   # Temporarily, you have to subclass both.  Put MM_Any first.
34   require ExtUtils::MM_Any;
35   require ExtUtils::MM_Unix;
36   @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
37
38 =head1 DESCRIPTION
39
40 B<FOR INTERNAL USE ONLY!>
41
42 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
43 modules.  It contains methods which are either inherently
44 cross-platform or are written in a cross-platform manner.
45
46 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix.  This is a
47 temporary solution.
48
49 B<THIS MAY BE TEMPORARY!>
50
51
52 =head1 METHODS
53
54 Any methods marked I<Abstract> must be implemented by subclasses.
55
56
57 =head2 Cross-platform helper methods
58
59 These are methods which help writing cross-platform code.
60
61
62
63 =head3 os_flavor  I<Abstract>
64
65     my @os_flavor = $mm->os_flavor;
66
67 @os_flavor is the style of operating system this is, usually
68 corresponding to the MM_*.pm file we're using.  
69
70 The first element of @os_flavor is the major family (ie. Unix,
71 Windows, VMS, OS/2, etc...) and the rest are sub families.
72
73 Some examples:
74
75     Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
76     Windows NT     ('Win32', 'WinNT')
77     Win98          ('Win32', 'Win9x')
78     Linux          ('Unix',  'Linux')
79     MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
80     OS/2           ('OS/2')
81
82 This is used to write code for styles of operating system.  
83 See os_flavor_is() for use.
84
85
86 =head3 os_flavor_is
87
88     my $is_this_flavor = $mm->os_flavor_is($this_flavor);
89     my $is_this_flavor = $mm->os_flavor_is(@one_of_these_flavors);
90
91 Checks to see if the current operating system is one of the given flavors.
92
93 This is useful for code like:
94
95     if( $mm->os_flavor_is('Unix') ) {
96         $out = `foo 2>&1`;
97     }
98     else {
99         $out = `foo`;
100     }
101
102 =cut
103
104 sub os_flavor_is {
105     my $self = shift;
106     my %flavors = map { ($_ => 1) } $self->os_flavor;
107     return (grep { $flavors{$_} } @_) ? 1 : 0;
108 }
109
110
111 =head3 split_command
112
113     my @cmds = $MM->split_command($cmd, @args);
114
115 Most OS have a maximum command length they can execute at once.  Large
116 modules can easily generate commands well past that limit.  Its
117 necessary to split long commands up into a series of shorter commands.
118
119 C<split_command> will return a series of @cmds each processing part of
120 the args.  Collectively they will process all the arguments.  Each
121 individual line in @cmds will not be longer than the
122 $self->max_exec_len being careful to take into account macro expansion.
123
124 $cmd should include any switches and repeated initial arguments.
125
126 If no @args are given, no @cmds will be returned.
127
128 Pairs of arguments will always be preserved in a single command, this
129 is a heuristic for things like pm_to_blib and pod2man which work on
130 pairs of arguments.  This makes things like this safe:
131
132     $self->split_command($cmd, %pod2man);
133
134
135 =cut
136
137 sub split_command {
138     my($self, $cmd, @args) = @_;
139
140     my @cmds = ();
141     return(@cmds) unless @args;
142
143     # If the command was given as a here-doc, there's probably a trailing
144     # newline.
145     chomp $cmd;
146
147     # set aside 30% for macro expansion.
148     my $len_left = int($self->max_exec_len * 0.70);
149     $len_left -= length $self->_expand_macros($cmd);
150
151     do {
152         my $arg_str = '';
153         my @next_args;
154         while( @next_args = splice(@args, 0, 2) ) {
155             # Two at a time to preserve pairs.
156             my $next_arg_str = "\t  ". join ' ', @next_args, "\n";
157
158             if( !length $arg_str ) {
159                 $arg_str .= $next_arg_str
160             }
161             elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
162                 unshift @args, @next_args;
163                 last;
164             }
165             else {
166                 $arg_str .= $next_arg_str;
167             }
168         }
169         chop $arg_str;
170
171         push @cmds, $self->escape_newlines("$cmd \n$arg_str");
172     } while @args;
173
174     return @cmds;
175 }
176
177
178 sub _expand_macros {
179     my($self, $cmd) = @_;
180
181     $cmd =~ s{\$\((\w+)\)}{
182         defined $self->{$1} ? $self->{$1} : "\$($1)"
183     }e;
184     return $cmd;
185 }
186
187
188 =head3 echo
189
190     my @commands = $MM->echo($text);
191     my @commands = $MM->echo($text, $file);
192     my @commands = $MM->echo($text, $file, $appending);
193
194 Generates a set of @commands which print the $text to a $file.
195
196 If $file is not given, output goes to STDOUT.
197
198 If $appending is true the $file will be appended to rather than
199 overwritten.
200
201 =cut
202
203 sub echo {
204     my($self, $text, $file, $appending) = @_;
205     $appending ||= 0;
206
207     my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) } 
208                split /\n/, $text;
209     if( $file ) {
210         my $redirect = $appending ? '>>' : '>';
211         $cmds[0] .= " $redirect $file";
212         $_ .= " >> $file" foreach @cmds[1..$#cmds];
213     }
214
215     return @cmds;
216 }
217
218
219 =head3 wraplist
220
221   my $args = $mm->wraplist(@list);
222
223 Takes an array of items and turns them into a well-formatted list of
224 arguments.  In most cases this is simply something like:
225
226     FOO \
227     BAR \
228     BAZ
229
230 =cut
231
232 sub wraplist {
233     my $self = shift;
234     return join " \\\n\t", @_;
235 }
236
237
238 =head3 maketext_filter
239
240     my $filter_make_text = $mm->maketext_filter($make_text);
241
242 The text of the Makefile is run through this method before writing to
243 disk.  It allows systems a chance to make portability fixes to the
244 Makefile.
245
246 By default it does nothing.
247
248 This method is protected and not intended to be called outside of
249 MakeMaker.
250
251 =cut
252
253 sub maketext_filter { return $_[1] }
254
255
256 =head3 cd  I<Abstract>
257
258   my $subdir_cmd = $MM->cd($subdir, @cmds);
259
260 This will generate a make fragment which runs the @cmds in the given
261 $dir.  The rough equivalent to this, except cross platform.
262
263   cd $subdir && $cmd
264
265 Currently $dir can only go down one level.  "foo" is fine.  "foo/bar" is
266 not.  "../foo" is right out.
267
268 The resulting $subdir_cmd has no leading tab nor trailing newline.  This
269 makes it easier to embed in a make string.  For example.
270
271       my $make = sprintf <<'CODE', $subdir_cmd;
272   foo :
273       $(ECHO) what
274       %s
275       $(ECHO) mouche
276   CODE
277
278
279 =head3 oneliner  I<Abstract>
280
281   my $oneliner = $MM->oneliner($perl_code);
282   my $oneliner = $MM->oneliner($perl_code, \@switches);
283
284 This will generate a perl one-liner safe for the particular platform
285 you're on based on the given $perl_code and @switches (a -e is
286 assumed) suitable for using in a make target.  It will use the proper
287 shell quoting and escapes.
288
289 $(PERLRUN) will be used as perl.
290
291 Any newlines in $perl_code will be escaped.  Leading and trailing
292 newlines will be stripped.  Makes this idiom much easier:
293
294     my $code = $MM->oneliner(<<'CODE', [...switches...]);
295 some code here
296 another line here
297 CODE
298
299 Usage might be something like:
300
301     # an echo emulation
302     $oneliner = $MM->oneliner('print "Foo\n"');
303     $make = '$oneliner > somefile';
304
305 All dollar signs must be doubled in the $perl_code if you expect them
306 to be interpreted normally, otherwise it will be considered a make
307 macro.  Also remember to quote make macros else it might be used as a
308 bareword.  For example:
309
310     # Assign the value of the $(VERSION_FROM) make macro to $vf.
311     $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
312
313 Its currently very simple and may be expanded sometime in the figure
314 to include more flexible code and switches.
315
316
317 =head3 quote_literal  I<Abstract>
318
319     my $safe_text = $MM->quote_literal($text);
320
321 This will quote $text so it is interpreted literally in the shell.
322
323 For example, on Unix this would escape any single-quotes in $text and
324 put single-quotes around the whole thing.
325
326
327 =head3 escape_newlines  I<Abstract>
328
329     my $escaped_text = $MM->escape_newlines($text);
330
331 Shell escapes newlines in $text.
332
333
334 =head3 max_exec_len  I<Abstract>
335
336     my $max_exec_len = $MM->max_exec_len;
337
338 Calculates the maximum command size the OS can exec.  Effectively,
339 this is the max size of a shell command line.
340
341 =for _private
342 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
343
344
345 =head3 make
346
347     my $make = $MM->make;
348
349 Returns the make variant we're generating the Makefile for.  This attempts
350 to do some normalization on the information from %Config or the user.
351
352 =cut
353
354 sub make {
355     my $self = shift;
356
357     my $make = lc $self->{MAKE};
358
359     # Truncate anything like foomake6 to just foomake.
360     $make =~ s/^(\w+make).*/$1/;
361
362     # Turn gnumake into gmake.
363     $make =~ s/^gnu/g/;
364
365     return $make;
366 }
367
368
369 =head2 Targets
370
371 These are methods which produce make targets.
372
373
374 =head3 all_target
375
376 Generate the default target 'all'.
377
378 =cut
379
380 sub all_target {
381     my $self = shift;
382
383     return <<'MAKE_EXT';
384 all :: pure_all
385         $(NOECHO) $(NOOP)
386 MAKE_EXT
387
388 }
389
390
391 =head3 blibdirs_target
392
393     my $make_frag = $mm->blibdirs_target;
394
395 Creates the blibdirs target which creates all the directories we use
396 in blib/.
397
398 The blibdirs.ts target is deprecated.  Depend on blibdirs instead.
399
400
401 =cut
402
403 sub blibdirs_target {
404     my $self = shift;
405
406     my @dirs = map { uc "\$(INST_$_)" } qw(libdir archlib
407                                            autodir archautodir
408                                            bin script
409                                            man1dir man3dir
410                                           );
411
412     my @exists = map { $_.'$(DFSEP).exists' } @dirs;
413
414     my $make = sprintf <<'MAKE', join(' ', @exists);
415 blibdirs : %s
416         $(NOECHO) $(NOOP)
417
418 # Backwards compat with 6.18 through 6.25
419 blibdirs.ts : blibdirs
420         $(NOECHO) $(NOOP)
421
422 MAKE
423
424     $make .= $self->dir_target(@dirs);
425
426     return $make;
427 }
428
429
430 =head3 clean (o)
431
432 Defines the clean target.
433
434 =cut
435
436 sub clean {
437 # --- Cleanup and Distribution Sections ---
438
439     my($self, %attribs) = @_;
440     my @m;
441     push(@m, '
442 # Delete temporary files but do not touch installed files. We don\'t delete
443 # the Makefile here so a later make realclean still has a makefile to use.
444
445 clean :: clean_subdirs
446 ');
447
448     my @files = values %{$self->{XS}}; # .c files from *.xs files
449     my @dirs  = qw(blib);
450
451     # Normally these are all under blib but they might have been
452     # redefined.
453     # XXX normally this would be a good idea, but the Perl core sets
454     # INST_LIB = ../../lib rather than actually installing the files.
455     # So a "make clean" in an ext/ directory would blow away lib.
456     # Until the core is adjusted let's leave this out.
457 #     push @dirs, qw($(INST_ARCHLIB) $(INST_LIB)
458 #                    $(INST_BIN) $(INST_SCRIPT)
459 #                    $(INST_MAN1DIR) $(INST_MAN3DIR)
460 #                    $(INST_LIBDIR) $(INST_ARCHLIBDIR) $(INST_AUTODIR) 
461 #                    $(INST_STATIC) $(INST_DYNAMIC) $(INST_BOOT)
462 #                 );
463                   
464
465     if( $attribs{FILES} ) {
466         # Use @dirs because we don't know what's in here.
467         push @dirs, ref $attribs{FILES}                ?
468                         @{$attribs{FILES}}             :
469                         split /\s+/, $attribs{FILES}   ;
470     }
471
472     push(@files, qw[$(MAKE_APERL_FILE) 
473                     perlmain.c tmon.out mon.out so_locations 
474                     blibdirs.ts pm_to_blib pm_to_blib.ts
475                     *$(OBJ_EXT) *$(LIB_EXT) perl.exe perl perl$(EXE_EXT)
476                     $(BOOTSTRAP) $(BASEEXT).bso
477                     $(BASEEXT).def lib$(BASEEXT).def
478                     $(BASEEXT).exp $(BASEEXT).x
479                    ]);
480
481     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.all'));
482     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.ld'));
483
484     # core files
485     push(@files, qw[core core.*perl.*.? *perl.core]);
486     push(@files, map { "core." . "[0-9]"x$_ } (1..5));
487
488     # OS specific things to clean up.  Use @dirs since we don't know
489     # what might be in here.
490     push @dirs, $self->extra_clean_files;
491
492     # Occasionally files are repeated several times from different sources
493     { my(%f) = map { ($_ => 1) } @files; @files = keys %f; }
494     { my(%d) = map { ($_ => 1) } @dirs;  @dirs  = keys %d; }
495
496     push @m, map "\t$_\n", $self->split_command('- $(RM_F)',  @files);
497     push @m, map "\t$_\n", $self->split_command('- $(RM_RF)', @dirs);
498
499     # Leave Makefile.old around for realclean
500     push @m, <<'MAKE';
501         - $(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD) $(DEV_NULL)
502 MAKE
503
504     push(@m, "\t$attribs{POSTOP}\n")   if $attribs{POSTOP};
505
506     join("", @m);
507 }
508
509
510 =head3 clean_subdirs_target
511
512   my $make_frag = $MM->clean_subdirs_target;
513
514 Returns the clean_subdirs target.  This is used by the clean target to
515 call clean on any subdirectories which contain Makefiles.
516
517 =cut
518
519 sub clean_subdirs_target {
520     my($self) = shift;
521
522     # No subdirectories, no cleaning.
523     return <<'NOOP_FRAG' unless @{$self->{DIR}};
524 clean_subdirs :
525         $(NOECHO) $(NOOP)
526 NOOP_FRAG
527
528
529     my $clean = "clean_subdirs :\n";
530
531     for my $dir (@{$self->{DIR}}) {
532         my $subclean = $self->oneliner(sprintf <<'CODE', $dir);
533 chdir '%s';  system '$(MAKE) clean' if -f '$(FIRST_MAKEFILE)';
534 CODE
535
536         $clean .= "\t$subclean\n";
537     }
538
539     return $clean;
540 }
541
542
543 =head3 dir_target
544
545     my $make_frag = $mm->dir_target(@directories);
546
547 Generates targets to create the specified directories and set its
548 permission to 0755.
549
550 Because depending on a directory to just ensure it exists doesn't work
551 too well (the modified time changes too often) dir_target() creates a
552 .exists file in the created directory.  It is this you should depend on.
553 For portability purposes you should use the $(DIRFILESEP) macro rather
554 than a '/' to seperate the directory from the file.
555
556     yourdirectory$(DIRFILESEP).exists
557
558 =cut
559
560 sub dir_target {
561     my($self, @dirs) = @_;
562
563     my $make = '';
564     foreach my $dir (@dirs) {
565         $make .= sprintf <<'MAKE', ($dir) x 7;
566 %s$(DFSEP).exists :: Makefile.PL
567         $(NOECHO) $(MKPATH) %s
568         $(NOECHO) $(CHMOD) 755 %s
569         $(NOECHO) $(TOUCH) %s$(DFSEP).exists
570
571 MAKE
572
573     }
574
575     return $make;
576 }
577
578
579 =head3 distdir
580
581 Defines the scratch directory target that will hold the distribution
582 before tar-ing (or shar-ing).
583
584 =cut
585
586 # For backwards compatibility.
587 *dist_dir = *distdir;
588
589 sub distdir {
590     my($self) = shift;
591
592     my $meta_target = $self->{NO_META} ? '' : 'distmeta';
593     my $sign_target = !$self->{SIGN}   ? '' : 'distsignature';
594
595     return sprintf <<'MAKE_FRAG', $meta_target, $sign_target;
596 create_distdir :
597         $(RM_RF) $(DISTVNAME)
598         $(PERLRUN) "-MExtUtils::Manifest=manicopy,maniread" \
599                 -e "manicopy(maniread(),'$(DISTVNAME)', '$(DIST_CP)');"
600
601 distdir : create_distdir %s %s
602         $(NOECHO) $(NOOP)
603
604 MAKE_FRAG
605
606 }
607
608
609 =head3 dist_test
610
611 Defines a target that produces the distribution in the
612 scratchdirectory, and runs 'perl Makefile.PL; make ;make test' in that
613 subdirectory.
614
615 =cut
616
617 sub dist_test {
618     my($self) = shift;
619
620     my $mpl_args = join " ", map qq["$_"], @ARGV;
621
622     my $test = $self->cd('$(DISTVNAME)',
623                          '$(ABSPERLRUN) Makefile.PL '.$mpl_args,
624                          '$(MAKE) $(PASTHRU)',
625                          '$(MAKE) test $(PASTHRU)'
626                         );
627
628     return sprintf <<'MAKE_FRAG', $test;
629 disttest : distdir
630         %s
631
632 MAKE_FRAG
633
634
635 }
636
637
638 =head3 dynamic (o)
639
640 Defines the dynamic target.
641
642 =cut
643
644 sub dynamic {
645 # --- Dynamic Loading Sections ---
646
647     my($self) = shift;
648     '
649 dynamic :: $(FIRST_MAKEFILE) $(INST_DYNAMIC) $(INST_BOOT)
650         $(NOECHO) $(NOOP)
651 ';
652 }
653
654
655 =head3 makemakerdflt_target
656
657   my $make_frag = $mm->makemakerdflt_target
658
659 Returns a make fragment with the makemakerdeflt_target specified.
660 This target is the first target in the Makefile, is the default target
661 and simply points off to 'all' just in case any make variant gets
662 confused or something gets snuck in before the real 'all' target.
663
664 =cut
665
666 sub makemakerdflt_target {
667     return <<'MAKE_FRAG';
668 makemakerdflt : all
669         $(NOECHO) $(NOOP)
670 MAKE_FRAG
671
672 }
673
674
675 =head3 manifypods_target
676
677   my $manifypods_target = $self->manifypods_target;
678
679 Generates the manifypods target.  This target generates man pages from
680 all POD files in MAN1PODS and MAN3PODS.
681
682 =cut
683
684 sub manifypods_target {
685     my($self) = shift;
686
687     my $man1pods      = '';
688     my $man3pods      = '';
689     my $dependencies  = '';
690
691     # populate manXpods & dependencies:
692     foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
693         $dependencies .= " \\\n\t$name";
694     }
695
696     my $manify = <<END;
697 manifypods : pure_all $dependencies
698 END
699
700     my @man_cmds;
701     foreach my $section (qw(1 3)) {
702         my $pods = $self->{"MAN${section}PODS"};
703         push @man_cmds, $self->split_command(<<CMD, %$pods);
704         \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
705 CMD
706     }
707
708     $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
709     $manify .= join '', map { "$_\n" } @man_cmds;
710
711     return $manify;
712 }
713
714
715 =head3 metafile_target
716
717     my $target = $mm->metafile_target;
718
719 Generate the metafile target.
720
721 Writes the file META.yml YAML encoded meta-data about the module in
722 the distdir.  The format follows Module::Build's as closely as
723 possible.
724
725 =cut
726
727 sub metafile_target {
728     my $self = shift;
729
730     return <<'MAKE_FRAG' if $self->{NO_META};
731 metafile :
732         $(NOECHO) $(NOOP)
733 MAKE_FRAG
734
735     my @metadata   = $self->metafile_data(
736         $self->{META_ADD}   || {},
737         $self->{META_MERGE} || {},
738     );
739     my $meta       = $self->metafile_file(@metadata);
740     my @write_meta = $self->echo($meta, 'META_new.yml');
741
742     return sprintf <<'MAKE_FRAG', join("\n\t", @write_meta);
743 metafile : create_distdir
744         $(NOECHO) $(ECHO) Generating META.yml
745         %s
746         -$(NOECHO) $(MV) META_new.yml $(DISTVNAME)/META.yml
747 MAKE_FRAG
748
749 }
750
751
752 =begin private
753
754 =head3 _sort_pairs
755
756     my @pairs = _sort_pairs($sort_sub, \%hash);
757
758 Sorts the pairs of a hash based on keys ordered according 
759 to C<$sort_sub>.
760
761 =end private
762
763 =cut
764
765 sub _sort_pairs {
766     my $sort  = shift;
767     my $pairs = shift;
768     return map  { $_ => $pairs->{$_} }
769            sort $sort
770            keys %$pairs;
771 }
772
773
774 # Taken from Module::Build::Base
775 sub _hash_merge {
776     my ($self, $h, $k, $v) = @_;
777     if (ref $h->{$k} eq 'ARRAY') {
778         push @{$h->{$k}}, ref $v ? @$v : $v;
779     } elsif (ref $h->{$k} eq 'HASH') {
780         $self->_hash_merge($h->{$k}, $_, $v->{$_}) foreach keys %$v;
781     } else {
782         $h->{$k} = $v;
783     }
784 }
785
786
787 =head3 metafile_data
788
789     my @metadata_pairs = $mm->metafile_data(\%meta_add, \%meta_merge);
790
791 Returns the data which MakeMaker turns into the META.yml file.
792
793 Values of %meta_add will overwrite any existing metadata in those
794 keys.  %meta_merge will be merged with them.
795
796 =cut
797
798 sub metafile_data {
799     my $self = shift;
800     my($meta_add, $meta_merge) = @_;
801
802     # The order in which standard meta keys should be written.
803     my @meta_order = qw(
804         name
805         version
806         abstract
807         author
808         license
809         distribution_type
810
811         configure_requires
812         build_requires
813         requires
814
815         resources
816
817         provides
818         no_index
819
820         generated_by
821         meta-spec
822     );
823
824     my %meta = (
825         name         => $self->{DISTNAME},
826         version      => $self->{VERSION},
827         abstract     => $self->{ABSTRACT},
828         license      => $self->{LICENSE} || 'unknown',
829         distribution_type => $self->{PM} ? 'module' : 'script',
830
831         configure_requires => {
832             'ExtUtils::MakeMaker'       => 0
833         },
834
835         no_index     => {
836             directory   => [qw(t inc)]
837         },
838
839         generated_by => "ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION",
840         'meta-spec'  => {
841             url         => 'http://module-build.sourceforge.net/META-spec-v1.4.html', 
842             version     => 1.4
843         },
844     );
845
846     # The author key is required and it takes a list.
847     $meta{author}   = defined $self->{AUTHOR}    ? [$self->{AUTHOR}] : [];
848
849     $meta{requires} = $self->{PREREQ_PM} if defined $self->{PREREQ_PM};
850     $meta{requires}{perl} = $self->{MIN_PERL_VERSION} if $self->{MIN_PERL_VERSION};
851
852     while( my($key, $val) = each %$meta_add ) {
853         $meta{$key} = $val;
854     }
855
856     while( my($key, $val) = each %$meta_merge ) {
857         $self->_hash_merge(\%meta, $key, $val);
858     }
859
860     my @meta_pairs;
861
862     # Put the standard keys first in the proper order.
863     for my $key (@meta_order) {
864         next unless exists $meta{$key};
865
866         push @meta_pairs, $key, delete $meta{$key};
867     }
868
869     # Then tack everything else onto the end, alpha sorted.
870     for my $key (sort {lc $a cmp lc $b} keys %meta) {
871         push @meta_pairs, $key, $meta{$key};
872     }
873
874     return @meta_pairs
875 }
876
877 =begin private
878
879 =head3 _dump_hash
880
881     $yaml = _dump_hash(\%options, %hash);
882
883 Implements a fake YAML dumper for a hash given
884 as a list of pairs. No quoting/escaping is done. Keys
885 are supposed to be strings. Values are undef, strings, 
886 hash refs or array refs of strings.
887
888 Supported options are:
889
890     delta => STR - indentation delta
891     use_header => BOOL - whether to include a YAML header
892     indent => STR - a string of spaces 
893           default: ''
894
895     max_key_length => INT - maximum key length used to align
896         keys and values of the same hash
897         default: 20
898     key_sort => CODE - a sort sub 
899             It may be undef, which means no sorting by keys
900         default: sub { lc $a cmp lc $b }
901
902     customs => HASH - special options for certain keys 
903            (whose values are hashes themselves)
904         may contain: max_key_length, key_sort, customs
905
906 =end private
907
908 =cut
909
910 sub _dump_hash {
911     croak "first argument should be a hash ref" unless ref $_[0] eq 'HASH';
912     my $options = shift;
913     my %hash = @_;
914
915     # Use a list to preserve order.
916     my @pairs;
917
918     my $k_sort 
919         = exists $options->{key_sort} ? $options->{key_sort} 
920                                       : sub { lc $a cmp lc $b };
921     if ($k_sort) {
922         croak "'key_sort' should be a coderef" unless ref $k_sort eq 'CODE';
923         @pairs = _sort_pairs($k_sort, \%hash);
924     } else { # list of pairs, no sorting
925         @pairs = @_;
926     }
927
928     my $yaml     = $options->{use_header} ? "--- #YAML:1.0\n" : '';
929     my $indent   = $options->{indent} || '';
930     my $k_length = min(
931         ($options->{max_key_length} || 20),
932         max(map { length($_) + 1 } grep { !ref $hash{$_} } keys %hash)
933     );
934     my $customs  = $options->{customs} || {};
935
936     # printf format for key
937     my $k_format = "%-${k_length}s";
938
939     while( @pairs ) {
940         my($key, $val) = splice @pairs, 0, 2;
941         $val = '~' unless defined $val;
942         if(ref $val eq 'HASH') {
943             if ( keys %$val ) {
944                 my %k_options = ( # options for recursive call
945                     delta => $options->{delta},
946                     use_header => 0,
947                     indent => $indent . $options->{delta},
948                 );
949                 if (exists $customs->{$key}) {
950                     my %k_custom = %{$customs->{$key}};
951                     foreach my $k qw(key_sort max_key_length customs) {
952                         $k_options{$k} = $k_custom{$k} if exists $k_custom{$k};
953                     }
954                 }
955                 $yaml .= $indent . "$key:\n" 
956                   . _dump_hash(\%k_options, %$val);
957             }
958             else {
959                 $yaml .= $indent . "$key:  {}\n";
960             }
961         }
962         elsif (ref $val eq 'ARRAY') {
963             if( @$val ) {
964                 $yaml .= $indent . "$key:\n";
965
966                 for (@$val) {
967                     croak "only nested arrays of non-refs are supported" if ref $_;
968                     $yaml .= $indent . $options->{delta} . "- $_\n";
969                 }
970             }
971             else {
972                 $yaml .= $indent . "$key:  []\n";
973             }
974         }
975         elsif( ref $val and !blessed($val) ) {
976             croak "only nested hashes, arrays and objects are supported";
977         }
978         else {  # if it's an object, just stringify it
979             $yaml .= $indent . sprintf "$k_format  %s\n", "$key:", $val;
980         }
981     };
982
983     return $yaml;
984
985 }
986
987 sub blessed {
988     return eval { $_[0]->isa("UNIVERSAL"); };
989 }
990
991 sub max {
992     return (sort { $b <=> $a } @_)[0];
993 }
994
995 sub min {
996     return (sort { $a <=> $b } @_)[0];
997 }
998
999 =head3 metafile_file
1000
1001     my $meta_yml = $mm->metafile_file(@metadata_pairs);
1002
1003 Turns the @metadata_pairs into YAML.
1004
1005 This method does not implement a complete YAML dumper, being limited
1006 to dump a hash with values which are strings, undef's or nested hashes
1007 and arrays of strings. No quoting/escaping is done.
1008
1009 =cut
1010
1011 sub metafile_file {
1012     my $self = shift;
1013
1014     my %dump_options = (
1015         use_header => 1, 
1016         delta      => ' ' x 4, 
1017         key_sort   => undef,
1018     );
1019     return _dump_hash(\%dump_options, @_);
1020
1021 }
1022
1023
1024 =head3 distmeta_target
1025
1026     my $make_frag = $mm->distmeta_target;
1027
1028 Generates the distmeta target to add META.yml to the MANIFEST in the
1029 distdir.
1030
1031 =cut
1032
1033 sub distmeta_target {
1034     my $self = shift;
1035
1036     my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1037 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) } 
1038     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
1039 CODE
1040
1041     my $add_meta_to_distdir = $self->cd('$(DISTVNAME)', $add_meta);
1042
1043     return sprintf <<'MAKE', $add_meta_to_distdir;
1044 distmeta : create_distdir metafile
1045         $(NOECHO) %s
1046
1047 MAKE
1048
1049 }
1050
1051
1052 =head3 realclean (o)
1053
1054 Defines the realclean target.
1055
1056 =cut
1057
1058 sub realclean {
1059     my($self, %attribs) = @_;
1060
1061     my @dirs  = qw($(DISTVNAME));
1062     my @files = qw($(FIRST_MAKEFILE) $(MAKEFILE_OLD));
1063
1064     # Special exception for the perl core where INST_* is not in blib.
1065     # This cleans up the files built from the ext/ directory (all XS).
1066     if( $self->{PERL_CORE} ) {
1067         push @dirs, qw($(INST_AUTODIR) $(INST_ARCHAUTODIR));
1068         push @files, values %{$self->{PM}};
1069     }
1070
1071     if( $self->has_link_code ){
1072         push @files, qw($(OBJECT));
1073     }
1074
1075     if( $attribs{FILES} ) {
1076         if( ref $attribs{FILES} ) {
1077             push @dirs, @{ $attribs{FILES} };
1078         }
1079         else {
1080             push @dirs, split /\s+/, $attribs{FILES};
1081         }
1082     }
1083
1084     # Occasionally files are repeated several times from different sources
1085     { my(%f) = map { ($_ => 1) } @files;  @files = keys %f; }
1086     { my(%d) = map { ($_ => 1) } @dirs;   @dirs  = keys %d; }
1087
1088     my $rm_cmd  = join "\n\t", map { "$_" } 
1089                     $self->split_command('- $(RM_F)',  @files);
1090     my $rmf_cmd = join "\n\t", map { "$_" } 
1091                     $self->split_command('- $(RM_RF)', @dirs);
1092
1093     my $m = sprintf <<'MAKE', $rm_cmd, $rmf_cmd;
1094 # Delete temporary files (via clean) and also delete dist files
1095 realclean purge ::  clean realclean_subdirs
1096         %s
1097         %s
1098 MAKE
1099
1100     $m .= "\t$attribs{POSTOP}\n" if $attribs{POSTOP};
1101
1102     return $m;
1103 }
1104
1105
1106 =head3 realclean_subdirs_target
1107
1108   my $make_frag = $MM->realclean_subdirs_target;
1109
1110 Returns the realclean_subdirs target.  This is used by the realclean
1111 target to call realclean on any subdirectories which contain Makefiles.
1112
1113 =cut
1114
1115 sub realclean_subdirs_target {
1116     my $self = shift;
1117
1118     return <<'NOOP_FRAG' unless @{$self->{DIR}};
1119 realclean_subdirs :
1120         $(NOECHO) $(NOOP)
1121 NOOP_FRAG
1122
1123     my $rclean = "realclean_subdirs :\n";
1124
1125     foreach my $dir (@{$self->{DIR}}) {
1126         foreach my $makefile ('$(MAKEFILE_OLD)', '$(FIRST_MAKEFILE)' ) {
1127             my $subrclean .= $self->oneliner(sprintf <<'CODE', $dir, ($makefile) x 2);
1128 chdir '%s';  system '$(MAKE) $(USEMAKEFILE) %s realclean' if -f '%s';
1129 CODE
1130
1131             $rclean .= sprintf <<'RCLEAN', $subrclean;
1132         - %s
1133 RCLEAN
1134
1135         }
1136     }
1137
1138     return $rclean;
1139 }
1140
1141
1142 =head3 signature_target
1143
1144     my $target = $mm->signature_target;
1145
1146 Generate the signature target.
1147
1148 Writes the file SIGNATURE with "cpansign -s".
1149
1150 =cut
1151
1152 sub signature_target {
1153     my $self = shift;
1154
1155     return <<'MAKE_FRAG';
1156 signature :
1157         cpansign -s
1158 MAKE_FRAG
1159
1160 }
1161
1162
1163 =head3 distsignature_target
1164
1165     my $make_frag = $mm->distsignature_target;
1166
1167 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
1168 distdir.
1169
1170 =cut
1171
1172 sub distsignature_target {
1173     my $self = shift;
1174
1175     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1176 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) } 
1177     or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
1178 CODE
1179
1180     my $sign_dist        = $self->cd('$(DISTVNAME)' => 'cpansign -s');
1181
1182     # cpansign -s complains if SIGNATURE is in the MANIFEST yet does not
1183     # exist
1184     my $touch_sig        = $self->cd('$(DISTVNAME)' => '$(TOUCH) SIGNATURE');
1185     my $add_sign_to_dist = $self->cd('$(DISTVNAME)' => $add_sign );
1186
1187     return sprintf <<'MAKE', $add_sign_to_dist, $touch_sig, $sign_dist
1188 distsignature : create_distdir
1189         $(NOECHO) %s
1190         $(NOECHO) %s
1191         %s
1192
1193 MAKE
1194
1195 }
1196
1197
1198 =head3 special_targets
1199
1200   my $make_frag = $mm->special_targets
1201
1202 Returns a make fragment containing any targets which have special
1203 meaning to make.  For example, .SUFFIXES and .PHONY.
1204
1205 =cut
1206
1207 sub special_targets {
1208     my $make_frag = <<'MAKE_FRAG';
1209 .SUFFIXES : .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
1210
1211 .PHONY: all config static dynamic test linkext manifest blibdirs clean realclean disttest distdir
1212
1213 MAKE_FRAG
1214
1215     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
1216 .NO_CONFIG_REC: Makefile
1217
1218 MAKE_FRAG
1219
1220     return $make_frag;
1221 }
1222
1223
1224
1225
1226 =head2 Init methods
1227
1228 Methods which help initialize the MakeMaker object and macros.
1229
1230
1231 =head3 init_ABSTRACT
1232
1233     $mm->init_ABSTRACT
1234
1235 =cut
1236
1237 sub init_ABSTRACT {
1238     my $self = shift;
1239
1240     if( $self->{ABSTRACT_FROM} and $self->{ABSTRACT} ) {
1241         warn "Both ABSTRACT_FROM and ABSTRACT are set.  ".
1242              "Ignoring ABSTRACT_FROM.\n";
1243         return;
1244     }
1245
1246     if ($self->{ABSTRACT_FROM}){
1247         $self->{ABSTRACT} = $self->parse_abstract($self->{ABSTRACT_FROM}) or
1248             carp "WARNING: Setting ABSTRACT via file ".
1249                  "'$self->{ABSTRACT_FROM}' failed\n";
1250     }
1251 }
1252
1253 =head3 init_INST
1254
1255     $mm->init_INST;
1256
1257 Called by init_main.  Sets up all INST_* variables except those related
1258 to XS code.  Those are handled in init_xs.
1259
1260 =cut
1261
1262 sub init_INST {
1263     my($self) = shift;
1264
1265     $self->{INST_ARCHLIB} ||= $self->catdir($Curdir,"blib","arch");
1266     $self->{INST_BIN}     ||= $self->catdir($Curdir,'blib','bin');
1267
1268     # INST_LIB typically pre-set if building an extension after
1269     # perl has been built and installed. Setting INST_LIB allows
1270     # you to build directly into, say $Config{privlibexp}.
1271     unless ($self->{INST_LIB}){
1272         if ($self->{PERL_CORE}) {
1273             if (defined $Cross::platform) {
1274                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = 
1275                   $self->catdir($self->{PERL_LIB},"..","xlib",
1276                                      $Cross::platform);
1277             }
1278             else {
1279                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = $self->{PERL_LIB};
1280             }
1281         } else {
1282             $self->{INST_LIB} = $self->catdir($Curdir,"blib","lib");
1283         }
1284     }
1285
1286     my @parentdir = split(/::/, $self->{PARENT_NAME});
1287     $self->{INST_LIBDIR}      = $self->catdir('$(INST_LIB)',     @parentdir);
1288     $self->{INST_ARCHLIBDIR}  = $self->catdir('$(INST_ARCHLIB)', @parentdir);
1289     $self->{INST_AUTODIR}     = $self->catdir('$(INST_LIB)', 'auto', 
1290                                               '$(FULLEXT)');
1291     $self->{INST_ARCHAUTODIR} = $self->catdir('$(INST_ARCHLIB)', 'auto',
1292                                               '$(FULLEXT)');
1293
1294     $self->{INST_SCRIPT}  ||= $self->catdir($Curdir,'blib','script');
1295
1296     $self->{INST_MAN1DIR} ||= $self->catdir($Curdir,'blib','man1');
1297     $self->{INST_MAN3DIR} ||= $self->catdir($Curdir,'blib','man3');
1298
1299     return 1;
1300 }
1301
1302
1303 =head3 init_INSTALL
1304
1305     $mm->init_INSTALL;
1306
1307 Called by init_main.  Sets up all INSTALL_* variables (except
1308 INSTALLDIRS) and *PREFIX.
1309
1310 =cut
1311
1312 sub init_INSTALL {
1313     my($self) = shift;
1314
1315     if( $self->{ARGS}{INSTALL_BASE} and $self->{ARGS}{PREFIX} ) {
1316         die "Only one of PREFIX or INSTALL_BASE can be given.  Not both.\n";
1317     }
1318
1319     if( $self->{ARGS}{INSTALL_BASE} ) {
1320         $self->init_INSTALL_from_INSTALL_BASE;
1321     }
1322     else {
1323         $self->init_INSTALL_from_PREFIX;
1324     }
1325 }
1326
1327
1328 =head3 init_INSTALL_from_PREFIX
1329
1330   $mm->init_INSTALL_from_PREFIX;
1331
1332 =cut
1333
1334 sub init_INSTALL_from_PREFIX {
1335     my $self = shift;
1336
1337     $self->init_lib2arch;
1338
1339     # There are often no Config.pm defaults for these new man variables so 
1340     # we fall back to the old behavior which is to use installman*dir
1341     foreach my $num (1, 3) {
1342         my $k = 'installsiteman'.$num.'dir';
1343
1344         $self->{uc $k} ||= uc "\$(installman${num}dir)"
1345           unless $Config{$k};
1346     }
1347
1348     foreach my $num (1, 3) {
1349         my $k = 'installvendorman'.$num.'dir';
1350
1351         unless( $Config{$k} ) {
1352             $self->{uc $k}  ||= $Config{usevendorprefix}
1353                               ? uc "\$(installman${num}dir)"
1354                               : '';
1355         }
1356     }
1357
1358     $self->{INSTALLSITEBIN} ||= '$(INSTALLBIN)'
1359       unless $Config{installsitebin};
1360     $self->{INSTALLSITESCRIPT} ||= '$(INSTALLSCRIPT)'
1361       unless $Config{installsitescript};
1362
1363     unless( $Config{installvendorbin} ) {
1364         $self->{INSTALLVENDORBIN} ||= $Config{usevendorprefix} 
1365                                     ? $Config{installbin}
1366                                     : '';
1367     }
1368     unless( $Config{installvendorscript} ) {
1369         $self->{INSTALLVENDORSCRIPT} ||= $Config{usevendorprefix}
1370                                        ? $Config{installscript}
1371                                        : '';
1372     }
1373
1374
1375     my $iprefix = $Config{installprefixexp} || $Config{installprefix} || 
1376                   $Config{prefixexp}        || $Config{prefix} || '';
1377     my $vprefix = $Config{usevendorprefix}  ? $Config{vendorprefixexp} : '';
1378     my $sprefix = $Config{siteprefixexp}    || '';
1379
1380     # 5.005_03 doesn't have a siteprefix.
1381     $sprefix = $iprefix unless $sprefix;
1382
1383
1384     $self->{PREFIX}       ||= '';
1385
1386     if( $self->{PREFIX} ) {
1387         @{$self}{qw(PERLPREFIX SITEPREFIX VENDORPREFIX)} =
1388           ('$(PREFIX)') x 3;
1389     }
1390     else {
1391         $self->{PERLPREFIX}   ||= $iprefix;
1392         $self->{SITEPREFIX}   ||= $sprefix;
1393         $self->{VENDORPREFIX} ||= $vprefix;
1394
1395         # Lots of MM extension authors like to use $(PREFIX) so we
1396         # put something sensible in there no matter what.
1397         $self->{PREFIX} = '$('.uc $self->{INSTALLDIRS}.'PREFIX)';
1398     }
1399
1400     my $arch    = $Config{archname};
1401     my $version = $Config{version};
1402
1403     # default style
1404     my $libstyle = $Config{installstyle} || 'lib/perl5';
1405     my $manstyle = '';
1406
1407     if( $self->{LIBSTYLE} ) {
1408         $libstyle = $self->{LIBSTYLE};
1409         $manstyle = $self->{LIBSTYLE} eq 'lib/perl5' ? 'lib/perl5' : '';
1410     }
1411
1412     # Some systems, like VOS, set installman*dir to '' if they can't
1413     # read man pages.
1414     for my $num (1, 3) {
1415         $self->{'INSTALLMAN'.$num.'DIR'} ||= 'none'
1416           unless $Config{'installman'.$num.'dir'};
1417     }
1418
1419     my %bin_layouts = 
1420     (
1421         bin         => { s => $iprefix,
1422                          t => 'perl',
1423                          d => 'bin' },
1424         vendorbin   => { s => $vprefix,
1425                          t => 'vendor',
1426                          d => 'bin' },
1427         sitebin     => { s => $sprefix,
1428                          t => 'site',
1429                          d => 'bin' },
1430         script      => { s => $iprefix,
1431                          t => 'perl',
1432                          d => 'bin' },
1433         vendorscript=> { s => $vprefix,
1434                          t => 'vendor',
1435                          d => 'bin' },
1436         sitescript  => { s => $sprefix,
1437                          t => 'site',
1438                          d => 'bin' },
1439     );
1440     
1441     my %man_layouts =
1442     (
1443         man1dir         => { s => $iprefix,
1444                              t => 'perl',
1445                              d => 'man/man1',
1446                              style => $manstyle, },
1447         siteman1dir     => { s => $sprefix,
1448                              t => 'site',
1449                              d => 'man/man1',
1450                              style => $manstyle, },
1451         vendorman1dir   => { s => $vprefix,
1452                              t => 'vendor',
1453                              d => 'man/man1',
1454                              style => $manstyle, },
1455
1456         man3dir         => { s => $iprefix,
1457                              t => 'perl',
1458                              d => 'man/man3',
1459                              style => $manstyle, },
1460         siteman3dir     => { s => $sprefix,
1461                              t => 'site',
1462                              d => 'man/man3',
1463                              style => $manstyle, },
1464         vendorman3dir   => { s => $vprefix,
1465                              t => 'vendor',
1466                              d => 'man/man3',
1467                              style => $manstyle, },
1468     );
1469
1470     my %lib_layouts =
1471     (
1472         privlib     => { s => $iprefix,
1473                          t => 'perl',
1474                          d => '',
1475                          style => $libstyle, },
1476         vendorlib   => { s => $vprefix,
1477                          t => 'vendor',
1478                          d => '',
1479                          style => $libstyle, },
1480         sitelib     => { s => $sprefix,
1481                          t => 'site',
1482                          d => 'site_perl',
1483                          style => $libstyle, },
1484         
1485         archlib     => { s => $iprefix,
1486                          t => 'perl',
1487                          d => "$version/$arch",
1488                          style => $libstyle },
1489         vendorarch  => { s => $vprefix,
1490                          t => 'vendor',
1491                          d => "$version/$arch",
1492                          style => $libstyle },
1493         sitearch    => { s => $sprefix,
1494                          t => 'site',
1495                          d => "site_perl/$version/$arch",
1496                          style => $libstyle },
1497     );
1498
1499
1500     # Special case for LIB.
1501     if( $self->{LIB} ) {
1502         foreach my $var (keys %lib_layouts) {
1503             my $Installvar = uc "install$var";
1504
1505             if( $var =~ /arch/ ) {
1506                 $self->{$Installvar} ||= 
1507                   $self->catdir($self->{LIB}, $Config{archname});
1508             }
1509             else {
1510                 $self->{$Installvar} ||= $self->{LIB};
1511             }
1512         }
1513     }
1514
1515     my %type2prefix = ( perl    => 'PERLPREFIX',
1516                         site    => 'SITEPREFIX',
1517                         vendor  => 'VENDORPREFIX'
1518                       );
1519
1520     my %layouts = (%bin_layouts, %man_layouts, %lib_layouts);
1521     while( my($var, $layout) = each(%layouts) ) {
1522         my($s, $t, $d, $style) = @{$layout}{qw(s t d style)};
1523         my $r = '$('.$type2prefix{$t}.')';
1524
1525         print STDERR "Prefixing $var\n" if $Verbose >= 2;
1526
1527         my $installvar = "install$var";
1528         my $Installvar = uc $installvar;
1529         next if $self->{$Installvar};
1530
1531         $d = "$style/$d" if $style;
1532         $self->prefixify($installvar, $s, $r, $d);
1533
1534         print STDERR "  $Installvar == $self->{$Installvar}\n" 
1535           if $Verbose >= 2;
1536     }
1537
1538     # Generate these if they weren't figured out.
1539     $self->{VENDORARCHEXP} ||= $self->{INSTALLVENDORARCH};
1540     $self->{VENDORLIBEXP}  ||= $self->{INSTALLVENDORLIB};
1541
1542     return 1;
1543 }
1544
1545
1546 =head3 init_from_INSTALL_BASE
1547
1548     $mm->init_from_INSTALL_BASE
1549
1550 =cut
1551
1552 my %map = (
1553            lib      => [qw(lib perl5)],
1554            arch     => [('lib', 'perl5', $Config{archname})],
1555            bin      => [qw(bin)],
1556            man1dir  => [qw(man man1)],
1557            man3dir  => [qw(man man3)]
1558           );
1559 $map{script} = $map{bin};
1560
1561 sub init_INSTALL_from_INSTALL_BASE {
1562     my $self = shift;
1563
1564     @{$self}{qw(PREFIX VENDORPREFIX SITEPREFIX PERLPREFIX)} = 
1565                                                          '$(INSTALL_BASE)';
1566
1567     my %install;
1568     foreach my $thing (keys %map) {
1569         foreach my $dir (('', 'SITE', 'VENDOR')) {
1570             my $uc_thing = uc $thing;
1571             my $key = "INSTALL".$dir.$uc_thing;
1572
1573             $install{$key} ||= 
1574               $self->catdir('$(INSTALL_BASE)', @{$map{$thing}});
1575         }
1576     }
1577
1578     # Adjust for variable quirks.
1579     $install{INSTALLARCHLIB} ||= delete $install{INSTALLARCH};
1580     $install{INSTALLPRIVLIB} ||= delete $install{INSTALLLIB};
1581
1582     foreach my $key (keys %install) {
1583         $self->{$key} ||= $install{$key};
1584     }
1585
1586     return 1;
1587 }
1588
1589
1590 =head3 init_VERSION  I<Abstract>
1591
1592     $mm->init_VERSION
1593
1594 Initialize macros representing versions of MakeMaker and other tools
1595
1596 MAKEMAKER: path to the MakeMaker module.
1597
1598 MM_VERSION: ExtUtils::MakeMaker Version
1599
1600 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards 
1601              compat)
1602
1603 VERSION: version of your module
1604
1605 VERSION_MACRO: which macro represents the version (usually 'VERSION')
1606
1607 VERSION_SYM: like version but safe for use as an RCS revision number
1608
1609 DEFINE_VERSION: -D line to set the module version when compiling
1610
1611 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
1612
1613 XS_VERSION_MACRO: which macro represents the XS version.
1614
1615 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
1616
1617 Called by init_main.
1618
1619 =cut
1620
1621 sub init_VERSION {
1622     my($self) = shift;
1623
1624     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
1625     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
1626     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
1627     $self->{VERSION_FROM} ||= '';
1628
1629     if ($self->{VERSION_FROM}){
1630         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
1631         if( $self->{VERSION} eq 'undef' ) {
1632             carp("WARNING: Setting VERSION via file ".
1633                  "'$self->{VERSION_FROM}' failed\n");
1634         }
1635     }
1636
1637     # strip blanks
1638     if (defined $self->{VERSION}) {
1639         $self->{VERSION} =~ s/^\s+//;
1640         $self->{VERSION} =~ s/\s+$//;
1641     }
1642     else {
1643         $self->{VERSION} = '';
1644     }
1645
1646
1647     $self->{VERSION_MACRO}  = 'VERSION';
1648     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
1649     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
1650
1651
1652     # Graham Barr and Paul Marquess had some ideas how to ensure
1653     # version compatibility between the *.pm file and the
1654     # corresponding *.xs file. The bottomline was, that we need an
1655     # XS_VERSION macro that defaults to VERSION:
1656     $self->{XS_VERSION} ||= $self->{VERSION};
1657
1658     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
1659     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
1660
1661 }
1662
1663
1664 =head3 init_others  I<Abstract>
1665
1666     $MM->init_others();
1667
1668 Initializes the macro definitions used by tools_other() and places them
1669 in the $MM object.
1670
1671 If there is no description, its the same as the parameter to
1672 WriteMakefile() documented in ExtUtils::MakeMaker.
1673
1674 Defines at least these macros.
1675
1676   Macro             Description
1677
1678   NOOP              Do nothing
1679   NOECHO            Tell make not to display the command itself
1680
1681   MAKEFILE
1682   FIRST_MAKEFILE
1683   MAKEFILE_OLD
1684   MAKE_APERL_FILE   File used by MAKE_APERL
1685
1686   SHELL             Program used to run shell commands
1687
1688   ECHO              Print text adding a newline on the end
1689   RM_F              Remove a file 
1690   RM_RF             Remove a directory          
1691   TOUCH             Update a file's timestamp   
1692   TEST_F            Test for a file's existence 
1693   CP                Copy a file                 
1694   MV                Move a file                 
1695   CHMOD             Change permissions on a     
1696                     file
1697
1698   UMASK_NULL        Nullify umask
1699   DEV_NULL          Suppress all command output
1700
1701
1702 =head3 init_DIRFILESEP  I<Abstract>
1703
1704   $MM->init_DIRFILESEP;
1705   my $dirfilesep = $MM->{DIRFILESEP};
1706
1707 Initializes the DIRFILESEP macro which is the seperator between the
1708 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
1709 nothing on VMS.
1710
1711 For example:
1712
1713     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
1714     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
1715
1716 Something of a hack but it prevents a lot of code duplication between
1717 MM_* variants.
1718
1719 Do not use this as a seperator between directories.  Some operating
1720 systems use different seperators between subdirectories as between
1721 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
1722
1723 =head3 init_linker  I<Abstract>
1724
1725     $mm->init_linker;
1726
1727 Initialize macros which have to do with linking.
1728
1729 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
1730 extensions.
1731
1732 PERL_ARCHIVE_AFTER: path to a library which should be put on the
1733 linker command line I<after> the external libraries to be linked to
1734 dynamic extensions.  This may be needed if the linker is one-pass, and
1735 Perl includes some overrides for C RTL functions, such as malloc().
1736
1737 EXPORT_LIST: name of a file that is passed to linker to define symbols
1738 to be exported.
1739
1740 Some OSes do not need these in which case leave it blank.
1741
1742
1743 =head3 init_platform
1744
1745     $mm->init_platform
1746
1747 Initialize any macros which are for platform specific use only.
1748
1749 A typical one is the version number of your OS specific mocule.
1750 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
1751
1752 =cut
1753
1754 sub init_platform {
1755     return '';
1756 }
1757
1758
1759 =head3 init_MAKE
1760
1761     $mm->init_MAKE
1762
1763 Initialize MAKE from either a MAKE environment variable or $Config{make}.
1764
1765 =cut
1766
1767 sub init_MAKE {
1768     my $self = shift;
1769
1770     $self->{MAKE} ||= $ENV{MAKE} || $Config{make};
1771 }
1772
1773
1774 =head2 Tools
1775
1776 A grab bag of methods to generate specific macros and commands.
1777
1778
1779
1780 =head3 manifypods
1781
1782 Defines targets and routines to translate the pods into manpages and
1783 put them into the INST_* directories.
1784
1785 =cut
1786
1787 sub manifypods {
1788     my $self          = shift;
1789
1790     my $POD2MAN_macro = $self->POD2MAN_macro();
1791     my $manifypods_target = $self->manifypods_target();
1792
1793     return <<END_OF_TARGET;
1794
1795 $POD2MAN_macro
1796
1797 $manifypods_target
1798
1799 END_OF_TARGET
1800
1801 }
1802
1803
1804 =head3 POD2MAN_macro
1805
1806   my $pod2man_macro = $self->POD2MAN_macro
1807
1808 Returns a definition for the POD2MAN macro.  This is a program
1809 which emulates the pod2man utility.  You can add more switches to the
1810 command by simply appending them on the macro.
1811
1812 Typical usage:
1813
1814     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
1815
1816 =cut
1817
1818 sub POD2MAN_macro {
1819     my $self = shift;
1820
1821 # Need the trailing '--' so perl stops gobbling arguments and - happens
1822 # to be an alternative end of line seperator on VMS so we quote it
1823     return <<'END_OF_DEF';
1824 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
1825 POD2MAN = $(POD2MAN_EXE)
1826 END_OF_DEF
1827 }
1828
1829
1830 =head3 test_via_harness
1831
1832   my $command = $mm->test_via_harness($perl, $tests);
1833
1834 Returns a $command line which runs the given set of $tests with
1835 Test::Harness and the given $perl.
1836
1837 Used on the t/*.t files.
1838
1839 =cut
1840
1841 sub test_via_harness {
1842     my($self, $perl, $tests) = @_;
1843
1844     return qq{\t$perl "-MExtUtils::Command::MM" }.
1845            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
1846 }
1847
1848 =head3 test_via_script
1849
1850   my $command = $mm->test_via_script($perl, $script);
1851
1852 Returns a $command line which just runs a single test without
1853 Test::Harness.  No checks are done on the results, they're just
1854 printed.
1855
1856 Used for test.pl, since they don't always follow Test::Harness
1857 formatting.
1858
1859 =cut
1860
1861 sub test_via_script {
1862     my($self, $perl, $script) = @_;
1863     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
1864 }
1865
1866
1867 =head3 tool_autosplit
1868
1869 Defines a simple perl call that runs autosplit. May be deprecated by
1870 pm_to_blib soon.
1871
1872 =cut
1873
1874 sub tool_autosplit {
1875     my($self, %attribs) = @_;
1876
1877     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};' 
1878                                   : '';
1879
1880     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
1881 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
1882 PERL_CODE
1883
1884     return sprintf <<'MAKE_FRAG', $asplit;
1885 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
1886 AUTOSPLITFILE = %s
1887
1888 MAKE_FRAG
1889
1890 }
1891
1892
1893
1894
1895 =head2 File::Spec wrappers
1896
1897 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
1898 override File::Spec.
1899
1900
1901
1902 =head3 catfile
1903
1904 File::Spec <= 0.83 has a bug where the file part of catfile is not
1905 canonicalized.  This override fixes that bug.
1906
1907 =cut
1908
1909 sub catfile {
1910     my $self = shift;
1911     return $self->canonpath($self->SUPER::catfile(@_));
1912 }
1913
1914
1915
1916 =head2 Misc
1917
1918 Methods I can't really figure out where they should go yet.
1919
1920
1921 =head3 find_tests
1922
1923   my $test = $mm->find_tests;
1924
1925 Returns a string suitable for feeding to the shell to return all
1926 tests in t/*.t.
1927
1928 =cut
1929
1930 sub find_tests {
1931     my($self) = shift;
1932     return -d 't' ? 't/*.t' : '';
1933 }
1934
1935
1936 =head3 extra_clean_files
1937
1938     my @files_to_clean = $MM->extra_clean_files;
1939
1940 Returns a list of OS specific files to be removed in the clean target in
1941 addition to the usual set.
1942
1943 =cut
1944
1945 # An empty method here tickled a perl 5.8.1 bug and would return its object.
1946 sub extra_clean_files { 
1947     return;
1948 }
1949
1950
1951 =head3 installvars
1952
1953     my @installvars = $mm->installvars;
1954
1955 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
1956 for iteration or building related variable sets.
1957
1958 =cut
1959
1960 sub installvars {
1961     return qw(PRIVLIB SITELIB  VENDORLIB
1962               ARCHLIB SITEARCH VENDORARCH
1963               BIN     SITEBIN  VENDORBIN
1964               SCRIPT  SITESCRIPT  VENDORSCRIPT
1965               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
1966               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
1967              );
1968 }
1969
1970
1971 =head3 libscan
1972
1973   my $wanted = $self->libscan($path);
1974
1975 Takes a path to a file or dir and returns an empty string if we don't
1976 want to include this file in the library.  Otherwise it returns the
1977 the $path unchanged.
1978
1979 Mainly used to exclude version control administrative directories from
1980 installation.
1981
1982 =cut
1983
1984 sub libscan {
1985     my($self,$path) = @_;
1986     my($dirs,$file) = ($self->splitpath($path))[1,2];
1987     return '' if grep /^(?:RCS|CVS|SCCS|\.svn|_darcs)$/, 
1988                      $self->splitdir($dirs), $file;
1989
1990     return $path;
1991 }
1992
1993
1994 =head3 platform_constants
1995
1996     my $make_frag = $mm->platform_constants
1997
1998 Returns a make fragment defining all the macros initialized in
1999 init_platform() rather than put them in constants().
2000
2001 =cut
2002
2003 sub platform_constants {
2004     return '';
2005 }
2006
2007
2008 =head1 AUTHOR
2009
2010 Michael G Schwern <schwern@pobox.com> and the denizens of
2011 makemaker@perl.org with code from ExtUtils::MM_Unix and
2012 ExtUtils::MM_Win32.
2013
2014
2015 =cut
2016
2017 1;