Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Devel::Modlist(3)     User Contributed Perl Documentation    Devel::Modlist(3)

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

SYNOPSIS
	   perl	-d:Modlist script.pl

DESCRIPTION
       The Devel::Modlist 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", Devel::Modlist is	intended to assist script
       authors in preparing dependancy information for potential users of
       their scripts.

USAGE
       Usage of	Devel::Modlist 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 use 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 no 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 CPAN 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 CPAN "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	CPAN filename rather than the
	   module name in the standard Perl syntax. This can also be fed to
	   the CPAN 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,
	   Devel::Modlist 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 noversion 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
	   rpm.

       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 yaml 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
		   yamlheader 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
		   yamlheaderindent, 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. yamlheader may still be set to "none" to
		   supress the header, even when a complete document is	being
		   generated.

	   The yaml 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 yaml would be unnecessary.

	   The YAML output format respects other options (stdout, noversion,
	   zerodefault,	etc.). If noversion is given, the output is a
	   sequential list rather than key/value pairings. If path 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
	   require, eval 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	stop 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 stop to work) while the second causes the
       options to be parsed and	recorded by Devel::Modlist.

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

       Because Devel::Modlist 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).

perl v5.32.0			  2008-09-05		     Devel::Modlist(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | OPTIONS | CAVEATS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::Modlist&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help