Chapter 24

Building and Installing the Perl 5 Interpreter

CONTENTS

• Getting Perl 5
  • Getting Perl from the Internet
  • Getting Perl via E-mail
  • Web Sites with Perl Information
  • On CD-ROM
• Installing Perl on Most UNIX Systems
  • Configuring Your Perl Distribution
  • Making Dependencies
  • What Are hints Files?
• Running Some Tests
  • Finishing It Up
  • Confirming the Installation
• The DOS Platform
• Other Platforms
• Linux: A Special Case for Perl 5
  • Partial Upgrades of Your Linux Kernel for Getting Perl Running
  • The Real Danger During the Partial Upgrade
• Summary

This chapter covers the gory details of installing Perl 5 on a given system. First, you find out where to get the distributions via the Internet. Then you learn the details of some of the things you need to do to get the Perl 5 package built and installed on to your machine. I cover building the sources for a UNIX system here in detail because this is what most of the sources are targeted for anyway. However, I also cover how to get Perl 5 on other platforms.

Getting Perl 5

There are several ways to get the Perl 5 package for your system. Some of the ways include buying a commercial package, getting it from the Internet via FTP or e-mail, or having someone else get it for you.

Getting Perl from the Internet

The latest Perl packages are usually available from any comp.sources.misc archive on a given news site. The latest source distribution will almost always be at Larry Wall's site. Here's the address: ftp://ftp.sems.com/pub/outgoing/perl5.0/

Larry Wall maintains the official distribution site (for both perl4.036 and perl5) at his site. Always check this site first for the latest versions and, if you are the brave sort, for the beta releases being worked on.

A number of archives have materialized over the years, and these archives hold Perl source code and related items. Probably the largest archive is at the University of Florida. The Comprehensive Perl Archive Network (CPAN) is a collection of all Perl materials including source files, modules, and documentation. In order of probability, these other sites should also have the Perl source files: ftp://ftp.cis.ufl.edu/pub/perl/src/5.0/
ftp://ftp.cbi.tamucc.edu/pub/duff/Perl/
ftp://ftp.metronet.com/pub/perl/sources/
ftp://genetics.upenn.edu/perl5/
ftp://ikra.com/pub/perl5

By the time you get this book, this listing might be superseded by newer sites. The best course of action is to use archie or a Web search site such as Yahoo to search for the words Perl, CPAN, or Perl5 to get the list of the latest versions of Perl 5 packages.

Getting Perl via E-mail

If you do not have direct FTP access, all is not lost. You can get the packages via e-mail. Table 24.1 is a small list of known FTP mail sites. As a general rule, you should always attempt to use the site closest to you with the FTP archive closest to it. Many of these sites already have Perl on them.

For information on how to use one of these sites, send e-mail containing the word help to the address.

Send a message to mail-server@cs.ruu.nl containing this: begin
path your_email_address
send help
send PERL/perl5.0/INDEX
end

You can omit the path line if your message contains a normal From: line. You'll receive a help file and an index of the directory that contains the Perl materials.

Web Sites with Perl Information

The following Web sites contain information on Perl 5. You can get more listings by using the Net search facilities on the Web by searching for the keyword Perl5. http://www.metronet.com/perlinfo/perl5.html
http://www-cgi.cs.cmu.edu/cgi-bin/perl-man
http:://www.perl.com/
http://src.doc.ic.ac.uk/packages/perl5

Naturally, your Web search tool will return a different list of directories. These sites will get you started at the very least.

The FAQ for Perl 5 is available at this site: http://mox.perl.com/perl/faq

On CD-ROM

The best collection I've found to date is the InfoMagic release of the CD-ROM Mother of Perl. This two-disc set includes the archives, mailing list archives, and lots of mirrors of CPAN sites. My disc was up to 5.001m, but a more current disc set should be available at the time this book goes to print. For more information contact InfoMagic at this address: InfoMagic
Box 30370
Flagstaff, AZ 86003
520-526-9565
www.infomagic.com

Installing Perl on Most UNIX Systems

Installing Perl takes time, but it's easy. I cover the installation on a UNIX-based system because this covers the most general installations of Perl. Please check the section titled "Other Platforms" for more instructions if you are not on a UNIX platform.

Here are the basic steps to follow:

1. Make sure you have all the files.
2. Configure your Perl distribution for your system.
3. Construct the dependencies.
4. Make the executables in your local directory.
5. Run a test version to see if everything is okay.
6. If everything checks out, make the distribution available to the rest of the users on your machine.

First, unzip and untar the Perl 5 package in a directory not in the /usr directory tree. You'll install this distribution in the /usr or /usr/local later. For now, just use a subdirectory in your home directory.

