local-lib5/man/man3/ExtUtils::MM_Any.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ExtUtils::MM_Any 3"
 132 .TH ExtUtils::MM_Any 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::MM_Any \- Platform\-agnostic MM methods
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  FOR INTERNAL USE ONLY!
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&  package ExtUtils::MM_SomeOS;
 143 .Ve
 144 .PP
 145 .Vb 4
 146 \&  # Temporarily, you have to subclass both.  Put MM_Any first.
 147 \&  require ExtUtils::MM_Any;
 148 \&  require ExtUtils::MM_Unix;
 149 \&  @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 \&\fB\s-1FOR\s0 \s-1INTERNAL\s0 \s-1USE\s0 \s-1ONLY\s0!\fR
 154 .PP
 155 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
 156 modules.  It contains methods which are either inherently
 157 cross-platform or are written in a cross-platform manner.
 158 .PP
 159 Subclass off of ExtUtils::MM_Any \fIand\fR ExtUtils::MM_Unix.  This is a
 160 temporary solution.
 161 .PP
 162 \&\fB\s-1THIS\s0 \s-1MAY\s0 \s-1BE\s0 \s-1TEMPORARY\s0!\fR
 163 .SH "METHODS"
 164 .IX Header "METHODS"
 165 Any methods marked \fIAbstract\fR must be implemented by subclasses.
 166 .Sh "Cross-platform helper methods"
 167 .IX Subsection "Cross-platform helper methods"
 168 These are methods which help writing cross-platform code.
 169 .PP
 170 \fIos_flavor  \fIAbstract\fI\fR
 171 .IX Subsection "os_flavor  Abstract"
 172 .PP
 173 .Vb 1
 174 \&    my @os_flavor = $mm\->os_flavor;
 175 .Ve
 176 .PP
 177 @os_flavor is the style of operating system this is, usually
 178 corresponding to the MM_*.pm file we're using.
 179 .PP
 180 The first element of \f(CW@os_flavor\fR is the major family (ie. Unix,
 181 Windows, \s-1VMS\s0, \s-1OS/2\s0, etc...) and the rest are sub families.
 182 .PP
 183 Some examples:
 184 .PP
 185 .Vb 6
 186 \&    Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
 187 \&    Windows NT     ('Win32', 'WinNT')
 188 \&    Win98          ('Win32', 'Win9x')
 189 \&    Linux          ('Unix',  'Linux')
 190 \&    MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
 191 \&    OS/2           ('OS/2')
 192 .Ve
 193 .PP
 194 This is used to write code for styles of operating system.
 195 See \fIos_flavor_is()\fR for use.
 196 .PP
 197 \fIos_flavor_is\fR
 198 .IX Subsection "os_flavor_is"
 199 .PP
 200 .Vb 2
 201 \&    my $is_this_flavor = $mm\->os_flavor_is($this_flavor);
 202 \&    my $is_this_flavor = $mm\->os_flavor_is(@one_of_these_flavors);
 203 .Ve
 204 .PP
 205 Checks to see if the current operating system is one of the given flavors.
 206 .PP
 207 This is useful for code like:
 208 .PP
 209 .Vb 6
 210 \&    if( $mm\->os_flavor_is('Unix') ) {
 211 \&        $out = `foo 2>&1`;
 212 \&    }
 213 \&    else {
 214 \&        $out = `foo`;
 215 \&    }
 216 .Ve
 217 .PP
 218 \fIcan_load_xs\fR
 219 .IX Subsection "can_load_xs"
 220 .PP
 221 .Vb 1
 222 \&    my $can_load_xs = $self\->can_load_xs;
 223 .Ve
 224 .PP
 225 Returns true if we have the ability to load \s-1XS\s0.
 226 .PP
 227 This is important because miniperl, used to build \s-1XS\s0 modules in the
 228 core, can not load \s-1XS\s0.
 229 .PP
 230 \fIsplit_command\fR
 231 .IX Subsection "split_command"
 232 .PP
 233 .Vb 1
 234 \&    my @cmds = $MM\->split_command($cmd, @args);
 235 .Ve
 236 .PP
 237 Most \s-1OS\s0 have a maximum command length they can execute at once.  Large
 238 modules can easily generate commands well past that limit.  Its
 239 necessary to split long commands up into a series of shorter commands.
 240 .PP
 241 \&\f(CW\*(C`split_command\*(C'\fR will return a series of \f(CW@cmds\fR each processing part of
 242 the args.  Collectively they will process all the arguments.  Each
 243 individual line in \f(CW@cmds\fR will not be longer than the
 244 \&\f(CW$self\fR\->max_exec_len being careful to take into account macro expansion.
 245 .PP
 246 $cmd should include any switches and repeated initial arguments.
 247 .PP
 248 If no \f(CW@args\fR are given, no \f(CW@cmds\fR will be returned.
 249 .PP
 250 Pairs of arguments will always be preserved in a single command, this
 251 is a heuristic for things like pm_to_blib and pod2man which work on
 252 pairs of arguments.  This makes things like this safe:
 253 .PP
 254 .Vb 1
 255 \&    $self\->split_command($cmd, %pod2man);
 256 .Ve
 257 .PP
 258 \fIecho\fR
 259 .IX Subsection "echo"
 260 .PP
 261 .Vb 3
 262 \&    my @commands = $MM\->echo($text);
 263 \&    my @commands = $MM\->echo($text, $file);
 264 \&    my @commands = $MM\->echo($text, $file, $appending);
 265 .Ve
 266 .PP
 267 Generates a set of \f(CW@commands\fR which print the \f(CW$text\fR to a \f(CW$file\fR.
 268 .PP
 269 If \f(CW$file\fR is not given, output goes to \s-1STDOUT\s0.
 270 .PP
 271 If \f(CW$appending\fR is true the \f(CW$file\fR will be appended to rather than
 272 overwritten.
 273 .PP
 274 \fIwraplist\fR
 275 .IX Subsection "wraplist"
 276 .PP
 277 .Vb 1
 278 \&  my $args = $mm\->wraplist(@list);
 279 .Ve
 280 .PP
 281 Takes an array of items and turns them into a well-formatted list of
 282 arguments.  In most cases this is simply something like:
 283 .PP
 284 .Vb 3
 285 \&    FOO \e
 286 \&    BAR \e
 287 \&    BAZ
 288 .Ve
 289 .PP
 290 \fImaketext_filter\fR
 291 .IX Subsection "maketext_filter"
 292 .PP
 293 .Vb 1
 294 \&    my $filter_make_text = $mm\->maketext_filter($make_text);
 295 .Ve
 296 .PP
 297 The text of the Makefile is run through this method before writing to
 298 disk.  It allows systems a chance to make portability fixes to the
 299 Makefile.
 300 .PP
 301 By default it does nothing.
 302 .PP
 303 This method is protected and not intended to be called outside of
 304 MakeMaker.
 305 .PP
 306 \fIcd  \fIAbstract\fI\fR
 307 .IX Subsection "cd  Abstract"
 308 .PP
 309 .Vb 1
 310 \&  my $subdir_cmd = $MM\->cd($subdir, @cmds);
 311 .Ve
 312 .PP
 313 This will generate a make fragment which runs the \f(CW@cmds\fR in the given
 314 \&\f(CW$dir\fR.  The rough equivalent to this, except cross platform.
 315 .PP
 316 .Vb 1
 317 \&  cd $subdir && $cmd
 318 .Ve
 319 .PP
 320 Currently \f(CW$dir\fR can only go down one level.  \*(L"foo\*(R" is fine.  \*(L"foo/bar\*(R" is
 321 not.  \*(L"../foo\*(R" is right out.
 322 .PP
 323 The resulting \f(CW$subdir_cmd\fR has no leading tab nor trailing newline.  This
 324 makes it easier to embed in a make string.  For example.
 325 .PP
 326 .Vb 6
 327 \&      my $make = sprintf <<'CODE', $subdir_cmd;
 328 \&  foo :
 329 \&      $(ECHO) what
 330 \&      %s
 331 \&      $(ECHO) mouche
 332 \&  CODE
 333 .Ve
 334 .PP
 335 \fIoneliner  \fIAbstract\fI\fR
 336 .IX Subsection "oneliner  Abstract"
 337 .PP
 338 .Vb 2
 339 \&  my $oneliner = $MM\->oneliner($perl_code);
 340 \&  my $oneliner = $MM\->oneliner($perl_code, \e@switches);
 341 .Ve
 342 .PP
 343 This will generate a perl one-liner safe for the particular platform
 344 you're on based on the given \f(CW$perl_code\fR and \f(CW@switches\fR (a \-e is
 345 assumed) suitable for using in a make target.  It will use the proper
 346 shell quoting and escapes.
 347 .PP
 348 $(\s-1PERLRUN\s0) will be used as perl.
 349 .PP
 350 Any newlines in \f(CW$perl_code\fR will be escaped.  Leading and trailing
 351 newlines will be stripped.  Makes this idiom much easier:
 352 .PP
 353 .Vb 4
 354 \&    my $code = $MM\->oneliner(<<'CODE', [...switches...]);
 355 \&some code here
 356 \&another line here
 357 \&CODE
 358 .Ve
 359 .PP
 360 Usage might be something like:
 361 .PP
 362 .Vb 3
 363 \&    # an echo emulation
 364 \&    $oneliner = $MM\->oneliner('print "Foo\en"');
 365 \&    $make = '$oneliner > somefile';
 366 .Ve
 367 .PP
 368 All dollar signs must be doubled in the \f(CW$perl_code\fR if you expect them
 369 to be interpreted normally, otherwise it will be considered a make
 370 macro.  Also remember to quote make macros else it might be used as a
 371 bareword.  For example:
 372 .PP
 373 .Vb 2
 374 \&    # Assign the value of the $(VERSION_FROM) make macro to $vf.
 375 \&    $oneliner = $MM\->oneliner('$$vf = "$(VERSION_FROM)"');
 376 .Ve
 377 .PP
 378 Its currently very simple and may be expanded sometime in the figure
 379 to include more flexible code and switches.
 380 .PP
 381 \fIquote_literal  \fIAbstract\fI\fR
 382 .IX Subsection "quote_literal  Abstract"
 383 .PP
 384 .Vb 1
 385 \&    my $safe_text = $MM\->quote_literal($text);
 386 .Ve
 387 .PP
 388 This will quote \f(CW$text\fR so it is interpreted literally in the shell.
 389 .PP
 390 For example, on Unix this would escape any single-quotes in \f(CW$text\fR and
 391 put single-quotes around the whole thing.
 392 .PP
 393 \fIescape_newlines  \fIAbstract\fI\fR
 394 .IX Subsection "escape_newlines  Abstract"
 395 .PP
 396 .Vb 1
 397 \&    my $escaped_text = $MM\->escape_newlines($text);
 398 .Ve
 399 .PP
 400 Shell escapes newlines in \f(CW$text\fR.
 401 .PP
 402 \fImax_exec_len  \fIAbstract\fI\fR
 403 .IX Subsection "max_exec_len  Abstract"
 404 .PP
 405 .Vb 1
 406 \&    my $max_exec_len = $MM\->max_exec_len;
 407 .Ve
 408 .PP
 409 Calculates the maximum command size the \s-1OS\s0 can exec.  Effectively,
 410 this is the max size of a shell command line.
 411 .PP
 412 \fImake\fR
 413 .IX Subsection "make"
 414 .PP
 415 .Vb 1
 416 \&    my $make = $MM\->make;
 417 .Ve
 418 .PP
 419 Returns the make variant we're generating the Makefile for.  This attempts
 420 to do some normalization on the information from \f(CW%Config\fR or the user.
 421 .Sh "Targets"
 422 .IX Subsection "Targets"
 423 These are methods which produce make targets.
 424 .PP
 425 \fIall_target\fR
 426 .IX Subsection "all_target"
 427 .PP
 428 Generate the default target 'all'.
 429 .PP
 430 \fIblibdirs_target\fR
 431 .IX Subsection "blibdirs_target"
 432 .PP
 433 .Vb 1
 434 \&    my $make_frag = $mm\->blibdirs_target;
 435 .Ve
 436 .PP
 437 Creates the blibdirs target which creates all the directories we use
 438 in blib/.
 439 .PP
 440 The blibdirs.ts target is deprecated.  Depend on blibdirs instead.
 441 .PP
 442 \fIclean (o)\fR
 443 .IX Subsection "clean (o)"
 444 .PP
 445 Defines the clean target.
 446 .PP
 447 \fIclean_subdirs_target\fR
 448 .IX Subsection "clean_subdirs_target"
 449 .PP
 450 .Vb 1
 451 \&  my $make_frag = $MM\->clean_subdirs_target;
 452 .Ve
 453 .PP
 454 Returns the clean_subdirs target.  This is used by the clean target to
 455 call clean on any subdirectories which contain Makefiles.
 456 .PP
 457 \fIdir_target\fR
 458 .IX Subsection "dir_target"
 459 .PP
 460 .Vb 1
 461 \&    my $make_frag = $mm\->dir_target(@directories);
 462 .Ve
 463 .PP
 464 Generates targets to create the specified directories and set its
 465 permission to \s-1PERM_DIR\s0.
 466 .PP
 467 Because depending on a directory to just ensure it exists doesn't work
 468 too well (the modified time changes too often) \fIdir_target()\fR creates a
 469 \&.exists file in the created directory.  It is this you should depend on.
 470 For portability purposes you should use the $(\s-1DIRFILESEP\s0) macro rather
 471 than a '/' to seperate the directory from the file.
 472 .PP
 473 .Vb 1
 474 \&    yourdirectory$(DIRFILESEP).exists
 475 .Ve
 476 .PP
 477 \fIdistdir\fR
 478 .IX Subsection "distdir"
 479 .PP
 480 Defines the scratch directory target that will hold the distribution
 481 before tar-ing (or shar\-ing).
 482 .PP
 483 \fIdist_test\fR
 484 .IX Subsection "dist_test"
 485 .PP
 486 Defines a target that produces the distribution in the
 487 scratchdirectory, and runs 'perl Makefile.PL; make ;make test' in that
 488 subdirectory.
 489 .PP
 490 \fIdynamic (o)\fR
 491 .IX Subsection "dynamic (o)"
 492 .PP
 493 Defines the dynamic target.
 494 .PP
 495 \fImakemakerdflt_target\fR
 496 .IX Subsection "makemakerdflt_target"
 497 .PP
 498 .Vb 1
 499 \&  my $make_frag = $mm\->makemakerdflt_target
 500 .Ve
 501 .PP
 502 Returns a make fragment with the makemakerdeflt_target specified.
 503 This target is the first target in the Makefile, is the default target
 504 and simply points off to 'all' just in case any make variant gets
 505 confused or something gets snuck in before the real 'all' target.
 506 .PP
 507 \fImanifypods_target\fR
 508 .IX Subsection "manifypods_target"
 509 .PP
 510 .Vb 1
 511 \&  my $manifypods_target = $self\->manifypods_target;
 512 .Ve
 513 .PP
 514 Generates the manifypods target.  This target generates man pages from
 515 all \s-1POD\s0 files in \s-1MAN1PODS\s0 and \s-1MAN3PODS\s0.
 516 .PP
 517 \fImetafile_target\fR
 518 .IX Subsection "metafile_target"
 519 .PP
 520 .Vb 1
 521 \&    my $target = $mm\->metafile_target;
 522 .Ve
 523 .PP
 524 Generate the metafile target.
 525 .PP
 526 Writes the file \s-1META\s0.yml \s-1YAML\s0 encoded meta-data about the module in
 527 the distdir.  The format follows Module::Build's as closely as
 528 possible.
 529 .PP
 530 \fImetafile_data\fR
 531 .IX Subsection "metafile_data"
 532 .PP
 533 .Vb 1
 534 \&    my @metadata_pairs = $mm\->metafile_data(\e%meta_add, \e%meta_merge);
 535 .Ve
 536 .PP
 537 Returns the data which MakeMaker turns into the \s-1META\s0.yml file.
 538 .PP
 539 Values of \f(CW%meta_add\fR will overwrite any existing metadata in those
 540 keys.  \f(CW%meta_merge\fR will be merged with them.
 541 .PP
 542 \fImetafile_file\fR
 543 .IX Subsection "metafile_file"
 544 .PP
 545 .Vb 1
 546 \&    my $meta_yml = $mm\->metafile_file(@metadata_pairs);
 547 .Ve
 548 .PP
 549 Turns the \f(CW@metadata_pairs\fR into \s-1YAML\s0.
 550 .PP
 551 This method does not implement a complete \s-1YAML\s0 dumper, being limited
 552 to dump a hash with values which are strings, undef's or nested hashes
 553 and arrays of strings. No quoting/escaping is done.
 554 .PP
 555 \fIdistmeta_target\fR
 556 .IX Subsection "distmeta_target"
 557 .PP
 558 .Vb 1
 559 \&    my $make_frag = $mm\->distmeta_target;
 560 .Ve
 561 .PP
 562 Generates the distmeta target to add \s-1META\s0.yml to the \s-1MANIFEST\s0 in the
 563 distdir.
 564 .PP
 565 \fIrealclean (o)\fR
 566 .IX Subsection "realclean (o)"
 567 .PP
 568 Defines the realclean target.
 569 .PP
 570 \fIrealclean_subdirs_target\fR
 571 .IX Subsection "realclean_subdirs_target"
 572 .PP
 573 .Vb 1
 574 \&  my $make_frag = $MM\->realclean_subdirs_target;
 575 .Ve
 576 .PP
 577 Returns the realclean_subdirs target.  This is used by the realclean
 578 target to call realclean on any subdirectories which contain Makefiles.
 579 .PP
 580 \fIsignature_target\fR
 581 .IX Subsection "signature_target"
 582 .PP
 583 .Vb 1
 584 \&    my $target = $mm\->signature_target;
 585 .Ve
 586 .PP
 587 Generate the signature target.
 588 .PP
 589 Writes the file \s-1SIGNATURE\s0 with \*(L"cpansign \-s\*(R".
 590 .PP
 591 \fIdistsignature_target\fR
 592 .IX Subsection "distsignature_target"
 593 .PP
 594 .Vb 1
 595 \&    my $make_frag = $mm\->distsignature_target;
 596 .Ve
 597 .PP
 598 Generates the distsignature target to add \s-1SIGNATURE\s0 to the \s-1MANIFEST\s0 in the
 599 distdir.
 600 .PP
 601 \fIspecial_targets\fR
 602 .IX Subsection "special_targets"
 603 .PP
 604 .Vb 1
 605 \&  my $make_frag = $mm\->special_targets
 606 .Ve
 607 .PP
 608 Returns a make fragment containing any targets which have special
 609 meaning to make.  For example, .SUFFIXES and .PHONY.
 610 .Sh "Init methods"
 611 .IX Subsection "Init methods"
 612 Methods which help initialize the MakeMaker object and macros.
 613 .PP
 614 \fIinit_ABSTRACT\fR
 615 .IX Subsection "init_ABSTRACT"
 616 .PP
 617 .Vb 1
 618 \&    $mm\->init_ABSTRACT
 619 .Ve
 620 .PP
 621 \fIinit_INST\fR
 622 .IX Subsection "init_INST"
 623 .PP
 624 .Vb 1
 625 \&    $mm\->init_INST;
 626 .Ve
 627 .PP
 628 Called by init_main.  Sets up all INST_* variables except those related
 629 to \s-1XS\s0 code.  Those are handled in init_xs.
 630 .PP
 631 \fIinit_INSTALL\fR
 632 .IX Subsection "init_INSTALL"
 633 .PP
 634 .Vb 1
 635 \&    $mm\->init_INSTALL;
 636 .Ve
 637 .PP
 638 Called by init_main.  Sets up all INSTALL_* variables (except
 639 \&\s-1INSTALLDIRS\s0) and *PREFIX.
 640 .PP
 641 \fIinit_INSTALL_from_PREFIX\fR
 642 .IX Subsection "init_INSTALL_from_PREFIX"
 643 .PP
 644 .Vb 1
 645 \&  $mm\->init_INSTALL_from_PREFIX;
 646 .Ve
 647 .PP
 648 \fIinit_from_INSTALL_BASE\fR
 649 .IX Subsection "init_from_INSTALL_BASE"
 650 .PP
 651 .Vb 1
 652 \&    $mm\->init_from_INSTALL_BASE
 653 .Ve
 654 .PP
 655 \fIinit_VERSION  \fIAbstract\fI\fR
 656 .IX Subsection "init_VERSION  Abstract"
 657 .PP
 658 .Vb 1
 659 \&    $mm\->init_VERSION
 660 .Ve
 661 .PP
 662 Initialize macros representing versions of MakeMaker and other tools
 663 .PP
 664 \&\s-1MAKEMAKER:\s0 path to the MakeMaker module.
 665 .PP
 666 \&\s-1MM_VERSION:\s0 ExtUtils::MakeMaker Version
 667 .PP
 668 \&\s-1MM_REVISION:\s0 ExtUtils::MakeMaker version control revision (for backwards
 669              compat)
 670 .PP
 671 \&\s-1VERSION:\s0 version of your module
 672 .PP
 673 \&\s-1VERSION_MACRO:\s0 which macro represents the version (usually '\s-1VERSION\s0')
 674 .PP
 675 \&\s-1VERSION_SYM:\s0 like version but safe for use as an \s-1RCS\s0 revision number
 676 .PP
 677 \&\s-1DEFINE_VERSION:\s0 \-D line to set the module version when compiling
 678 .PP
 679 \&\s-1XS_VERSION:\s0 version in your .xs file.  Defaults to $(\s-1VERSION\s0)
 680 .PP
 681 \&\s-1XS_VERSION_MACRO:\s0 which macro represents the \s-1XS\s0 version.
 682 .PP
 683 \&\s-1XS_DEFINE_VERSION:\s0 \-D line to set the xs version when compiling.
 684 .PP
 685 Called by init_main.
 686 .PP
 687 \fIinit_others\fR
 688 .IX Subsection "init_others"
 689 .PP
 690 .Vb 1
 691 \&    $MM\->init_others();
 692 .Ve
 693 .PP
 694 Initializes the macro definitions used by \fItools_other()\fR and places them
 695 in the \f(CW$MM\fR object.
 696 .PP
 697 If there is no description, its the same as the parameter to
 698 \&\fIWriteMakefile()\fR documented in ExtUtils::MakeMaker.
 699 .PP
 700 Defines at least these macros.
 701 .PP
 702 .Vb 1
 703 \&  Macro             Description
 704 .Ve
 705 .PP
 706 .Vb 2
 707 \&  NOOP              Do nothing
 708 \&  NOECHO            Tell make not to display the command itself
 709 .Ve
 710 .PP
 711 .Vb 4
 712 \&  MAKEFILE
 713 \&  FIRST_MAKEFILE
 714 \&  MAKEFILE_OLD
 715 \&  MAKE_APERL_FILE   File used by MAKE_APERL
 716 .Ve
 717 .PP
 718 .Vb 1
 719 \&  SHELL             Program used to run shell commands
 720 .Ve
 721 .PP
 722 .Vb 10
 723 \&  ECHO              Print text adding a newline on the end
 724 \&  RM_F              Remove a file
 725 \&  RM_RF             Remove a directory
 726 \&  TOUCH             Update a file's timestamp
 727 \&  TEST_F            Test for a file's existence
 728 \&  CP                Copy a file
 729 \&  MV                Move a file
 730 \&  CHMOD             Change permissions on a file
 731 \&  FALSE             Exit with non\-zero
 732 \&  TRUE              Exit with zero
 733 .Ve
 734 .PP
 735 .Vb 2
 736 \&  UMASK_NULL        Nullify umask
 737 \&  DEV_NULL          Suppress all command output
 738 .Ve
 739 .PP
 740 \fItools_other\fR
 741 .IX Subsection "tools_other"
 742 .PP
 743 .Vb 1
 744 \&    my $make_frag = $MM\->tools_other;
 745 .Ve
 746 .PP
 747 Returns a make fragment containing definitions for the macros \fIinit_others()\fR
 748 initializes.
 749 .PP
 750 \fIinit_DIRFILESEP  \fIAbstract\fI\fR
 751 .IX Subsection "init_DIRFILESEP  Abstract"
 752 .PP
 753 .Vb 2
 754 \&  $MM\->init_DIRFILESEP;
 755 \&  my $dirfilesep = $MM\->{DIRFILESEP};
 756 .Ve
 757 .PP
 758 Initializes the \s-1DIRFILESEP\s0 macro which is the seperator between the
 759 directory and filename in a filepath.  ie. / on Unix, \e on Win32 and
 760 nothing on \s-1VMS\s0.
 761 .PP
 762 For example:
 763 .PP
 764 .Vb 2
 765 \&    # instead of $(INST_ARCHAUTODIR)/extralibs.ld
 766 \&    $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
 767 .Ve
 768 .PP
 769 Something of a hack but it prevents a lot of code duplication between
 770 MM_* variants.
 771 .PP
 772 Do not use this as a seperator between directories.  Some operating
 773 systems use different seperators between subdirectories as between
 774 directories and filenames (for example:  VOLUME:[dir1.dir2]file on \s-1VMS\s0).
 775 .PP
 776 \fIinit_linker  \fIAbstract\fI\fR
 777 .IX Subsection "init_linker  Abstract"
 778 .PP
 779 .Vb 1
 780 \&    $mm\->init_linker;
 781 .Ve
 782 .PP
 783 Initialize macros which have to do with linking.
 784 .PP
 785 \&\s-1PERL_ARCHIVE:\s0 path to libperl.a equivalent to be linked to dynamic
 786 extensions.
 787 .PP
 788 \&\s-1PERL_ARCHIVE_AFTER:\s0 path to a library which should be put on the
 789 linker command line \fIafter\fR the external libraries to be linked to
 790 dynamic extensions.  This may be needed if the linker is one\-pass, and
 791 Perl includes some overrides for C \s-1RTL\s0 functions, such as \fImalloc()\fR.
 792 .PP
 793 \&\s-1EXPORT_LIST:\s0 name of a file that is passed to linker to define symbols
 794 to be exported.
 795 .PP
 796 Some OSes do not need these in which case leave it blank.
 797 .PP
 798 \fIinit_platform\fR
 799 .IX Subsection "init_platform"
 800 .PP
 801 .Vb 1
 802 \&    $mm\->init_platform
 803 .Ve
 804 .PP
 805 Initialize any macros which are for platform specific use only.
 806 .PP
 807 A typical one is the version number of your \s-1OS\s0 specific mocule.
 808 (ie. MM_Unix_VERSION or \s-1MM_VMS_VERSION\s0).
 809 .PP
 810 \fIinit_MAKE\fR
 811 .IX Subsection "init_MAKE"
 812 .PP
 813 .Vb 1
 814 \&    $mm\->init_MAKE
 815 .Ve
 816 .PP
 817 Initialize \s-1MAKE\s0 from either a \s-1MAKE\s0 environment variable or \f(CW$Config\fR{make}.
 818 .Sh "Tools"
 819 .IX Subsection "Tools"
 820 A grab bag of methods to generate specific macros and commands.
 821 .PP
 822 \fImanifypods\fR
 823 .IX Subsection "manifypods"
 824 .PP
 825 Defines targets and routines to translate the pods into manpages and
 826 put them into the INST_* directories.
 827 .PP
 828 \fIPOD2MAN_macro\fR
 829 .IX Subsection "POD2MAN_macro"
 830 .PP
 831 .Vb 1
 832 \&  my $pod2man_macro = $self\->POD2MAN_macro
 833 .Ve
 834 .PP
 835 Returns a definition for the \s-1POD2MAN\s0 macro.  This is a program
 836 which emulates the pod2man utility.  You can add more switches to the
 837 command by simply appending them on the macro.
 838 .PP
 839 Typical usage:
 840 .PP
 841 .Vb 1
 842 \&    $(POD2MAN) \-\-section=3 \-\-perm_rw=$(PERM_RW) podfile1 man_page1 ...
 843 .Ve
 844 .PP
 845 \fItest_via_harness\fR
 846 .IX Subsection "test_via_harness"
 847 .PP
 848 .Vb 1
 849 \&  my $command = $mm\->test_via_harness($perl, $tests);
 850 .Ve
 851 .PP
 852 Returns a \f(CW$command\fR line which runs the given set of \f(CW$tests\fR with
 853 Test::Harness and the given \f(CW$perl\fR.
 854 .PP
 855 Used on the t/*.t files.
 856 .PP
 857 \fItest_via_script\fR
 858 .IX Subsection "test_via_script"
 859 .PP
 860 .Vb 1
 861 \&  my $command = $mm\->test_via_script($perl, $script);
 862 .Ve
 863 .PP
 864 Returns a \f(CW$command\fR line which just runs a single test without
 865 Test::Harness.  No checks are done on the results, they're just
 866 printed.
 867 .PP
 868 Used for test.pl, since they don't always follow Test::Harness
 869 formatting.
 870 .PP
 871 \fItool_autosplit\fR
 872 .IX Subsection "tool_autosplit"
 873 .PP
 874 Defines a simple perl call that runs autosplit. May be deprecated by
 875 pm_to_blib soon.
 876 .PP
 877 \fIarch_check\fR
 878 .IX Subsection "arch_check"
 879 .PP
 880 .Vb 4
 881 \&    my $arch_ok = $mm\->arch_check(
 882 \&        $INC{"Config.pm"},
 883 \&        File::Spec\->catfile($Config{archlibexp}, "Config.pm")
 884 \&    );
 885 .Ve
 886 .PP
 887 A sanity check that what Perl thinks the architecture is and what
 888 Config thinks the architecture is are the same.  If they're not it
 889 will return false and show a diagnostic message.
 890 .PP
 891 When building Perl it will always return true, as nothing is installed
 892 yet.
 893 .PP
 894 The interface is a bit odd because this is the result of a
 895 quick refactoring.  Don't rely on it.
 896 .Sh "File::Spec wrappers"
 897 .IX Subsection "File::Spec wrappers"
 898 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
 899 override File::Spec.
 900 .PP
 901 \fIcatfile\fR
 902 .IX Subsection "catfile"
 903 .PP
 904 File::Spec <= 0.83 has a bug where the file part of catfile is not
 905 canonicalized.  This override fixes that bug.
 906 .Sh "Misc"
 907 .IX Subsection "Misc"
 908 Methods I can't really figure out where they should go yet.
 909 .PP
 910 \fIfind_tests\fR
 911 .IX Subsection "find_tests"
 912 .PP
 913 .Vb 1
 914 \&  my $test = $mm\->find_tests;
 915 .Ve
 916 .PP
 917 Returns a string suitable for feeding to the shell to return all
 918 tests in t/*.t.
 919 .PP
 920 \fIextra_clean_files\fR
 921 .IX Subsection "extra_clean_files"
 922 .PP
 923 .Vb 1
 924 \&    my @files_to_clean = $MM\->extra_clean_files;
 925 .Ve
 926 .PP
 927 Returns a list of \s-1OS\s0 specific files to be removed in the clean target in
 928 addition to the usual set.
 929 .PP
 930 \fIinstallvars\fR
 931 .IX Subsection "installvars"
 932 .PP
 933 .Vb 1
 934 \&    my @installvars = $mm\->installvars;
 935 .Ve
 936 .PP
 937 A list of all the INSTALL* variables without the \s-1INSTALL\s0 prefix.  Useful
 938 for iteration or building related variable sets.
 939 .PP
 940 \fIlibscan\fR
 941 .IX Subsection "libscan"
 942 .PP
 943 .Vb 1
 944 \&  my $wanted = $self\->libscan($path);
 945 .Ve
 946 .PP
 947 Takes a path to a file or dir and returns an empty string if we don't
 948 want to include this file in the library.  Otherwise it returns the
 949 the \f(CW$path\fR unchanged.
 950 .PP
 951 Mainly used to exclude version control administrative directories from
 952 installation.
 953 .PP
 954 \fIplatform_constants\fR
 955 .IX Subsection "platform_constants"
 956 .PP
 957 .Vb 1
 958 \&    my $make_frag = $mm\->platform_constants
 959 .Ve
 960 .PP
 961 Returns a make fragment defining all the macros initialized in
 962 \&\fIinit_platform()\fR rather than put them in \fIconstants()\fR.
 963 .SH "AUTHOR"
 964 .IX Header "AUTHOR"
 965 Michael G Schwern <schwern@pobox.com> and the denizens of
 966 makemaker@perl.org with code from ExtUtils::MM_Unix and
 967 ExtUtils::MM_Win32.