NAME

Module::Dependency::Indexer - creates the databases used by the dependency mapping module

SYNOPSIS

        use Module::Dependency::Indexer;
        Module::Dependency::Indexer::setIndex( '/var/tmp/dependency/unified.dat' );
        Module::Dependency::Indexer::makeIndex( $directory, [ $another, $andanother... ] );
        Module::Dependency::Indexer::setShebangCheck( 0 );

DESCRIPTION

This module looks at all .pm, .pl and .plx files within and below a given directory/directories (found with File::Find), reads through them and extracts some information about them. If the shebang check is turned on then it also looks at the first line of all other files, to see if they're perl programs too. We extract this information:

The name of the package (e.g. 'Foo::Bar') or the name of the script (e.g. 'chat.pl')
The full filesystem location of the file.
The dependencies of the file - i.e. the packages that it 'use's or 'require's
The reverse dependencies - i.e. what other scripts and modules THAT IT HAS INDEXED use or require the file. It can't, of course, know about 'use' statements in files it hasn't examined.

When it has extracted all this information it uses Storable to write the data to disk in the indexfile location.

This search is quite an expensive operation, taking around 10 seconds for the site_perl directory here. However once the information has been gathered it's extremely fast to use.

FUNCTIONS

setIndex( $filename ): This function tells the module where to write out the datafile. You can set this, make an index of some directory of perl stuff, set it to something else, index a different folder, etc., in order to build up many indices. This only affects this module - you need to tell ...::Info where to look for datafiles independently of this module.
Default is /var/tmp/dependence/unified.dat
makeIndex( $directory, [ $another, $andanother... ] ): Builds, and stores to the current data file, a SINGLE database for all the files found under all of the supplied directories. To create multiple indexes, run this method many times with a setIndex inbetween each so that you don't clobber the previous run's datafile.
setShebangCheck( BOOLEAN ): Turns on or off the checking of #! lines for all files that are not .pl, .plx or .pm filenames. By default we do check the #! lines.

NOTE ABOUT WHAT IS INDEXED

A database entry is made for each file scanned. This makes the generally good assumption that a .pl file is a script that is not use/required by anything else, and a .pm file is a package file which may be use/required by many other files. Database entries ARE NOT made just because a file is use/required - hence the database will not contain an entry for 'strict' or 'File::Find' (for example) unless you explicitly index your perl's lib/ folder.

E.g., if 'Local::Foo.pm' uses strict and File::Find and we index it, its entry in the database will show that it depends on strict and File::Find, as you'd expect. It's just that we won't create an entry for 'strict' on that basis alone.

In practice this behaviour is what you want - you want to see how the mass of perl in your cgi-bin and site_perl folders fits together (for example), or maybe just a single project in CVS. You may of course include your perl lib directory in the database should you want to see the dependencies involving the standard modules, but generally that's not relevant.

USE OF THE DATA

Now you've got a datafile which links all the scripts and modules in a set of directories. Use ...::Info to get at the data. Note that the data is stored using Storable's nstore method which _should_ make these indexes portable across platforms. Not tested though.

ADVICE, GETTING AT DATA

As Storable is so fast, you may want to make one big index of all folders where perl things are. Then you can load this datafile back up, extract the entry for, say, Local::Foo and examine its dependencies (and reverse dependencies). Based on what you find, you can get the entries for Local::Foo::Bar and Local::Foo::Baz (things used by Local::Foo) or perhaps Local::Stuff (which uses Local::Foo). Then you can examine those records, etc. This is how ...::Grapher builds the tree of dependencies, basically.

You use Module::Dependency::Info to get at these records using a nice simple API. If you're feeling keen you can just grab the entire object - but that's in the ...::Info module.

Here we have a single index for all our local perl code, and that lives in /var/tmp/dependence/unified.dat - the default location. Other applications just use that file.

DEBUGGING

There is a TRACE stub function, and the module uses TRACE() to log activity. Override our TRACE with your own routine, e.g. one that prints to STDERR, to see these messages.

VERSION

$Id: Indexer.pm 6643 2006-07-12 20:23:31Z timbo $