lib/ExtUtils/MM_Any.pm

   1 package ExtUtils::MM_Any;
   2
   3 use strict;
   4 our $VERSION = '6.49_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         build_requires => {
 836             'ExtUtils::MakeMaker'       => 0
 837         },
 838
 839         no_index     => {
 840             directory   => [qw(t inc)]
 841         },
 842
 843         generated_by => "ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION",
 844         'meta-spec'  => {
 845             url         => 'http://module-build.sourceforge.net/META-spec-v1.4.html',
 846             version     => 1.4
 847         },
 848     );
 849
 850     # The author key is required and it takes a list.
 851     $meta{author}   = defined $self->{AUTHOR}    ? [$self->{AUTHOR}] : [];
 852
 853     $meta{requires} = $self->{PREREQ_PM} if defined $self->{PREREQ_PM};
 854     $meta{requires}{perl} = $self->{MIN_PERL_VERSION} if $self->{MIN_PERL_VERSION};
 855
 856     while( my($key, $val) = each %$meta_add ) {
 857         $meta{$key} = $val;
 858     }
 859
 860     while( my($key, $val) = each %$meta_merge ) {
 861         $self->_hash_merge(\%meta, $key, $val);
 862     }
 863
 864     my @meta_pairs;
 865
 866     # Put the standard keys first in the proper order.
 867     for my $key (@meta_order) {
 868         next unless exists $meta{$key};
 869
 870         push @meta_pairs, $key, delete $meta{$key};
 871     }
 872
 873     # Then tack everything else onto the end, alpha sorted.
 874     for my $key (sort {lc $a cmp lc $b} keys %meta) {
 875         push @meta_pairs, $key, $meta{$key};
 876     }
 877
 878     return @meta_pairs
 879 }
 880
 881 =begin private
 882
 883 =head3 _dump_hash
 884
 885     $yaml = _dump_hash(\%options, %hash);
 886
 887 Implements a fake YAML dumper for a hash given
 888 as a list of pairs. No quoting/escaping is done. Keys
 889 are supposed to be strings. Values are undef, strings,
 890 hash refs or array refs of strings.
 891
 892 Supported options are:
 893
 894     delta => STR - indentation delta
 895     use_header => BOOL - whether to include a YAML header
 896     indent => STR - a string of spaces
 897           default: ''
 898
 899     max_key_length => INT - maximum key length used to align
 900         keys and values of the same hash
 901         default: 20
 902     key_sort => CODE - a sort sub
 903             It may be undef, which means no sorting by keys
 904         default: sub { lc $a cmp lc $b }
 905
 906     customs => HASH - special options for certain keys
 907            (whose values are hashes themselves)
 908         may contain: max_key_length, key_sort, customs
 909
 910 =end private
 911
 912 =cut
 913
 914 sub _dump_hash {
 915     croak "first argument should be a hash ref" unless ref $_[0] eq 'HASH';
 916     my $options = shift;
 917     my %hash = @_;
 918
 919     # Use a list to preserve order.
 920     my @pairs;
 921
 922     my $k_sort
 923         = exists $options->{key_sort} ? $options->{key_sort}
 924                                       : sub { lc $a cmp lc $b };
 925     if ($k_sort) {
 926         croak "'key_sort' should be a coderef" unless ref $k_sort eq 'CODE';
 927         @pairs = _sort_pairs($k_sort, \%hash);
 928     } else { # list of pairs, no sorting
 929         @pairs = @_;
 930     }
 931
 932     my $yaml     = $options->{use_header} ? "--- #YAML:1.0\n" : '';
 933     my $indent   = $options->{indent} || '';
 934     my $k_length = min(
 935         ($options->{max_key_length} || 20),
 936         max(map { length($_) + 1 } grep { !ref $hash{$_} } keys %hash)
 937     );
 938     my $customs  = $options->{customs} || {};
 939
 940     # printf format for key
 941     my $k_format = "%-${k_length}s";
 942
 943     while( @pairs ) {
 944         my($key, $val) = splice @pairs, 0, 2;
 945         $val = '~' unless defined $val;
 946         if(ref $val eq 'HASH') {
 947             if ( keys %$val ) {
 948                 my %k_options = ( # options for recursive call
 949                     delta => $options->{delta},
 950                     use_header => 0,
 951                     indent => $indent . $options->{delta},
 952                 );
 953                 if (exists $customs->{$key}) {
 954                     my %k_custom = %{$customs->{$key}};
 955                     foreach my $k qw(key_sort max_key_length customs) {
 956                         $k_options{$k} = $k_custom{$k} if exists $k_custom{$k};
 957                     }
 958                 }
 959                 $yaml .= $indent . "$key:\n"
 960                   . _dump_hash(\%k_options, %$val);
 961             }
 962             else {
 963                 $yaml .= $indent . "$key:  {}\n";
 964             }
 965         }
 966         elsif (ref $val eq 'ARRAY') {
 967             if( @$val ) {
 968                 $yaml .= $indent . "$key:\n";
 969
 970                 for (@$val) {
 971                     croak "only nested arrays of non-refs are supported" if ref $_;
 972                     $yaml .= $indent . $options->{delta} . "- $_\n";
 973                 }
 974             }
 975             else {
 976                 $yaml .= $indent . "$key:  []\n";
 977             }
 978         }
 979         elsif( ref $val and !blessed($val) ) {
 980             croak "only nested hashes, arrays and objects are supported";
 981         }
 982         else {  # if it's an object, just stringify it
 983             $yaml .= $indent . sprintf "$k_format  %s\n", "$key:", $val;
 984         }
 985     };
 986
 987     return $yaml;
 988
 989 }
 990
 991 sub blessed {
 992     return eval { $_[0]->isa("UNIVERSAL"); };
 993 }
 994
 995 sub max {
 996     return (sort { $b <=> $a } @_)[0];
 997 }
 998
 999 sub min {
1000     return (sort { $a <=> $b } @_)[0];
1001 }
1002
1003 =head3 metafile_file
1004
1005     my $meta_yml = $mm->metafile_file(@metadata_pairs);
1006
1007 Turns the @metadata_pairs into YAML.
1008
1009 This method does not implement a complete YAML dumper, being limited
1010 to dump a hash with values which are strings, undef's or nested hashes
1011 and arrays of strings. No quoting/escaping is done.
1012
1013 =cut
1014
1015 sub metafile_file {
1016     my $self = shift;
1017
1018     my %dump_options = (
1019         use_header => 1,
1020         delta      => ' ' x 4,
1021         key_sort   => undef,
1022     );
1023     return _dump_hash(\%dump_options, @_);
1024
1025 }
1026
1027
1028 =head3 distmeta_target
1029
1030     my $make_frag = $mm->distmeta_target;
1031
1032 Generates the distmeta target to add META.yml to the MANIFEST in the
1033 distdir.
1034
1035 =cut
1036
1037 sub distmeta_target {
1038     my $self = shift;
1039
1040     my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1041 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
1042     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
1043 CODE
1044
1045     my $add_meta_to_distdir = $self->cd('$(DISTVNAME)', $add_meta);
1046
1047     return sprintf <<'MAKE', $add_meta_to_distdir;
1048 distmeta : create_distdir metafile
1049         $(NOECHO) %s
1050
1051 MAKE
1052
1053 }
1054
1055
1056 =head3 realclean (o)
1057
1058 Defines the realclean target.
1059
1060 =cut
1061
1062 sub realclean {
1063     my($self, %attribs) = @_;
1064
1065     my @dirs  = qw($(DISTVNAME));
1066     my @files = qw($(FIRST_MAKEFILE) $(MAKEFILE_OLD));
1067
1068     # Special exception for the perl core where INST_* is not in blib.
1069     # This cleans up the files built from the ext/ directory (all XS).
1070     if( $self->{PERL_CORE} ) {
1071         push @dirs, qw($(INST_AUTODIR) $(INST_ARCHAUTODIR));
1072         push @files, values %{$self->{PM}};
1073     }
1074
1075     if( $self->has_link_code ){
1076         push @files, qw($(OBJECT));
1077     }
1078
1079     if( $attribs{FILES} ) {
1080         if( ref $attribs{FILES} ) {
1081             push @dirs, @{ $attribs{FILES} };
1082         }
1083         else {
1084             push @dirs, split /\s+/, $attribs{FILES};
1085         }
1086     }
1087
1088     # Occasionally files are repeated several times from different sources
1089     { my(%f) = map { ($_ => 1) } @files;  @files = keys %f; }
1090     { my(%d) = map { ($_ => 1) } @dirs;   @dirs  = keys %d; }
1091
1092     my $rm_cmd  = join "\n\t", map { "$_" }
1093                     $self->split_command('- $(RM_F)',  @files);
1094     my $rmf_cmd = join "\n\t", map { "$_" }
1095                     $self->split_command('- $(RM_RF)', @dirs);
1096
1097     my $m = sprintf <<'MAKE', $rm_cmd, $rmf_cmd;
1098 # Delete temporary files (via clean) and also delete dist files
1099 realclean purge ::  clean realclean_subdirs
1100         %s
1101         %s
1102 MAKE
1103
1104     $m .= "\t$attribs{POSTOP}\n" if $attribs{POSTOP};
1105
1106     return $m;
1107 }
1108
1109
1110 =head3 realclean_subdirs_target
1111
1112   my $make_frag = $MM->realclean_subdirs_target;
1113
1114 Returns the realclean_subdirs target.  This is used by the realclean
1115 target to call realclean on any subdirectories which contain Makefiles.
1116
1117 =cut
1118
1119 sub realclean_subdirs_target {
1120     my $self = shift;
1121
1122     return <<'NOOP_FRAG' unless @{$self->{DIR}};
1123 realclean_subdirs :
1124         $(NOECHO) $(NOOP)
1125 NOOP_FRAG
1126
1127     my $rclean = "realclean_subdirs :\n";
1128
1129     foreach my $dir (@{$self->{DIR}}) {
1130         foreach my $makefile ('$(MAKEFILE_OLD)', '$(FIRST_MAKEFILE)' ) {
1131             my $subrclean .= $self->oneliner(sprintf <<'CODE', $dir, ($makefile) x 2);
1132 chdir '%s';  system '$(MAKE) $(USEMAKEFILE) %s realclean' if -f '%s';
1133 CODE
1134
1135             $rclean .= sprintf <<'RCLEAN', $subrclean;
1136         - %s
1137 RCLEAN
1138
1139         }
1140     }
1141
1142     return $rclean;
1143 }
1144
1145
1146 =head3 signature_target
1147
1148     my $target = $mm->signature_target;
1149
1150 Generate the signature target.
1151
1152 Writes the file SIGNATURE with "cpansign -s".
1153
1154 =cut
1155
1156 sub signature_target {
1157     my $self = shift;
1158
1159     return <<'MAKE_FRAG';
1160 signature :
1161         cpansign -s
1162 MAKE_FRAG
1163
1164 }
1165
1166
1167 =head3 distsignature_target
1168
1169     my $make_frag = $mm->distsignature_target;
1170
1171 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
1172 distdir.
1173
1174 =cut
1175
1176 sub distsignature_target {
1177     my $self = shift;
1178
1179     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1180 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
1181     or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
1182 CODE
1183
1184     my $sign_dist        = $self->cd('$(DISTVNAME)' => 'cpansign -s');
1185
1186     # cpansign -s complains if SIGNATURE is in the MANIFEST yet does not
1187     # exist
1188     my $touch_sig        = $self->cd('$(DISTVNAME)' => '$(TOUCH) SIGNATURE');
1189     my $add_sign_to_dist = $self->cd('$(DISTVNAME)' => $add_sign );
1190
1191     return sprintf <<'MAKE', $add_sign_to_dist, $touch_sig, $sign_dist
1192 distsignature : create_distdir
1193         $(NOECHO) %s
1194         $(NOECHO) %s
1195         %s
1196
1197 MAKE
1198
1199 }
1200
1201
1202 =head3 special_targets
1203
1204   my $make_frag = $mm->special_targets
1205
1206 Returns a make fragment containing any targets which have special
1207 meaning to make.  For example, .SUFFIXES and .PHONY.
1208
1209 =cut
1210
1211 sub special_targets {
1212     my $make_frag = <<'MAKE_FRAG';
1213 .SUFFIXES : .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
1214
1215 .PHONY: all config static dynamic test linkext manifest blibdirs clean realclean disttest distdir
1216
1217 MAKE_FRAG
1218
1219     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
1220 .NO_CONFIG_REC: Makefile
1221
1222 MAKE_FRAG
1223
1224     return $make_frag;
1225 }
1226
1227
1228
1229
1230 =head2 Init methods
1231
1232 Methods which help initialize the MakeMaker object and macros.
1233
1234
1235 =head3 init_ABSTRACT
1236
1237     $mm->init_ABSTRACT
1238
1239 =cut
1240
1241 sub init_ABSTRACT {
1242     my $self = shift;
1243
1244     if( $self->{ABSTRACT_FROM} and $self->{ABSTRACT} ) {
1245         warn "Both ABSTRACT_FROM and ABSTRACT are set.  ".
1246              "Ignoring ABSTRACT_FROM.\n";
1247         return;
1248     }
1249
1250     if ($self->{ABSTRACT_FROM}){
1251         $self->{ABSTRACT} = $self->parse_abstract($self->{ABSTRACT_FROM}) or
1252             carp "WARNING: Setting ABSTRACT via file ".
1253                  "'$self->{ABSTRACT_FROM}' failed\n";
1254     }
1255 }
1256
1257 =head3 init_INST
1258
1259     $mm->init_INST;
1260
1261 Called by init_main.  Sets up all INST_* variables except those related
1262 to XS code.  Those are handled in init_xs.
1263
1264 =cut
1265
1266 sub init_INST {
1267     my($self) = shift;
1268
1269     $self->{INST_ARCHLIB} ||= $self->catdir($Curdir,"blib","arch");
1270     $self->{INST_BIN}     ||= $self->catdir($Curdir,'blib','bin');
1271
1272     # INST_LIB typically pre-set if building an extension after
1273     # perl has been built and installed. Setting INST_LIB allows
1274     # you to build directly into, say $Config{privlibexp}.
1275     unless ($self->{INST_LIB}){
1276         if ($self->{PERL_CORE}) {
1277             if (defined $Cross::platform) {
1278                 $self->{INST_LIB} = $self->{INST_ARCHLIB} =
1279                   $self->catdir($self->{PERL_LIB},"..","xlib",
1280                                      $Cross::platform);
1281             }
1282             else {
1283                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = $self->{PERL_LIB};
1284             }
1285         } else {
1286             $self->{INST_LIB} = $self->catdir($Curdir,"blib","lib");
1287         }
1288     }
1289
1290     my @parentdir = split(/::/, $self->{PARENT_NAME});
1291     $self->{INST_LIBDIR}      = $self->catdir('$(INST_LIB)',     @parentdir);
1292     $self->{INST_ARCHLIBDIR}  = $self->catdir('$(INST_ARCHLIB)', @parentdir);
1293     $self->{INST_AUTODIR}     = $self->catdir('$(INST_LIB)', 'auto',
1294                                               '$(FULLEXT)');
1295     $self->{INST_ARCHAUTODIR} = $self->catdir('$(INST_ARCHLIB)', 'auto',
1296                                               '$(FULLEXT)');
1297
1298     $self->{INST_SCRIPT}  ||= $self->catdir($Curdir,'blib','script');
1299
1300     $self->{INST_MAN1DIR} ||= $self->catdir($Curdir,'blib','man1');
1301     $self->{INST_MAN3DIR} ||= $self->catdir($Curdir,'blib','man3');
1302
1303     return 1;
1304 }
1305
1306
1307 =head3 init_INSTALL
1308
1309     $mm->init_INSTALL;
1310
1311 Called by init_main.  Sets up all INSTALL_* variables (except
1312 INSTALLDIRS) and *PREFIX.
1313
1314 =cut
1315
1316 sub init_INSTALL {
1317     my($self) = shift;
1318
1319     if( $self->{ARGS}{INSTALL_BASE} and $self->{ARGS}{PREFIX} ) {
1320         die "Only one of PREFIX or INSTALL_BASE can be given.  Not both.\n";
1321     }
1322
1323     if( $self->{ARGS}{INSTALL_BASE} ) {
1324         $self->init_INSTALL_from_INSTALL_BASE;
1325     }
1326     else {
1327         $self->init_INSTALL_from_PREFIX;
1328     }
1329 }
1330
1331
1332 =head3 init_INSTALL_from_PREFIX
1333
1334   $mm->init_INSTALL_from_PREFIX;
1335
1336 =cut
1337
1338 sub init_INSTALL_from_PREFIX {
1339     my $self = shift;
1340
1341     $self->init_lib2arch;
1342
1343     # There are often no Config.pm defaults for these new man variables so
1344     # we fall back to the old behavior which is to use installman*dir
1345     foreach my $num (1, 3) {
1346         my $k = 'installsiteman'.$num.'dir';
1347
1348         $self->{uc $k} ||= uc "\$(installman${num}dir)"
1349           unless $Config{$k};
1350     }
1351
1352     foreach my $num (1, 3) {
1353         my $k = 'installvendorman'.$num.'dir';
1354
1355         unless( $Config{$k} ) {
1356             $self->{uc $k}  ||= $Config{usevendorprefix}
1357                               ? uc "\$(installman${num}dir)"
1358                               : '';
1359         }
1360     }
1361
1362     $self->{INSTALLSITEBIN} ||= '$(INSTALLBIN)'
1363       unless $Config{installsitebin};
1364     $self->{INSTALLSITESCRIPT} ||= '$(INSTALLSCRIPT)'
1365       unless $Config{installsitescript};
1366
1367     unless( $Config{installvendorbin} ) {
1368         $self->{INSTALLVENDORBIN} ||= $Config{usevendorprefix}
1369                                     ? $Config{installbin}
1370                                     : '';
1371     }
1372     unless( $Config{installvendorscript} ) {
1373         $self->{INSTALLVENDORSCRIPT} ||= $Config{usevendorprefix}
1374                                        ? $Config{installscript}
1375                                        : '';
1376     }
1377
1378
1379     my $iprefix = $Config{installprefixexp} || $Config{installprefix} ||
1380                   $Config{prefixexp}        || $Config{prefix} || '';
1381     my $vprefix = $Config{usevendorprefix}  ? $Config{vendorprefixexp} : '';
1382     my $sprefix = $Config{siteprefixexp}    || '';
1383
1384     # 5.005_03 doesn't have a siteprefix.
1385     $sprefix = $iprefix unless $sprefix;
1386
1387
1388     $self->{PREFIX}       ||= '';
1389
1390     if( $self->{PREFIX} ) {
1391         @{$self}{qw(PERLPREFIX SITEPREFIX VENDORPREFIX)} =
1392           ('$(PREFIX)') x 3;
1393     }
1394     else {
1395         $self->{PERLPREFIX}   ||= $iprefix;
1396         $self->{SITEPREFIX}   ||= $sprefix;
1397         $self->{VENDORPREFIX} ||= $vprefix;
1398
1399         # Lots of MM extension authors like to use $(PREFIX) so we
1400         # put something sensible in there no matter what.
1401         $self->{PREFIX} = '$('.uc $self->{INSTALLDIRS}.'PREFIX)';
1402     }
1403
1404     my $arch    = $Config{archname};
1405     my $version = $Config{version};
1406
1407     # default style
1408     my $libstyle = $Config{installstyle} || 'lib/perl5';
1409     my $manstyle = '';
1410
1411     if( $self->{LIBSTYLE} ) {
1412         $libstyle = $self->{LIBSTYLE};
1413         $manstyle = $self->{LIBSTYLE} eq 'lib/perl5' ? 'lib/perl5' : '';
1414     }
1415
1416     # Some systems, like VOS, set installman*dir to '' if they can't
1417     # read man pages.
1418     for my $num (1, 3) {
1419         $self->{'INSTALLMAN'.$num.'DIR'} ||= 'none'
1420           unless $Config{'installman'.$num.'dir'};
1421     }
1422
1423     my %bin_layouts =
1424     (
1425         bin         => { s => $iprefix,
1426                          t => 'perl',
1427                          d => 'bin' },
1428         vendorbin   => { s => $vprefix,
1429                          t => 'vendor',
1430                          d => 'bin' },
1431         sitebin     => { s => $sprefix,
1432                          t => 'site',
1433                          d => 'bin' },
1434         script      => { s => $iprefix,
1435                          t => 'perl',
1436                          d => 'bin' },
1437         vendorscript=> { s => $vprefix,
1438                          t => 'vendor',
1439                          d => 'bin' },
1440         sitescript  => { s => $sprefix,
1441                          t => 'site',
1442                          d => 'bin' },
1443     );
1444
1445     my %man_layouts =
1446     (
1447         man1dir         => { s => $iprefix,
1448                              t => 'perl',
1449                              d => 'man/man1',
1450                              style => $manstyle, },
1451         siteman1dir     => { s => $sprefix,
1452                              t => 'site',
1453                              d => 'man/man1',
1454                              style => $manstyle, },
1455         vendorman1dir   => { s => $vprefix,
1456                              t => 'vendor',
1457                              d => 'man/man1',
1458                              style => $manstyle, },
1459
1460         man3dir         => { s => $iprefix,
1461                              t => 'perl',
1462                              d => 'man/man3',
1463                              style => $manstyle, },
1464         siteman3dir     => { s => $sprefix,
1465                              t => 'site',
1466                              d => 'man/man3',
1467                              style => $manstyle, },
1468         vendorman3dir   => { s => $vprefix,
1469                              t => 'vendor',
1470                              d => 'man/man3',
1471                              style => $manstyle, },
1472     );
1473
1474     my %lib_layouts =
1475     (
1476         privlib     => { s => $iprefix,
1477                          t => 'perl',
1478                          d => '',
1479                          style => $libstyle, },
1480         vendorlib   => { s => $vprefix,
1481                          t => 'vendor',
1482                          d => '',
1483                          style => $libstyle, },
1484         sitelib     => { s => $sprefix,
1485                          t => 'site',
1486                          d => 'site_perl',
1487                          style => $libstyle, },
1488
1489         archlib     => { s => $iprefix,
1490                          t => 'perl',
1491                          d => "$version/$arch",
1492                          style => $libstyle },
1493         vendorarch  => { s => $vprefix,
1494                          t => 'vendor',
1495                          d => "$version/$arch",
1496                          style => $libstyle },
1497         sitearch    => { s => $sprefix,
1498                          t => 'site',
1499                          d => "site_perl/$version/$arch",
1500                          style => $libstyle },
1501     );
1502
1503
1504     # Special case for LIB.
1505     if( $self->{LIB} ) {
1506         foreach my $var (keys %lib_layouts) {
1507             my $Installvar = uc "install$var";
1508
1509             if( $var =~ /arch/ ) {
1510                 $self->{$Installvar} ||=
1511                   $self->catdir($self->{LIB}, $Config{archname});
1512             }
1513             else {
1514                 $self->{$Installvar} ||= $self->{LIB};
1515             }
1516         }
1517     }
1518
1519     my %type2prefix = ( perl    => 'PERLPREFIX',
1520                         site    => 'SITEPREFIX',
1521                         vendor  => 'VENDORPREFIX'
1522                       );
1523
1524     my %layouts = (%bin_layouts, %man_layouts, %lib_layouts);
1525     while( my($var, $layout) = each(%layouts) ) {
1526         my($s, $t, $d, $style) = @{$layout}{qw(s t d style)};
1527         my $r = '$('.$type2prefix{$t}.')';
1528
1529         print STDERR "Prefixing $var\n" if $Verbose >= 2;
1530
1531         my $installvar = "install$var";
1532         my $Installvar = uc $installvar;
1533         next if $self->{$Installvar};
1534
1535         $d = "$style/$d" if $style;
1536         $self->prefixify($installvar, $s, $r, $d);
1537
1538         print STDERR "  $Installvar == $self->{$Installvar}\n"
1539           if $Verbose >= 2;
1540     }
1541
1542     # Generate these if they weren't figured out.
1543     $self->{VENDORARCHEXP} ||= $self->{INSTALLVENDORARCH};
1544     $self->{VENDORLIBEXP}  ||= $self->{INSTALLVENDORLIB};
1545
1546     return 1;
1547 }
1548
1549
1550 =head3 init_from_INSTALL_BASE
1551
1552     $mm->init_from_INSTALL_BASE
1553
1554 =cut
1555
1556 my %map = (
1557            lib      => [qw(lib perl5)],
1558            arch     => [('lib', 'perl5', $Config{archname})],
1559            bin      => [qw(bin)],
1560            man1dir  => [qw(man man1)],
1561            man3dir  => [qw(man man3)]
1562           );
1563 $map{script} = $map{bin};
1564
1565 sub init_INSTALL_from_INSTALL_BASE {
1566     my $self = shift;
1567
1568     @{$self}{qw(PREFIX VENDORPREFIX SITEPREFIX PERLPREFIX)} =
1569                                                          '$(INSTALL_BASE)';
1570
1571     my %install;
1572     foreach my $thing (keys %map) {
1573         foreach my $dir (('', 'SITE', 'VENDOR')) {
1574             my $uc_thing = uc $thing;
1575             my $key = "INSTALL".$dir.$uc_thing;
1576
1577             $install{$key} ||=
1578               $self->catdir('$(INSTALL_BASE)', @{$map{$thing}});
1579         }
1580     }
1581
1582     # Adjust for variable quirks.
1583     $install{INSTALLARCHLIB} ||= delete $install{INSTALLARCH};
1584     $install{INSTALLPRIVLIB} ||= delete $install{INSTALLLIB};
1585
1586     foreach my $key (keys %install) {
1587         $self->{$key} ||= $install{$key};
1588     }
1589
1590     return 1;
1591 }
1592
1593
1594 =head3 init_VERSION  I<Abstract>
1595
1596     $mm->init_VERSION
1597
1598 Initialize macros representing versions of MakeMaker and other tools
1599
1600 MAKEMAKER: path to the MakeMaker module.
1601
1602 MM_VERSION: ExtUtils::MakeMaker Version
1603
1604 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
1605              compat)
1606
1607 VERSION: version of your module
1608
1609 VERSION_MACRO: which macro represents the version (usually 'VERSION')
1610
1611 VERSION_SYM: like version but safe for use as an RCS revision number
1612
1613 DEFINE_VERSION: -D line to set the module version when compiling
1614
1615 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
1616
1617 XS_VERSION_MACRO: which macro represents the XS version.
1618
1619 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
1620
1621 Called by init_main.
1622
1623 =cut
1624
1625 sub init_VERSION {
1626     my($self) = shift;
1627
1628     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
1629     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
1630     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
1631     $self->{VERSION_FROM} ||= '';
1632
1633     if ($self->{VERSION_FROM}){
1634         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
1635         if( $self->{VERSION} eq 'undef' ) {
1636             carp("WARNING: Setting VERSION via file ".
1637                  "'$self->{VERSION_FROM}' failed\n");
1638         }
1639     }
1640
1641     # strip blanks
1642     if (defined $self->{VERSION}) {
1643         $self->{VERSION} =~ s/^\s+//;
1644         $self->{VERSION} =~ s/\s+$//;
1645     }
1646     else {
1647         $self->{VERSION} = '';
1648     }
1649
1650
1651     $self->{VERSION_MACRO}  = 'VERSION';
1652     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
1653     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
1654
1655
1656     # Graham Barr and Paul Marquess had some ideas how to ensure
1657     # version compatibility between the *.pm file and the
1658     # corresponding *.xs file. The bottomline was, that we need an
1659     # XS_VERSION macro that defaults to VERSION:
1660     $self->{XS_VERSION} ||= $self->{VERSION};
1661
1662     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
1663     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
1664
1665 }
1666
1667
1668 =head3 init_others  I<Abstract>
1669
1670     $MM->init_others();
1671
1672 Initializes the macro definitions used by tools_other() and places them
1673 in the $MM object.
1674
1675 If there is no description, its the same as the parameter to
1676 WriteMakefile() documented in ExtUtils::MakeMaker.
1677
1678 Defines at least these macros.
1679
1680   Macro             Description
1681
1682   NOOP              Do nothing
1683   NOECHO            Tell make not to display the command itself
1684
1685   MAKEFILE
1686   FIRST_MAKEFILE
1687   MAKEFILE_OLD
1688   MAKE_APERL_FILE   File used by MAKE_APERL
1689
1690   SHELL             Program used to run shell commands
1691
1692   ECHO              Print text adding a newline on the end
1693   RM_F              Remove a file
1694   RM_RF             Remove a directory
1695   TOUCH             Update a file's timestamp
1696   TEST_F            Test for a file's existence
1697   CP                Copy a file
1698   MV                Move a file
1699   CHMOD             Change permissions on a
1700                     file
1701
1702   UMASK_NULL        Nullify umask
1703   DEV_NULL          Suppress all command output
1704
1705
1706 =head3 init_DIRFILESEP  I<Abstract>
1707
1708   $MM->init_DIRFILESEP;
1709   my $dirfilesep = $MM->{DIRFILESEP};
1710
1711 Initializes the DIRFILESEP macro which is the seperator between the
1712 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
1713 nothing on VMS.
1714
1715 For example:
1716
1717     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
1718     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
1719
1720 Something of a hack but it prevents a lot of code duplication between
1721 MM_* variants.
1722
1723 Do not use this as a seperator between directories.  Some operating
1724 systems use different seperators between subdirectories as between
1725 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
1726
1727 =head3 init_linker  I<Abstract>
1728
1729     $mm->init_linker;
1730
1731 Initialize macros which have to do with linking.
1732
1733 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
1734 extensions.
1735
1736 PERL_ARCHIVE_AFTER: path to a library which should be put on the
1737 linker command line I<after> the external libraries to be linked to
1738 dynamic extensions.  This may be needed if the linker is one-pass, and
1739 Perl includes some overrides for C RTL functions, such as malloc().
1740
1741 EXPORT_LIST: name of a file that is passed to linker to define symbols
1742 to be exported.
1743
1744 Some OSes do not need these in which case leave it blank.
1745
1746
1747 =head3 init_platform
1748
1749     $mm->init_platform
1750
1751 Initialize any macros which are for platform specific use only.
1752
1753 A typical one is the version number of your OS specific mocule.
1754 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
1755
1756 =cut
1757
1758 sub init_platform {
1759     return '';
1760 }
1761
1762
1763 =head3 init_MAKE
1764
1765     $mm->init_MAKE
1766
1767 Initialize MAKE from either a MAKE environment variable or $Config{make}.
1768
1769 =cut
1770
1771 sub init_MAKE {
1772     my $self = shift;
1773
1774     $self->{MAKE} ||= $ENV{MAKE} || $Config{make};
1775 }
1776
1777
1778 =head2 Tools
1779
1780 A grab bag of methods to generate specific macros and commands.
1781
1782
1783
1784 =head3 manifypods
1785
1786 Defines targets and routines to translate the pods into manpages and
1787 put them into the INST_* directories.
1788
1789 =cut
1790
1791 sub manifypods {
1792     my $self          = shift;
1793
1794     my $POD2MAN_macro = $self->POD2MAN_macro();
1795     my $manifypods_target = $self->manifypods_target();
1796
1797     return <<END_OF_TARGET;
1798
1799 $POD2MAN_macro
1800
1801 $manifypods_target
1802
1803 END_OF_TARGET
1804
1805 }
1806
1807
1808 =head3 POD2MAN_macro
1809
1810   my $pod2man_macro = $self->POD2MAN_macro
1811
1812 Returns a definition for the POD2MAN macro.  This is a program
1813 which emulates the pod2man utility.  You can add more switches to the
1814 command by simply appending them on the macro.
1815
1816 Typical usage:
1817
1818     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
1819
1820 =cut
1821
1822 sub POD2MAN_macro {
1823     my $self = shift;
1824
1825 # Need the trailing '--' so perl stops gobbling arguments and - happens
1826 # to be an alternative end of line seperator on VMS so we quote it
1827     return <<'END_OF_DEF';
1828 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
1829 POD2MAN = $(POD2MAN_EXE)
1830 END_OF_DEF
1831 }
1832
1833
1834 =head3 test_via_harness
1835
1836   my $command = $mm->test_via_harness($perl, $tests);
1837
1838 Returns a $command line which runs the given set of $tests with
1839 Test::Harness and the given $perl.
1840
1841 Used on the t/*.t files.
1842
1843 =cut
1844
1845 sub test_via_harness {
1846     my($self, $perl, $tests) = @_;
1847
1848     return qq{\t$perl "-MExtUtils::Command::MM" }.
1849            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
1850 }
1851
1852 =head3 test_via_script
1853
1854   my $command = $mm->test_via_script($perl, $script);
1855
1856 Returns a $command line which just runs a single test without
1857 Test::Harness.  No checks are done on the results, they're just
1858 printed.
1859
1860 Used for test.pl, since they don't always follow Test::Harness
1861 formatting.
1862
1863 =cut
1864
1865 sub test_via_script {
1866     my($self, $perl, $script) = @_;
1867     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
1868 }
1869
1870
1871 =head3 tool_autosplit
1872
1873 Defines a simple perl call that runs autosplit. May be deprecated by
1874 pm_to_blib soon.
1875
1876 =cut
1877
1878 sub tool_autosplit {
1879     my($self, %attribs) = @_;
1880
1881     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
1882                                   : '';
1883
1884     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
1885 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
1886 PERL_CODE
1887
1888     return sprintf <<'MAKE_FRAG', $asplit;
1889 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
1890 AUTOSPLITFILE = %s
1891
1892 MAKE_FRAG
1893
1894 }
1895
1896
1897
1898
1899 =head2 File::Spec wrappers
1900
1901 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
1902 override File::Spec.
1903
1904
1905
1906 =head3 catfile
1907
1908 File::Spec <= 0.83 has a bug where the file part of catfile is not
1909 canonicalized.  This override fixes that bug.
1910
1911 =cut
1912
1913 sub catfile {
1914     my $self = shift;
1915     return $self->canonpath($self->SUPER::catfile(@_));
1916 }
1917
1918
1919
1920 =head2 Misc
1921
1922 Methods I can't really figure out where they should go yet.
1923
1924
1925 =head3 find_tests
1926
1927   my $test = $mm->find_tests;
1928
1929 Returns a string suitable for feeding to the shell to return all
1930 tests in t/*.t.
1931
1932 =cut
1933
1934 sub find_tests {
1935     my($self) = shift;
1936     return -d 't' ? 't/*.t' : '';
1937 }
1938
1939
1940 =head3 extra_clean_files
1941
1942     my @files_to_clean = $MM->extra_clean_files;
1943
1944 Returns a list of OS specific files to be removed in the clean target in
1945 addition to the usual set.
1946
1947 =cut
1948
1949 # An empty method here tickled a perl 5.8.1 bug and would return its object.
1950 sub extra_clean_files {
1951     return;
1952 }
1953
1954
1955 =head3 installvars
1956
1957     my @installvars = $mm->installvars;
1958
1959 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
1960 for iteration or building related variable sets.
1961
1962 =cut
1963
1964 sub installvars {
1965     return qw(PRIVLIB SITELIB  VENDORLIB
1966               ARCHLIB SITEARCH VENDORARCH
1967               BIN     SITEBIN  VENDORBIN
1968               SCRIPT  SITESCRIPT  VENDORSCRIPT
1969               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
1970               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
1971              );
1972 }
1973
1974
1975 =head3 libscan
1976
1977   my $wanted = $self->libscan($path);
1978
1979 Takes a path to a file or dir and returns an empty string if we don't
1980 want to include this file in the library.  Otherwise it returns the
1981 the $path unchanged.
1982
1983 Mainly used to exclude version control administrative directories from
1984 installation.
1985
1986 =cut
1987
1988 sub libscan {
1989     my($self,$path) = @_;
1990     my($dirs,$file) = ($self->splitpath($path))[1,2];
1991     return '' if grep /^(?:RCS|CVS|SCCS|\.svn|_darcs)$/,
1992                      $self->splitdir($dirs), $file;
1993
1994     return $path;
1995 }
1996
1997
1998 =head3 platform_constants
1999
2000     my $make_frag = $mm->platform_constants
2001
2002 Returns a make fragment defining all the macros initialized in
2003 init_platform() rather than put them in constants().
2004
2005 =cut
2006
2007 sub platform_constants {
2008     return '';
2009 }
2010
2011
2012 =head1 AUTHOR
2013
2014 Michael G Schwern <schwern@pobox.com> and the denizens of
2015 makemaker@perl.org with code from ExtUtils::MM_Unix and
2016 ExtUtils::MM_Win32.
2017
2018
2019 =cut
2020
2021 1;