/ 
Devel-SearchINC-1.35
River stage one • 1 direct dependent • 1 total dependent
/ Devel::SearchINC

NAME

Devel::SearchINC - loading Perl modules from their development dirs

SYNOPSIS

use Devel::SearchINC '/my/dev/dir';
use My::Brand::New::Module;

DESCRIPTION

When developing a new module, I always start with a standard skeleton distribution directory. The directory structure is such, however, that you have to install the module first (with make install) before you can use it in another program or module. For example, bringing in a module like so:

use My::Module;

requires the module to be somewhere in a path listed in @INC, and the relative path is expected to be My/Module.pm. However, h2xs creates a structure where the module ends up in My/Module/Module.pm.

This module tries to compensate for that. The idea is that you use() it right at the beginning of your program so it can modify @INC to look for modules in relative paths of the special structure mentioned above, starting with directories specified along with the use() statement (i.e. the arguments passed to this module's import()).

This is useful because with this module you can test your programs using your newly developed modules without having to install them just so you can use them. This is especially advantageous when you consider working on many new modules at the same time.

To automatically make your development modules available to all your scripts, you can place the following in your .bashrc (or your shell initialization file of choice):

export PERL5OPT=-MDevel::SearchINC=/my/dev/dir

Tilde expansion is also performed.

When this module is first run, that is, when perl first consults @INC, all candidate files are remembered in a cache. A candidate file is one whose name ends in .pm, is not within a directory called t, CVS, .svn, skel or _build, and is within a directory called lib, blib/lib or blib/arch. This is a long-winded way of saying that it tries to find your perl module files within standard development directories.

Note that there is a small limitation for the PERL5OPT approach: development modules can't be loaded via -M on the perl command line. So the following won't work:

$ export PERL5OPT=-MDevel::SearchINC=/my/dev/dir
$ perl -MMy::Brand::New::Module -e'print "hello world\n"'

This is probably because PERL5OPT options are appended to the perl command line, and processed after the actual command line options.

Also, the PERL5OPT variable is ignored when Taint checks are enabled.

MULTIPLE DEVELOPMENT DIRECTORIES

You can have multiple development directories. Just list them when using this module:

use Devel::SearchINC qw(/my/first/dir my/second/dir);

or

perl -MDevel::SearchINC=/my/first/dir,/my/second/dir

You can also use semicolons instead of commas as delimiters for directories.

perlrun details the syntax for specifying multiple arguments for modules brought in with the -M switch.

DEBUGGING THIS MODULE

By using :debug as one of the development directories, you can turn on debugging. Note that despite the leading colon, this has nothing to do with Exporter semantics. With debugging activated, this module will print detailed information while trying to find the requested file.

For example

use Devel::SearchINC qw(/my/first/dir my/second/dir :debug);

or

perl -MDevel::SearchINC=/my/first/dir,:debug,/my/second/dir

The :debug option can be specified anywhere in the list of development directories.

TAGS

If you talk about this module in blogs, on del.icio.us or anywhere else, please use the develsearchinc tag.

VERSION

This document describes version 1.33 of Devel::SearchINC.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to <bug-devel-searchinc@rt.cpan.org>, or through the web interface at http://rt.cpan.org.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.

AUTHORS

Marcel Grünauer, <marcel@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2004-2008 by the authors.

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