NAME

App::PrereqGrapher - generate dependency graph using Perl::PrereqScanner

SYNOPSIS

  use App::PrereqGrapher;
  
  my %options = (
                          format => 'dot',
                         no_core => 0,
                 no_recurse_core => 1,
                     output_file => 'prereqs.dot'
                         verbose => 0,
                );
  my $grapher = App::PrereqGrapher->new( %options );
  
  $grapher->generate_graph('Module::Path');

DESCRIPTION

App::PrereqGrapher builds a directed graph of the prereqs or dependencies for a file or module. It uses Perl::PrereqScanner to find the dependencies for the seed, and then repeatedly calls Perl::PrereqScanner on those dependencies, and so on, until all dependencies have been found.

It then saves the resulting graph to a file, using one of the five supported formats. The default format is 'dot', the format used by the GraphViz graph drawing toolkit.

If your code contains lines like:

 require 5.006;
 use 5.006;

Then you'll end up with a dependency labelled perl 5.006; this way you can see where you're dependent on modules which require different minimum versions of perl.

METHODS

new

The constructor understands the following options:

format

Select the output format, which must be one of: dot, svg, vcg, gml, or html. See "OUTPUT FORMATS" for more about the supported output formats. If not specified, the default format is 'dot'.

output_file

Specifies the name of the file to write the dependency graph into, including the extension. If not specified, the filename will be dependencies, with the extension set according to the format.

depth

Only generate the graph to the specified depth. If the complete dependency graph is very large, this option may help you get an overview.

no_core

Don't include any modules which are core (included with perl) for the version of perl being used.

no_recurse_core

When a core module is used, include it in the dependency graph, but don't show any of its dependencies.

timeout

Specifies the timeout for Graph::Easy when its laying out the graph. This is mainly relevant for formats like SVG and HTML, where the graph layout is done in Perl. Defaults to 5 seconds.

verbose

Display verbose logging as the grapher runs. Currently this will just tell you if a module was use'd or require'd, but couldn't be found locally.

generate_graph

Takes one or more seed items. Each item may be a module or the path to a perl file.

  $grapher->generate_graph('Module::Path', 'Module::Version');

It will first try and interpret each item as a module, but if it can't find a module with the given name, it will try and interpret it as a file path. This means that if you have a file called strict for example, then you won't be able to run:

  $grapher->generate_graph('strict');

as it will be interpreted as the module of that name. Put an explicit path to stop this:

  $grapher->generate_graph('./strict');

OUTPUT FORMATS

dot

The format used by GraphViz and related tools.

svg

Scalable Vector Graphics (SVG) a W3C standard. You have to install Graph::Easy::As_svg if you want to use this format.

vcg

The VCG or GDL format.

gml

Graph Markup Language, aka GraphML.

html

Generate an HTML format with embedded CSS. I haven't been able to get this to work, but it's one of the formats supported by Graph::Easy.

KNOWN BUGS

Perl::PrereqScanner uses PPI to parse each item. PPI has a hard-coded limit for the size of file it's prepared to parse (currently just over 1M). This means that very large files will be ignored; for example Perl::Tidy cannot be graphed, and if you try and graph a file that use's Perl::Tidy, then it just won't appear in the graph.

If a class isn't defined in its own file, then App::PrereqGrapher won't find it; for example Tie::StdHash is defined inside Tie::Hash. By default these are silently ignored, but if you use the -verbose option you'll get the following warning:

  can't find Tie::StdHash - keeping calm and carrying on.

Perl::PrereqScanner parses code and makes no attempt to determine whether any of it would actually run on your platform. For example, one module might decide at run-time whether to require Foo::Bar or Foo::Baz, and might never use Foo::Baz on your OS. But Perl::PrereqScanner will see both of Foo::Bar and Foo::Baz as pre-reqs.

TODO

• Have an option to control what depth we should recurse to? You might only be interested in the dependencies of your code, and their first level of dependencies.

• Show some indication that we're running. It can take a long time to run if your ultimate dependency graph is very large.

SEE ALSO

The distribution for this module contains a command-line script, prereq-grapher. It has its own documentation.

This module uses Perl::PrereqScanner to parse the source code, and Graph::Easy to generate and save the dependency graph.

http://neilb.org/reviews/dependencies.html: a review of CPAN modules that can be used to get dependency information.

REPOSITORY

https://github.com/neilbowers/App-PrereqGrapher

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Neil Bowers <neilb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm App::PrereqGrapher

perl -MCPAN -e shell
install App::PrereqGrapher