man Module::ScanDeps () - Recursively scan Perl code for dependencies


Module::ScanDeps - Recursively scan Perl code for dependencies


This document describes version 0.51 of Module::ScanDeps, released January 8, 2005.


Via the command-line program

    % *.pm          # Print PREREQ_PM section for *.pm
    % -e "use utf8" # Read script from command line
    % -B *.pm       # Include core modules
    % -V *.pm       # Show autoload/shared/data files

Used in a program;

    use Module::ScanDeps;

    # standard usage
    my $hash_ref = scan_deps(
        files   => [ '', '' ],
        recurse => 1,

    # shorthand; assume recurse == 1
    my $hash_ref = scan_deps( '', '' );

    # App::Packer::Frontend compatible interface
    # see App::Packer::Frontend for the structure returned by get_files
    my $scan = Module::ScanDeps->new;
    $scan->set_file( '' );
    $scan->set_options( add_modules => [ 'Test::More' ] );
    my $files = $scan->get_files;


This module scans potential modules used by perl programs, and returns a hash reference; its keys are the module names as appears in CW%INC (e.g. CWTest/; the values are hash references with this structure:

        file    => '/usr/local/lib/perl5/5.8.0/Test/',
        key     => 'Test/',
        type    => 'module',    # or 'autoload', 'data', 'shared'
        used_by => [ 'Test/', ... ],

One function, CWscan_deps, is exported by default. Three other functions (CWscan_line, CWscan_chunk, CWadd_deps) are exported upon request.

Users of App::Packer may also use this module as the dependency-checking frontend, by tweaking their like below:

    use Module::ScanDeps;
    my $packer = App::Packer->new( frontend => 'Module::ScanDeps' );

Please see App::Packer::Frontend for detailed explanation on the structure returned by CWget_files.


    $rv_ref = scan_deps(
        files   => \@files,     recurse => $recurse,
        rv      => \%rv,        skip    => \%skip,
        compile => $compile,    execute => $execute,
    $rv_ref = scan_deps(@files); # shorthand, with recurse => 1

This function scans each file in CW@files, registering their dependencies into CW%rv, and returns a reference to the updated CW%rv. The meaning of keys and values are explained above.

If CW$recurse is true, CWscan_deps will call itself recursively, to perform a breadth-first search on text files (as defined by the -T operator) found in CW%rv.

If the CW\%skip is specified, files that exists as its keys are skipped. This is used internally to avoid infinite recursion.

If CW$compile or CW$execute is true, runs CWfiles in either compile-only or normal mode, then inspects their CW%INC after termination to determine additional runtime dependencies.

If CW$execute is an array reference, runs the files contained in it instead of CW@files.


Like scan_deps, but skips the static scanning part.


    @modules = scan_line($line);

Splits a line into chunks (currently with the semicolon characters), and return the union of CWscan_chunk calls of them.

If the line is CW__END__ or CW__DATA__, a single CW__END__ element is returned to signify the end of the program.

Similarly, it returns a single CW__POD__ if the line matches CW/^=\w/; the caller is responsible for skipping appropriate number of lines until CW=cut, before calling CWscan_line again.


    $module = scan_chunk($chunk);
    @modules = scan_chunk($chunk);

Apply various heuristics to CW$chunk to find and return the module name(s) it contains. In scalar context, returns only the first module or CWundef.


    $rv_ref = add_deps( rv => \%rv, modules => \@modules );
    $rv_ref = add_deps( @modules ); # shorthand, without rv

Resolves a list of module names to its actual on-disk location, by finding in CW@INC; modules that cannot be found are skipped.

This function populates the CW%rv hash with module/filename pairs, and returns a reference to it.


This module intentially ignores the BSDPAN hack on FreeBSD the additional directory is removed from CW@INC altogether.

The static-scanning heuristic is not likely to be 100% accurate, especially on modules that dynamically load other modules.

Chunks that span multiple lines are not handled correctly. For example, this one works:

    use base 'Foo::Bar';

But this one does not:

    use base

SEE ALSO is a bundled utility that writes CWPREREQ_PM section for a number of files.

An application of Module::ScanDeps is to generate executables from scripts that contains prerequisite modules; this module supports two such projects, PAR and App::Packer. Please see their respective documentations on CPAN for further information.


Autrijus Tang <>

Parts of heuristics were deduced from:

PerlApp by ActiveState Tools Corp <>
Perl2Exe by IndigoStar, Inc <>

The scan_deps_runtime function is contributed by Edward S. Peschko.

<> is the official website for this module. You can write to the mailing list at <>, or send an empty mail to <> to participate in the discussion.

Please submit bug reports to <>.


Copyright 2002, 2003, 2004, 2005 by Autrijus Tang <>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <>