lib/ExtUtils/MM_Any.pm

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