### 12.5 Perl and Perl 5 Modules

Perl 4.036 allows you to specify different locations for installation and for run-time. It is the only widely-used package in this author’s experience that allows this, though hopefully more packages will adopt this model.

Unfortunately, the authors of Perl believed that only AFS sites need this ability. The configuration instructions for Perl 4 misleadingly state that some occult means are used under AFS to transport files from their installation tree to their run-time tree. In fact, that confusion arises from the fact that Depot, Stow’s predecessor, originated at Carnegie Mellon University, which was also the birthplace of AFS. CMU’s need to separate install-time and run-time trees stemmed from its use of Depot, not from AFS.

The result of this confusion is that Perl 5’s configuration script doesn’t even offer the option of separating install-time and run-time trees unless you’re running AFS. Fortunately, after you’ve entered all the configuration settings, Perl’s setup script gives you the opportunity to edit those settings in a file called `config.sh`. When prompted, you should edit this file and replace occurrences of

    inst…/usr/local…

with

    inst…/usr/local/stow/perl…

You can do this with the following Unix command:

    sed 's,^\(inst.*/usr/local\),\1/stow/perl,' config.sh > config.sh.new
    mv config.sh.new config.sh

Hopefully, the Perl authors will correct this deficiency in Perl 5’s configuration mechanism.

Perl 5 modules—i.e., extensions to Perl 5—generally conform to a set of standards for building and installing them. The standard says that the package comes with a top-level `Makefile.PL`, which is a Perl script. When it runs, it generates a `Makefile`.

If you followed the instructions above for editing `config.sh` when Perl was built, then when you create a `Makefile` from a `Makefile.PL`, it will contain separate locations for run-time (`/usr/local`) and install-time (`/usr/local/stow/perl`). Thus you can do

    perl Makefile.PL
    make
    make install

and the files will be installed into `/usr/local/stow/perl`. However, you might prefer each Perl module to be stowed separately. In that case, you must edit the resulting Makefile, replacing `/usr/local/stow/perl` with `/usr/local/stow/module`. The best way to do this is:

    perl Makefile.PL
    find . -name Makefile -print | \
      xargs perl -pi~ -e 's,^(INST.*/stow)/perl,$1/module,;'
    make
    make install

(The use of ‘`find`’ and ‘`xargs`’ ensures that all Makefiles in the module’s source tree, even those in subdirectories, get edited.) A good convention to follow is to name the stow directory for a Perl module `cpan.module`, where ‘`cpan`’ stands for Comprehensive Perl Archive Network, a collection of FTP sites that is the source of most Perl 5 extensions. This way, it’s easy to tell at a glance which of the subdirectories of `/usr/local/stow` are Perl 5 extensions.

When you stow separate Perl 5 modules separately, you are likely to encounter conflicts (see Conflicts) with files named `.exists` and `perllocal.pod`. One way to work around this is to remove those files before stowing the module. If you use the `cpan.module` naming convention, you can simply do this:

    cd /usr/local/stow
    find cpan.* \( -name .exists -o -name perllocal.pod \) -print | \
      xargs rm