lib/ExtUtils/MM_Any.pm

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