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

FreeBSD Manual Pages

  
 
  

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

NAME
       Devel::TraceUse - show the modules your program loads, recursively

VERSION
       version 2.096

SYNOPSIS
       An apparently simple program may	load a lot of modules.	That's useful,
       but sometimes you may wonder exactly which part of your program loads
       which module.

       "Devel::TraceUse" can analyze a program to see which part used which
       module.	I recommend using it from the command line:

	 $ perl	-d:TraceUse your_program.pl

       This will display a tree	of the modules ultimately used to run your
       program.	 (It also runs your program with only a	little startup cost
       all the way through to the end.)

	 Modules used from your_program.pl:
	    1.	strict 1.04, your_program.pl line 1 [main]
	    2.	warnings 1.06, your_program.pl line 2 [main]
	    3.	Getopt::Long 2.37, your_program.pl line	3 [main]
	    4.	  vars 1.01, Getopt/Long.pm line 37
	    5.	    warnings::register 1.01, vars.pm line 7
	    6.	  Exporter 5.62, Getopt/Long.pm	line 43
	    9.	    Exporter::Heavy 5.62, Exporter.pm line 18
	    7.	  constant 1.13, Getopt/Long.pm	line 226
	    8.	  overload 1.06, Getopt/Long.pm	line 1487 [Getopt::Long::CallBack]

       The load	order is listed	on the first column. The version is displayed
       after the module	name, if available. The	calling	package	is shown
       between square brackets if different from the package that can be
       inferred	from the file name. Extra information is also provided if the
       module was loaded from within and "eval".

       "Devel::TraceUse" will also report modules that failed to be loaded,
       under the modules that tried to load them.

       In the very rare	case when "Devel::TraceUse" is not able	to attach a
       loaded module to	the tree, it will be reported at the end.

       If a particular line of code is used at least 2 times to	load modules,
       it is considered	as part	of a "module loading proxy subroutine",	or
       just "proxy".  "base::import", "parent::import",
       "Module::Runtime::require_module" are such subroutines, among others.
       If proxies are found, the list is reported like this:

	    <occurences> <filename> line <line>[, sub <subname>]

       Example:

	   Possible proxies:
	     59	Module/Runtime.pm, line	317, sub require_module
	     13	base.pm	line 90, sub import
	      3	Module/Pluggable/Object.pm line	311, sub _require

       Even though using "-MDevel::TraceUse" is	possible, it is	preferable to
       use "-d:TraceUse", as the debugger will provide more accurate
       information.  You will be reminded in the output.

       If you want to know only	the modules loaded during the compile phase,
       use the standard	"-c" option of perl (see perlrun):

	 $ perl	-c -d:TraceUse your_program.pl

   Parameters
       You can hide the	core modules that your program used by providing
       parameters at "use" time:

	 $ perl	-d:TraceUse[=<option1>:<value1>[,<option2>:<value2>[...]]]

       "hidecore"
	     $ perl -d:TraceUse=hidecore your_program.pl

	   This	will not renumber the modules so the core module's positions
	   will	be visible as gaps in the numbering. In	some cases evidence
	   may also be visible of the core module's usage (e.g.	a caller shown
	   as base or parent).

	   You may also	specify	the version of Perl for	which you want to hide
	   the core modules (the default is the	running	version):

	     $ perl -d:TraceUse=hidecore:5.8.1 your_program.pl

	   The version string can be given as x.yyy.zzz	(dot-separated)	or
	   x.yyyzzz (decimal). For example, the	strings	5.8.1, 5.08.01,
	   5.008.001 and 5.008001 will all represent Perl version 5.8.1, and
	   5.5.30, "5.005_03" will all represent Perl version 5.005_03.

       "output"
	     $ perl -d:TraceUse=output:out.txt your_program.pl

	   This	will output the	TraceUse result	to the given file instead of
	   warn.

	   Note	that TraceUse warnings will still be output as warnings.

	   The output file is opened at	initialization time, so	there should
	   be no surprise in relative path interpretation even if your program
	   changes the current directory.

