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, passes @$execute as arguments to
90       each file in @files when it is run.
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 intentionally 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

SEE ALSO

181       scandeps.pl is a bundled utility that writes "PREREQ_PM" section for a
182       number of files.
183
184       An application of Module::ScanDeps is to generate executables from
185       scripts that contains prerequisite modules; this module supports two
186       such projects, PAR and App::Packer.  Please see their respective
187       documentations on CPAN for further information.
188
189       Other modules which accomplish the same goal with different approach:
190       Module::ExtractUse, Perl::PrereqScanner, Perl::PrereqScanner::Lite,
191       Perl::PrereqScanner::NotQuiteLite.
192

AUTHORS

194       Audrey Tang <cpan@audreyt.org>
195
196       To a lesser degree: Steffen Mueller <smueller@cpan.org>
197
198       Parts of heuristics were deduced from:
199
200       ·   PerlApp by ActiveState Tools Corp <http://www.activestate.com/>
201
202       ·   Perl2Exe by IndigoStar, Inc <http://www.indigostar.com/>
203
204       The scan_deps_runtime function is contributed by Edward S. Peschko.
205
206       You can write to the mailing list at <par@perl.org>, or send an empty
207       mail to <par-subscribe@perl.org> to participate in the discussion.
208
209       Please submit bug reports to <bug-Module-ScanDeps@rt.cpan.org>.
210
212       Copyright 2002-2008 by Audrey Tang <cpan@audreyt.org>; 2005-2010 by
213       Steffen Mueller <smueller@cpan.org>.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.
217
218       See <http://www.perl.com/perl/misc/Artistic.html>
219
220
221
222perl v5.32.0                      2020-08-06               Module::ScanDeps(3)
Impressum