Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / TRELoad.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 "TRELoad 3"
.TH TRELoad 3 "2003-04-16" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
TRELoad \- Perl extension for loading modules under TRE control
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use TRELoad 'Foo' => ['abc', 'def'],
\&              'Bar',
\&              'Baz' => [ '$somevar' ];
.Ve
.PP
.Vb 1
\&  which is the same as
.Ve
.PP
.Vb 3
\&  use Foo 'abc', 'def';
\&  use Bar;
\&  use Baz '$somevar';
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
.Vb 5
\& This module adds a layer of indirection between modules under
\& TRE control and the scripts/modules that use them.  It allows
\& the TRE-controlled modules to be intstalled unmodified.  TRELoad
\& emulates the Exporter, so client modules are able to import
\& symbols from the TRE modules.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The TRELoad module exists as a layer of indirection between perl
modules under \s-1TRE\s0 control and scripts/modules that use them.  The
basic idea is that we want to use \s-1TRE\s0 mechanisms to find perl modules,
rather than the include mechanisms built into perl.  That said, we
want to support arbitrary perl modules and fully export the perl
exporter.
.Sh "\s-1USING\s0 A \s-1TRE\s0 \s-1MODULE\s0"
.IX Subsection "USING A TRE MODULE"
The entire usage for the TRELoad module is the 'use' line.  The syntax is:
.PP
.Vb 1
\&  use TRELoad <list>;
.Ve
.PP
In its simplest (and most common) usage, the list contains the names
of modules to import.  For instance, the \s-1TRE\s0 equivalent of:
.PP
.Vb 2
\&  use Foo;
\&  use Bar;
.Ve
.PP
is
.PP
.Vb 1
\&  use TRELoad 'Foo', 'Bar';
.Ve
.PP
With this syntax (i.e., no import list explicitly defined for the
modules), you import symbols in the default export list, just as you
would with the bare 'use' directives.
.PP
A normal use directive can also contain a list of symbols to import,
which override the default export list of the module.  For instance:
.PP
.Vb 1
\&  use Foo 'abc', 'def';
.Ve
.PP
will load the Foo module and import the symbols 'abc' and 'def'
instead of the default export list.  The TRELoad equivalent is to use
an array reference immediately following the module name in the
TRELoad argument list.  The above TRELoad equivalent would be:
.PP
.Vb 1
\&  use TRELoad 'Foo' => ['abc', 'def'];
.Ve
.PP
The perl exporter also supports tags (pseudo\-symbols starting with
\&':'), which are names for lists of symbols.  There is a predefined tag
called ':DEFAULT' which contains all of the symbols in the default
export list.  These tags are also supported by TRELoad.  Therefore,
the following statement:
.PP
.Vb 1
\&  use Foo ':DEFAULT', 'abc';
.Ve
.PP
has the \s-1TRE\s0 equivalent of:
.PP
.Vb 1
\&  use TRELoad 'Foo' => [':DEFAULT', 'abc']
.Ve
.PP
which means to import all symbols in the default export list, plus the
symbol 'abc'.
.PP
TRELoad also supports negations, see 'perldoc Exporter' for more
details.  As a more complicated example, consider:
.PP
.Vb 3
\&  use Foo 'abc';
\&  use Bar ':DEFAULT', 'aaa', '!bbb', '!:ccc';
\&  use Baz;
.Ve
.PP
This means, load Foo, Bar, and Baz.  Import the symbol 'abc' from Foo,
import all the default symbols from Bar, plus 'aaa', minus the symbol
\&'bbb' and minus all symbols in the tag ':ccc'.  Finally, import the
symbols in the default export list from Baz.
.PP
The \s-1TRE\s0 equivalent is:
.PP
.Vb 3
\&  use TRELoad 'Foo' => [ 'abc' ],
\&              'Bar' => [ ':DEFAULT', 'aaa', '!bbb', '!:ccc'],
\&              'Baz';
.Ve
.PP
I assume you get the idea.
.Sh "\s-1OVERRIDING\s0 \s-1TRE_ENTRY\s0"
.IX Subsection "OVERRIDING TRE_ENTRY"
The TRELoad module obeys the \s-1TRE\s0 mechanism of appending tool paths to
\&\s-1TRE_ENTRY\s0.  It is possible, however, to override the \s-1TRE_ENTRY\s0
setting.  To do this requires a more general syntax.  Basically,
whereever an array reference can appear in the usage list, you may
substitute a hash reference.  The legal keys of this hash are 'import'
(whose value is an array reference that is treated as an import list)
and 'tre_entry' (whose value is intrepreted as a string to use as a
value for \s-1TRE_ENTRY\s0).
.PP
For example:
.PP
.Vb 1
\&  use TRELoad 'Foo' => ['abc', 'def'];
.Ve
.PP
and
.PP
.Vb 1
\&  use TRELoad 'Foo' => { import => ['abc', 'def'] };
.Ve
.PP
are exactly identical.
.PP
.Vb 2
\&  use TRELoad 'Foo' => { import    => ['abc', 'def'],
\&                         tre_entry => '/SomeTool' };
.Ve
.PP
is the same thing except that it will use the \s-1TRE_ENTRY\s0 of
\&\*(L"/SomeTool\*(R".
.Sh "\s-1INSTALLING\s0 A \s-1MODULE\s0"
.IX Subsection "INSTALLING A MODULE"
Modules are installed using the normal perl install mechanism.  The
only TRE-specific step is to override the default install prefix:
.PP
.Vb 5
\&  make clean     # if Makefile is already present
\&  perl Makefile.PL \e
\&     PREFIX=/import/bw/tools/release/perlmod/<module_name>/<version>
\&  make
\&  make install
.Ve
.PP
If it is a new module, you will also need to add a .tver entry for the
module name.
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None.
.Sh "\s-1RESTRICTIONS\s0"
.IX Subsection "RESTRICTIONS"
There are couple of restrictions to be aware of:
.IP "\(bu" 4
You cannot use pattern rules in an import list (i.e., import symbols
that begin with '/' or '!/'.  There is no reason this couldn't be made
to work, but it's a fair amount of work and this feature is almost
never used.
.IP "\(bu" 4
You can only use TRELoad on a top-level module.  For instance, if a
module Foo contains a Foo.pm with interface code for the underlying
modules Foo::Bar and Foo::Baz, you must use a \*(L"use TRELoad 'Foo'\*(R",
since Foo::Bar and Foo::Baz will not be recognized by configsrch.  If
you need to use those modules directly (which usually is not a good
idea), you can do:
.Sp
.Vb 3
\&  use TRELoad 'Foo';
\&  use Foo::Bar;
\&  use Foo::Baz;
.Ve
.Sp
The TRELoad line will add the appropriate version of Foo to the
include path, so you can just use a regular 'use' for its sub\-modules.
.IP "\(bu" 4
Using a number to specify a minimum version is not supported (as in:
\&\*(L"use Foo 3.01;\*(R") on the TRELoad 'use' line.  You can get the effect,
however, by using:
.Sp
.Vb 2
\&  use TRELoad 'Foo';
\&  use Foo 3.01;
.Ve
.Sp
The TRELoad line will add the correct version of Foo to the include
path, so the following line will work correctly.
.IP "\(bu" 4
Use perl-style version numbers for your \s-1TRE\s0 versions.  That is to say,
use two decimal places after the '.'.  The reason is that perl does a
simple \s-1ASCII\s0 comparison when it compares version numbers, so it
believes 1.9 to be more recent than 1.10.  \s-1TRE\s0 does not care, but perl
does, so if users want to check the version of the module (see
previous bullet), this convention is required.
.IP "\(bu" 4
You cannot load two different versions of a module in the same script.
For instance, suppose you had a module called Abc and another module
called Composite, where Composite itself used Abc.  If your .tver file
consisted of:
.Sp
.Vb 3
\& Abc / 1.01
\& Abc /Composite 1.02
\& Composite / 2.01
.Ve
.Sp
you would be able to use Abc by itself, and you would get version
1.01.  You could use Composite by itself, which would get version 1.02
of Abc.  What you cannot do is include Abc by itself \s-1AND\s0 from within
Composite via something like:
.Sp
.Vb 1
\&  use TRELoad 'Abc', 'Composite';
.Ve
.Sp
This is because it would try to load \s-1BOTH\s0 versions of 1.01 and 1.02
of Abc in the same interpreter, and the names would conflict.  In this
case, TRELoad prints a warning message to stderr and uses the first
version loaded of the module in question.  It is impossible to make
this work without modifying the modules themselves, and the major
design goal of TRELoad was to enable the \s-1TRE\s0 use of arbitrary perl
modules.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 2
\& perlmod(1), Exporter(3),
\& http://ppgweb.eng/cad/cheetah-cad/public/dev_env/tre_design_spec.pdf
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeff Gibson, <jeff.gibson@sun.com>