lib/ExtUtils/MM_Any.pm

   1 package ExtUtils::MM_Any;
   2
   3 use strict;
   4 our $VERSION = '6.48';
   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;