lib/ExtUtils/MM_Any.pm

   1 package ExtUtils::MM_Any;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA);
   5 $VERSION = 0.09;
   6 @ISA = qw(File::Spec);
   7
   8 use Config;
   9 use File::Spec;
  10
  11
  12 =head1 NAME
  13
  14 ExtUtils::MM_Any - Platform-agnostic MM methods
  15
  16 =head1 SYNOPSIS
  17
  18   FOR INTERNAL USE ONLY!
  19
  20   package ExtUtils::MM_SomeOS;
  21
  22   # Temporarily, you have to subclass both.  Put MM_Any first.
  23   require ExtUtils::MM_Any;
  24   require ExtUtils::MM_Unix;
  25   @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
  26
  27 =head1 DESCRIPTION
  28
  29 B<FOR INTERNAL USE ONLY!>
  30
  31 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
  32 modules.  It contains methods which are either inherently
  33 cross-platform or are written in a cross-platform manner.
  34
  35 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix.  This is a
  36 temporary solution.
  37
  38 B<THIS MAY BE TEMPORARY!>
  39
  40 =head1 Inherently Cross-Platform Methods
  41
  42 These are methods which are by their nature cross-platform and should
  43 always be cross-platform.
  44
  45 =over 4
  46
  47 =item installvars
  48
  49     my @installvars = $mm->installvars;
  50
  51 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
  52 for iteration or building related variable sets.
  53
  54 =cut
  55
  56 sub installvars {
  57     return qw(PRIVLIB SITELIB  VENDORLIB
  58               ARCHLIB SITEARCH VENDORARCH
  59               BIN     SITEBIN  VENDORBIN
  60               SCRIPT
  61               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
  62               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
  63              );
  64 }
  65
  66 =item os_flavor_is
  67
  68     $mm->os_flavor_is($this_flavor);
  69     $mm->os_flavor_is(@one_of_these_flavors);
  70
  71 Checks to see if the current operating system is one of the given flavors.
  72
  73 This is useful for code like:
  74
  75     if( $mm->os_flavor_is('Unix') ) {
  76         $out = `foo 2>&1`;
  77     }
  78     else {
  79         $out = `foo`;
  80     }
  81
  82 =cut
  83
  84 sub os_flavor_is {
  85     my $self = shift;
  86     my %flavors = map { ($_ => 1) } $self->os_flavor;
  87     return (grep { $flavors{$_} } @_) ? 1 : 0;
  88 }
  89
  90 =item blibdirs_target (o)
  91
  92     my $make_frag = $mm->blibdirs_target;
  93
  94 Creates the blibdirs target which creates all the directories we use in
  95 blib/.
  96
  97 =cut
  98
  99 sub blibdirs_target {
 100     my $self = shift;
 101
 102     my @dirs = map { uc "\$(INST_$_)" } qw(libdir
 103                                        autodir archautodir
 104                                        bin script
 105                                        man1dir man3dir
 106                                       );
 107     my @mkpath = $self->split_command('$(NOECHO) $(MKPATH)', @dirs);
 108     my @chmod  = $self->split_command('$(NOECHO) $(CHMOD) 755', @dirs);
 109
 110     my $make = "\nblibdirs :: \n";
 111     $make .= join "", map { "\t$_\n" } @mkpath, @chmod;
 112     $make .= "\t\$(NOECHO) \$(TOUCH) blibdirs\n\n";
 113
 114     return $make;
 115 }
 116
 117
 118 =back
 119
 120 =head2 File::Spec wrappers
 121
 122 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
 123 override File::Spec.
 124
 125 =over 4
 126
 127 =item catfile
 128
 129 File::Spec <= 0.83 has a bug where the file part of catfile is not
 130 canonicalized.  This override fixes that bug.
 131
 132 =cut
 133
 134 sub catfile {
 135     my $self = shift;
 136     return $self->canonpath($self->SUPER::catfile(@_));
 137 }
 138
 139 =back
 140
 141 =head1 Thought To Be Cross-Platform Methods
 142
 143 These are methods which are thought to be cross-platform by virtue of
 144 having been written in a way to avoid incompatibilities.  They may
 145 require partial overrides.
 146
 147 =over 4
 148
 149 =item B<split_command>
 150
 151     my @cmds = $MM->split_command($cmd, @args);
 152
 153 Most OS have a maximum command length they can execute at once.  Large
 154 modules can easily generate commands well past that limit.  Its
 155 necessary to split long commands up into a series of shorter commands.
 156
 157 split_command() will return a series of @cmds each processing part of
 158 the args.  Collectively they will process all the arguments.  Each
 159 individual line in @cmds will not be longer than the
 160 $self->max_exec_len being careful to take into account macro expansion.
 161
 162 $cmd should include any switches and repeated initial arguments.
 163
 164 If no @args are given, no @cmds will be returned.
 165
 166 Pairs of arguments will always be preserved in a single command, this
 167 is a heuristic for things like pm_to_blib and pod2man which work on
 168 pairs of arguments.  This makes things like this safe:
 169
 170     $self->split_command($cmd, %pod2man);
 171
 172
 173 =cut
 174
 175 sub split_command {
 176     my($self, $cmd, @args) = @_;
 177
 178     my @cmds = ();
 179     return(@cmds) unless @args;
 180
 181     # If the command was given as a here-doc, there's probably a trailing
 182     # newline.
 183     chomp $cmd;
 184
 185     # set aside 20% for macro expansion.
 186     my $len_left = int($self->max_exec_len * 0.80);
 187     $len_left -= length $self->_expand_macros($cmd);
 188
 189     do {
 190         my $arg_str = '';
 191         my @next_args;
 192         while( @next_args = splice(@args, 0, 2) ) {
 193             # Two at a time to preserve pairs.
 194             my $next_arg_str = "\t  ". join ' ', @next_args, "\n";
 195
 196             if( !length $arg_str ) {
 197                 $arg_str .= $next_arg_str
 198             }
 199             elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
 200                 unshift @args, @next_args;
 201                 last;
 202             }
 203             else {
 204                 $arg_str .= $next_arg_str;
 205             }
 206         }
 207         chop $arg_str;
 208
 209         push @cmds, $self->escape_newlines("$cmd \n$arg_str");
 210     } while @args;
 211
 212     return @cmds;
 213 }
 214
 215
 216 sub _expand_macros {
 217     my($self, $cmd) = @_;
 218
 219     $cmd =~ s{\$\((\w+)\)}{
 220         defined $self->{$1} ? $self->{$1} : "\$($1)"
 221     }e;
 222     return $cmd;
 223 }
 224
 225
 226 =item B<echo>
 227
 228     my @commands = $MM->echo($text);
 229     my @commands = $MM->echo($text, $file);
 230     my @commands = $MM->echo($text, $file, $appending);
 231
 232 Generates a set of @commands which print the $text to a $file.
 233
 234 If $file is not given, output goes to STDOUT.
 235
 236 If $appending is true the $file will be appended to rather than
 237 overwritten.
 238
 239 =cut
 240
 241 sub echo {
 242     my($self, $text, $file, $appending) = @_;
 243     $appending ||= 0;
 244
 245     my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) }
 246                split /\n/, $text;
 247     if( $file ) {
 248         my $redirect = $appending ? '>>' : '>';
 249         $cmds[0] .= " $redirect $file";
 250         $_ .= " >> $file" foreach @cmds[1..$#cmds];
 251     }
 252
 253     return @cmds;
 254 }
 255
 256
 257 =item init_VERSION
 258
 259     $mm->init_VERSION
 260
 261 Initialize macros representing versions of MakeMaker and other tools
 262
 263 MAKEMAKER: path to the MakeMaker module.
 264
 265 MM_VERSION: ExtUtils::MakeMaker Version
 266
 267 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
 268              compat)
 269
 270 VERSION: version of your module
 271
 272 VERSION_MACRO: which macro represents the version (usually 'VERSION')
 273
 274 VERSION_SYM: like version but safe for use as an RCS revision number
 275
 276 DEFINE_VERSION: -D line to set the module version when compiling
 277
 278 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
 279
 280 XS_VERSION_MACRO: which macro represents the XS version.
 281
 282 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
 283
 284 Called by init_main.
 285
 286 =cut
 287
 288 sub init_VERSION {
 289     my($self) = shift;
 290
 291     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
 292     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
 293     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
 294     $self->{VERSION_FROM} ||= '';
 295
 296     if ($self->{VERSION_FROM}){
 297         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
 298         if( $self->{VERSION} eq 'undef' ) {
 299             require Carp;
 300             Carp::carp("WARNING: Setting VERSION via file ".
 301                        "'$self->{VERSION_FROM}' failed\n");
 302         }
 303     }
 304
 305     # strip blanks
 306     if (defined $self->{VERSION}) {
 307         $self->{VERSION} =~ s/^\s+//;
 308         $self->{VERSION} =~ s/\s+$//;
 309     }
 310     else {
 311         $self->{VERSION} = '';
 312     }
 313
 314
 315     $self->{VERSION_MACRO}  = 'VERSION';
 316     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
 317     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
 318
 319
 320     # Graham Barr and Paul Marquess had some ideas how to ensure
 321     # version compatibility between the *.pm file and the
 322     # corresponding *.xs file. The bottomline was, that we need an
 323     # XS_VERSION macro that defaults to VERSION:
 324     $self->{XS_VERSION} ||= $self->{VERSION};
 325
 326     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
 327     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
 328
 329 }
 330
 331 =item wraplist
 332
 333 Takes an array of items and turns them into a well-formatted list of
 334 arguments.  In most cases this is simply something like:
 335
 336     FOO \
 337     BAR \
 338     BAZ
 339
 340 =cut
 341
 342 sub wraplist {
 343     my $self = shift;
 344     return join " \\\n\t", @_;
 345 }
 346
 347 =item manifypods
 348
 349 Defines targets and routines to translate the pods into manpages and
 350 put them into the INST_* directories.
 351
 352 =cut
 353
 354 sub manifypods {
 355     my $self          = shift;
 356
 357     my $POD2MAN_macro = $self->POD2MAN_macro();
 358     my $manifypods_target = $self->manifypods_target();
 359
 360     return <<END_OF_TARGET;
 361
 362 $POD2MAN_macro
 363
 364 $manifypods_target
 365
 366 END_OF_TARGET
 367
 368 }
 369
 370
 371 =item manifypods_target
 372
 373   my $manifypods_target = $self->manifypods_target;
 374
 375 Generates the manifypods target.  This target generates man pages from
 376 all POD files in MAN1PODS and MAN3PODS.
 377
 378 =cut
 379
 380 sub manifypods_target {
 381     my($self) = shift;
 382
 383     my $man1pods      = '';
 384     my $man3pods      = '';
 385     my $dependencies  = '';
 386
 387     # populate manXpods & dependencies:
 388     foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
 389         $dependencies .= " \\\n\t$name";
 390     }
 391
 392     foreach my $name (keys %{$self->{MAN3PODS}}) {
 393         $dependencies .= " \\\n\t$name"
 394     }
 395
 396     my $manify = <<END;
 397 manifypods : pure_all $dependencies
 398 END
 399
 400     my @man_cmds;
 401     foreach my $section (qw(1 3)) {
 402         my $pods = $self->{"MAN${section}PODS"};
 403         push @man_cmds, $self->split_command(<<CMD, %$pods);
 404         \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
 405 CMD
 406     }
 407
 408     $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
 409     $manify .= join '', map { "$_\n" } @man_cmds;
 410
 411     return $manify;
 412 }
 413
 414
 415 =item makemakerdflt_target
 416
 417   my $make_frag = $mm->makemakerdflt_target
 418
 419 Returns a make fragment with the makemakerdeflt_target specified.
 420 This target is the first target in the Makefile, is the default target
 421 and simply points off to 'all' just in case any make variant gets
 422 confused or something gets snuck in before the real 'all' target.
 423
 424 =cut
 425
 426 sub makemakerdflt_target {
 427     return <<'MAKE_FRAG';
 428 makemakerdflt: all
 429         $(NOECHO) $(NOOP)
 430 MAKE_FRAG
 431
 432 }
 433
 434
 435 =item special_targets
 436
 437   my $make_frag = $mm->special_targets
 438
 439 Returns a make fragment containing any targets which have special
 440 meaning to make.  For example, .SUFFIXES and .PHONY.
 441
 442 =cut
 443
 444 sub special_targets {
 445     my $make_frag = <<'MAKE_FRAG';
 446 .SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
 447
 448 .PHONY: all config static dynamic test linkext manifest
 449
 450 MAKE_FRAG
 451
 452     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
 453 .NO_CONFIG_REC: Makefile
 454
 455 MAKE_FRAG
 456
 457     return $make_frag;
 458 }
 459
 460 =item POD2MAN_macro
 461
 462   my $pod2man_macro = $self->POD2MAN_macro
 463
 464 Returns a definition for the POD2MAN macro.  This is a program
 465 which emulates the pod2man utility.  You can add more switches to the
 466 command by simply appending them on the macro.
 467
 468 Typical usage:
 469
 470     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
 471
 472 =cut
 473
 474 sub POD2MAN_macro {
 475     my $self = shift;
 476
 477 # Need the trailing '--' so perl stops gobbling arguments and - happens
 478 # to be an alternative end of line seperator on VMS so we quote it
 479     return <<'END_OF_DEF';
 480 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
 481 POD2MAN = $(POD2MAN_EXE)
 482 END_OF_DEF
 483 }
 484
 485
 486 =item test_via_harness
 487
 488   my $command = $mm->test_via_harness($perl, $tests);
 489
 490 Returns a $command line which runs the given set of $tests with
 491 Test::Harness and the given $perl.
 492
 493 Used on the t/*.t files.
 494
 495 =cut
 496
 497 sub test_via_harness {
 498     my($self, $perl, $tests) = @_;
 499
 500     return qq{\t$perl "-MExtUtils::Command::MM" }.
 501            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
 502 }
 503
 504 =item test_via_script
 505
 506   my $command = $mm->test_via_script($perl, $script);
 507
 508 Returns a $command line which just runs a single test without
 509 Test::Harness.  No checks are done on the results, they're just
 510 printed.
 511
 512 Used for test.pl, since they don't always follow Test::Harness
 513 formatting.
 514
 515 =cut
 516
 517 sub test_via_script {
 518     my($self, $perl, $script) = @_;
 519     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
 520 }
 521
 522 =item libscan
 523
 524   my $wanted = $self->libscan($path);
 525
 526 Takes a path to a file or dir and returns an empty string if we don't
 527 want to include this file in the library.  Otherwise it returns the
 528 the $path unchanged.
 529
 530 Mainly used to exclude RCS, CVS, and SCCS directories from
 531 installation.
 532
 533 =cut
 534
 535 sub libscan {
 536     my($self,$path) = @_;
 537     my($dirs,$file) = ($self->splitpath($path))[1,2];
 538     return '' if grep /^(?:RCS|CVS|SCCS|\.svn)$/,
 539                      $self->splitdir($dirs), $file;
 540
 541     return $path;
 542 }
 543
 544 =item tool_autosplit
 545
 546 Defines a simple perl call that runs autosplit. May be deprecated by
 547 pm_to_blib soon.
 548
 549 =cut
 550
 551 sub tool_autosplit {
 552     my($self, %attribs) = @_;
 553
 554     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
 555                                   : '';
 556
 557     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
 558 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
 559 PERL_CODE
 560
 561     return sprintf <<'MAKE_FRAG', $asplit;
 562 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
 563 AUTOSPLITFILE = %s
 564
 565 MAKE_FRAG
 566
 567 }
 568
 569
 570 =item all_target
 571
 572 Generate the default target 'all'.
 573
 574 =cut
 575
 576 sub all_target {
 577     my $self = shift;
 578
 579     return <<'MAKE_EXT';
 580 all :: pure_all
 581         $(NOECHO) $(NOOP)
 582 MAKE_EXT
 583
 584 }
 585
 586
 587 =item metafile_target
 588
 589     my $target = $mm->metafile_target;
 590
 591 Generate the metafile target.
 592
 593 Writes the file META.yml, YAML encoded meta-data about the module.  The
 594 format follows Module::Build's as closely as possible.  Additionally, we
 595 include:
 596
 597     version_from
 598     installdirs
 599
 600 =cut
 601
 602 sub metafile_target {
 603     my $self = shift;
 604
 605     return <<'MAKE_FRAG' if $self->{NO_META};
 606 metafile:
 607         $(NOECHO) $(NOOP)
 608 MAKE_FRAG
 609
 610     my $prereq_pm = '';
 611     foreach my $mod ( sort { lc $a cmp lc $b } keys %{$self->{PREREQ_PM}} ) {
 612         my $ver = $self->{PREREQ_PM}{$mod};
 613         $prereq_pm .= sprintf "    %-30s %s\n", "$mod:", $ver;
 614     }
 615
 616     my $meta = <<YAML;
 617 # http://module-build.sourceforge.net/META-spec.html
 618 #XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#
 619 name:         $self->{DISTNAME}
 620 version:      $self->{VERSION}
 621 version_from: $self->{VERSION_FROM}
 622 installdirs:  $self->{INSTALLDIRS}
 623 requires:
 624 $prereq_pm
 625 distribution_type: module
 626 generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
 627 YAML
 628
 629     my @write_meta = $self->echo($meta, 'META_new.yml');
 630     my $move = $self->oneliner(<<'CODE', ['-MExtUtils::Command', '-MFile::Compare']);
 631 compare(@ARGV) != 0 ? (mv or warn "Cannot move @ARGV: $$!\n") : unlink(shift);
 632 CODE
 633
 634     return sprintf <<'MAKE_FRAG', join("\n\t", @write_meta), $move;
 635 metafile :
 636         $(NOECHO) $(ECHO) Generating META.yml
 637         %s
 638         -$(NOECHO) %s META_new.yml META.yml
 639 MAKE_FRAG
 640
 641 }
 642
 643
 644 =item signature_target
 645
 646     my $target = $mm->signature_target;
 647
 648 Generate the signature target.
 649
 650 Writes the file SIGNATURE with "cpansign -s".
 651
 652 =cut
 653
 654 sub signature_target {
 655     my $self = shift;
 656
 657     return <<'MAKE_FRAG' if !$self->{SIGN};
 658 signature :
 659         $(NOECHO) $(NOOP)
 660 MAKE_FRAG
 661
 662     return <<'MAKE_FRAG';
 663 signature :  signature_addtomanifest
 664         cpansign -s
 665 MAKE_FRAG
 666
 667 }
 668
 669
 670 =item metafile_addtomanifest_target
 671
 672   my $target = $mm->metafile_addtomanifest_target
 673
 674 Adds the META.yml file to the MANIFEST.
 675
 676 =cut
 677
 678 sub metafile_addtomanifest_target {
 679     my $self = shift;
 680
 681     return <<'MAKE_FRAG' if $self->{NO_META};
 682 metafile_addtomanifest:
 683         $(NOECHO) $(NOOP)
 684 MAKE_FRAG
 685
 686     my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
 687 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
 688     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
 689 CODE
 690
 691     return sprintf <<'MAKE_FRAG', $add_meta;
 692 metafile_addtomanifest:
 693         $(NOECHO) $(ECHO) Adding META.yml to MANIFEST
 694         $(NOECHO) %s
 695 MAKE_FRAG
 696
 697 }
 698
 699
 700 =item signature_addtomanifest_target
 701
 702   my $target = $mm->signature_addtomanifest_target
 703
 704 Adds the META.yml file to the MANIFEST.
 705
 706 =cut
 707
 708 sub signature_addtomanifest_target {
 709     my $self = shift;
 710
 711     return <<'MAKE_FRAG' if !$self->{SIGN};
 712 signature_addtomanifest :
 713         $(NOECHO) $(NOOP)
 714 MAKE_FRAG
 715
 716     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
 717 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
 718     or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
 719 CODE
 720
 721     return sprintf <<'MAKE_FRAG', $add_sign;
 722 signature_addtomanifest :
 723         $(NOECHO) $(ECHO) Adding SIGNATURE to MANIFEST
 724         $(NOECHO) %s
 725 MAKE_FRAG
 726
 727 }
 728
 729
 730 =back
 731
 732 =head2 Abstract methods
 733
 734 Methods which cannot be made cross-platform and each subclass will
 735 have to do their own implementation.
 736
 737 =over 4
 738
 739 =item oneliner
 740
 741   my $oneliner = $MM->oneliner($perl_code);
 742   my $oneliner = $MM->oneliner($perl_code, \@switches);
 743
 744 This will generate a perl one-liner safe for the particular platform
 745 you're on based on the given $perl_code and @switches (a -e is
 746 assumed) suitable for using in a make target.  It will use the proper
 747 shell quoting and escapes.
 748
 749 $(PERLRUN) will be used as perl.
 750
 751 Any newlines in $perl_code will be escaped.  Leading and trailing
 752 newlines will be stripped.  Makes this idiom much easier:
 753
 754     my $code = $MM->oneliner(<<'CODE', [...switches...]);
 755 some code here
 756 another line here
 757 CODE
 758
 759 Usage might be something like:
 760
 761     # an echo emulation
 762     $oneliner = $MM->oneliner('print "Foo\n"');
 763     $make = '$oneliner > somefile';
 764
 765 All dollar signs must be doubled in the $perl_code if you expect them
 766 to be interpreted normally, otherwise it will be considered a make
 767 macro.  Also remember to quote make macros else it might be used as a
 768 bareword.  For example:
 769
 770     # Assign the value of the $(VERSION_FROM) make macro to $vf.
 771     $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
 772
 773 Its currently very simple and may be expanded sometime in the figure
 774 to include more flexible code and switches.
 775
 776
 777 =item B<quote_literal>
 778
 779     my $safe_text = $MM->quote_literal($text);
 780
 781 This will quote $text so it is interpreted literally in the shell.
 782
 783 For example, on Unix this would escape any single-quotes in $text and
 784 put single-quotes around the whole thing.
 785
 786
 787 =item B<escape_newlines>
 788
 789     my $escaped_text = $MM->escape_newlines($text);
 790
 791 Shell escapes newlines in $text.
 792
 793
 794 =item max_exec_len
 795
 796     my $max_exec_len = $MM->max_exec_len;
 797
 798 Calculates the maximum command size the OS can exec.  Effectively,
 799 this is the max size of a shell command line.
 800
 801 =for _private
 802 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
 803
 804 =item B<init_others>
 805
 806     $MM->init_others();
 807
 808 Initializes the macro definitions used by tools_other() and places them
 809 in the $MM object.
 810
 811 If there is no description, its the same as the parameter to
 812 WriteMakefile() documented in ExtUtils::MakeMaker.
 813
 814 Defines at least these macros.
 815
 816   Macro             Description
 817
 818   NOOP              Do nothing
 819   NOECHO            Tell make not to display the command itself
 820
 821   MAKEFILE
 822   FIRST_MAKEFILE
 823   MAKEFILE_OLD
 824   MAKE_APERL_FILE   File used by MAKE_APERL
 825
 826   SHELL             Program used to run
 827                     shell commands
 828
 829   ECHO              Print text adding a newline on the end
 830   RM_F              Remove a file
 831   RM_RF             Remove a directory
 832   TOUCH             Update a file's timestamp
 833   TEST_F            Test for a file's existence
 834   CP                Copy a file
 835   MV                Move a file
 836   CHMOD             Change permissions on a
 837                     file
 838
 839   UMASK_NULL        Nullify umask
 840   DEV_NULL          Supress all command output
 841
 842 =item init_DIRFILESEP
 843
 844   $MM->init_DIRFILESEP;
 845   my $dirfilesep = $MM->{DIRFILESEP};
 846
 847 Initializes the DIRFILESEP macro which is the seperator between the
 848 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
 849 nothing on VMS.
 850
 851 For example:
 852
 853     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
 854     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
 855
 856 Something of a hack but it prevents a lot of code duplication between
 857 MM_* variants.
 858
 859 Do not use this as a seperator between directories.  Some operating
 860 systems use different seperators between subdirectories as between
 861 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
 862
 863 =item init_linker
 864
 865     $mm->init_linker;
 866
 867 Initialize macros which have to do with linking.
 868
 869 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
 870 extensions.
 871
 872 PERL_ARCHIVE_AFTER: path to a library which should be put on the
 873 linker command line I<after> the external libraries to be linked to
 874 dynamic extensions.  This may be needed if the linker is one-pass, and
 875 Perl includes some overrides for C RTL functions, such as malloc().
 876
 877 EXPORT_LIST: name of a file that is passed to linker to define symbols
 878 to be exported.
 879
 880 Some OSes do not need these in which case leave it blank.
 881
 882
 883 =item init_platform
 884
 885     $mm->init_platform
 886
 887 Initialize any macros which are for platform specific use only.
 888
 889 A typical one is the version number of your OS specific mocule.
 890 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
 891
 892 =item platform_constants
 893
 894     my $make_frag = $mm->platform_constants
 895
 896 Returns a make fragment defining all the macros initialized in
 897 init_platform() rather than put them in constants().
 898
 899 =cut
 900
 901 sub init_platform {
 902     return '';
 903 }
 904
 905 sub platform_constants {
 906     return '';
 907 }
 908
 909 =item os_flavor
 910
 911     my @os_flavor = $mm->os_flavor;
 912
 913 @os_flavor is the style of operating system this is, usually
 914 corresponding to the MM_*.pm file we're using.
 915
 916 The first element of @os_flavor is the major family (ie. Unix,
 917 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
 918
 919 Some examples:
 920
 921     Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
 922     Windows NT     ('Win32', 'WinNT')
 923     Win98          ('Win32', 'Win9x')
 924     Linux          ('Unix',  'Linux')
 925     MacOS Classic  ('MacOS', 'MacOS Classic')
 926     MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
 927     OS/2           ('OS/2')
 928
 929 This is used to write code for styles of operating system.
 930 See os_flavor_is() for use.
 931
 932
 933 =back
 934
 935 =head1 AUTHOR
 936
 937 Michael G Schwern <schwern@pobox.com> and the denizens of
 938 makemaker@perl.org with code from ExtUtils::MM_Unix and
 939 ExtUtils::MM_Win32.
 940
 941
 942 =cut
 943
 944 1;