SEE ALSO
       There are plenty	of modules on CPAN for getting a list of your code's
       dependencies. They fall into three general classes:

       1.  Those that tell you what modules were actually loaded at run-time,
	   like	"Devel-TraceUse", through introspection.

	   This	is often done by looking at %INC, but other approaches include
	   over-riding the "require" built-in, or adding a coderef to the head
	   of @INC (see	perldoc	require
	   <http://perldoc.perl.org/functions/require.html> for	more details
	   of that approach).  This may	not give you the full list of
	   dependencies, because different modules may be loaded depended on
	   the path taken through the code.

       2.  Those that parse the	code, to determine dependencies.

	   This	may catch some dependencies missed by the previous category,
	   but in turn may miss	modules	that are dynamically loaded, or	where
	   the code doesn't match the regexps /	parsing	techniques used	to
	   find	"use", "require" and friends.

       3.  Those that look at the declared dependencies	in distributions'
	   metadata files ("META.yml" and "META.json").

   Introspectors
       App::FatPacker::Trace and Devel::Dependencies just gives	a flat list of
       dependencies.  Devel::VersionDump is similar, but also displays the
       version of each module found.

       Instead of listing the names of modules loaded, Devel::Loaded lists the
       full paths to the modules. This might help you spot issues caused by
       the same	module being in	multiple directories on	your @INC path,	I
       guess.

       Devel::Modlist prints a table of	the modules used, and the version of
       the module installed (not the version that was specified	when "use"ing
       the module). It can also	map modules to CPAN distributions, and list
       the distributions you're	dependent on.

       Devel::TraceDeps	overrides the "do" and "require" built-ins, so it can
       get finer-grained information about which modules were used by which
       module. It generates information	about the dependencies,	which you can
       then process with Devel::TraceDeps::Scan.

       Devel::TraceLoad	also overrides "require", but it doesn't override
       "do", so	it might miss some dependencies	in older code.

       Module::PrintUsed looks at %INC to identify dependencies, and prints a
       table with module name, version,	and the	local path where it was	loaded
       from.

   Parsers
       Module::Dependency::Grapher parses locally installed modules to
       determine the full dependency graph, which it can then dump as ASCII or
       one of several graph formats.

       Module::Extract::Use uses PPI to	parse a	source file and	extract
       modules used. It	only reports the first level of	dependencies.

       Module::Used also uses PPI and provides a nice clean API, also only
       providing the first level of dependencies.

       Perl::PrereqScanner is yet another PPI-based scanner, but is probably
       the best	of the lot. App::PrereqGrapher uses "Perl::PrereqScanner" to
       recursively identify dependencies, then generate	a graph	in a number of
       formats;	the prereq-grapher <https://metacpan.org/pod/distribution/App-
       PrereqGrapher/bin/prereq-grapher> provides a command-line interface to
       all of that.

       Module::ExtractUse (not to be confused with the previous	module!)  uses
       Parse::RecDescent to parse perl files looking for "use" and "require"
       statements. It doesn't recurse, so you just get the first level of
       dependencies.

   Metadata spelunkers
       CPAN::FindDependencies fetches "META.yml" or "Makefile.PL" files	from
       search.cpan.org <http://search.cpan.org>, so it takes a while to	run.

       Dist::Requires looks at the tarball for a module	(or the	extracted
       directory structure) and	determines the immediate dependencies. It
       doesn't find the	next level of dependencies and beyond, which
       CPAN::FindDependencies does.

       Module::Depends::Tree uses CPANPLUS to grab tarballs for	distributions
       then extracts dependency	information from metadata files.  It includes
       a front-end script called "deptree".

AUTHORS
       chromatic, "<chromatic@wgz.org>"

       Philippe	Bruhat,	"<book@cpan.org>"

   Contributors
       "hidecore" option contributed by	David Leadbeater, "<dgl@dgl.cx>".

       "output"	option contributed by Olivier MenguA(C)	("<dolmen@cpan.org>").

       "perl -c" support contributed by	Olivier	MenguA(C)
       ("<dolmen@cpan.org>").

       Proxy detection owes a lot to Olivier MenguA(C) ("<dolmen@cpan.org>"),
       who submitted several patches and discussed the topic with me on	IRC.

       The thorough "SEE ALSO" section was written by Neil Bowers
       ("<neilb@cpan.org>").

BUGS
       Please report any bugs or feature requests to "bug-devel-traceuse at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel-TraceUse>.	 We
       can both	track it there.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc Devel::TraceUse

       You can also look for information at:

       o   Perl	Hacks, hack #74

	   O'Reilly Media, 2006.

	   <http://shop.oreilly.com/product/9780596526740.do>

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-TraceUse>

       o   MetaCPAN

	   <https://metacpan.org/release/Devel-TraceUse>

COPYRIGHT
       Copyright 2006 chromatic, most rights reserved.

       Copyright 2010-2018 Philippe Bruhat (BooK), for the rewrite.

LICENSE
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2018-12-30		    Devel::TraceUse(3)

NAME | VERSION | SYNOPSIS | SEE ALSO | AUTHORS | BUGS | SUPPORT | COPYRIGHT | LICENSE

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

home | help