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
Devel::TraceUse(3) User Contributed Perl Documentation Devel::TraceUse(3)

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

version 2.096

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

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.

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").

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.

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.

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".

chromatic, "<chromatic@wgz.org>"

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

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

"output" option contributed by Olivier Mengué ("<dolmen@cpan.org>").

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

Proxy detection owes a lot to Olivier Mengué ("<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>").

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.

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

    perldoc Devel::TraceUse

You can also look for information at:

  • Perl Hacks, hack #74

    O'Reilly Media, 2006.

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

  • RT: CPAN's request tracker

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

  • MetaCPAN

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

Copyright 2006 chromatic, most rights reserved.

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

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2018-12-30 perl v5.32.1
Search for    or go to Top of page |  Section 3 |  Main Index

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