Module::ScanDeps(3pm)

1Module::ScanDeps(3)   User Contributed Perl Documentation  Module::ScanDeps(3)
2
3
4

NAME

6       Module::ScanDeps - Recursively scan Perl code for dependencies
7

VERSION

9       This document describes version 0.71 of Module::ScanDeps, released Jan‐
10       uary  4, 2007.
11

SYNOPSIS

13       Via the command-line program scandeps.pl:
14
15           % scandeps.pl *.pm          # Print PREREQ_PM section for *.pm
16           % scandeps.pl -e "use utf8" # Read script from command line
17           % scandeps.pl -B *.pm       # Include core modules
18           % scandeps.pl -V *.pm       # Show autoload/shared/data files
19
20       Used in a program;
21
22           use Module::ScanDeps;
23
24           # standard usage
25           my $hash_ref = scan_deps(
26               files   => [ 'a.pl', 'b.pl' ],
27               recurse => 1,
28           );
29
30           # shorthand; assume recurse == 1
31           my $hash_ref = scan_deps( 'a.pl', 'b.pl' );
32
33           # App::Packer::Frontend compatible interface
34           # see App::Packer::Frontend for the structure returned by get_files
35           my $scan = Module::ScanDeps->new;
36           $scan->set_file( 'a.pl' );
37           $scan->set_options( add_modules => [ 'Test::More' ] );
38           $scan->calculate_info;
39           my $files = $scan->get_files;
40

DESCRIPTION

42       This module scans potential modules used by perl programs, and returns
43       a hash reference; its keys are the module names as appears in %INC
44       (e.g. "Test/More.pm"); the values are hash references with this struc‐
45       ture:
46
47           {
48               file    => '/usr/local/lib/perl5/5.8.0/Test/More.pm',
49               key     => 'Test/More.pm',
50               type    => 'module',    # or 'autoload', 'data', 'shared'
51               used_by => [ 'Test/Simple.pm', ... ],
52           }
53
54       One function, "scan_deps", is exported by default.  Three other func‐
55       tions ("scan_line", "scan_chunk", "add_deps") are exported upon
56       request.
57
58       Users of App::Packer may also use this module as the dependency-check‐
59       ing frontend, by tweaking their p2e.pl like below:
60
61           use Module::ScanDeps;
62           ...
63           my $packer = App::Packer->new( frontend => 'Module::ScanDeps' );
64           ...
65
66       Please see App::Packer::Frontend for detailed explanation on the struc‐
67       ture returned by "get_files".
68
69       scan_deps
70
71           $rv_ref = scan_deps(
72               files   => \@files,     recurse => $recurse,
73               rv      => \%rv,        skip    => \%skip,
74               compile => $compile,    execute => $execute,
75           );
76           $rv_ref = scan_deps(@files); # shorthand, with recurse => 1
77
78       This function scans each file in @files, registering their dependencies
79       into %rv, and returns a reference to the updated %rv.  The meaning of
80       keys and values are explained above.
81
82       If $recurse is true, "scan_deps" will call itself recursively, to per‐
83       form a breadth-first search on text files (as defined by the -T opera‐
84       tor) found in %rv.
85
86       If the "\%skip" is specified, files that exists as its keys are
87       skipped.  This is used internally to avoid infinite recursion.
88
89       If $compile or $execute is true, runs "files" in either compile-only or
90       normal mode, then inspects their %INC after termination to determine
91       additional runtime dependencies.
92
93       If $execute is an array reference, runs the files contained in it
94       instead of @files.
95
96       Additionally, an option "warn_missing" is recognized. If set to true,
97       "scan_deps" issues a warning to STDOUT for every module file that the
98       scanned code depends but that wasn't found. Please note that this may
99       also report numerous false positives. That is why by default, the
100       heuristic silently drops all dependencies it cannot find.
101
102       scan_deps_runtime
103
104       Like scan_deps, but skips the static scanning part.
105
106       scan_line
107
108           @modules = scan_line($line);
109
110       Splits a line into chunks (currently with the semicolon characters),
111       and return the union of "scan_chunk" calls of them.
112
113       If the line is "__END__" or "__DATA__", a single "__END__" element is
114       returned to signify the end of the program.
115
116       Similarly, it returns a single "__POD__" if the line matches "/^=\w/";
117       the caller is responsible for skipping appropriate number of lines
118       until "=cut", before calling "scan_line" again.
119
120       scan_chunk
121
122           $module = scan_chunk($chunk);
123           @modules = scan_chunk($chunk);
124
125       Apply various heuristics to $chunk to find and return the module
126       name(s) it contains.  In scalar context, returns only the first module
127       or "undef".
128
129       add_deps
130
131           $rv_ref = add_deps( rv => \%rv, modules => \@modules );
132           $rv_ref = add_deps( @modules ); # shorthand, without rv
133
134       Resolves a list of module names to its actual on-disk location, by
135       finding in @INC and @Module::ScanDeps::IncludeLibs; modules that cannot
136       be found are skipped.
137
138       This function populates the %rv hash with module/filename pairs, and
139       returns a reference to it.
140

NOTES

142       You can set the global variable @Module::ScanDeps::IncludeLibs to spec‐
143       ify additional directories in which to search modules without modifying
144       @INC itself.
145

CAVEATS

147       This module intentially ignores the BSDPAN hack on FreeBSD -- the addi‐
148       tional directory is removed from @INC altogether.
149
150       The static-scanning heuristic is not likely to be 100% accurate, espe‐
151       cially on modules that dynamically load other modules.
152
153       Chunks that span multiple lines are not handled correctly.  For exam‐
154       ple, this one works:
155
156           use base 'Foo::Bar';
157
158       But this one does not:
159
160           use base
161               'Foo::Bar';
162

AUTHORS

173       Audrey Tang <autrijus@autrijus.org>
174
175       To a lesser degree: Steffen Mueller <smueller@cpan.org>
176
177       Parts of heuristics were deduced from:
178
179       ·   PerlApp by ActiveState Tools Corp <http://www.activestate.com/>
180
181       ·   Perl2Exe by IndigoStar, Inc <http://www.indigostar.com/>
182
183       The scan_deps_runtime function is contributed by Edward S. Peschko.
184
185       <http://par.perl.org/> is the official website for this module.  You
186       can write to the mailing list at <par@perl.org>, or send an empty mail
187       to <par-subscribe@perl.org> to participate in the discussion.
188
189       Please submit bug reports to <bug-Module-ScanDeps@rt.cpan.org>.
190

COPYRIGHT

192       Copyright 2002, 2003, 2004, 2005, 2006 by Audrey Tang <autrijus@autri‐
193       jus.org>; 2005, 2006 by Steffen Mueller <smueller@cpan.org>.
194
195       This program is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.
197
198       See <http://www.perl.com/perl/misc/Artistic.html>
199
200
201
202perl v5.8.8                       2007-02-03               Module::ScanDeps(3)