Go to the directory where you downloaded your Perl distribution. Then unzip and untar the distribution files with these commands: $ gunzip XXXX.tar.gz
$ tax -cvf XXXX.tar

where XXXX is the name of the Perl distribution you got from the Internet. At the time this book was written, this was perl5.002.tar.gz. The 5.002 version is installed and used for all examples in this book.

The INSTALL file is the master document you need to refer to if this chapter does not get you started. The text in the INSTALL file is in the plain old documentation (pod) format. Run pod2man to get the documentation in the man page format.

The MANIFEST file should contain the information you need on what files go where. The files after untarring the package should look like those shown in Listing 24.1.

Your Perl directory should contain the following source files after you untar the package:

Artistic     configure   hints        op.h          proto.h
Changes      cop.h       hv.c         opcode.h      regcomp.c
Changes.Conf cv.h        hv.h         opcode.pl     regcomp.h
Configure    deb.c       installman   os2           regexec.c
Copying      doio.c      installperl  patchlevel.h  regexp.h
EXTERN.h     doop.c      interp.sym   perl.c        run.c
INSTALL      dosish.h    keywords.h   perl.h        scope.c
INTERN.h     dump.c      keywords.pl  perl_exp.SH   scope.h
MANIFEST     eg          lib          perlsh        sv.c
Makefile.SH  emacs       makeaperl.SH perly.c       sv.h
README       embed.h     makedepend.SH perly.c.diff  t
README.vms   embed.pl    makedir.SH   perly.fixer   taint.c
Todo         ext         malloc.c     perly.h       toke.c
XSUB.h       form.h      mg.c         perly.y       unixish.h
av.c         global.sym  mg.h         pod           util.c
av.h         globals.c   minimod.pl   pp.c          util.h
cflags.SH    gv.c        miniperlmain.c  pp.h          utils
config_H     gv.h        mv-if-diff   pp_ctl.c      vms
config_h.SH  h2pl        myconfig     pp_hot.c      writemain.SH
configpm     handy.h     op.c         pp_sys.c      x2p

Configuring Your Perl Distribution

To configure your system, first run the Configure command in the perl5 directory where your source files were untarred. The Configure command will figure out various settings about your system. Configure will be able to default to many settings by itself; for other things it will ask you about. Figure 24.1 contains the output from the Configure command.

Figure 24.1 : The output from a configure command.

If the test scripts and programs run okay, the defaults are usually right. Configure will then create a set of defaults for itself and then proceed to make three files to store these sets of defaults: config.h, config.sh, and Makefile.

If you feel lucky, run Configure -d to take all the defaults, and edit config.sh yourself to patch up any flaws. I do not recommend this course of action unless you're a Perl wizard, in which case you probably would have skipped this entire chapter.

The Configure command supports a lot of options. The one option to know about is the -h option, which prints a list of the available options for Configure. The options are useful in overriding any predefined values. For example, you may have cc's and GNU's compilers both on your system with cc as the default. To force Configure to use gcc-elf, run the command Configure -Dcc=gcc-elf. Alternatively, in the interactive mode, you can answer gcc-elf at the cc prompt.

By default, Perl will be installed in the following directories:

• /usr/local/bin
• /usr/local/lib
• /usr/local/man

You can specify a different directory for the default installation location as long as you have read and write access to the directory. The default directory pathname can be changed with the -D flag; for example, for specifying a pathname to a subdirectory in my home directory I would use the command line option -Dprefix='/home/khusain/perl5'. The replacement for /usr/local is changed when you respond to the question of prefix in Configure script.

A couple of other points about running Configure: Do not reuse your old config.h or config.SH file from a previous version. Too many things may have changed. This is true for patches to the Perl package as well. If you want to see some differences, save a copy of the old file, rerun the Configure command, and then run a diff command to see the differences.

Actually, if you have some overrides that you want to use regardless of those set up with Configure, you can put them in a file called config.over. This file can be used by Configure and overrides any values just before it writes the config.sh file. To get a head start, copy config.sh onto config.over, and then edit config.over. The details of this procedure are given in the INSTALL document.

Perl will use any dynamic extensions if your system supports them. If you want to force Perl to be compiled and linked statically, then you can choose this when Configure prompts you about it. Most of the later versions of Perl use dynamic loading; therefore, if your system does not support it, consider upgrading. See the section: "Linux: A Special Case for Perl 5," in this chapter to see what some of the issues are.

While you are running Configure, be patient. Answer each question after reading it carefully. Yes, the defaults are great, but ultimately you are the one who has to run Perl on your system. Make sure you know enough about your system to know if the defaults look right or not.

