use Perl

In celebration of the release of Perl 5.8.0, here is my own personal notes on what works best for me in installing Perl. This is a nearly complete brain download.

There are many ways to do it, of course, but my way works great for me at work and at play.

Comments and insight appreciated.

My ulterior motive in posting these notes here is so I can get to them when I'm not at the machine I wrote them on. :)

Perl comes with a lot of pieces besides just an executable named perl. It has a large set of documentation. It has a standard module library, and there is a vast archive of library modules that you might want to add. It also comes with several auxiliary programs that your programmers might need. Because all these things are complexly interlinked, it is definitely not wise to just copy /usr/local/bin/perl from one system to another. It is best to have a complete installation, either by compiling it yourself or using a package.

Many systems include perl as part of the OS or as an add-on. However, it is sometimes hard to add modules to this installation of perl because of non-standard decisions made by the OS vendor. It may also be a bad idea because scripts in the OS may depend on particular module versions included. Also, a version of perl supplied by a vendor may be out of date. For these reasons, I find it useful to leave the "system perl" alone and install my own.

If at all possible, perl should be installed in a directory all its own. As you know, free UNIX software usually installs into a directory structure that mimics the UNIX setup: a bin/ directory, a lib/ directory, a man/ directory, and so on. By default, this will be in /usr/local. However, it is nice to keep everything in a single directory. I usually install perl in a directory called /usr/local/perl561 (since perl 5.6.1 has been the latest version for a while). This helps facilitate installing multiple versions. perl itself, as well as several supporting utilities, will be in /usr/local/perl561/bin; it is best to make symbolic links to these from /usr/local/bin. With perl and all of its components installed in a single directory, it is easy to create a package (Solaris SysV package, RedHat RPM package, or just a .tar.gz tarball) so you can have an identical installation of perl on identical computers.

When possible, I create a separate user to compile and own perl named perl. Then I can create the /usr/local/perl561 directory as root and change its ownership to perl. It is safer to compile and install software as a non-root user when possible.

If you have a directory on your system named /usr/local/scripts, perl will attempt to put some things in it that you would rather have in the bin/ subdirectory. If you have this directory, move it to /usr/local/scripts.off before compiling perl and move it back after installing.

Before installing perl, it is best to clean up your PATH so you don't accidentally compile it to use any non-standard replacements for standard utilities. The PATH ought to include at a minimum /bin:/usr/bin:/usr/local/bin . Also, if your gcc is in a non-standard location, be sure to include it. On Solaris, you will also need to include /usr/ccs/bin, because this is where make is located.

Perl has a complex interactive configure program you are supposed to run before compiling. However, there is a non-interactive frontend that works more like other free UNIX software. So, when installing, don't run the Configure script; run configure.gnu. This will set up defaults for you to make the installation of perl very similar to other installations. It is easy to make mistakes with the interactive version the instructions tell you to use.

configure.gnu needs you to specify using gcc with the environment variable CC. It allows you to specify the directory to install perl in with the --prefix argument. So, I usually run:

$ CC=gcc ./configure.gnu --prefix=/usr/local/perl561

You might find that the execute permission bit isn't set on configure.gnu.

After all the configuration, you are ready to compile, test and install, like lots of other free UNIX software:

$ make
$ make test
$ make install


The test suite is optional, but I see no reason not to run it. If it fails a test, it would be good to know and report it to the people who make perl.

If you system includes a perl in any location in your PATH, the installer will issue a warning. It may ask if you would like to make an existing perl into a symbolic link to the new perl. Do not do this; leave the system perl alone. It is for the OS, and you are installing a perl for your programmers. (This question appears to be the only interactive prompt issued by the install process; I hope they eliminate it some day so perl can be installed completely unattended.)

Once you have installed perl, you will want to make symbolic links to everything in /usr/local/perl???/bin from /usr/local/bin. However, you may not want to do this yet, because below I will show you how to install modules, and some of the modules I recommend you install will also install programs in /usr/local/perl???/bin that you will want to link to. I will mention the need to make these links again below when the time comes.

The CPAN (Comprehensive Perl Archive Network) includes almost a GB of libraries and classes for you to use in your Perl programs. While Perl comes with a standard set of libraries, this set is not sufficient for many common tasks. Also, it is important for you and your programmers to be in the habit of searching CPAN for modules to simply programming tasks in the future and reuse existing code. The makers of perl have decided that Perl 6 will come with no standard modules to help perl installers realize that they are expected to install additional modules for their programmers.

Most modules follow a standard installation process. If they are written properly, you should be able to install them with the help of a standard perl module called CPAN. The CPAN module provides an interactive shell for installing modules, as well as routine calls that can be written into programs that would like to locate or install modules.

Start up the CPAN shell with this command:

$ perl5.6.1 -MCPAN -e shell

You will want to make sure perl5.6.1 is in your PATH, or use the full path to it. See below about upgrading perl for why you should type perl5.6.1 instead of just perl.

Also, make sure gcc and make are in your PATH. And make sure gcc is the same version you used to compile perl. If you compile perl with gcc 2.7.x, you should install modules with gcc 2.7.x, and the same if you used gcc 2.9.x, or gcc 3.0.x. Don't mix and match gcc versions, or it won't work for modules that are partially written in C.

Installing modules is another good reason to have a separate perl user instead of installing it all as root. Be sure to run the CPAN shell as perl, if you created a perl user.

