lib/ExtUtils/MM_Any.pm

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