lib/ExtUtils/MM_Any.pm

   1 package ExtUtils::MM_Any;
   2
   3 use strict;
   4 our $VERSION = '6.44';
   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 $prereq_pm = '';
 736     foreach my $mod ( sort { lc $a cmp lc $b } keys %{$self->{PREREQ_PM}} ) {
 737         my $ver = $self->{PREREQ_PM}{$mod};
 738         $prereq_pm .= sprintf "\n    %-30s %s", "$mod:", $ver;
 739     }
 740
 741     my $author_value = defined $self->{AUTHOR}
 742         ? "\n    - $self->{AUTHOR}"
 743         : undef;
 744
 745     # Use a list to preserve order.
 746     my @meta_to_mm = (
 747         name         => $self->{DISTNAME},
 748         version      => $self->{VERSION},
 749         abstract     => $self->{ABSTRACT},
 750         license      => $self->{LICENSE},
 751         author       => $author_value,
 752         generated_by =>
 753                 "ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION",
 754         distribution_type => $self->{PM} ? 'module' : 'script',
 755     );
 756
 757     my $meta = "--- #YAML:1.0\n";
 758
 759     while( @meta_to_mm ) {
 760         my($key, $val) = splice @meta_to_mm, 0, 2;
 761
 762         $val = '~' unless defined $val;
 763
 764         $meta .= sprintf "%-20s %s\n", "$key:", $val;
 765     };
 766
 767     $meta .= <<"YAML";
 768 requires:     $prereq_pm
 769 meta-spec:
 770     url:     http://module-build.sourceforge.net/META-spec-v1.3.html
 771     version: 1.3
 772 YAML
 773
 774     $meta .= $self->{EXTRA_META} if $self->{EXTRA_META};
 775
 776     my @write_meta = $self->echo($meta, 'META_new.yml');
 777
 778     return sprintf <<'MAKE_FRAG', join("\n\t", @write_meta);
 779 metafile : create_distdir
 780         $(NOECHO) $(ECHO) Generating META.yml
 781         %s
 782         -$(NOECHO) $(MV) META_new.yml $(DISTVNAME)/META.yml
 783 MAKE_FRAG
 784
 785 }
 786
 787
 788 =head3 distmeta_target
 789
 790     my $make_frag = $mm->distmeta_target;
 791
 792 Generates the distmeta target to add META.yml to the MANIFEST in the
 793 distdir.
 794
 795 =cut
 796
 797 sub distmeta_target {
 798     my $self = shift;
 799
 800     my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
 801 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
 802     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
 803 CODE
 804
 805     my $add_meta_to_distdir = $self->cd('$(DISTVNAME)', $add_meta);
 806
 807     return sprintf <<'MAKE', $add_meta_to_distdir;
 808 distmeta : create_distdir metafile
 809         $(NOECHO) %s
 810
 811 MAKE
 812
 813 }
 814
 815
 816 =head3 realclean (o)
 817
 818 Defines the realclean target.
 819
 820 =cut
 821
 822 sub realclean {
 823     my($self, %attribs) = @_;
 824
 825     my @dirs  = qw($(DISTVNAME));
 826     my @files = qw($(FIRST_MAKEFILE) $(MAKEFILE_OLD));
 827
 828     # Special exception for the perl core where INST_* is not in blib.
 829     # This cleans up the files built from the ext/ directory (all XS).
 830     if( $self->{PERL_CORE} ) {
 831         push @dirs, qw($(INST_AUTODIR) $(INST_ARCHAUTODIR));
 832         push @files, values %{$self->{PM}};
 833     }
 834
 835     if( $self->has_link_code ){
 836         push @files, qw($(OBJECT));
 837     }
 838
 839     if( $attribs{FILES} ) {
 840         if( ref $attribs{FILES} ) {
 841             push @dirs, @{ $attribs{FILES} };
 842         }
 843         else {
 844             push @dirs, split /\s+/, $attribs{FILES};
 845         }
 846     }
 847
 848     # Occasionally files are repeated several times from different sources
 849     { my(%f) = map { ($_ => 1) } @files;  @files = keys %f; }
 850     { my(%d) = map { ($_ => 1) } @dirs;   @dirs  = keys %d; }
 851
 852     my $rm_cmd  = join "\n\t", map { "$_" }
 853                     $self->split_command('- $(RM_F)',  @files);
 854     my $rmf_cmd = join "\n\t", map { "$_" }
 855                     $self->split_command('- $(RM_RF)', @dirs);
 856
 857     my $m = sprintf <<'MAKE', $rm_cmd, $rmf_cmd;
 858 # Delete temporary files (via clean) and also delete dist files
 859 realclean purge ::  clean realclean_subdirs
 860         %s
 861         %s
 862 MAKE
 863
 864     $m .= "\t$attribs{POSTOP}\n" if $attribs{POSTOP};
 865
 866     return $m;
 867 }
 868
 869
 870 =head3 realclean_subdirs_target
 871
 872   my $make_frag = $MM->realclean_subdirs_target;
 873
 874 Returns the realclean_subdirs target.  This is used by the realclean
 875 target to call realclean on any subdirectories which contain Makefiles.
 876
 877 =cut
 878
 879 sub realclean_subdirs_target {
 880     my $self = shift;
 881
 882     return <<'NOOP_FRAG' unless @{$self->{DIR}};
 883 realclean_subdirs :
 884         $(NOECHO) $(NOOP)
 885 NOOP_FRAG
 886
 887     my $rclean = "realclean_subdirs :\n";
 888
 889     foreach my $dir (@{$self->{DIR}}) {
 890         foreach my $makefile ('$(MAKEFILE_OLD)', '$(FIRST_MAKEFILE)' ) {
 891             my $subrclean .= $self->oneliner(sprintf <<'CODE', $dir, ($makefile) x 2);
 892 chdir '%s';  system '$(MAKE) $(USEMAKEFILE) %s realclean' if -f '%s';
 893 CODE
 894
 895             $rclean .= sprintf <<'RCLEAN', $subrclean;
 896         - %s
 897 RCLEAN
 898
 899         }
 900     }
 901
 902     return $rclean;
 903 }
 904
 905
 906 =head3 signature_target
 907
 908     my $target = $mm->signature_target;
 909
 910 Generate the signature target.
 911
 912 Writes the file SIGNATURE with "cpansign -s".
 913
 914 =cut
 915
 916 sub signature_target {
 917     my $self = shift;
 918
 919     return <<'MAKE_FRAG';
 920 signature :
 921         cpansign -s
 922 MAKE_FRAG
 923
 924 }
 925
 926
 927 =head3 distsignature_target
 928
 929     my $make_frag = $mm->distsignature_target;
 930
 931 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
 932 distdir.
 933
 934 =cut
 935
 936 sub distsignature_target {
 937     my $self = shift;
 938
 939     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
 940 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
 941     or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
 942 CODE
 943
 944     my $sign_dist        = $self->cd('$(DISTVNAME)' => 'cpansign -s');
 945
 946     # cpansign -s complains if SIGNATURE is in the MANIFEST yet does not
 947     # exist
 948     my $touch_sig        = $self->cd('$(DISTVNAME)' => '$(TOUCH) SIGNATURE');
 949     my $add_sign_to_dist = $self->cd('$(DISTVNAME)' => $add_sign );
 950
 951     return sprintf <<'MAKE', $add_sign_to_dist, $touch_sig, $sign_dist
 952 distsignature : create_distdir
 953         $(NOECHO) %s
 954         $(NOECHO) %s
 955         %s
 956
 957 MAKE
 958
 959 }
 960
 961
 962 =head3 special_targets
 963
 964   my $make_frag = $mm->special_targets
 965
 966 Returns a make fragment containing any targets which have special
 967 meaning to make.  For example, .SUFFIXES and .PHONY.
 968
 969 =cut
 970
 971 sub special_targets {
 972     my $make_frag = <<'MAKE_FRAG';
 973 .SUFFIXES : .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
 974
 975 .PHONY: all config static dynamic test linkext manifest blibdirs clean realclean disttest distdir
 976
 977 MAKE_FRAG
 978
 979     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
 980 .NO_CONFIG_REC: Makefile
 981
 982 MAKE_FRAG
 983
 984     return $make_frag;
 985 }
 986
 987
 988
 989
 990 =head2 Init methods
 991
 992 Methods which help initialize the MakeMaker object and macros.
 993
 994
 995 =head3 init_ABSTRACT
 996
 997     $mm->init_ABSTRACT
 998
 999 =cut
