7.2 Modules

A module is a package defined in a file whose name is the same as the package. Perl locates modules by searching the @INC array, which contains a list of library directories. Perl's use of @INC is roughly comparable to the Unix shell's use of the PATH environment variable to locate executable programs. @INC is defined when Perl is built, and can be supplemented with the -I command-line option to Perl or with use lib within a program.

When you refer to ModuleName in your program, Perl searches in the directories listed in @INC for the module file ModuleName.pm, and uses the first one it finds. When you refer to a module embedded in another package, such as ParentPackage::ModuleName, Perl looks for a ParentPackage/ subdirectory in the @INC path, and for a ModuleName.pm file in that subdirectory.

Every Perl installation includes a central lib directory. The actual pathname of this directory varies from system to system, but it's commonly /usr/lib/perl or /usr/local/lib/perl. Looking at the central lib directory for your Perl distribution, you'll see something like this:

% ls -aF /usr/local/lib/perl
./               I18N/            bigfloat.pl      less.pm
../              IO/              bigint.pl        lib.pm
AnyDBM_File.pm   IPC/             bigrat.pl        locale.pm
AutoLoader.pm    Math/            blib.pm          look.pl
AutoSplit.pm     Net/             cacheout.pl      man/
Benchmark.pm     Pod/             chat2.pl         newgetopt.pl
Bundle/          Search/          complete.pl      open2.pl
CGI/             SelectSaver.pm   constant.pm      open3.pl
CGI.pm           SelfLoader.pm    ctime.pl         perl5db.pl
CPAN/            Shell.pm         diagnostics.pm   pod/
CPAN.pm          Symbol.pm        dotsh.pl         pwd.pl
Carp.pm          Sys/             dumpvar.pl       shellwords.pl              
	...

When you request the AnyDBM_File module, it uses AnyDBM_File.pm. When you request the Math::Complex module, it looks for Math/Complex.pm.

A module can be included in your program with use or require. Both use and require read in a module file for use with your program.

require Module;

or:

use Module;

use can also take a list of strings naming entities that you want to import from the module. The list only has to include entities that are not automatically exported by the module. You don't have to provide this list at all if the module automatically exports all the entities you need.

use Module qw(const1 const2 func1 func2 func3);

The difference between use and require is that use pulls in the module at compile time. This means that functions like func1 or func2 can be used as predeclared list operators throughout the file. The require call does not necessarily load the module during compilation, so you must explicitly qualify its routines with the package name.