lib/ExtUtils/MM_Any.pm

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