If your system is not recognized, you'll most certainly have to answer questions alertly. The Configure script tells you if it has recognized your system, as shown in Figure 24.2.

Figure 24.2 : Recognition of a computer system by the configure command.

Also, do not hold down the Enter key or press it too many times. The returns may remain queued and provide a default reply when you really did not mean to.

There is no way to back up or re-enter all the information if you make a mistake. You have to start the entire process all over from the initial Configure command. Keep this in mind as you answer the questions. You can backspace on the current line, but you cannot go back to the previous prompt. The prompter will recognize $* as the entire default line should you want to append to the default values given. Arguments to responses can also be referred to as $1, $2, and so on to keep you from too much typing or typographical errors.

Use sh at least or some other shell instead that looks like the Bourne shell for the purpose of this installation. If you are bent on using your own version of csh, you'll have to copy the sample file config_H to config.h, and edit config.h to adapt to your shell.

Now would be a good time to peruse the config.h file to make sure that the system dependencies are correct. Most of them are taken care of by running the Configure script, but this will give you some insight on how the configuration sets everything up.

If you have any additional changes to make to the C definitions, make them in the cflags.SH file. For example, to turn off the optimizer on toke.c, find the line in the switch structure for toke.c and put the command optimize='-g' before the double semicolons. By default, the value is set to $optdebug.

To change the C flags for all the files, edit config.sh and change either $ccflags or $optimize. In order to ensure that the changes you have made to these header files propagate to all other programs, you must run the following command: Configure -S ; make depend

Making Dependencies

After you've configured your Perl package for your system, you must set up all the dependencies for the source files. This is done by typing the command make depend. The make file looks for all the affected include files and modifies the Makefile accordingly.

The Configure program will offer to do this for you; you just have to answer Yes, as shown in Figure 24.3. If you do not get this prompt, you can always run it from the command line.

Figure 24.3 : Running make depend from configure.

Now, attempt to make Perl in the current directory. Run the make command from the prompt without any arguments. The execution of this make command will take a while.

Generally speaking, you should encounter no errors. If you see errors and if these errors impede the development of the platform, the make program will terminate. If the errors are not critical or can be compensated for, make will continue and generate the correct files for you. Linux users should refer to the online documentation on ELF in Linux.

No errors during the compile phase does not equal a clean build in this case. Finish the entire procedure by testing the installation.

You may see some warnings, too. Again, this depends on the platform on which you are building Perl. In most cases, the warnings can be ignored. If you do see warnings about LITTLE_ENDIAN being redefined, ignore them. For your peace of mind, you might want to check the definitions of LITTLE_ENDIAN in the files that the make file warns you about. Both the declarations should be the same-that is, either 1234 or 4321, depending on the type of machine you happen to be building the version of Perl on.

The gcc compilers installed in your system should be able to handle the Perl distribution with only a few burps. For example, some function prototypes might not be recognized by the compiler. There is a way to counter some of these errors. For instance, try adding a -DCRIPPLED_cc flag. You might even consider turning off the -O2 optimization flag in config.sh in your compiler.

If you get duplicate function definitions (a Perl function has the same name as another function on your system), try using the -DEMBED switch to get rid of the error. These errors are rare, but not impossible to come by.

The worst error you could run into is an incomplete distribution. In this case, the only recourse you have is to abandon all efforts with your distribution and just start over with a fresh release from the Internet. Chances are that even if you actually paid someone for this crippled Perl release, they won't be interested in providing you with free support.

The config.sh file is the one you need to know about if you have to modify the compiler switches. The file is too long to list here, but I have listed some of the switches that you should definitely take a look at if you need to correct something:

• For the architecture type of CPU in your machine:

• For your binary files' directories:

• For the little endian or big endian order of your machine:

• For the c flags for your compiler:

• For the preprocessor flags:

• For any extensions you have added to Perl:

• For the gcc version number:

• For the locations where the binaries pages will be installed:

• For the locations where man pages will be installed:

• For the libraries used to build Perl:

• For your system's generic shell:

startsh='#!/bin/bash'

Some compilers will not compile or optimize the larger files without some extra switches for using larger jump offsets or allocating larger internal tables.

Perl without any extensions is referred to as Miniperl. If you run into problems while building with extensions, you should try to build Miniperl. If you can successfully build Miniperl but the process crashes during the building of extensions, you need to get the later versions of the extensions. In such an event, get a completely new package and try to avoid doing piecemeal patches, unless you know what you are doing-in which case you should not even be reading this chapter ;-) .

