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

SYNOPSIS

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

DESCRIPTION

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

NOTES

149   @Module::ScanDeps::IncludeLibs
150       You can set this global variable to specify additional directories in
151       which to search modules without modifying @INC itself.
152
153   $Module::ScanDeps::ScanFileRE
154       You can set this global variable to specify a regular expression to
155       identify what files to scan. By default it includes all files of the
156       following types: .pm, .pl, .t and .al. Additionally, all files without
157       a suffix are considered.
158
159       For instance, if you want to scan all files then use the following:
160
161       "$Module::ScanDeps::ScanFileRE = qr/./"
162

CAVEATS

164       This module intentially ignores the BSDPAN hack on FreeBSD -- the
165       additional directory is removed from @INC altogether.
166
167       The static-scanning heuristic is not likely to be 100% accurate,
168       especially on modules that dynamically load other modules.
169
170       Chunks that span multiple lines are not handled correctly.  For
171       example, this one works:
172
173           use base 'Foo::Bar';
174
175       But this one does not:
176
177           use base
178               'Foo::Bar';
179

AUTHORS

190       Audrey Tang <cpan@audreyt.org>
191
192       To a lesser degree: Steffen Mueller <smueller@cpan.org>
193
194       Parts of heuristics were deduced from:
195
196       ·   PerlApp by ActiveState Tools Corp <http://www.activestate.com/>
197
198       ·   Perl2Exe by IndigoStar, Inc <http://www.indigostar.com/>
199
200       The scan_deps_runtime function is contributed by Edward S. Peschko.
201
202       <http://par.perl.org/> is the official website for this module.  You
203       can write to the mailing list at <par@perl.org>, or send an empty mail
204       to <par-subscribe@perl.org> to participate in the discussion.
205
206       Please submit bug reports to <bug-Module-ScanDeps@rt.cpan.org>.
207

COPYRIGHT

209       Copyright 2002-2008 by Audrey Tang <cpan@audreyt.org>; 2005-2009 by
210       Steffen Mueller <smueller@cpan.org>.
211
212       This program is free software; you can redistribute it and/or modify it
213       under the same terms as Perl itself.
214
215       See <http://www.perl.com/perl/misc/Artistic.html>
216
217
218
219perl v5.10.1                      2009-09-16               Module::ScanDeps(3)