1.6 Storing Modules

Where you store your .pm module files on your computer affects the name of the module, so let's take a moment to sort out the most important points. For all the details, consult the perlmod and the perlmodlib parts of the Perl documentation at http://www.perldoc.org. You can also type perldoc perlmod or perldoc perlmodlib at a shell prompt or in a command window.

Once you start using multiple files for your program code, which happens if you're defining and using modules, Perl needs to be able to find these various files; it provides a few different ways to do so.

The simplest method is to put all your program files, including your modules, in the same directory and run your programs from that directory. Here's how the module file Celegans.pm is loaded from another program:

 use Celegans; 

However, it's often not so simple. Perl uses modules extensively; many are built-in when you install Perl, and many more are available from CPAN, as you'll see later. Some modules are used frequently, some rarely; many modules call other modules, which in turn call still other modules.

To organize the many modules a Perl program might need, you should place them in certain standard directories or in your own development directories. Perl needs to know where these directories are so that when a module is called in a program, it can search the directories, find the file that contains the module, and load it in.

When Perl was installed on your computer, a list of directories in which to find modules was configured. Every time a Perl program on your computer refers to a module, Perl looks in those directories. To see those directories, you only need to run a Perl program and examine the built-in array @INC , like so:

 print join("\n", @INC), "\n"; 

On my Linux computer, I get the following output from that statement:

 /usr/local/lib/perl5/5.8.0/i686-linux /usr/local/lib/perl5/5.8.0 /usr/local/lib/perl5/site_perl/5.8.0/i686-linux /usr/local/lib/perl5/site_perl/5.8.0 /usr/local/lib/perl5/site_perl/5.6.1 /usr/local/lib/perl5/site_perl/5.6.0 /usr/local/lib/perl5/site_perl . 

These are all locations in which the standard Perl modules live on my Linux computer. @INC is simply an array whose entries are directories on your computer. The way it looks depends on how your computer is configured and your operating system (for instance, Unix computers handle directories a bit differently than Windows).

Note that the last line of that list of directories is a solitary period. This is shorthand for "the current directory," that is, whatever directory you happen to be in when you run your Perl program. If this directory is on the list, and you run your program from that directory as well, Perl will find the .pm files.

When you develop Perl software that uses modules, you should put all the modules together in a certain directory. In order for Perl to find this directory, and load the modules, you need to add a line before the use MODULE directives, telling Perl to additionally search your own module directory for any modules requested in your program. For instance, if I put a module I'm developing for my program into a file named Celegans.pm , and put the Celegans.pm file into my Linux directory /home/tisdall/MasteringPerlBio/development/lib , I need to add a use lib directive to my program, like so:

 use lib "/home/tisdall/MasteringPerlBio/development/lib"; use Celegans; 

Perl then adds my development module directory to the @INC array and searches there for the Celegans.pm module file. The following code demonstrates this:

 use lib "/home/tisdall/MasteringPerlBio/development/lib"; print join("\n", @INC), "\n"; 

This produces the output:

 /home/tisdall/MasteringPerlBio/development/lib /usr/local/lib/perl5/5.8.0/i686-linux /usr/local/lib/perl5/5.8.0 /usr/local/lib/perl5/site_perl/5.8.0/i686-linux /usr/local/lib/perl5/site_perl/5.8.0 /usr/local/lib/perl5/site_perl/5.6.1 /usr/local/lib/perl5/site_perl/5.6.0 /usr/local/lib/perl5/site_perl . 

Thanks to the use lib directive, Perl can now find the Celegans.pm file in the @INC list of directories.

A problem with this approach to finding libraries is that the directory pathnames are hardcoded into each program. If you then want to move your own library directory somewhere else or move the programs to another computer where different pathnames are used, you need to change the pathnames in all the program files where they occur.

If, for instance, you download several programs from this book's web site, and you don't want to edit each one to change pathnames, you can use the PERL5LIB environmental variable. To do so, put all the modules under the directory /my/perl/module s (for example). Now set the PERL5LIB variable:

 PERL5LIB=$PERL5LIB:/my/perl/modules 

You can also set it this way:

 setenv PERL5LIB /my/perl/modules 

If you have " taint " security checks enabled in your version of Perl, you still have to hardcode the pathname into the program. This, of course, behaves differently on different operating systems.

You can also specify an additional directory on the command line:

 perl -I/my/perl/modules myprogram.pl 

There's one other detail about modules that's important. You'll sometimes see modules in Perl programs with names such as Genomes::Modelorganisms::Celegans , in which the name is two or more words separated by two colons. This is how Perl looks into subdirectories of directories named in the @INC built-in array. In the example, Perl looks for a subdirectory named Genomes in one of the @INC directories; then for a subdirectory named Modelorganisms within the Genomes subdirectory; finally, for a file named Celegans.pm within the Modelorganisms subdirectory. That is, my module is in the file:

 /home/tisdall/MasteringPerlBio/development/lib/Genomes/Modelorganisms/Celegans.pm 

and it's called in my Perl program like so:

 use lib "/home/tisdall/MasteringPerlBio/development/lib"; use Genomes::Modelorganisms::Celegans; 

There are more details you can learn about storing and finding modules on your computer, but these are the most useful facts. See the perlmod , perlrun , and perlmodlib sections of the Perl manual for more details if and when you need them.