NAME

Module::ScanDeps - Recursively scan Perl programs for dependencies

VERSION

This document describes version 0.19 of Module::ScanDeps, released March 22, 2003.

SYNOPSIS

Via the command-line program scandeps.pl:

    % scandeps.pl *.pm		# Print PREREQ_PM section for *.pm
    % scandeps.pl -B *.pm	# Include core modules
    % scandeps.pl -V *.pm	# Show autoload/shared/data files

Used in a program;

    use Module::ScanDeps;

    # standard usage
    my $hash_ref = scan_deps(
	files	=> [ 'a.pl', 'b.pl' ],
	recurse	=> 1,
    );

    # shorthand; assume recurse == 1
    my $hash_ref = scan_deps( 'a.pl', 'b.pl' );

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

DESCRIPTION

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

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

One function, scan_deps, is exported by default. Three other functions (scan_line, scan_chunk, add_deps) are exported upon request.

Users of App::Packer may also use this module as the dependency-checking frontend, by tweaking their p2e.pl 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 get_files.

scan_deps

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

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

If the recurse flag is true, scan_deps will call itself recursively, to perform a breadth-first search on text files (as recognized by -T) found in %rv.

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

scan_line

    @modules = scan_line($line);

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

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

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

scan_chunk

    $module = scan_chunk($chunk);

Apply various heuristics to $chunk to find and return the module name it contains, or undef if nothing were found.

add_deps

    $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 @INC; modules that cannot be found are skipped.

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

CAVEATS

This module is oblivious about the BSDPAN hack on FreeBSD -- the additional directory is removed from @INC altogether.

Finally, since no source code are actually compiled by this module, so the heuristic is not likely to be 100% accurate. Patches welcome!

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

Part of heuristics are taken from Perl2Exe by IndigoStar, Inc http://www.indigostar.com/

Part of heuristics are deduced from PerlApp by ActiveState Tools Corp http://www.activestate.com/

COPYRIGHT

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

See http://www.perl.com/perl/misc/Artistic.html