[Chapter 6] 6.2 Packages and Files
Author: Sriram Srinivasan
Date: 1999-07-02T01:33:03Z

#

| Chapter 6 Modules |

## 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:

1. 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.

2. Set the `PERL5LIB` environment variable as a set of paths, separated by colons.

3. Modify `@INC` before calling `require`:

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

6.1 Basic Package |  | 6.3 Package Initialization and Destruction