Machines with incomplete dbm routines (specifically the dbm_open() function) will need to set the #undef I_ODBM preprocessor directive. For duplicate reference error messages when linking files that call malloc, try the -DHIDEMYMALLOC switch. Both of these problems did not disappear on my Linux machine until I upgraded the entire system and kernel to ELF. I did not have to use I_ODBM or the -DHIDEMYMALLOC flag after the upgrade.

What Are hints Files?

In the Perl distribution, you'll find a ./hints subdirectory. The ./hints subdirectory is where platform-specific declarations are kept. The files here are used by Configure to set things that Configure either cannot or does not guess properly. You may have to edit these files for special versions of your computer operating system.

Generally, you should not have to use the hints file if you are using a UNIX-like operating system. Check the contents of this directory to see whether your system is listed and whether Perl works correctly with it. Check the README.hints file for a list of those systems for which Perl has been tested.

A sample listing of the linux.sh file is shown in Listing 24.2.

A hint is simply a shell script run by Configure that sets things it needs for your system. Usually the hint files are documented well enough to know why certain variables are defined.

And sometimes they're not. It's usually not that hard to figure out what the define is about, though. Case in point: the lines from the linux.sh file. Turning malloc off turns off Perl's version of malloc. There is really no need for an explanation here: # Explanation?
usemymalloc='n'

I use linux.sh here as the example because it's the system I happen to run. If you are on an SCO system, you have some choices to make, depending on the type of system you have. Here are the hints files included with 5.002: 3b1.sh                           dnix.sh         irix_6.sh&nb sp;    opus.sh    svr4.sh
3b1cc           dynix.sh         isc.sh          powerunix    .sh ti1500.sh
README.hints    epix.sh          isc_2.sh        sco_2_3_0    .sh titanos.sh
aix.sh          esix4.sh         linux.sh        sco_2_3_1    .sh ultrix_4.sh
altos486.sh     fps.sh           machten.sh      sco_2_3_2    .sh unicos.sh
apollo.sh       freebsd.sh       mips.sh         sco_2_3_3    .sh unisysdynix.sh
aux.sh          genix.sh         mpc.sh          sco_2_3_4    .sh utekv.sh
bsd386.sh       greenhills.sh    mpeix.sh        sco_3        .sh uts.sh
convexos.sh     hpux_9.sh        ncr_tower.sh    solaris_2.sh
cxux.sh         i386.sh          netbsd.sh       stellar.sh
dec_osf.sh      irix_4.sh        next_3.sh       sunos_4_0.sh
dgux.sh         irix_5.sh        next_3_0.sh     sunos_4_1.sh

Running Some Tests

Just because everything compiled doesn't mean you are out of the woods. You have to run the regression tests on the perl you just made. You should see the message All tests successful. (See Figure 24.4.)

Figure 24.4 : Results from a test run.

If it doesn't say All tests successful, something went wrong. Figure 24.4 shows a sample run without any error messages.

In the unfortunate event that you do not see the successful message, you have to figure out what went wrong. Go to the t directory. (I just love these directory names in UNIX.) Then run the TEST command to see the results.

If an individual test has cratered, you can run that test manually with this command: ./perl op/groups.t

Note that in the t directory, ./perl is linked to ../perl. This is a fully working version of the real enchilada!

Finishing It Up

You've now run the test, and the doubts in your mind are a faded memory. Let's discuss how to install Perl so that other users on your system are able to use it.

It would be a good idea to run as root now if you are writing in the /usr tree. Of course, you could have specified a totally different location over which you have write privileges-in which case being root is a moot point. Keep in mind that if you are not root, you must own the directories where you are writing and ignore any messages about chown not working.

Now, take a deep breath and run the make install command: make install

This command puts Perl into a public directory. If you used the defaults, the location is /usr/local/bin. The make install command will also try to put the man pages in a reasonable place, possibly under /usr/man. You may have to nroff the man page yourself, though. (In newer systems, the first time you run the man(1) command, it will automatically run nroff and update the cat-files for you.)

The make install command creates the following files for you (I'm using /usr/local/bin as the default location):

• perl5.002 and link /usr/local/bin/perl to it
• suidperl if you requested setuid emulation
• cppstdin, which is used by perl -P if your cc -E can't read from stdin
• c2ph and pstruct scripts, which are used for handling C structures in header files
• a2p, which converts awk scripts to Perl
• s2p, which converts sed scripts to Perl
• find2perl, which converts find command options to the Perl translator
• h2xs and other header files to Perl extensions
• pod2html, which contains Perl's pod documentation format to HTML
• pod2latex, which contains programs to convert documentation in the pod format to LaTeX
• pod2man, which contains programs to convert documentation in the pod format to man pages
• perldoc, a tool for reading Perl's pod documentation