[Chapter 6] 6.2 Packages and Files

6.2 Packages and Files

The same package declaration can be present in multiple files. Or multiple packages can be declared in one file. By convention, a package is usually assigned its own file and named package.pm or package.pl. Files with the suffix .pm are called Perl modules, and packages inside files with the suffix .pl are usually referred to as libraries. The former naming convention is preferred now because the use statement requires it, as we will soon see.

The require keyword simply loads a file into your program (sources it, in shell parlance). This is identical in spirit to #include in C, except that Perl does not bother about a file that has already been loaded:[1]

require "test.pl"; # load test.pl if it hasn't already been loaded

[1] Another important distinction from C or C++ is that modules are not split up into separate declaration and implementation files (header files versus ".c" files) and it is not necessary to go through a linker to bring modules together.

If you omit the suffix and the quotes, a .pm suffix is assumed. The use statement is similar in that respect, but is more restrictive in that it accepts only module names, not filenames. So, while there is no necessary relation between module names and filenames in general, use does force you to adopt a standard naming convention, which is a very good thing indeed, in my opinion. But there is more to use than just syntactic sugar.

The big difference between use and require is that the use statement is executed as soon as it is parsed. For this reason, the following attempt to load a module dynamically won't work, because the assignment statement is executed only after everything has been parsed and compiled:

$pkg_name = "Account";  # executes at run-time
use $pkg_name;          # executes at compile-time

It is, in fact, a syntax error; you have to use require in this case. The advantage of use is that when a program starts executing, there's a guarantee that all required modules have been successfully loaded, and there won't be any surprises at run-time.

Another important difference between use and require is described later, in the section "Importing Symbols."

When a file is require'd or use'd, it is expected to return a Boolean success value (zero for failure, nonzero for success). That is, the last executing statement at global scope must be a statement such as "return 1;" or just "1;". Note that this is not necessarily the last statement in the file; it is just the last executing statement.

6.2.1 Load Path

Perl first looks for the file given to use or require in the current directory and then looks up the @INC built-in array to search the include paths. By default, @INC contains a few standard directory names specified when the interpreter was installed and built. On my machine, @INC looks like this:

% perl -e 'print "@INC \n";'
/opt/lib/perl5/sun4-solaris/5.004 /opt/lib/perl5 /opt/lib/perl5/site_perl/sun4-solaris /opt/lib/perl5/site_perl .

You can also use perl -V to get this and other configuration information.

If you want to specify additional directories of your own, you have these choices:

Use the -I command-line option as you would with the C preprocessor:
```
   % perl -I/home/sriram/perl -I/local/mylib script.pl
```
I sometimes have instrumented or development versions of my modules in a separate directory. This option makes it easy to use these modules without having to change any of the code that uses them.
Set the PERL5LIB environment variable as a set of paths, separated by colons.

Modify @INC before calling require:

   unshift (@INC, "/usr/perl/include"); # Prepend a directory name
   require 'foo.pl';