1000
1001 sub init_ABSTRACT {
1002     my $self = shift;
1003
1004     if( $self->{ABSTRACT_FROM} and $self->{ABSTRACT} ) {
1005         warn "Both ABSTRACT_FROM and ABSTRACT are set.  ".
1006              "Ignoring ABSTRACT_FROM.\n";
1007         return;
1008     }
1009
1010     if ($self->{ABSTRACT_FROM}){
1011         $self->{ABSTRACT} = $self->parse_abstract($self->{ABSTRACT_FROM}) or
1012             carp "WARNING: Setting ABSTRACT via file ".
1013                  "'$self->{ABSTRACT_FROM}' failed\n";
1014     }
1015 }
1016
1017 =head3 init_INST
1018
1019     $mm->init_INST;
1020
1021 Called by init_main.  Sets up all INST_* variables except those related
1022 to XS code.  Those are handled in init_xs.
1023
1024 =cut
1025
1026 sub init_INST {
1027     my($self) = shift;
1028
1029     $self->{INST_ARCHLIB} ||= $self->catdir($Curdir,"blib","arch");
1030     $self->{INST_BIN}     ||= $self->catdir($Curdir,'blib','bin');
1031
1032     # INST_LIB typically pre-set if building an extension after
1033     # perl has been built and installed. Setting INST_LIB allows
1034     # you to build directly into, say $Config{privlibexp}.
1035     unless ($self->{INST_LIB}){
1036         if ($self->{PERL_CORE}) {
1037             if (defined $Cross::platform) {
1038                 $self->{INST_LIB} = $self->{INST_ARCHLIB} =
1039                   $self->catdir($self->{PERL_LIB},"..","xlib",
1040                                      $Cross::platform);
1041             }
1042             else {
1043                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = $self->{PERL_LIB};
1044             }
1045         } else {
1046             $self->{INST_LIB} = $self->catdir($Curdir,"blib","lib");
1047         }
1048     }
1049
1050     my @parentdir = split(/::/, $self->{PARENT_NAME});
1051     $self->{INST_LIBDIR}      = $self->catdir('$(INST_LIB)',     @parentdir);
1052     $self->{INST_ARCHLIBDIR}  = $self->catdir('$(INST_ARCHLIB)', @parentdir);
1053     $self->{INST_AUTODIR}     = $self->catdir('$(INST_LIB)', 'auto',
1054                                               '$(FULLEXT)');
1055     $self->{INST_ARCHAUTODIR} = $self->catdir('$(INST_ARCHLIB)', 'auto',
1056                                               '$(FULLEXT)');
1057
1058     $self->{INST_SCRIPT}  ||= $self->catdir($Curdir,'blib','script');
1059
1060     $self->{INST_MAN1DIR} ||= $self->catdir($Curdir,'blib','man1');
1061     $self->{INST_MAN3DIR} ||= $self->catdir($Curdir,'blib','man3');
1062
1063     return 1;
1064 }
1065
1066
1067 =head3 init_INSTALL
1068
1069     $mm->init_INSTALL;
1070
1071 Called by init_main.  Sets up all INSTALL_* variables (except
1072 INSTALLDIRS) and *PREFIX.
1073
1074 =cut
1075
1076 sub init_INSTALL {
1077     my($self) = shift;
1078
1079     if( $self->{ARGS}{INSTALL_BASE} and $self->{ARGS}{PREFIX} ) {
1080         die "Only one of PREFIX or INSTALL_BASE can be given.  Not both.\n";
1081     }
1082
1083     if( $self->{ARGS}{INSTALL_BASE} ) {
1084         $self->init_INSTALL_from_INSTALL_BASE;
1085     }
1086     else {
1087         $self->init_INSTALL_from_PREFIX;
1088     }
1089 }
1090
1091
1092 =head3 init_INSTALL_from_PREFIX
1093
1094   $mm->init_INSTALL_from_PREFIX;
1095
1096 =cut
1097
1098 sub init_INSTALL_from_PREFIX {
1099     my $self = shift;
1100
1101     $self->init_lib2arch;
1102
1103     # There are often no Config.pm defaults for these new man variables so
1104     # we fall back to the old behavior which is to use installman*dir
1105     foreach my $num (1, 3) {
1106         my $k = 'installsiteman'.$num.'dir';
1107
1108         $self->{uc $k} ||= uc "\$(installman${num}dir)"
1109           unless $Config{$k};
1110     }
1111
1112     foreach my $num (1, 3) {
1113         my $k = 'installvendorman'.$num.'dir';
1114
1115         unless( $Config{$k} ) {
1116             $self->{uc $k}  ||= $Config{usevendorprefix}
1117                               ? uc "\$(installman${num}dir)"
1118                               : '';
1119         }
1120     }
1121
1122     $self->{INSTALLSITEBIN} ||= '$(INSTALLBIN)'
1123       unless $Config{installsitebin};
1124     $self->{INSTALLSITESCRIPT} ||= '$(INSTALLSCRIPT)'
1125       unless $Config{installsitescript};
1126
1127     unless( $Config{installvendorbin} ) {
1128         $self->{INSTALLVENDORBIN} ||= $Config{usevendorprefix}
1129                                     ? $Config{installbin}
1130                                     : '';
1131     }
1132     unless( $Config{installvendorscript} ) {
1133         $self->{INSTALLVENDORSCRIPT} ||= $Config{usevendorprefix}
1134                                        ? $Config{installscript}
1135                                        : '';
1136     }
1137
1138
1139     my $iprefix = $Config{installprefixexp} || $Config{installprefix} ||
1140                   $Config{prefixexp}        || $Config{prefix} || '';
1141     my $vprefix = $Config{usevendorprefix}  ? $Config{vendorprefixexp} : '';
1142     my $sprefix = $Config{siteprefixexp}    || '';
1143
1144     # 5.005_03 doesn't have a siteprefix.
1145     $sprefix = $iprefix unless $sprefix;
1146
1147
1148     $self->{PREFIX}       ||= '';
1149
1150     if( $self->{PREFIX} ) {
1151         @{$self}{qw(PERLPREFIX SITEPREFIX VENDORPREFIX)} =
1152           ('$(PREFIX)') x 3;
1153     }
1154     else {
1155         $self->{PERLPREFIX}   ||= $iprefix;
1156         $self->{SITEPREFIX}   ||= $sprefix;
1157         $self->{VENDORPREFIX} ||= $vprefix;
1158
1159         # Lots of MM extension authors like to use $(PREFIX) so we
1160         # put something sensible in there no matter what.
1161         $self->{PREFIX} = '$('.uc $self->{INSTALLDIRS}.'PREFIX)';
1162     }
1163
1164     my $arch    = $Config{archname};
1165     my $version = $Config{version};
1166
1167     # default style
1168     my $libstyle = $Config{installstyle} || 'lib/perl5';
1169     my $manstyle = '';
1170
1171     if( $self->{LIBSTYLE} ) {
1172         $libstyle = $self->{LIBSTYLE};
1173         $manstyle = $self->{LIBSTYLE} eq 'lib/perl5' ? 'lib/perl5' : '';
1174     }
1175
1176     # Some systems, like VOS, set installman*dir to '' if they can't
1177     # read man pages.
1178     for my $num (1, 3) {
1179         $self->{'INSTALLMAN'.$num.'DIR'} ||= 'none'
1180           unless $Config{'installman'.$num.'dir'};
1181     }
1182
1183     my %bin_layouts =
1184     (
1185         bin         => { s => $iprefix,
1186                          t => 'perl',
1187                          d => 'bin' },
1188         vendorbin   => { s => $vprefix,
1189                          t => 'vendor',
1190                          d => 'bin' },
1191         sitebin     => { s => $sprefix,
1192                          t => 'site',
1193                          d => 'bin' },
1194         script      => { s => $iprefix,
1195                          t => 'perl',
1196                          d => 'bin' },
1197         vendorscript=> { s => $vprefix,
1198                          t => 'vendor',
1199                          d => 'bin' },
1200         sitescript  => { s => $sprefix,
1201                          t => 'site',
1202                          d => 'bin' },
1203     );
1204
1205     my %man_layouts =
1206     (
1207         man1dir         => { s => $iprefix,
1208                              t => 'perl',
1209                              d => 'man/man1',
1210                              style => $manstyle, },
1211         siteman1dir     => { s => $sprefix,
1212                              t => 'site',
1213                              d => 'man/man1',
1214                              style => $manstyle, },
1215         vendorman1dir   => { s => $vprefix,
1216                              t => 'vendor',
1217                              d => 'man/man1',
1218                              style => $manstyle, },
1219
1220         man3dir         => { s => $iprefix,
1221                              t => 'perl',
1222                              d => 'man/man3',
1223                              style => $manstyle, },
1224         siteman3dir     => { s => $sprefix,
1225                              t => 'site',
1226                              d => 'man/man3',
1227                              style => $manstyle, },
1228         vendorman3dir   => { s => $vprefix,
1229                              t => 'vendor',
1230                              d => 'man/man3',
1231                              style => $manstyle, },
1232     );
1233
1234     my %lib_layouts =
1235     (
1236         privlib     => { s => $iprefix,
1237                          t => 'perl',
1238                          d => '',
1239                          style => $libstyle, },
1240         vendorlib   => { s => $vprefix,
1241                          t => 'vendor',
1242                          d => '',
1243                          style => $libstyle, },
1244         sitelib     => { s => $sprefix,
1245                          t => 'site',
1246                          d => 'site_perl',
1247                          style => $libstyle, },
1248
1249         archlib     => { s => $iprefix,
1250                          t => 'perl',
1251                          d => "$version/$arch",
1252                          style => $libstyle },
1253         vendorarch  => { s => $vprefix,
1254                          t => 'vendor',
1255                          d => "$version/$arch",
1256                          style => $libstyle },
1257         sitearch    => { s => $sprefix,
1258                          t => 'site',
1259                          d => "site_perl/$version/$arch",
1260                          style => $libstyle },
1261     );
1262
1263
1264     # Special case for LIB.
1265     if( $self->{LIB} ) {
1266         foreach my $var (keys %lib_layouts) {
1267             my $Installvar = uc "install$var";
1268
1269             if( $var =~ /arch/ ) {
1270                 $self->{$Installvar} ||=
1271                   $self->catdir($self->{LIB}, $Config{archname});
1272             }
1273             else {
1274                 $self->{$Installvar} ||= $self->{LIB};
1275             }
1276         }
1277     }
1278
1279     my %type2prefix = ( perl    => 'PERLPREFIX',
1280                         site    => 'SITEPREFIX',
1281                         vendor  => 'VENDORPREFIX'
1282                       );
1283
1284     my %layouts = (%bin_layouts, %man_layouts, %lib_layouts);
1285     while( my($var, $layout) = each(%layouts) ) {
1286         my($s, $t, $d, $style) = @{$layout}{qw(s t d style)};
1287         my $r = '$('.$type2prefix{$t}.')';
1288
1289         print STDERR "Prefixing $var\n" if $Verbose >= 2;
1290
1291         my $installvar = "install$var";
1292         my $Installvar = uc $installvar;
1293         next if $self->{$Installvar};
1294
1295         $d = "$style/$d" if $style;
1296         $self->prefixify($installvar, $s, $r, $d);
1297
1298         print STDERR "  $Installvar == $self->{$Installvar}\n"
1299           if $Verbose >= 2;
1300     }
1301
1302     # Generate these if they weren't figured out.
1303     $self->{VENDORARCHEXP} ||= $self->{INSTALLVENDORARCH};
1304     $self->{VENDORLIBEXP}  ||= $self->{INSTALLVENDORLIB};
1305
1306     return 1;
1307 }
1308
1309
1310 =head3 init_from_INSTALL_BASE
1311
1312     $mm->init_from_INSTALL_BASE
1313
1314 =cut
1315
1316 my %map = (
1317            lib      => [qw(lib perl5)],
1318            arch     => [('lib', 'perl5', $Config{archname})],
1319            bin      => [qw(bin)],
1320            man1dir  => [qw(man man1)],
1321            man3dir  => [qw(man man3)]
1322           );
1323 $map{script} = $map{bin};
1324
1325 sub init_INSTALL_from_INSTALL_BASE {
1326     my $self = shift;
1327
1328     @{$self}{qw(PREFIX VENDORPREFIX SITEPREFIX PERLPREFIX)} =
1329                                                          '$(INSTALL_BASE)';
1330
1331     my %install;
1332     foreach my $thing (keys %map) {
1333         foreach my $dir (('', 'SITE', 'VENDOR')) {
1334             my $uc_thing = uc $thing;
1335             my $key = "INSTALL".$dir.$uc_thing;
1336
1337             $install{$key} ||=
1338               $self->catdir('$(INSTALL_BASE)', @{$map{$thing}});
1339         }
1340     }
1341
1342     # Adjust for variable quirks.
1343     $install{INSTALLARCHLIB} ||= delete $install{INSTALLARCH};
1344     $install{INSTALLPRIVLIB} ||= delete $install{INSTALLLIB};
1345
1346     foreach my $key (keys %install) {
1347         $self->{$key} ||= $install{$key};
1348     }
1349
1350     return 1;
1351 }
1352
1353
1354 =head3 init_VERSION  I<Abstract>
1355
1356     $mm->init_VERSION
1357
1358 Initialize macros representing versions of MakeMaker and other tools
1359
1360 MAKEMAKER: path to the MakeMaker module.
1361
1362 MM_VERSION: ExtUtils::MakeMaker Version
1363
1364 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
1365              compat)
1366
1367 VERSION: version of your module
1368
1369 VERSION_MACRO: which macro represents the version (usually 'VERSION')
1370
1371 VERSION_SYM: like version but safe for use as an RCS revision number
1372
1373 DEFINE_VERSION: -D line to set the module version when compiling
1374
1375 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
1376
1377 XS_VERSION_MACRO: which macro represents the XS version.
1378
1379 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
1380
1381 Called by init_main.
1382
1383 =cut
1384
1385 sub init_VERSION {
1386     my($self) = shift;
1387
1388     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
1389     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
1390     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
1391     $self->{VERSION_FROM} ||= '';
1392
1393     if ($self->{VERSION_FROM}){
1394         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
1395         if( $self->{VERSION} eq 'undef' ) {
1396             carp("WARNING: Setting VERSION via file ".
1397                  "'$self->{VERSION_FROM}' failed\n");
1398         }
1399     }
1400
1401     # strip blanks
1402     if (defined $self->{VERSION}) {
1403         $self->{VERSION} =~ s/^\s+//;
1404         $self->{VERSION} =~ s/\s+$//;
1405     }
1406     else {
1407         $self->{VERSION} = '';
1408     }
1409
1410
1411     $self->{VERSION_MACRO}  = 'VERSION';
1412     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
1413     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
1414
1415
1416     # Graham Barr and Paul Marquess had some ideas how to ensure
1417     # version compatibility between the *.pm file and the
1418     # corresponding *.xs file. The bottomline was, that we need an
1419     # XS_VERSION macro that defaults to VERSION:
1420     $self->{XS_VERSION} ||= $self->{VERSION};
1421
1422     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
1423     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
1424
1425 }
1426
1427
1428 =head3 init_others  I<Abstract>
1429
1430     $MM->init_others();
1431
1432 Initializes the macro definitions used by tools_other() and places them
1433 in the $MM object.
1434
1435 If there is no description, its the same as the parameter to
1436 WriteMakefile() documented in ExtUtils::MakeMaker.
1437
1438 Defines at least these macros.
1439
1440   Macro             Description
1441
1442   NOOP              Do nothing
1443   NOECHO            Tell make not to display the command itself
1444
1445   MAKEFILE
1446   FIRST_MAKEFILE
1447   MAKEFILE_OLD
1448   MAKE_APERL_FILE   File used by MAKE_APERL
1449
1450   SHELL             Program used to run shell commands
1451
1452   ECHO              Print text adding a newline on the end
1453   RM_F              Remove a file
1454   RM_RF             Remove a directory
1455   TOUCH             Update a file's timestamp
1456   TEST_F            Test for a file's existence
1457   CP                Copy a file
1458   MV                Move a file
1459   CHMOD             Change permissions on a
1460                     file
1461
1462   UMASK_NULL        Nullify umask
1463   DEV_NULL          Suppress all command output
1464
1465
1466 =head3 init_DIRFILESEP  I<Abstract>
1467
1468   $MM->init_DIRFILESEP;
1469   my $dirfilesep = $MM->{DIRFILESEP};
1470
1471 Initializes the DIRFILESEP macro which is the seperator between the
1472 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
1473 nothing on VMS.
1474
1475 For example:
1476
1477     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
1478     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
1479
1480 Something of a hack but it prevents a lot of code duplication between
1481 MM_* variants.
1482
1483 Do not use this as a seperator between directories.  Some operating
1484 systems use different seperators between subdirectories as between
1485 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
1486
1487 =head3 init_linker  I<Abstract>
1488
1489     $mm->init_linker;
1490
1491 Initialize macros which have to do with linking.
1492
1493 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
1494 extensions.
1495
1496 PERL_ARCHIVE_AFTER: path to a library which should be put on the
1497 linker command line I<after> the external libraries to be linked to
1498 dynamic extensions.  This may be needed if the linker is one-pass, and
1499 Perl includes some overrides for C RTL functions, such as malloc().
1500
1501 EXPORT_LIST: name of a file that is passed to linker to define symbols
1502 to be exported.
1503
1504 Some OSes do not need these in which case leave it blank.
1505
1506
1507 =head3 init_platform
1508
1509     $mm->init_platform
1510
1511 Initialize any macros which are for platform specific use only.
1512
1513 A typical one is the version number of your OS specific mocule.
1514 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
1515
1516 =cut
1517
1518 sub init_platform {
1519     return '';
1520 }
1521
1522
1523 =head3 init_MAKE
1524
1525     $mm->init_MAKE
1526
1527 Initialize MAKE from either a MAKE environment variable or $Config{make}.
1528
1529 =cut
1530
1531 sub init_MAKE {
1532     my $self = shift;
1533
1534     $self->{MAKE} ||= $ENV{MAKE} || $Config{make};
1535 }
1536
1537
1538 =head2 Tools
1539
1540 A grab bag of methods to generate specific macros and commands.
1541
1542
1543
1544 =head3 manifypods
1545
1546 Defines targets and routines to translate the pods into manpages and
1547 put them into the INST_* directories.
1548
1549 =cut
1550
1551 sub manifypods {
1552     my $self          = shift;
1553
1554     my $POD2MAN_macro = $self->POD2MAN_macro();
1555     my $manifypods_target = $self->manifypods_target();
1556
1557     return <<END_OF_TARGET;
1558
1559 $POD2MAN_macro
1560
1561 $manifypods_target
1562
1563 END_OF_TARGET
1564
1565 }
1566
1567
1568 =head3 POD2MAN_macro
1569
1570   my $pod2man_macro = $self->POD2MAN_macro
1571
1572 Returns a definition for the POD2MAN macro.  This is a program
1573 which emulates the pod2man utility.  You can add more switches to the
1574 command by simply appending them on the macro.
1575
1576 Typical usage:
1577
1578     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
1579
1580 =cut
1581
1582 sub POD2MAN_macro {
1583     my $self = shift;
1584
1585 # Need the trailing '--' so perl stops gobbling arguments and - happens
1586 # to be an alternative end of line seperator on VMS so we quote it
1587     return <<'END_OF_DEF';
1588 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
1589 POD2MAN = $(POD2MAN_EXE)
1590 END_OF_DEF
1591 }
1592
1593
1594 =head3 test_via_harness
1595
1596   my $command = $mm->test_via_harness($perl, $tests);
1597
1598 Returns a $command line which runs the given set of $tests with
1599 Test::Harness and the given $perl.
1600
1601 Used on the t/*.t files.
1602
1603 =cut
1604
1605 sub test_via_harness {
1606     my($self, $perl, $tests) = @_;
1607
1608     return qq{\t$perl "-MExtUtils::Command::MM" }.
1609            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
1610 }
1611
1612 =head3 test_via_script
1613
1614   my $command = $mm->test_via_script($perl, $script);
1615
1616 Returns a $command line which just runs a single test without
1617 Test::Harness.  No checks are done on the results, they're just
1618 printed.
1619
1620 Used for test.pl, since they don't always follow Test::Harness
1621 formatting.
1622
1623 =cut
1624
1625 sub test_via_script {
1626     my($self, $perl, $script) = @_;
1627     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
1628 }
1629
1630
1631 =head3 tool_autosplit
1632
1633 Defines a simple perl call that runs autosplit. May be deprecated by
1634 pm_to_blib soon.
1635
1636 =cut
1637
1638 sub tool_autosplit {
1639     my($self, %attribs) = @_;
1640
1641     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
1642                                   : '';
1643
1644     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
1645 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
1646 PERL_CODE
1647
1648     return sprintf <<'MAKE_FRAG', $asplit;
1649 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
1650 AUTOSPLITFILE = %s
1651
1652 MAKE_FRAG
1653
1654 }
1655
1656
1657
1658
1659 =head2 File::Spec wrappers
1660
1661 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
1662 override File::Spec.
1663
1664
1665
1666 =head3 catfile
1667
1668 File::Spec <= 0.83 has a bug where the file part of catfile is not
1669 canonicalized.  This override fixes that bug.
1670
1671 =cut
1672
1673 sub catfile {
1674     my $self = shift;
1675     return $self->canonpath($self->SUPER::catfile(@_));
1676 }
1677
1678
1679
1680 =head2 Misc
1681
1682 Methods I can't really figure out where they should go yet.
1683
1684
1685 =head3 find_tests
1686
1687   my $test = $mm->find_tests;
1688
1689 Returns a string suitable for feeding to the shell to return all
1690 tests in t/*.t.
1691
1692 =cut
1693
1694 sub find_tests {
1695     my($self) = shift;
1696     return -d 't' ? 't/*.t' : '';
1697 }
1698
1699
1700 =head3 extra_clean_files
1701
1702     my @files_to_clean = $MM->extra_clean_files;
1703
1704 Returns a list of OS specific files to be removed in the clean target in
1705 addition to the usual set.
1706
1707 =cut
1708
1709 # An empty method here tickled a perl 5.8.1 bug and would return its object.
1710 sub extra_clean_files {
1711     return;
1712 }
1713
1714
1715 =head3 installvars
1716
1717     my @installvars = $mm->installvars;
1718
1719 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
1720 for iteration or building related variable sets.
1721
1722 =cut
1723
1724 sub installvars {
1725     return qw(PRIVLIB SITELIB  VENDORLIB
1726               ARCHLIB SITEARCH VENDORARCH
1727               BIN     SITEBIN  VENDORBIN
1728               SCRIPT  SITESCRIPT  VENDORSCRIPT
1729               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
1730               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
1731              );
1732 }
1733
1734
1735 =head3 libscan
1736
1737   my $wanted = $self->libscan($path);
1738
1739 Takes a path to a file or dir and returns an empty string if we don't
1740 want to include this file in the library.  Otherwise it returns the
1741 the $path unchanged.
1742
1743 Mainly used to exclude version control administrative directories from
1744 installation.
1745
1746 =cut
1747
1748 sub libscan {
1749     my($self,$path) = @_;
1750     my($dirs,$file) = ($self->splitpath($path))[1,2];
1751     return '' if grep /^(?:RCS|CVS|SCCS|\.svn|_darcs)$/,
1752                      $self->splitdir($dirs), $file;
1753
1754     return $path;
1755 }
1756
1757
1758 =head3 platform_constants
1759
1760     my $make_frag = $mm->platform_constants
1761
1762 Returns a make fragment defining all the macros initialized in
1763 init_platform() rather than put them in constants().
1764
1765 =cut
1766
1767 sub platform_constants {
1768     return '';
1769 }
1770
1771
1772 =head1 AUTHOR
1773
1774 Michael G Schwern <schwern@pobox.com> and the denizens of
1775 makemaker@perl.org with code from ExtUtils::MM_Unix and
1776 ExtUtils::MM_Win32.
1777
1778
1779 =cut
1780
1781 1;