local-lib5/man/man3/Module::ScanDeps.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Module::ScanDeps 3"
 132 .TH Module::ScanDeps 3 "2009-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::ScanDeps \- Recursively scan Perl code for dependencies
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 Via the command-line program scandeps.pl:
 138 .PP
 139 .Vb 4
 140 \&    % scandeps.pl *.pm          # Print PREREQ_PM section for *.pm
 141 \&    % scandeps.pl \-e "use utf8" # Read script from command line
 142 \&    % scandeps.pl \-B *.pm       # Include core modules
 143 \&    % scandeps.pl \-V *.pm       # Show autoload/shared/data files
 144 .Ve
 145 .PP
 146 Used in a program;
 147 .PP
 148 .Vb 1
 149 \&    use Module::ScanDeps;
 150 .Ve
 151 .PP
 152 .Vb 5
 153 \&    # standard usage
 154 \&    my $hash_ref = scan_deps(
 155 \&        files   => [ 'a.pl', 'b.pl' ],
 156 \&        recurse => 1,
 157 \&    );
 158 .Ve
 159 .PP
 160 .Vb 2
 161 \&    # shorthand; assume recurse == 1
 162 \&    my $hash_ref = scan_deps( 'a.pl', 'b.pl' );
 163 .Ve
 164 .PP
 165 .Vb 7
 166 \&    # App::Packer::Frontend compatible interface
 167 \&    # see App::Packer::Frontend for the structure returned by get_files
 168 \&    my $scan = Module::ScanDeps\->new;
 169 \&    $scan\->set_file( 'a.pl' );
 170 \&    $scan\->set_options( add_modules => [ 'Test::More' ] );
 171 \&    $scan\->calculate_info;
 172 \&    my $files = $scan\->get_files;
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 This module scans potential modules used by perl programs, and returns a
 177 hash reference; its keys are the module names as appears in \f(CW%INC\fR
 178 (e.g. \f(CW\*(C`Test/More.pm\*(C'\fR); the values are hash references with this structure:
 179 .PP
 180 .Vb 7
 181 \&    {
 182 \&        file    => '/usr/local/lib/perl5/5.8.0/Test/More.pm',
 183 \&        key     => 'Test/More.pm',
 184 \&        type    => 'module',    # or 'autoload', 'data', 'shared'
 185 \&        used_by => [ 'Test/Simple.pm', ... ],
 186 \&        uses    => [ 'Test/Other.pm', ... ],
 187 \&    }
 188 .Ve
 189 .PP
 190 One function, \f(CW\*(C`scan_deps\*(C'\fR, is exported by default.  Other
 191 functions such as (\f(CW\*(C`scan_line\*(C'\fR, \f(CW\*(C`scan_chunk\*(C'\fR, \f(CW\*(C`add_deps\*(C'\fR, \f(CW\*(C`path_to_inc_name\*(C'\fR)
 192 are exported upon request.
 193 .PP
 194 Users of \fBApp::Packer\fR may also use this module as the dependency-checking
 195 frontend, by tweaking their \fIp2e.pl\fR like below:
 196 .PP
 197 .Vb 4
 198 \&    use Module::ScanDeps;
 199 \&    ...
 200 \&    my $packer = App::Packer\->new( frontend => 'Module::ScanDeps' );
 201 \&    ...
 202 .Ve
 203 .PP
 204 Please see App::Packer::Frontend for detailed explanation on
 205 the structure returned by \f(CW\*(C`get_files\*(C'\fR.
 206 .Sh "\fBscan_deps\fP"
 207 .IX Subsection "scan_deps"
 208 .Vb 6
 209 \&    $rv_ref = scan_deps(
 210 \&        files      => \e@files,     recurse => $recurse,
 211 \&        rv         => \e%rv,        skip    => \e%skip,
 212 \&        compile    => $compile,    execute => $execute,
 213 \&    );
 214 \&    $rv_ref = scan_deps(@files); # shorthand, with recurse => 1
 215 .Ve
 216 .PP
 217 This function scans each file in \f(CW@files\fR, registering their
 218 dependencies into \f(CW%rv\fR, and returns a reference to the updated
 219 \&\f(CW%rv\fR.  The meaning of keys and values are explained above.
 220 .PP
 221 If \f(CW$recurse\fR is true, \f(CW\*(C`scan_deps\*(C'\fR will call itself recursively,
 222 to perform a breadth-first search on text files (as defined by the
 223 \&\-T operator) found in \f(CW%rv\fR.
 224 .PP
 225 If the \f(CW\*(C`\e%skip\*(C'\fR is specified, files that exists as its keys are
 226 skipped.  This is used internally to avoid infinite recursion.
 227 .PP
 228 If \f(CW$compile\fR or \f(CW$execute\fR is true, runs \f(CW\*(C`files\*(C'\fR in either
 229 compile-only or normal mode, then inspects their \f(CW%INC\fR after
 230 termination to determine additional runtime dependencies.
 231 .PP
 232 If \f(CW$execute\fR is an array reference, runs the files contained
 233 in it instead of \f(CW@files\fR.
 234 .PP
 235 If performance of the scanning process is a concern, \f(CW\*(C`cache_file\*(C'\fR can be
 236 set to a filename. The scanning results will be cached and written to the
 237 file. This will speed up the scanning process on subsequent runs.
 238 .PP
 239 Additionally, an option \f(CW\*(C`warn_missing\*(C'\fR is recognized. If set to true,
 240 \&\f(CW\*(C`scan_deps\*(C'\fR issues a warning to \s-1STDERR\s0 for every module file that the
 241 scanned code depends but that wasn't found. Please note that this may
 242 also report numerous false positives. That is why by default, the heuristic
 243 silently drops all dependencies it cannot find.
 244 .Sh "\fBscan_deps_runtime\fP"
 245 .IX Subsection "scan_deps_runtime"
 246 Like \fBscan_deps\fR, but skips the static scanning part.
 247 .Sh "\fBscan_line\fP"
 248 .IX Subsection "scan_line"
 249 .Vb 1
 250 \&    @modules = scan_line($line);
 251 .Ve
 252 .PP
 253 Splits a line into chunks (currently with the semicolon characters), and
 254 return the union of \f(CW\*(C`scan_chunk\*(C'\fR calls of them.
 255 .PP
 256 If the line is \f(CW\*(C`_\|_END_\|_\*(C'\fR or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR, a single \f(CW\*(C`_\|_END_\|_\*(C'\fR element is
 257 returned to signify the end of the program.
 258 .PP
 259 Similarly, it returns a single \f(CW\*(C`_\|_POD_\|_\*(C'\fR if the line matches \f(CW\*(C`/^=\ew/\*(C'\fR;
 260 the caller is responsible for skipping appropriate number of lines
 261 until \f(CW\*(C`=cut\*(C'\fR, before calling \f(CW\*(C`scan_line\*(C'\fR again.
 262 .Sh "\fBscan_chunk\fP"
 263 .IX Subsection "scan_chunk"
 264 .Vb 2
 265 \&    $module = scan_chunk($chunk);
 266 \&    @modules = scan_chunk($chunk);
 267 .Ve
 268 .PP
 269 Apply various heuristics to \f(CW$chunk\fR to find and return the module
 270 name(s) it contains.  In scalar context, returns only the first module
 271 or \f(CW\*(C`undef\*(C'\fR.
 272 .Sh "\fBadd_deps\fP"
 273 .IX Subsection "add_deps"
 274 .Vb 2
 275 \&    $rv_ref = add_deps( rv => \e%rv, modules => \e@modules );
 276 \&    $rv_ref = add_deps( @modules ); # shorthand, without rv
 277 .Ve
 278 .PP
 279 Resolves a list of module names to its actual on-disk location, by
 280 finding in \f(CW@INC\fR and \f(CW@Module::ScanDeps::IncludeLibs\fR;
 281 modules that cannot be found are skipped.
 282 .PP
 283 This function populates the \f(CW%rv\fR hash with module/filename pairs, and
 284 returns a reference to it.
 285 .Sh "\fBpath_to_inc_name\fP"
 286 .IX Subsection "path_to_inc_name"
 287 .Vb 1
 288 \&    $perl_name = path_to_inc_name($path, $warn)
 289 .Ve
 290 .PP
 291 Assumes \f(CW$path\fR refers to a perl file and does it's best to return the
 292 name as it would appear in \f(CW%INC\fR. Returns undef if no match was found
 293 and a prints a warning to \s-1STDERR\s0 if \f(CW$warn\fR is true.
 294 .PP
 295 E.g. if \f(CW$path\fR = perl/site/lib/Module/ScanDeps.pm then \f(CW$perl_name\fR
 296 will be Module/ScanDeps.pm.
 297 .SH "NOTES"
 298 .IX Header "NOTES"
 299 .Sh "\fB@Module::ScanDeps::IncludeLibs\fP"
 300 .IX Subsection "@Module::ScanDeps::IncludeLibs"
 301 You can set this global variable to specify additional directories in
 302 which to search modules without modifying \f(CW@INC\fR itself.
 303 .Sh "\fB$Module::ScanDeps::ScanFileRE\fP"
 304 .IX Subsection "$Module::ScanDeps::ScanFileRE"
 305 You can set this global variable to specify a regular expression to
 306 identify what files to scan. By default it includes all files of
 307 the following types: .pm, .pl, .t and .al. Additionally, all files
 308 without a suffix are considered.
 309 .PP
 310 For instance, if you want to scan all files then use the following:
 311 .PP
 312 \&\f(CW\*(C`$Module::ScanDeps::ScanFileRE = qr/./\*(C'\fR
 313 .SH "CAVEATS"
 314 .IX Header "CAVEATS"
 315 This module intentially ignores the \fB\s-1BSDPAN\s0\fR hack on FreeBSD \*(-- the
 316 additional directory is removed from \f(CW@INC\fR altogether.
 317 .PP
 318 The static-scanning heuristic is not likely to be 100% accurate, especially
 319 on modules that dynamically load other modules.
 320 .PP
 321 Chunks that span multiple lines are not handled correctly.  For example,
 322 this one works:
 323 .PP
 324 .Vb 1
 325 \&    use base 'Foo::Bar';
 326 .Ve
 327 .PP
 328 But this one does not:
 329 .PP
 330 .Vb 2
 331 \&    use base
 332 \&        'Foo::Bar';
 333 .Ve
 334 .SH "SEE ALSO"
 335 .IX Header "SEE ALSO"
 336 scandeps.pl is a bundled utility that writes \f(CW\*(C`PREREQ_PM\*(C'\fR section
 337 for a number of files.
 338 .PP
 339 An application of \fBModule::ScanDeps\fR is to generate executables from
 340 scripts that contains prerequisite modules; this module supports two
 341 such projects, \s-1PAR\s0 and App::Packer.  Please see their respective
 342 documentations on \s-1CPAN\s0 for further information.
 343 .SH "AUTHORS"
 344 .IX Header "AUTHORS"
 345 Audrey Tang <cpan@audreyt.org>
 346 .PP
 347 To a lesser degree: Steffen Mueller <smueller@cpan.org>
 348 .PP
 349 Parts of heuristics were deduced from:
 350 .IP "\(bu" 4
 351 \&\fBPerlApp\fR by ActiveState Tools Corp <http://www.activestate.com/>
 352 .IP "\(bu" 4
 353 \&\fBPerl2Exe\fR by IndigoStar, Inc <http://www.indigostar.com/>
 354 .PP
 355 The \fBscan_deps_runtime\fR function is contributed by Edward S. Peschko.
 356 .PP
 357 <http://par.perl.org/> is the official website for this module.  You
 358 can write to the mailing list at <par@perl.org>, or send an empty
 359 mail to <par\-subscribe@perl.org> to participate in the discussion.
 360 .PP
 361 Please submit bug reports to <bug\-Module\-ScanDeps@rt.cpan.org>.
 362 .SH "COPYRIGHT"
 363 .IX Header "COPYRIGHT"
 364 Copyright 2002\-2008 by
 365 Audrey Tang <cpan@audreyt.org>;
 366 2005\-2009 by Steffen Mueller <smueller@cpan.org>.
 367 .PP
 368 This program is free software; you can redistribute it and/or modify it
 369 under the same terms as Perl itself.
 370 .PP
 371 See <http://www.perl.com/perl/misc/Artistic.html>