GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DEVEL::MODLIST (3)

.ds Aq ’

NAME

Devel::Modlist - Perl extension to collect module use information

CONTENTS

SYNOPSIS



    perl -d:Modlist script.pl



DESCRIPTION

The <B>Devel::ModlistB> utility is provided as a means by which to get a quick run-down on which libraries and modules are being utilized by a given script.

Just as compiler systems like gcc provide dependancy information via switches such as -M, <B>Devel::ModlistB> is intended to assist script authors in preparing dependancy information for potential users of their scripts.

USAGE

Usage of <B>Devel::ModlistB> is simple. The primary method of invocation is to use the -d option of Perl:



    perl -d:Modlist script.pl



Alternately, one could use the -M option:



    perl -MDevel::Modlist script.pl



In the case of this module, the two are identical save for the amount of typing (and option passing, see below). It is not recommended that this module be loaded directly by a script via the <B>useB> keyword, as that would cause the dependancy reporting after every invocation until it was removed from the code.

OPTIONS

The following options may be specified to the package. These are specified either by:



    perl -MDevel::Modlist=option1[,option2,...]



or



    perl -d:Modlist=option1[,option2,...]



Options may also be given in an environment variable, which gets read at any invocation in which there are <B>noB> options explicitly provided. If any options are given in the invocation, then the environment variable is ignored. Two different names are recognized:



    Devel::Modlist
    Devel__Modlist



The latter is to accomodate shells that do not like the presence of :: in an environment variable name.

The options:
stdout By default, the report is printed on the STDERR filehandle. If this option is present, it is sent to STDOUT instead.
cpan Reduce the resulting list of modules by using the data maintained in the local CPAN configuration area. The <B>CPANB> module (see CPAN) maintains a very thorough representation of the contents of the archive, on a per-module basis. Using this option means that if there are two or more modules that are parts of the same distribution, only one will be reported (the one with the shortest name). This is useful for generating a minimalist dependancy set that can in turn be fed to the <B>CPANB> install command to ensure that all needed modules are in fact present.
cpandist This is identical to the option above, with the exception that it causes the reported output to be the <B>CPANB> filename rather than the module name in the standard Perl syntax. This can also be fed to the <B>CPANB> shell, but it can also be used by other front-ends as a path component in fetching the requisite file from an archive site. Since the name contains the version number, this behaves as though noversion (see below) was also set. If both cpan and cpandist are set, this option (cpandist) takes precedence. If path is also specified, this option again takes precedence.
nocore Suppress the display of those modules that are a part of the Perl core. This is dependant on the Perl private library area not being an exact substring of the site-dependant library. The build process checks this for you prior to install.
noversion Suppress the inclusion of version information with the module names. If a module has defined its version by means of the accepted standard of declaring a variable $VERSION in the package namespace, <B>Devel::ModlistB> finds this and includes it in the report by default. Use this option to override that default.
zerodefault Also oriented towards the display of versions, this option tells the report to use a zero (0) as the default version if the package has not provided a value. Otherwise, an empty string is displayed (unless <B>noversionB> is given).
path Display the path and filename of each module instead of the module name. Useful for producing lists for later input to tools such as <B>rpmB>.
yaml =item yamlheader=NAME =item yamlheaderindent=N =item yamlindent=N =item yamlcomplete (Experimental, some options and/or features may change in future releases.)

If any <B>yamlB> option is present, the output format is in YAML rather than simple text. Additionally, the options can exert a degree of control over the format of the resulting YAML. Those options that take value must provide them by using a = character immediately followed by the value, with no space surrounding the =.
yamlheader=NAME Specify a header for the YAML section being emitted. This roughly corresponds to the name of the section (or item) in the resulting parsed YAML tree. (See any of the YAML-related modules on CPAN for an explanation of how a YAML file is transformed into a Perl data structure.) If no header value is specified, the default is Requires. If you wish to suppress this header entirely, pass the special value none, i.e., yamlheader=none.
yamlheaderindent=N Specify the indentation for the section header. By default, the header is flush to the left, an indentation of 0. The value provided specifies the number of space characters printed before the header.
yamlindent=N Specify the indentation for the key/value pairs (or sequential-list items, see below). This defaults to 4, and represents the number of leading spaces on each line. If <B>yamlheaderB> is set to none, then this is not given a default, thus allowing the lines to be left-flush in the absence of the header. If you wish the lines to have no indentation, pass this option with a value of 0; the default is only applied if the option is not explicitly present. The indentation is relative to the value of <B>yamlheaderindentB>, so if you provide a non-zero value for that option, it will be added to this one (unless the header is suppressed by yamlheader=none).
yamlcomplete If this option is present, the output will be a complete YAML document, with a comment identifying the generator and a --- separator. <B>yamlheaderB> may still be set to none to supress the header, even when a complete document is being generated.

The <B>yamlB> option is just to allow selection of the YAML option without making any adjustments to the formatting. If any of the other YAML options are present, it will trigger this output format; an explicit <B>yamlB> would be unnecessary.

The YAML output format respects other options (<B>stdoutB>, <B>noversionB>, <B>zerodefaultB>, etc.). If <B>noversionB> is given, the output is a sequential list rather than key/value pairings. If <B>pathB> is given, the keys (or values of the sequential list) are pathnames. Whether pathnames or module names are used, those values are always explicitly quoted in the YAML output.

stop Exit before the first actual program line is executed. This provides for fetching the dependancy list without actually running the full program. This has a drawback: if the program uses any of <B>requireB>, <B>evalB> or other such mechanisms to load libraries after the compilation phase, these will not be reported.

CAVEATS

Perl versions up to 5.6.0 cannot accept options to the -d: flag as with the -M flag. Thus, to pass options one must use:



    perl -MDevel::Modlist=option1[,option2,...]



Unfortunately, this inhibits the <B>stopB> option detailed earlier. To use this option, an invocation of:



    perl -d:Modlist -MDevel::Modlist=option1[,option2,...]



does the trick, as the first invocation puts the interpreter in debugging mode (necessary for <B>stopB> to work) while the second causes the options to be parsed and recorded by <B>Devel::ModlistB>.

Versions of Perl from 5.6.1 onwards allow options to be included with the -d:Modlist flag.

Because <B>Devel::ModlistB> uses the strict pragma internally (as all modules should), that pragma is always removed from the output to avoid generating a false-positive.

AUTHOR

Randy J. Ray <rjray@blackperl.com>, using idea and prototype code provided by Tim Bunce <Tim.Bunce@ig.co.uk>

LICENSE

This module and the code within are released under the terms of the Artistic License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php). This code may be redistributed under either the Artistic License or the GNU Lesser General Public License (LGPL) version 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php).
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DEVEL::MODLIST (3) 2008-09-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.