1Module::ScanDeps(3) User Contributed Perl Documentation Module::ScanDeps(3)
2
6 Module::ScanDeps - Recursively scan Perl code for dependencies
7
9 Via the command-line program scandeps.pl:
10 % 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 Used in a program;
17 use Module::ScanDeps;
19 # standard usage
21 my $hash_ref = scan_deps(
22 files => [ 'a.pl', 'b.pl' ],
23 recurse => 1,
24 );
25 # shorthand; assume recurse == 1
27 my $hash_ref = scan_deps( 'a.pl', 'b.pl' );
28 # 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
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 {
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 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 Users of App::Packer may also use this module as the dependency-
56 checking frontend, by tweaking their p2e.pl like below:
57 use Module::ScanDeps;
59 ...
60 my $packer = App::Packer->new( frontend => 'Module::ScanDeps' );
61 ...
62 Please see App::Packer::Frontend for detailed explanation on the
64 structure returned by "get_files".
65 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 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 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 If the "\%skip" is specified, files that exists as its keys are
83 skipped. This is used internally to avoid infinite recursion.
84 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 If $execute is an array reference, passes @$execute as arguments to
90 each file in @files when it is run.
91 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 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 scan_deps_runtime
104 Like scan_deps, but skips the static scanning part.
105 scan_line
107 @modules = scan_line($line);
108 Splits a line into chunks (currently with the semicolon characters),
110 and return the union of "scan_chunk" calls of them.
111 If the line is "__END__" or "__DATA__", a single "__END__" element is
113 returned to signify the end of the program.
114 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 scan_chunk
120 $module = scan_chunk($chunk);
121 @modules = scan_chunk($chunk);
122 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 add_deps
128 $rv_ref = add_deps( rv => \%rv, modules => \@modules );
129 $rv_ref = add_deps( @modules ); # shorthand, without rv
130 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 This function populates the %rv hash with module/filename pairs, and
136 returns a reference to it.
137 path_to_inc_name
139 $perl_name = path_to_inc_name($path, $warn)
140 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 E.g. if $path = perl/site/lib/Module/ScanDeps.pm then $perl_name will
146 be Module/ScanDeps.pm.
147
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 $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 For instance, if you want to scan all files then use the following:
160 "$Module::ScanDeps::ScanFileRE = qr/./"
162
164 This module intentionally ignores the BSDPAN hack on FreeBSD -- the
165 additional directory is removed from @INC altogether.
166 The static-scanning heuristic is not likely to be 100% accurate,
168 especially on modules that dynamically load other modules.
169 Chunks that span multiple lines are not handled correctly. For
171 example, this one works:
172 use base 'Foo::Bar';
174 But this one does not:
176 use base
178 'Foo::Bar';
179
181 scandeps.pl is a bundled utility that writes "PREREQ_PM" section for a
182 number of files.
183 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 Other modules which accomplish the same goal with different approach:
190 Module::ExtractUse, Perl::PrereqScanner, Perl::PrereqScanner::Lite,
191 Perl::PrereqScanner::NotQuiteLite.
192
194 Audrey Tang <cpan@audreyt.org>
195 To a lesser degree: Steffen Mueller <smueller@cpan.org>
197 Parts of heuristics were deduced from:
199 • PerlApp by ActiveState Tools Corp <http://www.activestate.com/>
201 • Perl2Exe by IndigoStar, Inc <http://www.indigostar.com/>
203 The scan_deps_runtime function is contributed by Edward S. Peschko.
205 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 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 This program is free software; you can redistribute it and/or modify it
216 under the same terms as Perl itself.
217 See <http://www.perl.com/perl/misc/Artistic.html>
219perl v5.36.0 2023-01-20 Module::ScanDeps(3)