The first time you run the CPAN shell, it will configure itself. You can do this interactively, but I find it best to accept the defaults and change the few things I don't like. The prompt "Are you ready for manual configuration?" is very confusing. If you say yes, you can interactively configure. What do you think it should do if you say no? Regardless of what you might think, what it does do is configure automatically. Answer no to this question to accept the defaults.

After automatic configuration, change a few things:

cpan> o conf prerequisites_policy follow

This tells the CPAN module to automatically install prerequisites without asking. Many modules depend on other modules that may or may not be installed already. Properly coded modules specify these prerequisites so the CPAN shell can follow the whole dependency tree.

cpan> o conf urllist push http://...

Pick yourself out a CPAN mirror from http://www.cpan.org/ . If you don't specify a mirror, a default will be used. The default is usually great in the mornings, but loaded during the day. You can push several mirror URLs into the list if you want; use a separate command line for each.

cpan> o conf http_proxy http://...

This sets your proxy server. This might not be necessary, but might get you faster results. There is also an ftp_proxy variable for you to set if you wish.

cpan> o conf cpan_home /usr/local/perl561/.cpan

The CPAN shell needs a place to download and compile modules. This directory is where it keeps those things. Set the following directories, also:

cpan> o conf build_dir /usr/local/perl561/.cpan/build
cpan> o conf keep_source_where /usr/local/perl561/.cpan/sources
cpan> o conf commit

This saves your changes to the CPAN shell configuration. (Note that you can change settings, use them, and exit without saving if you need to, say to use a different CPAN mirror one day or something.)

Once you have set all this up, you are ready to install modules. To do so, you just issue the install command:

cpan> install

There are many "Bundle" modules which are basically lists of modules to install all together. I always install the following Bundles:

cpan> install Bundle::CPAN
cpan> install Bundle::LWP
cpan> install Bundle::DBI
cpan> install Bundle::DBD::CSV


and recently I've added:

cpan> install Expect
cpan> install Time::Piece


The CPAN bundle contains modules to make the CPAN shell (which you are using to install modules) work better; it provides command line history and editing, and so on. The LWP bundle contains libraries for accessing websites in a program: downloading with HTTP, parsing HTML, and so on. The DBI bundle contains the DBI module and associated utilities; DBI is the Perl DataBase Interface; it is a frontend to make accessing any database in Perl the same as accessing any other database. You install backends (DBD modules) to access different types of databases. For example, if you want to write a Perl program to work with Oracle, you would want to install the DBD::Oracle backend for DBI: (but keep reading for more advice before you do that) cpan> install DBD::Oracle

The DBD::CSV bundle contains a backend to use Excel compatible CSV (comma separated value) files as a database. It's invaluable.

Note that the Bundle::CPAN collection will require you to do some things interactively to help it test itself. (It will pause and wait for your input.) It will also install the libnet module, which will ask if you want to "update your configuration." (It is referring to configuration of the libnet module, not configuration of perl or the CPAN shell). Say no; this will give you some reasonable default settings.

After you have installed these four Bundles, issue the install commands again to verify that you see "Module Bundle::CPAN up to date" for each of them.

Also, some of these modules come with programs that get installed in /usr/local/perl561/bin, so now is the best time to make a symbolic link to everything in that directory from /usr/local/bin.

Note that you don't say "Bundle::" every time you install a module. Bundles are collections of related modules, and usually you will install individual modules.

The CPAN shell runs the test suites that come with most modules; this is usually a good practice.

Sometimes the CPAN shell will be unable to install a module. It is good for you to know how to manually install a module so you can find out what is going wrong and get the module installed. Sometimes it's a simple matter of reading the README that comes with the module and discovering you need to set some environment variables. (This is the case with the DBD::Oracle backend module I mentioned earlier.) The manual process of installing a module goes like this:

• Download
• Extract (gzip | tar -xvf -)
• $ perl5.6.1 Makefile.PL
• $ make
• $ make test
• $ make install

Upgrading perl can be a relatively painless process if it is installed in its own directory tree and a few other best practices are followed. For one thing, never write a program to use perl without specifying the version to use. The top line of a perl program should not read: #!/usr/local/bin/perl

instead, it should read:

#!/usr/local/bin/perl5.6.1

If all of your perl programs are written this way, you can install a new version of perl harmlessly in a separate directory such as /usr/local/perl580. Then, if you've kept good records of what programs use which version, you can test each program against the new version of perl and upgrade it when you're ready. When all programs have been upgraded to use the new version, you can delete the old version.

When you upgrade perl, be sure to handle the symbolic links in /usr/local/bin properly. The link to the old version of perl should stay there (/usr/local/bin/perl5.6.1 -> /usr/local/perl561/bin/perl5.6.1), but most of the associated utilities should be relinked to the new versions (such as splain and perldoc). See what's in the bin/ subdirectory to see what links you should make.

The /usr/local/bin/perl link itself is hard to handle. If people write programs using it, you won't be able to change it without risking breaking those programs. For this reason, no one should put this link in the #! line of a program. Make the policy well-known to the perl programmers on the system. If everyone is aware of this, you can update the link when you upgrade perl. Programmers can see where this link points to find out what the latest version of perl on the system is. If the policy is not well-known, you will be stuck leaving this link pointing to an older version, or you will risk breaking applications unexpectedly when you point it at a newer version of perl. (Breaking things like this might be a good way to make the policy well-known.)

One final note about modules: if you run the "r" command in the CPAN shell, you will get a list of new versions of all modules you have installed. I run a development system where I upgrade all modules immediately when new versions come out so I can find out if they have changed in ways that break the programs I am working on. This can be a good idea, but not a good idea on a production system.