Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / ExtUtils::MM_Any.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ExtUtils::MM_Any 3"
.TH ExtUtils::MM_Any 3 "2003-08-18" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
ExtUtils::MM_Any \- Platform\-agnostic MM methods
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  FOR INTERNAL USE ONLY!
.Ve
.PP
.Vb 1
\&  package ExtUtils::MM_SomeOS;
.Ve
.PP
.Vb 4
\&  # Temporarily, you have to subclass both.  Put MM_Any first.
\&  require ExtUtils::MM_Any;
\&  require ExtUtils::MM_Unix;
\&  @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1FOR\s0 \s-1INTERNAL\s0 \s-1USE\s0 \s-1ONLY\s0!\fR
.PP
ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
modules.  It contains methods which are either inherently
cross-platform or are written in a cross-platform manner.
.PP
Subclass off of ExtUtils::MM_Any \fIand\fR ExtUtils::MM_Unix.  This is a
temporary solution.
.PP
\&\fB\s-1THIS\s0 \s-1MAY\s0 \s-1BE\s0 \s-1TEMPORARY\s0!\fR
.SH "Inherently Cross-Platform Methods"
.IX Header "Inherently Cross-Platform Methods"
These are methods which are by their nature cross-platform and should
always be cross\-platform.
.IP "installvars" 4
.IX Item "installvars"
.Vb 1
\&    my @installvars = $mm->installvars;
.Ve
.Sp
A list of all the INSTALL* variables without the \s-1INSTALL\s0 prefix.  Useful
for iteration or building related variable sets.
.IP "os_flavor_is" 4
.IX Item "os_flavor_is"
.Vb 2
\&    $mm->os_flavor_is($this_flavor);
\&    $mm->os_flavor_is(@one_of_these_flavors);
.Ve
.Sp
Checks to see if the current operating system is one of the given flavors.
.Sp
This is useful for code like:
.Sp
.Vb 6
\&    if( $mm->os_flavor_is('Unix') ) {
\&        $out = `foo 2>&1`;
\&    }
\&    else {
\&        $out = `foo`;
\&    }
.Ve
.IP "dir_targets \fB\s-1DEPRECATED\s0\fR" 4
.IX Item "dir_targets DEPRECATED"
.Vb 1
\&    my $make_frag = $mm->dir_target(@directories);
.Ve
.Sp
\&\fIThis function is deprecated\fR its use is no longer necessary and is
\&\fIonly provided for backwards compatibility\fR.  It is now a no\-op.
blibdirs_target provides a much simpler mechanism and \fIpm_to_blib()\fR can
create its own directories anyway.
.IP "blibdirs_target (o)" 4
.IX Item "blibdirs_target (o)"
.Vb 1
\&    my $make_frag = $mm->blibdirs_target;
.Ve
.Sp
Creates the blibdirs.ts target which creates all the directories we use in
blib/.
.Sh "File::Spec wrappers"
.IX Subsection "File::Spec wrappers"
ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
override File::Spec.
.IP "catfile" 4
.IX Item "catfile"
File::Spec <= 0.83 has a bug where the file part of catfile is not
canonicalized.  This override fixes that bug.
.SH "Thought To Be Cross-Platform Methods"
.IX Header "Thought To Be Cross-Platform Methods"
These are methods which are thought to be cross-platform by virtue of
having been written in a way to avoid incompatibilities.  They may
require partial overrides.
.IP "\fBsplit_command\fR" 4
.IX Item "split_command"
.Vb 1
\&    my @cmds = $MM->split_command($cmd, @args);
.Ve
.Sp
Most \s-1OS\s0 have a maximum command length they can execute at once.  Large
modules can easily generate commands well past that limit.  Its
necessary to split long commands up into a series of shorter commands.
.Sp
\&\fIsplit_command()\fR will return a series of \f(CW@cmds\fR each processing part of
the args.  Collectively they will process all the arguments.  Each
individual line in \f(CW@cmds\fR will not be longer than the
\&\f(CW$self\fR\->max_exec_len being careful to take into account macro expansion.
.Sp
$cmd should include any switches and repeated initial arguments.
.Sp
If no \f(CW@args\fR are given, no \f(CW@cmds\fR will be returned.
.Sp
Pairs of arguments will always be preserved in a single command, this
is a heuristic for things like pm_to_blib and pod2man which work on
pairs of arguments.  This makes things like this safe:
.Sp
.Vb 1
\&    $self->split_command($cmd, %pod2man);
.Ve
.IP "\fBecho\fR" 4
.IX Item "echo"
.Vb 3
\&    my @commands = $MM->echo($text);
\&    my @commands = $MM->echo($text, $file);
\&    my @commands = $MM->echo($text, $file, $appending);
.Ve
.Sp
Generates a set of \f(CW@commands\fR which print the \f(CW$text\fR to a \f(CW$file\fR.
.Sp
If \f(CW$file\fR is not given, output goes to \s-1STDOUT\s0.
.Sp
If \f(CW$appending\fR is true the \f(CW$file\fR will be appended to rather than
overwritten.
.IP "init_VERSION" 4
.IX Item "init_VERSION"
.Vb 1
\&    $mm->init_VERSION
.Ve
.Sp
Initialize macros representing versions of MakeMaker and other tools
.Sp
\&\s-1MAKEMAKER:\s0 path to the MakeMaker module.
.Sp
\&\s-1MM_VERSION:\s0 ExtUtils::MakeMaker Version
.Sp
\&\s-1MM_REVISION:\s0 ExtUtils::MakeMaker version control revision (for backwards 
             compat)
.Sp
\&\s-1VERSION:\s0 version of your module
.Sp
\&\s-1VERSION_MACRO:\s0 which macro represents the version (usually '\s-1VERSION\s0')
.Sp
\&\s-1VERSION_SYM:\s0 like version but safe for use as an \s-1RCS\s0 revision number
.Sp
\&\s-1DEFINE_VERSION:\s0 \-D line to set the module version when compiling
.Sp
\&\s-1XS_VERSION:\s0 version in your .xs file.  Defaults to $(\s-1VERSION\s0)
.Sp
\&\s-1XS_VERSION_MACRO:\s0 which macro represents the \s-1XS\s0 version.
.Sp
\&\s-1XS_DEFINE_VERSION:\s0 \-D line to set the xs version when compiling.
.Sp
Called by init_main.
.IP "wraplist" 4
.IX Item "wraplist"
Takes an array of items and turns them into a well-formatted list of
arguments.  In most cases this is simply something like:
.Sp
.Vb 3
\&    FOO \e
\&    BAR \e
\&    BAZ
.Ve
.IP "manifypods" 4
.IX Item "manifypods"
Defines targets and routines to translate the pods into manpages and
put them into the INST_* directories.
.IP "manifypods_target" 4
.IX Item "manifypods_target"
.Vb 1
\&  my $manifypods_target = $self->manifypods_target;
.Ve
.Sp
Generates the manifypods target.  This target generates man pages from
all \s-1POD\s0 files in \s-1MAN1PODS\s0 and \s-1MAN3PODS\s0.
.IP "makemakerdflt_target" 4
.IX Item "makemakerdflt_target"
.Vb 1
\&  my $make_frag = $mm->makemakerdflt_target
.Ve
.Sp
Returns a make fragment with the makemakerdeflt_target specified.
This target is the first target in the Makefile, is the default target
and simply points off to 'all' just in case any make variant gets
confused or something gets snuck in before the real 'all' target.
.IP "special_targets" 4
.IX Item "special_targets"
.Vb 1
\&  my $make_frag = $mm->special_targets
.Ve
.Sp
Returns a make fragment containing any targets which have special
meaning to make.  For example, .SUFFIXES and .PHONY.
.IP "POD2MAN_macro" 4
.IX Item "POD2MAN_macro"
.Vb 1
\&  my $pod2man_macro = $self->POD2MAN_macro
.Ve
.Sp
Returns a definition for the \s-1POD2MAN\s0 macro.  This is a program
which emulates the pod2man utility.  You can add more switches to the
command by simply appending them on the macro.
.Sp
Typical usage:
.Sp
.Vb 1
\&    $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
.Ve
.IP "test_via_harness" 4
.IX Item "test_via_harness"
.Vb 1
\&  my $command = $mm->test_via_harness($perl, $tests);
.Ve
.Sp
Returns a \f(CW$command\fR line which runs the given set of \f(CW$tests\fR with
Test::Harness and the given \f(CW$perl\fR.
.Sp
Used on the t/*.t files.
.IP "test_via_script" 4
.IX Item "test_via_script"
.Vb 1
\&  my $command = $mm->test_via_script($perl, $script);
.Ve
.Sp
Returns a \f(CW$command\fR line which just runs a single test without
Test::Harness.  No checks are done on the results, they're just
printed.
.Sp
Used for test.pl, since they don't always follow Test::Harness
formatting.
.IP "libscan" 4
.IX Item "libscan"
.Vb 1
\&  my $wanted = $self->libscan($path);
.Ve
.Sp
Takes a path to a file or dir and returns an empty string if we don't
want to include this file in the library.  Otherwise it returns the
the \f(CW$path\fR unchanged.
.Sp
Mainly used to exclude \s-1RCS\s0, \s-1CVS\s0, and \s-1SCCS\s0 directories from
installation.
.IP "tool_autosplit" 4
.IX Item "tool_autosplit"
Defines a simple perl call that runs autosplit. May be deprecated by
pm_to_blib soon.
.IP "all_target" 4
.IX Item "all_target"
Generate the default target 'all'.
.IP "metafile_target" 4
.IX Item "metafile_target"
.Vb 1
\&    my $target = $mm->metafile_target;
.Ve
.Sp
Generate the metafile target.
.Sp
Writes the file \s-1META\s0.yml, \s-1YAML\s0 encoded meta-data about the module.  The
format follows Module::Build's as closely as possible.  Additionally, we
include:
.Sp
.Vb 2
\&    version_from
\&    installdirs
.Ve
.IP "signature_target" 4
.IX Item "signature_target"
.Vb 1
\&    my $target = $mm->signature_target;
.Ve
.Sp
Generate the signature target.
.Sp
Writes the file \s-1SIGNATURE\s0 with \*(L"cpansign \-s\*(R".
.IP "metafile_addtomanifest_target" 4
.IX Item "metafile_addtomanifest_target"
.Vb 1
\&  my $target = $mm->metafile_addtomanifest_target
.Ve
.Sp
Adds the \s-1META\s0.yml file to the \s-1MANIFEST\s0.
.IP "signature_addtomanifest_target" 4
.IX Item "signature_addtomanifest_target"
.Vb 1
\&  my $target = $mm->signature_addtomanifest_target
.Ve
.Sp
Adds the \s-1META\s0.yml file to the \s-1MANIFEST\s0.
.Sh "Abstract methods"
.IX Subsection "Abstract methods"
Methods which cannot be made cross-platform and each subclass will
have to do their own implementation.
.IP "oneliner" 4
.IX Item "oneliner"
.Vb 2
\&  my $oneliner = $MM->oneliner($perl_code);
\&  my $oneliner = $MM->oneliner($perl_code, \e@switches);
.Ve
.Sp
This will generate a perl one-liner safe for the particular platform
you're on based on the given \f(CW$perl_code\fR and \f(CW@switches\fR (a \-e is
assumed) suitable for using in a make target.  It will use the proper
shell quoting and escapes.
.Sp
$(\s-1PERLRUN\s0) will be used as perl.
.Sp
Any newlines in \f(CW$perl_code\fR will be escaped.  Leading and trailing
newlines will be stripped.  Makes this idiom much easier:
.Sp
.Vb 4
\&    my $code = $MM->oneliner(<<'CODE', [...switches...]);
\&some code here
\&another line here
\&CODE
.Ve
.Sp
Usage might be something like:
.Sp
.Vb 3
\&    # an echo emulation
\&    $oneliner = $MM->oneliner('print "Foo\en"');
\&    $make = '$oneliner > somefile';
.Ve
.Sp
All dollar signs must be doubled in the \f(CW$perl_code\fR if you expect them
to be interpreted normally, otherwise it will be considered a make
macro.  Also remember to quote make macros else it might be used as a
bareword.  For example:
.Sp
.Vb 2
\&    # Assign the value of the $(VERSION_FROM) make macro to $vf.
\&    $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
.Ve
.Sp
Its currently very simple and may be expanded sometime in the figure
to include more flexible code and switches.
.IP "\fBquote_literal\fR" 4
.IX Item "quote_literal"
.Vb 1
\&    my $safe_text = $MM->quote_literal($text);
.Ve
.Sp
This will quote \f(CW$text\fR so it is interpreted literally in the shell.
.Sp
For example, on Unix this would escape any single-quotes in \f(CW$text\fR and
put single-quotes around the whole thing.
.IP "\fBescape_newlines\fR" 4
.IX Item "escape_newlines"
.Vb 1
\&    my $escaped_text = $MM->escape_newlines($text);
.Ve
.Sp
Shell escapes newlines in \f(CW$text\fR.
.IP "max_exec_len" 4
.IX Item "max_exec_len"
.Vb 1
\&    my $max_exec_len = $MM->max_exec_len;
.Ve
.Sp
Calculates the maximum command size the \s-1OS\s0 can exec.  Effectively,
this is the max size of a shell command line.
.IP "\fBinit_others\fR" 4
.IX Item "init_others"
.Vb 1
\&    $MM->init_others();
.Ve
.Sp
Initializes the macro definitions used by \fItools_other()\fR and places them
in the \f(CW$MM\fR object.
.Sp
If there is no description, its the same as the parameter to
\&\fIWriteMakefile()\fR documented in ExtUtils::MakeMaker.
.Sp
Defines at least these macros.
.Sp
.Vb 1
\&  Macro             Description
.Ve
.Sp
.Vb 2
\&  NOOP              Do nothing
\&  NOECHO            Tell make not to display the command itself
.Ve
.Sp
.Vb 4
\&  MAKEFILE
\&  FIRST_MAKEFILE
\&  MAKEFILE_OLD
\&  MAKE_APERL_FILE   File used by MAKE_APERL
.Ve
.Sp
.Vb 2
\&  SHELL             Program used to run
\&                    shell commands
.Ve
.Sp
.Vb 9
\&  ECHO              Print text adding a newline on the end
\&  RM_F              Remove a file 
\&  RM_RF             Remove a directory          
\&  TOUCH             Update a file's timestamp   
\&  TEST_F            Test for a file's existence 
\&  CP                Copy a file                 
\&  MV                Move a file                 
\&  CHMOD             Change permissions on a     
\&                    file
.Ve
.Sp
.Vb 2
\&  UMASK_NULL        Nullify umask
\&  DEV_NULL          Supress all command output
.Ve
.IP "init_DIRFILESEP" 4
.IX Item "init_DIRFILESEP"
.Vb 2
\&  $MM->init_DIRFILESEP;
\&  my $dirfilesep = $MM->{DIRFILESEP};
.Ve
.Sp
Initializes the \s-1DIRFILESEP\s0 macro which is the seperator between the
directory and filename in a filepath.  ie. / on Unix, \e on Win32 and
nothing on \s-1VMS\s0.
.Sp
For example:
.Sp
.Vb 2
\&    # instead of $(INST_ARCHAUTODIR)/extralibs.ld
\&    $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
.Ve
.Sp
Something of a hack but it prevents a lot of code duplication between
MM_* variants.
.Sp
Do not use this as a seperator between directories.  Some operating
systems use different seperators between subdirectories as between
directories and filenames (for example:  VOLUME:[dir1.dir2]file on \s-1VMS\s0).
.IP "init_linker" 4
.IX Item "init_linker"
.Vb 1
\&    $mm->init_linker;
.Ve
.Sp
Initialize macros which have to do with linking.
.Sp
\&\s-1PERL_ARCHIVE:\s0 path to libperl.a equivalent to be linked to dynamic
extensions.
.Sp
\&\s-1PERL_ARCHIVE_AFTER:\s0 path to a library which should be put on the
linker command line \fIafter\fR the external libraries to be linked to
dynamic extensions.  This may be needed if the linker is one\-pass, and
Perl includes some overrides for C \s-1RTL\s0 functions, such as \fImalloc()\fR.
.Sp
\&\s-1EXPORT_LIST:\s0 name of a file that is passed to linker to define symbols
to be exported.
.Sp
Some OSes do not need these in which case leave it blank.
.IP "init_platform" 4
.IX Item "init_platform"
.Vb 1
\&    $mm->init_platform
.Ve
.Sp
Initialize any macros which are for platform specific use only.
.Sp
A typical one is the version number of your \s-1OS\s0 specific mocule.
(ie. MM_Unix_VERSION or \s-1MM_VMS_VERSION\s0).
.IP "platform_constants" 4
.IX Item "platform_constants"
.Vb 1
\&    my $make_frag = $mm->platform_constants
.Ve
.Sp
Returns a make fragment defining all the macros initialized in
\&\fIinit_platform()\fR rather than put them in \fIconstants()\fR.
.IP "os_flavor" 4
.IX Item "os_flavor"
.Vb 1
\&    my @os_flavor = $mm->os_flavor;
.Ve
.Sp
@os_flavor is the style of operating system this is, usually
corresponding to the MM_*.pm file we're using.  
.Sp
The first element of \f(CW@os_flavor\fR is the major family (ie. Unix,
Windows, \s-1VMS\s0, \s-1OS/2\s0, etc...) and the rest are sub families.
.Sp
Some examples:
.Sp
.Vb 6
\&    Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
\&    Windows NT     ('Win32', 'WinNT')
\&    Win98          ('Win32', 'Win9x')
\&    Linux          ('Unix',  'Linux')
\&    MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
\&    OS/2           ('OS/2')
.Ve
.Sp
This is used to write code for styles of operating system.  
See \fIos_flavor_is()\fR for use.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael G Schwern <schwern@pobox.com> and the denizens of
makemaker@perl.org with code from ExtUtils::MM_Unix and
ExtUtils::MM_Win32.