Initial import of Perl5. The king is dead; long live the king!

1 files changed, 1599 insertions, 0 deletions

diff --git a/contrib/perl5/INSTALL b/contrib/perl5/INSTALL
new file mode 100644
index 0000000..a892e7d
--- /dev/null
+++ b/contrib/perl5/INSTALL
@@ -0,0 +1,1599 @@
+=head1 NAME
+
+Install - Build and Installation guide for perl5.
+
+=head1 SYNOPSIS
+
+The basic steps to build and install perl5 on a Unix system are:
+
+	rm -f config.sh Policy.sh
+	sh Configure
+	make
+	make test
+	make install
+
+	# You may also wish to add these:
+	(cd /usr/include && h2ph *.h sys/*.h)
+	(installhtml --help)
+	(cd pod && make tex  && <process the latex files>)
+
+Each of these is explained in further detail below.
+
+For information on non-Unix systems, see the section on
+L<"Porting information"> below.
+
+For information on what's new in this release, see the
+pod/perldelta.pod file.  For more detailed information about specific
+changes, see the Changes file.
+
+=head1 DESCRIPTION
+
+This document is written in pod format as an easy way to indicate its
+structure.  The pod format is described in pod/perlpod.pod, but you can
+read it as is with any pager or editor.  Headings and items are marked
+by lines beginning with '='.  The other mark-up used is
+
+    B<text>     embolden text, used for switches, programs or commands
+    C<code>	literal code
+    L<name>     A link (cross reference) to name
+
+You should probably at least skim through this entire document before
+proceeding.
+
+If you're building Perl on a non-Unix system, you should also read
+the README file specific to your operating system, since this may
+provide additional or different instructions for building Perl.
+
+If there is a hint file for your system (in the hints/ directory) you
+should also read that hint file for specific information for your
+system.  (Unixware users should use the svr4.sh hint file.)
+
+=head1 WARNING:  This version is not binary compatible with Perl 5.004.
+
+Starting with Perl 5.004_50 there were many deep and far-reaching changes
+to the language internals.  If you have dynamically loaded extensions
+that you built under perl 5.003 or 5.004, you can continue to use them
+with 5.004, but you will need to rebuild and reinstall those extensions
+to use them 5.005.  See the discussions below on
+L<"Coexistence with earlier versions of perl5"> and
+L<"Upgrading from 5.004 to 5.005"> for more details.
+
+The standard extensions supplied with Perl will be handled automatically.
+
+In a related issue, old extensions may possibly be affected by the
+changes in the Perl language in the current release.  Please see
+pod/perldelta.pod for a description of what's changed.
+
+=head1 Space Requirements
+
+The complete perl5 source tree takes up about 10 MB of disk space.  The
+complete tree after completing make takes roughly 20 MB, though the
+actual total is likely to be quite system-dependent.  The installation
+directories need something on the order of 10 MB, though again that
+value is system-dependent.
+
+=head1 Start with a Fresh Distribution
+
+If you have built perl before, you should clean out the build directory
+with the command
+
+	make distclean
+
+or
+
+	make realclean
+
+The only difference between the two is that make distclean also removes
+your old config.sh and Policy.sh files.
+
+The results of a Configure run are stored in the config.sh and Policy.sh
+files.  If you are upgrading from a previous version of perl, or if you
+change systems or compilers or make other significant changes, or if
+you are experiencing difficulties building perl, you should probably
+not re-use your old config.sh.  Simply remove it or rename it, e.g.
+
+	mv config.sh config.sh.old
+
+If you wish to use your old config.sh, be especially attentive to the
+version and architecture-specific questions and answers.  For example,
+the default directory for architecture-dependent library modules
+includes the version name.  By default, Configure will reuse your old
+name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
+Configure for a different version, e.g. 5.004.  Yes, Configure should
+probably check and correct for this, but it doesn't, presently.
+Similarly, if you used a shared libperl.so (see below) with version
+numbers, you will probably want to adjust them as well.
+
+Also, be careful to check your architecture name.  Some Linux systems
+(such as Debian) use i386, while others may use i486, i586, or i686.
+If you pick up a precompiled binary, it might not use the same name.
+
+In short, if you wish to use your old config.sh, I recommend running
+Configure interactively rather than blindly accepting the defaults.
+
+If your reason to reuse your old config.sh is to save your
+particular installation choices, then you can probably achieve the
+same effect by using the new Policy.sh file.  See the section on
+L<"Site-wide Policy settings"> below.
+
+=head1 Run Configure
+
+Configure will figure out various things about your system.  Some
+things Configure will figure out for itself, other things it will ask
+you about.  To accept the default, just press RETURN.   The default
+is almost always okay.  At any Configure prompt, you can type  &-d
+and Configure will use the defaults from then on.
+
+After it runs, Configure will perform variable substitution on all the
+*.SH files and offer to run make depend.
+
+Configure supports a number of useful options.  Run B<Configure -h> to
+get a listing.  See the Porting/Glossary file for a complete list of
+Configure variables you can set and their definitions.
+
+To compile with gcc, for example, you should run
+
+	sh Configure -Dcc=gcc
+
+This is the preferred way to specify gcc (or another alternative
+compiler) so that the hints files can set appropriate defaults.
+
+If you want to use your old config.sh but override some of the items
+with command line options, you need to use B<Configure -O>.
+
+By default, for most systems, perl will be installed in
+/usr/local/{bin, lib, man}.  You can specify a different 'prefix' for
+the default installation directory, when Configure prompts you or by
+using the Configure command line option -Dprefix='/some/directory',
+e.g.
+
+	sh Configure -Dprefix=/opt/perl
+
+If your prefix contains the string "perl", then the directories
+are simplified.  For example, if you use prefix=/opt/perl,
+then Configure will suggest /opt/perl/lib instead of
+/opt/perl/lib/perl5/.
+
+NOTE:  You must not specify an installation directory that is below
+your perl source directory.  If you do, installperl will attempt
+infinite recursion.
+
+It may seem obvious to say, but Perl is useful only when users can
+easily find it.  It's often a good idea to have both /usr/bin/perl and
+/usr/local/bin/perl be symlinks to the actual binary.  Be especially
+careful, however, of overwriting a version of perl supplied by your
+vendor.  In any case, system administrators are strongly encouraged to
+put (symlinks to) perl and its accompanying utilities, such as perldoc,
+into a directory typically found along a user's PATH, or in another
+obvious and convenient place.
+
+By default, Configure will compile perl to use dynamic loading if
+your system supports it.  If you want to force perl to be compiled
+statically, you can either choose this when Configure prompts you or
+you can use the Configure command line option -Uusedl.
+
+If you are willing to accept all the defaults, and you want terse
+output, you can run
+
+	sh Configure -des
+
+For my Solaris system, I usually use
+
+	sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
+
+=head2 GNU-style configure
+
+If you prefer the GNU-style configure command line interface, you can
+use the supplied configure.gnu command, e.g.
+
+	CC=gcc ./configure.gnu
+
+The configure.gnu script emulates a few of the more common configure
+options.  Try
+
+	./configure.gnu --help
+
+for a listing.
+
+Cross compiling is not supported.
+
+(The file is called configure.gnu to avoid problems on systems
+that would not distinguish the files "Configure" and "configure".)
+
+=head2 Extensions
+
+By default, Configure will offer to build every extension which appears
+to be supported.  For example, Configure will offer to build GDBM_File
+only if it is able to find the gdbm library.  (See examples below.)
+B, DynaLoader, Fcntl, IO, and attrs are always built by default.
+Configure does not contain code to test for POSIX compliance, so POSIX
+is always built by default as well.  If you wish to skip POSIX, you can
+set the Configure variable useposix=false either in a hint file or from
+the Configure command line.  Similarly, the Opcode extension is always
+built by default, but you can skip it by setting the Configure variable
+useopcode=false either in a hint file for from the command line.
+
+You can learn more about each of these extensions by consulting the
+documentation in the individual .pm modules, located under the
+ext/ subdirectory.
+
+Even if you do not have dynamic loading, you must still build the
+DynaLoader extension; you should just build the stub dl_none.xs
+version.  (Configure will suggest this as the default.)
+
+In summary, here are the Configure command-line variables you can set
+to turn off each extension:
+
+    B			(Always included by default)
+    DB_File		i_db
+    DynaLoader		(Must always be included as a static extension)
+    Fcntl		(Always included by default)
+    GDBM_File		i_gdbm
+    IO			(Always included by default)
+    NDBM_File		i_ndbm
+    ODBM_File		i_dbm
+    POSIX		useposix
+    SDBM_File		(Always included by default)
+    Opcode		useopcode
+    Socket		d_socket
+    Threads		usethreads
+    attrs		(Always included by default)
+
+Thus to skip the NDBM_File extension, you can use
+
+	sh Configure -Ui_ndbm
+
+Again, this is taken care of automatically if you don't have the ndbm
+library.
+
+Of course, you may always run Configure interactively and select only
+the extensions you want.
+
+Note:  The DB_File module will only work with version 1.x of Berkeley
+DB or newer releases of version 2.  Configure will automatically detect
+this for you and refuse to try to build DB_File with version 2.
+
+If you re-use your old config.sh but change your system (e.g. by
+adding libgdbm) Configure will still offer your old choices of extensions
+for the default answer, but it will also point out the discrepancy to
+you.
+
+Finally, if you have dynamic loading (most modern Unix systems do)
+remember that these extensions do not increase the size of your perl
+executable, nor do they impact start-up time, so you probably might as
+well build all the ones that will work on your system.
+
+=head2 Including locally-installed libraries
+
+Perl5 comes with interfaces to number of database extensions, including
+dbm, ndbm, gdbm, and Berkeley db.  For each extension, if
+Configure can find the appropriate header files and libraries, it will
+automatically include that extension.  The gdbm and db libraries
+are not included with perl.  See the library documentation for
+how to obtain the libraries.
+
+Note:  If your database header (.h) files are not in a
+directory normally searched by your C compiler, then you will need to
+include the appropriate -I/your/directory option when prompted by
+Configure.  If your database library (.a) files are not in a directory
+normally searched by your C compiler and linker, then you will need to
+include the appropriate -L/your/directory option when prompted by
+Configure.  See the examples below.
+
+=head2 Examples
+
+=over 4
+
+=item gdbm in /usr/local
+
+Suppose you have gdbm and want Configure to find it and build the
+GDBM_File extension.  This examples assumes you have gdbm.h
+installed in /usr/local/include/gdbm.h and libgdbm.a installed in
+/usr/local/lib/libgdbm.a.  Configure should figure all the
+necessary steps out automatically.
+
+Specifically, when Configure prompts you for flags for
+your C compiler, you should include  -I/usr/local/include.
+
+When Configure prompts you for linker flags, you should include
+-L/usr/local/lib.
+
+If you are using dynamic loading, then when Configure prompts you for
+linker flags for dynamic loading, you should again include
+-L/usr/local/lib.
+
+Again, this should all happen automatically.  If you want to accept the
+defaults for all the questions and have Configure print out only terse
+messages, then you can just run
+
+	sh Configure -des
+
+and Configure should include the GDBM_File extension automatically.
+
+This should actually work if you have gdbm installed in any of
+(/usr/local, /opt/local, /usr/gnu, /opt/gnu, /usr/GNU, or /opt/GNU).
+
+=item gdbm in /usr/you
+
+Suppose you have gdbm installed in some place other than /usr/local/,
+but you still want Configure to find it.  To be specific, assume you
+have /usr/you/include/gdbm.h and /usr/you/lib/libgdbm.a.  You
+still have to add -I/usr/you/include to cc flags, but you have to take
+an extra step to help Configure find libgdbm.a.  Specifically, when
+Configure prompts you for library directories, you have to add
+/usr/you/lib to the list.
+
+It is possible to specify this from the command line too (all on one
+line):
+
+	sh Configure -des \
+		-Dlocincpth="/usr/you/include" \
+		-Dloclibpth="/usr/you/lib"
+
+locincpth is a space-separated list of include directories to search.
+Configure will automatically add the appropriate -I directives.
+
+loclibpth is a space-separated list of library directories to search.
+Configure will automatically add the appropriate -L directives.  If
+you have some libraries under /usr/local/ and others under
+/usr/you, then you have to include both, namely
+
+	sh Configure -des \
+		-Dlocincpth="/usr/you/include /usr/local/include" \
+		-Dloclibpth="/usr/you/lib /usr/local/lib"
+
+=back
+
+=head2 Installation Directories
+
+The installation directories can all be changed by answering the
+appropriate questions in Configure.  For convenience, all the
+installation questions are near the beginning of Configure.
+
+I highly recommend running Configure interactively to be sure it puts
+everything where you want it.  At any point during the Configure
+process, you can answer a question with  &-d  and Configure
+will use the defaults from then on.
+
+By default, Configure will use the following directories for library files
+for 5.005 (archname is a string like sun4-sunos, determined by Configure).
+
+    Configure variable		Default value
+	$archlib 	/usr/local/lib/perl5/5.005/archname
+	$privlib	/usr/local/lib/perl5/5.005
+	$sitearch	/usr/local/lib/perl5/site_perl/5.005/archname
+	$sitelib	/usr/local/lib/perl5/site_perl/5.005
+
+Some users prefer to append a "/share" to $privlib and $sitelib
+to emphasize that those directories can be shared among different
+architectures.
+
+By default, Configure will use the following directories for manual pages:
+
+    Configure variable		Default value
+	$man1dir	/usr/local/man/man1
+	$man3dir	/usr/local/lib/perl5/man/man3
+
+(Actually, Configure recognizes the SVR3-style
+/usr/local/man/l_man/man1 directories, if present, and uses those
+instead.)
+
+The module man pages are stuck in that strange spot so that
+they don't collide with other man pages stored in /usr/local/man/man3,
+and so that Perl's man pages don't hide system man pages.  On some
+systems, B<man less> would end up calling up Perl's less.pm module man
+page, rather than the less program.  (This default location will likely
+change to /usr/local/man/man3 in a future release of perl.)
+
+Note:  Many users prefer to store the module man pages in
+/usr/local/man/man3.  You can do this from the command line with
+
+	sh Configure -Dman3dir=/usr/local/man/man3
+
+Some users also prefer to use a .3pm suffix.  You can do that with
+
+	sh Configure -Dman3ext=3pm
+
+If you specify a prefix that contains the string "perl", then the
+directory structure is simplified.  For example, if you Configure with
+-Dprefix=/opt/perl, then the defaults for 5.005 are
+
+    Configure variable		Default value
+	$archlib	/opt/perl/lib/5.005/archname
+	$privlib	/opt/perl/lib/5.005
+	$sitearch	/opt/perl/lib/site_perl/5.005/archname
+	$sitelib	/opt/perl/lib/site_perl/5.005
+
+	$man1dir	/opt/perl/man/man1
+	$man3dir	/opt/perl/man/man3
+
+The perl executable will search the libraries in the order given
+above.
+
+The directories under site_perl are empty, but are intended to be used
+for installing local or site-wide extensions.  Perl will automatically
+look in these directories.
+
+In order to support using things like #!/usr/local/bin/perl5.005 after
+a later version is released, architecture-dependent libraries are
+stored in a version-specific directory, such as
+/usr/local/lib/perl5/archname/5.005/.
+
+Further details about the installation directories, maintenance and
+development subversions, and about supporting multiple versions are
+discussed in L<"Coexistence with earlier versions of perl5"> below.
+
+Again, these are just the defaults, and can be changed as you run
+Configure.
+
+=head2 Changing the installation directory
+
+Configure distinguishes between the directory in which perl (and its
+associated files) should be installed and the directory in which it
+will eventually reside.  For most sites, these two are the same; for
+sites that use AFS, this distinction is handled automatically.
+However, sites that use software such as depot to manage software
+packages may also wish to install perl into a different directory and
+use that management software to move perl to its final destination.
+This section describes how to do this.  Someday, Configure may support
+an option -Dinstallprefix=/foo to simplify this.
+
+Suppose you want to install perl under the /tmp/perl5 directory.  You
+can edit config.sh and change all the install* variables to point to
+/tmp/perl5 instead of /usr/local/wherever.  Or, you can automate this
+process by placing the following lines in a file config.over before you
+run Configure (replace /tmp/perl5 by a directory of your choice):
+
+    installprefix=/tmp/perl5
+    test -d $installprefix || mkdir $installprefix
+    test -d $installprefix/bin || mkdir $installprefix/bin
+    installarchlib=`echo $installarchlib | sed "s!$prefix!$installprefix!"`
+    installbin=`echo $installbin | sed "s!$prefix!$installprefix!"`
+    installman1dir=`echo $installman1dir | sed "s!$prefix!$installprefix!"`
+    installman3dir=`echo $installman3dir | sed "s!$prefix!$installprefix!"`
+    installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"`
+    installscript=`echo $installscript | sed "s!$prefix!$installprefix!"`
+    installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"`
+    installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"`
+
+Then, you can Configure and install in the usual way:
+
+    sh Configure -des
+    make
+    make test
+    make install
+
+Beware, though, that if you go to try to install new add-on
+extensions, they too will get installed in under '/tmp/perl5' if you
+follow this example.  The next section shows one way of dealing with
+that problem.
+
+=head2 Creating an installable tar archive
+
+If you need to install perl on many identical systems, it is
+convenient to compile it once and create an archive that can be
+installed on multiple systems.  Here's one way to do that:
+
+    # Set up config.over to install perl into a different directory,
+    # e.g. /tmp/perl5 (see previous part).
+    sh Configure -des
+    make
+    make test
+    make install
+    cd /tmp/perl5
+    # Edit $archlib/Config.pm to change all the
+    # install* variables back to reflect where everything will
+    # really be installed.
+    # Edit any of the scripts in $scriptdir to have the correct
+    # #!/wherever/perl line.
+    tar cvf ../perl5-archive.tar .
+    # Then, on each machine where you want to install perl,
+    cd /usr/local  # Or wherever you specified as $prefix
+    tar xvf perl5-archive.tar
+
+=head2 Site-wide Policy settings
+
+After Configure runs, it stores a number of common site-wide "policy"
+answers (such as installation directories and the local perl contact
+person) in the Policy.sh file.  If you want to build perl on another
+system using the same policy defaults, simply copy the Policy.sh file
+to the new system and Configure will use it along with the appropriate
+hint file for your system.
+
+Alternatively, if you wish to change some or all of those policy
+answers, you should
+
+	rm -f Policy.sh
+
+to ensure that Configure doesn't re-use them.
+
+Further information is in the Policy_sh.SH file itself.
+
+=head2 Configure-time Options
+
+There are several different ways to Configure and build perl for your
+system.  For most users, the defaults are sensible and will work.
+Some users, however, may wish to further customize perl.  Here are
+some of the main things you can change.
+
+=head2 Threads
+
+On some platforms, perl5.005 can be compiled to use threads.  To
+enable this, read the file README.threads, and then try
+
+	sh Configure -Dusethreads
+
+Currently, you need to specify -Dusethreads on the Configure command
+line so that the hint files can make appropriate adjustments.
+
+The default is to compile without thread support.
+
+=head2 Selecting File IO mechanisms
+
+Previous versions of perl used the standard IO mechanisms as defined in
+stdio.h.  Versions 5.003_02 and later of perl allow alternate IO
+mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
+the default and is the only supported mechanism.
+
+This PerlIO abstraction can be enabled either on the Configure command
+line with
+
+	sh Configure -Duseperlio
+
+or interactively at the appropriate Configure prompt.
+
+If you choose to use the PerlIO abstraction layer, there are two
+(experimental) possibilities for the underlying IO calls.  These have been
+tested to some extent on some platforms, but are not guaranteed to work
+everywhere.
+
+=over 4
+
+=item 1.
+
+AT&T's "sfio".  This has superior performance to stdio.h in many
+cases, and is extensible by the use of "discipline" modules.  Sfio
+currently only builds on a subset of the UNIX platforms perl supports.
+Because the data structures are completely different from stdio, perl
+extension modules or external libraries may not work.  This
+configuration exists to allow these issues to be worked on.
+
+This option requires the 'sfio' package to have been built and installed.
+A (fairly old) version of sfio is in CPAN.
+
+You select this option by
+
+	sh Configure -Duseperlio -Dusesfio
+
+If you have already selected -Duseperlio, and if Configure detects
+that you have sfio, then sfio will be the default suggested by
+Configure.
+
+Note:  On some systems, sfio's iffe configuration script fails
+to detect that you have an atexit function (or equivalent).
+Apparently, this is a problem at least for some versions of Linux
+and SunOS 4.
+
+You can test if you have this problem by trying the following shell
+script.  (You may have to add some extra cflags and libraries.  A
+portable version of this may eventually make its way into Configure.)
+
+    #!/bin/sh
+    cat > try.c <<'EOCP'
+    #include <stdio.h>
+    main() { printf("42\n"); }
+    EOCP
+    cc -o try try.c -lsfio
+    val=`./try`
+    if test X$val = X42; then
+	echo "Your sfio looks ok"
+    else
+	echo "Your sfio has the exit problem."
+    fi
+
+If you have this problem, the fix is to go back to your sfio sources
+and correct iffe's guess about atexit.
+
+There also might be a more recent release of Sfio that fixes your
+problem.
+
+=item 2.
+
+Normal stdio IO, but with all IO going through calls to the PerlIO
+abstraction layer.  This configuration can be used to check that perl and
+extension modules have been correctly converted to use the PerlIO
+abstraction.
+
+This configuration should work on all platforms (but might not).
+
+You select this option via:
+
+	sh Configure -Duseperlio -Uusesfio
+
+If you have already selected -Duseperlio, and if Configure does not
+detect sfio, then this will be the default suggested by Configure.
+
+=back
+
+=head2 Building a shared libperl.so Perl library
+
+Currently, for most systems, the main perl executable is built by
+linking the "perl library" libperl.a with perlmain.o, your static
+extensions (usually just DynaLoader.a) and various extra libraries,
+such as -lm.
+
+On some systems that support dynamic loading, it may be possible to
+replace libperl.a with a shared libperl.so.  If you anticipate building
+several different perl binaries (e.g. by embedding libperl into
+different programs, or by using the optional compiler extension), then
+you might wish to build a shared libperl.so so that all your binaries
+can share the same library.
+
+The disadvantages are that there may be a significant performance
+penalty associated with the shared libperl.so, and that the overall
+mechanism is still rather fragile with respect to different versions
+and upgrades.
+
+In terms of performance, on my test system (Solaris 2.5_x86) the perl
+test suite took roughly 15% longer to run with the shared libperl.so.
+Your system and typical applications may well give quite different
+results.
+
+The default name for the shared library is typically something like
+libperl.so.3.2 (for Perl 5.003_02) or libperl.so.302 or simply
+libperl.so.  Configure tries to guess a sensible naming convention
+based on your C library name.  Since the library gets installed in a
+version-specific architecture-dependent directory, the exact name
+isn't very important anyway, as long as your linker is happy.
+
+For some systems (mostly SVR4), building a shared libperl is required
+for dynamic loading to work, and hence is already the default.
+
+You can elect to build a shared libperl by
+
+	sh Configure -Duseshrplib
+
+To actually build perl, you must add the current working directory to your
+LD_LIBRARY_PATH environment variable before running make.  You can do
+this with
+
+   LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
+
+for Bourne-style shells, or
+
+   setenv LD_LIBRARY_PATH `pwd`
+
+for Csh-style shells.  You *MUST* do this before running make.
+Folks running NeXT OPENSTEP must substitute DYLD_LIBRARY_PATH for
+LD_LIBRARY_PATH above.
+
+There is also an potential problem with the shared perl library if you
+want to have more than one "flavor" of the same version of perl (e.g.
+with and without -DDEBUGGING).  For example, suppose you build and
+install a standard Perl 5.004 with a shared library.  Then, suppose you
+try to build Perl 5.004 with -DDEBUGGING enabled, but everything else
+the same, including all the installation directories.  How can you
+ensure that your newly built perl will link with your newly built
+libperl.so.4 rather with the installed libperl.so.4?  The answer is
+that you might not be able to.  The installation directory is encoded
+in the perl binary with the LD_RUN_PATH environment variable (or
+equivalent ld command-line option).  On Solaris, you can override that
+with LD_LIBRARY_PATH; on Linux you can't.  On Digital Unix, you can
+override LD_LIBRARY_PATH by setting the _RLD_ROOT environment variable
+to point to the perl build directory.
+
+The only reliable answer is that you should specify a different
+directory for the architecture-dependent library for your -DDEBUGGING
+version of perl.  You can do this by changing all the *archlib*
+variables in config.sh, namely archlib, archlib_exp, and
+installarchlib, to point to your new architecture-dependent library.
+
+=head2 Malloc Issues
+
+Perl relies heavily on malloc(3) to grow data structures as needed, so
+perl's performance can be noticeably affected by the performance of
+the malloc function on your system.
+
+The perl source is shipped with a version of malloc that is very fast but
+somewhat wasteful of space.  On the other hand, your system's malloc
+function may be a bit slower but also a bit more frugal.  However,
+as of 5.004_68, perl's malloc has been optimized for the typical
+requests from perl, so there's a chance that it may be both faster and
+use less memory.
+
+For many uses, speed is probably the most important consideration, so
+the default behavior (for most systems) is to use the malloc supplied
+with perl.  However, if you will be running very large applications
+(e.g. Tk or PDL) or if your system already has an excellent malloc, or
+if you are experiencing difficulties with extensions that use
+third-party libraries that call malloc, then you might wish to use
+your system's malloc.  (Or, you might wish to explore the malloc flags
+discussed below.)
+
+To build without perl's malloc, you can use the Configure command
+
+	sh Configure -Uusemymalloc
+
+or you can answer 'n' at the appropriate interactive Configure prompt.
+
+=head2 Malloc Performance Flags
+
+If you are using Perl's malloc, you may add one or more of the following
+items to your ccflags config.sh variable to change its behavior.  You can
+find out more about these and other flags by reading the commentary near
+the top of the malloc.c source.  The defaults should be fine for
+nearly everyone.
+
+=over 4
+
+=item -DNO_FANCY_MALLOC
+
+Undefined by default.  Defining it returns malloc to the version used
+in Perl 5.004.
+
+=item -DPLAIN_MALLOC
+
+Undefined by default.  Defining it in addition to NO_FANCY_MALLOC returns
+malloc to the version used in Perl version 5.000.
+
+=back
+
+=head2 Building a debugging perl
+
+You can run perl scripts under the perl debugger at any time with
+B<perl -d your_script>.  If, however, you want to debug perl itself,
+you probably want to do
+
+	sh Configure -Doptimize='-g'
+
+This will do two independent things:  First, it will force compilation
+to use cc -g so that you can use your system's debugger on the
+executable.  (Note:  Your system may actually require something like
+cc -g2.  Check your man pages for cc(1) and also any hint file for your
+system.)  Second, it will add -DDEBUGGING to your ccflags variable in
+config.sh so that you can use B<perl -D> to access perl's internal
+state.  (Note: Configure will only add -DDEBUGGING by
+default if you are not reusing your old config.sh.  If you want to
+reuse your old config.sh, then you can just edit it and change the
+optimize and ccflags variables by hand and then propagate your changes
+as shown in L<"Propagating your changes to config.sh"> below.)
+
+You can actually specify -g and -DDEBUGGING independently, but usually
+it's convenient to have both.
+
+If you are using a shared libperl, see the warnings about multiple
+versions of perl under L<Building a shared libperl.so Perl library>.
+
+=head2 Other Compiler Flags
+
+For most users, all of the Configure defaults are fine.  However,
+you can change a number of factors in the way perl is built
+by adding appropriate -D directives to your ccflags variable in
+config.sh.
+
+For example, you can replace the rand() and srand() functions in the
+perl source by any other random number generator by a trick such as the
+following (this should all be on one line):
+
+	sh Configure -Dccflags='-Dmy_rand=random -Dmy_srand=srandom' \
+		-Drandbits=31
+
+or you can use the drand48 family of functions with
+
+	sh Configure -Dccflags='-Dmy_rand=lrand48 -Dmy_srand=srand48' \
+		-Drandbits=31
+
+or by adding the -D flags to your ccflags at the appropriate Configure
+prompt.  (Read pp.c to see how this works.)
+
+You should also run Configure interactively to verify that a hint file
+doesn't inadvertently override your ccflags setting.  (Hints files
+shouldn't do that, but some might.)
+
+=head2 What if it doesn't work?
+
+=over 4
+
+=item Running Configure Interactively
+
+If Configure runs into trouble, remember that you can always run
+Configure interactively so that you can check (and correct) its
+guesses.
+
+All the installation questions have been moved to the top, so you don't
+have to wait for them.  Once you've handled them (and your C compiler and
+flags) you can type  &-d  at the next Configure prompt and Configure
+will use the defaults from then on.
+
+If you find yourself trying obscure command line incantations and
+config.over tricks, I recommend you run Configure interactively
+instead.  You'll probably save yourself time in the long run.
+
+=item Hint files
+
+The perl distribution includes a number of system-specific hints files
+in the hints/ directory.  If one of them matches your system, Configure
+will offer to use that hint file.
+
+Several of the hint files contain additional important information.
+If you have any problems, it is a good idea to read the relevant hint file
+for further information.  See hints/solaris_2.sh for an extensive example.
+More information about writing good hints is in the hints/README.hints
+file.
+
+=item *** WHOA THERE!!! ***
+
+Occasionally, Configure makes a wrong guess.  For example, on SunOS
+4.1.3, Configure incorrectly concludes that tzname[] is in the
+standard C library.  The hint file is set up to correct for this.  You
+will see a message:
+
+    *** WHOA THERE!!! ***
+	The recommended value for $d_tzname on this machine was "undef"!
+	Keep the recommended value? [y]
+
+You should always keep the recommended value unless, after reading the
+relevant section of the hint file, you are sure you want to try
+overriding it.
+
+If you are re-using an old config.sh, the word "previous" will be
+used instead of "recommended".  Again, you will almost always want
+to keep the previous value, unless you have changed something on your
+system.
+
+For example, suppose you have added libgdbm.a to your system
+and you decide to reconfigure perl to use GDBM_File.  When you run
+Configure again, you will need to add -lgdbm to the list of libraries.
+Now, Configure will find your gdbm include file and library and will
+issue a message:
+
+    *** WHOA THERE!!! ***
+	The previous value for $i_gdbm on this machine was "undef"!
+	Keep the previous value? [y]
+
+In this case, you do not want to keep the previous value, so you
+should answer 'n'.  (You'll also have to manually add GDBM_File to
+the list of dynamic extensions to build.)
+
+=item Changing Compilers
+
+If you change compilers or make other significant changes, you should
+probably not re-use your old config.sh.  Simply remove it or
+rename it, e.g. mv config.sh config.sh.old.  Then rerun Configure
+with the options you want to use.
+
+This is a common source of problems.  If you change from cc to
+gcc, you should almost always remove your old config.sh.
+
+=item Propagating your changes to config.sh
+
+If you make any changes to config.sh, you should propagate
+them to all the .SH files by running
+
+	sh Configure -S
+
+You will then have to rebuild by running
+
+	make depend
+	make
+
+=item config.over
+
+You can also supply a shell script config.over to over-ride Configure's
+guesses.  It will get loaded up at the very end, just before config.sh
+is created.  You have to be careful with this, however, as Configure
+does no checking that your changes make sense.  See the section on
+L<"Changing the installation directory"> for an example.
+
+=item config.h
+
+Many of the system dependencies are contained in config.h.
+Configure builds config.h by running the config_h.SH script.
+The values for the variables are taken from config.sh.
+
+If there are any problems, you can edit config.h directly.  Beware,
+though, that the next time you run Configure, your changes will be
+lost.
+
+=item cflags
+
+If you have any additional changes to make to the C compiler command
+line, they can be made in cflags.SH.  For instance, 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 ;; .  You
+can also edit cflags directly, but beware that your changes will be
+lost the next time you run Configure.
+
+To explore various ways of changing ccflags from within a hint file,
+see the file hints/README.hints.
+
+To change the C flags for all the files, edit config.sh and change either
+$ccflags or $optimize, and then re-run
+
+	sh Configure -S
+	make depend
+
+=item No sh
+
+If you don't have sh, you'll have to copy the sample file Porting/config_H
+to config.h and edit the config.h to reflect your system's peculiarities.
+You'll probably also have to extensively modify the extension building
+mechanism.
+
+=item Porting information
+
+Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
+corresponding README files and subdirectories.  Additional information,
+including a glossary of all those config.sh variables, is in the Porting
+subdirectory.
+
+Ports for other systems may also be available.  You should check out
+http://www.perl.com/CPAN/ports for current information on ports to
+various other operating systems.
+
+=back
+
+=head1 make depend
+
+This will look for all the includes.  The output is stored in makefile.
+The only difference between Makefile and makefile is the dependencies at
+the bottom of makefile.  If you have to make any changes, you should edit
+makefile, not Makefile since the Unix make command reads makefile first.
+(On non-Unix systems, the output may be stored in a different file.
+Check the value of $firstmakefile in your config.sh if in doubt.)
+
+Configure will offer to do this step for you, so it isn't listed
+explicitly above.
+
+=head1 make
+
+This will attempt to make perl in the current directory.
+
+If you can't compile successfully, try some of the following ideas.
+If none of them help, and careful reading of the error message and
+the relevant manual pages on your system doesn't help, you can
+send a message to either the comp.lang.perl.misc newsgroup or to
+perlbug@perl.com with an accurate description of your problem.
+See L<"Reporting Problems"> below.
+
+=over 4
+
+=item hints
+
+If you used a hint file, try reading the comments in the hint file
+for further tips and information.
+
+=item extensions
+
+If you can successfully build miniperl, but the process crashes
+during the building of extensions, you should run
+
+	make minitest
+
+to test your version of miniperl.
+
+=item locale
+
+If you have any locale-related environment variables set, try unsetting
+them.  I have some reports that some versions of IRIX hang while
+running B<./miniperl configpm> with locales other than the C locale.
+See the discussion under L<"make test"> below about locales and the
+whole L<"Locale problems"> section in the file pod/perllocale.pod.
+The latter is especially useful if you see something like this
+
+	perl: warning: Setting locale failed.
+	perl: warning: Please check that your locale settings:
+	        LC_ALL = "En_US",
+	        LANG = (unset)
+	    are supported and installed on your system.
+	perl: warning: Falling back to the standard locale ("C").
+
+at Perl startup.
+
+=item malloc duplicates
+
+If you get duplicates upon linking for malloc et al, add -DEMBEDMYMALLOC
+to your ccflags variable in config.sh.
+
+=item varargs
+
+If you get varargs problems with gcc, be sure that gcc is installed
+correctly and that you are not passing -I/usr/include to gcc.  When using
+gcc, you should probably have i_stdarg='define' and i_varargs='undef'
+in config.sh.  The problem is usually solved by running fixincludes
+correctly.  If you do change config.sh, don't forget to propagate
+your changes (see L<"Propagating your changes to config.sh"> below).
+See also the L<"vsprintf"> item below.
+
+=item util.c
+
+If you get error messages such as the following (the exact line
+numbers and function name may vary in different versions of perl):
+
+    util.c: In function `Perl_form':
+    util.c:1107: number of arguments doesn't match prototype
+    proto.h:125: prototype declaration
+
+it might well be a symptom of the gcc "varargs problem".  See the
+previous L<"varargs"> item.
+
+=item Solaris and SunOS dynamic loading
+
+If you have problems with dynamic loading using gcc on SunOS or
+Solaris, and you are using GNU as and GNU ld, you may need to add
+-B/bin/ (for SunOS) or -B/usr/ccs/bin/ (for Solaris) to your
+$ccflags, $ldflags, and $lddlflags so that the system's versions of as
+and ld are used.  Note that the trailing '/' is required.
+Alternatively, you can use the GCC_EXEC_PREFIX
+environment variable to ensure that Sun's as and ld are used.  Consult
+your gcc documentation for further information on the -B option and
+the GCC_EXEC_PREFIX variable.
+
+One convenient way to ensure you are not using GNU as and ld is to
+invoke Configure with
+
+    sh Configure -Dcc='gcc -B/usr/ccs/bin/'
+
+for Solaris systems.  For a SunOS system, you must use -B/bin/
+instead.
+
+Alternatively, recent versions of GNU ld reportedly work if you
+include C<-Wl,-export-dynamic> in the ccdlflags variable in
+config.sh.
+
+=item ld.so.1: ./perl: fatal: relocation error:
+
+If you get this message on SunOS or Solaris, and you're using gcc,
+it's probably the GNU as or GNU ld problem in the previous item
+L<"Solaris and SunOS dynamic loading">.
+
+=item LD_LIBRARY_PATH
+
+If you run into dynamic loading problems, check your setting of
+the LD_LIBRARY_PATH environment variable.  If you're creating a static
+Perl library (libperl.a rather than libperl.so) it should build
+fine with LD_LIBRARY_PATH unset, though that may depend on details
+of your local set-up.
+
+=item dlopen: stub interception failed
+
+The primary cause of the 'dlopen: stub interception failed' message is
+that the LD_LIBRARY_PATH environment variable includes a directory
+which is a symlink to /usr/lib (such as /lib).
+
+The reason this causes a problem is quite subtle.  The file libdl.so.1.0
+actually *only* contains functions which generate 'stub interception
+failed' errors!  The runtime linker intercepts links to
+"/usr/lib/libdl.so.1.0" and links in internal implementation of those
+functions instead.  [Thanks to Tim Bunce for this explanation.]
+
+=item nm extraction
+
+If Configure seems to be having trouble finding library functions,
+try not using nm extraction.  You can do this from the command line
+with
+
+	sh Configure -Uusenm
+
+or by answering the nm extraction question interactively.
+If you have previously run Configure, you should not reuse your old
+config.sh.
+
+=item umask not found
+
+If the build processes encounters errors relating to umask(), the problem
+is probably that Configure couldn't find your umask() system call.
+Check your config.sh.  You should have d_umask='define'.  If you don't,
+this is probably the L<"nm extraction"> problem discussed above.  Also,
+try reading the hints file for your system for further information.
+
+=item vsprintf
+
+If you run into problems with vsprintf in compiling util.c, the
+problem is probably that Configure failed to detect your system's
+version of vsprintf().  Check whether your system has vprintf().
+(Virtually all modern Unix systems do.)  Then, check the variable
+d_vprintf in config.sh.  If your system has vprintf, it should be:
+
+	d_vprintf='define'
+
+If Configure guessed wrong, it is likely that Configure guessed wrong
+on a number of other common functions too.  This is probably
+the L<"nm extraction"> problem discussed above.
+
+=item do_aspawn
+
+If you run into problems relating to do_aspawn or do_spawn, the
+problem is probably that Configure failed to detect your system's
+fork() function.  Follow the procedure in the previous item
+on L<"nm extraction">.
+
+=item __inet_* errors
+
+If you receive unresolved symbol errors during Perl build and/or test
+referring to __inet_* symbols, check to see whether BIND 8.1 is
+installed.  It installs a /usr/local/include/arpa/inet.h that refers to
+these symbols.  Versions of BIND later than 8.1 do not install inet.h
+in that location and avoid the errors.  You should probably update to a
+newer version of BIND.  If you can't, you can either link with the
+updated resolver library provided with BIND 8.1 or rename
+/usr/local/bin/arpa/inet.h during the Perl build and test process to
+avoid the problem.
+
+=item Optimizer
+
+If you can't compile successfully, try turning off your compiler's
+optimizer.  Edit config.sh and change the line
+
+	optimize='-O'
+
+to
+
+	optimize=' '
+
+then propagate your changes with B<sh Configure -S> and rebuild
+with B<make depend; make>.
+
+=item CRIPPLED_CC
+
+If you still can't compile successfully, try adding a -DCRIPPLED_CC
+flag.  (Just because you get no errors doesn't mean it compiled right!)
+This simplifies some complicated expressions for compilers that get
+indigestion easily.
+
+=item Missing functions
+
+If you have missing routines, you probably need to add some library or
+other, or you need to undefine some feature that Configure thought was
+there but is defective or incomplete.  Look through config.h for
+likely suspects.  If Configure guessed wrong on a number of functions,
+you might have the L<"nm extraction"> problem discussed above.
+
+=item toke.c
+
+Some compilers will not compile or optimize the larger files (such as
+toke.c) without some extra switches to use larger jump offsets or
+allocate larger internal tables.  You can customize the switches for
+each file in cflags.  It's okay to insert rules for specific files into
+makefile since a default rule only takes effect in the absence of a
+specific rule.
+
+=item Missing dbmclose
+
+SCO prior to 3.2.4 may be missing dbmclose().  An upgrade to 3.2.4
+that includes libdbm.nfs (which includes dbmclose()) may be available.
+
+=item Note (probably harmless): No library found for -lsomething
+
+If you see such a message during the building of an extension, but
+the extension passes its tests anyway (see L<"make test"> below),
+then don't worry about the warning message.  The extension
+Makefile.PL goes looking for various libraries needed on various
+systems; few systems will need all the possible libraries listed.
+For example, a system may have -lcposix or -lposix, but it's
+unlikely to have both, so most users will see warnings for the one
+they don't have.  The phrase 'probably harmless' is intended to
+reassure you that nothing unusual is happening, and the build
+process is continuing.
+
+On the other hand, if you are building GDBM_File and you get the
+message
+
+    Note (probably harmless): No library found for -lgdbm
+
+then it's likely you're going to run into trouble somewhere along
+the line, since it's hard to see how you can use the GDBM_File
+extension without the -lgdbm library.
+
+It is true that, in principle, Configure could have figured all of
+this out, but Configure and the extension building process are not
+quite that tightly coordinated.
+
+=item sh: ar: not found
+
+This is a message from your shell telling you that the command 'ar'
+was not found.  You need to check your PATH environment variable to
+make sure that it includes the directory with the 'ar' command.  This
+is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin
+directory.
+
+=item db-recno failure on tests 51, 53 and 55
+
+Old versions of the DB library (including the DB library which comes
+with FreeBSD 2.1) had broken handling of recno databases with modified
+bval settings.  Upgrade your DB library or OS.
+
+=item Bad arg length for semctl, is XX, should be ZZZ
+
+If you get this error message from the lib/ipc_sysv test, your System
+V IPC may be broken.  The XX typically is 20, and that is what ZZZ
+also should be.  Consider upgrading your OS, or reconfiguring your OS
+to include the System V semaphores.
+
+=item lib/ipc_sysv........semget: No space left on device
+
+Either your account or the whole system has run out of semaphores.  Or
+both.  Either list the semaphores with "ipcs" and remove the unneeded
+ones (which ones these are depends on your system and applications)
+with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
+system.
+
+=item Miscellaneous
+
+Some additional things that have been reported for either perl4 or perl5:
+
+Genix may need to use libc rather than libc_s, or #undef VARARGS.
+
+NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
+
+UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
+
+FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
+configured to the kernel.  Perl tries to detect this, though, and
+you will get a message telling what to do.
+
+If you get syntax errors on '(', try -DCRIPPLED_CC.
+
+Machines with half-implemented dbm routines will need to #undef I_ODBM
+
+=back
+
+=head1 make test
+
+This will run the regression tests on the perl you just made (you
+should run plain 'make' before 'make test' otherwise you won't have a
+complete build).  If 'make test' doesn't say "All tests successful"
+then something went wrong.  See the file t/README in the t subdirectory.
+
+Note that you can't run the tests in background if this disables
+opening of /dev/tty. You can use 'make test-notty' in that case but
+a few tty tests will be skipped.
+
+=head2 What if make test doesn't work?
+
+If make test bombs out, just cd to the t directory and run ./TEST
+by hand to see if it makes any difference.  If individual tests
+bomb, you can run them by hand, e.g.,
+
+	./perl op/groups.t
+
+Another way to get more detailed information about failed tests and
+individual subtests is to cd to the t directory and run
+
+	./perl harness
+
+(this assumes that most basic tests succeed, since harness uses
+complicated constructs).
+
+You should also read the individual tests to see if there are any helpful
+comments that apply to your system.
+
+=over 4
+
+=item locale
+
+Note:  One possible reason for errors is that some external programs
+may be broken due to the combination of your environment and the way
+B<make test> exercises them.  For example, this may happen if you have
+one or more of these environment variables set:  LC_ALL LC_CTYPE
+LC_COLLATE LANG.  In some versions of UNIX, the non-English locales
+are known to cause programs to exhibit mysterious errors.
+
+If you have any of the above environment variables set, please try
+
+	setenv LC_ALL C
+
+(for C shell) or
+
+	LC_ALL=C;export LC_ALL
+
+for Bourne or Korn shell) from the command line and then retry
+make test.  If the tests then succeed, you may have a broken program that
+is confusing the testing.  Please run the troublesome test by hand as
+shown above and see whether you can locate the program.  Look for
+things like:  exec, `backquoted command`, system, open("|...") or
+open("...|").  All these mean that Perl is trying to run some
+external program.
+
+=item Out of memory
+
+On some systems, particularly those with smaller amounts of RAM, some
+of the tests in t/op/pat.t may fail with an "Out of memory" message.
+Specifically, in perl5.004_64, tests 74 and 78 have been reported to
+fail on some systems.  On my SparcStation IPC with 8 MB of RAM, test 78
+will fail if the system is running any other significant tasks at the
+same time.
+
+Try stopping other jobs on the system and then running the test by itself:
+
+	cd t; ./perl op/pat.t
+
+to see if you have any better luck.  If your perl still fails this
+test, it does not necessarily mean you have a broken perl.  This test
+tries to exercise the regular expression subsystem quite thoroughly,
+and may well be far more demanding than your normal usage.
+
+=back
+
+=head1 make install
+
+This will put perl into the public directory you specified to
+Configure; by default this is /usr/local/bin.  It will also try
+to put the man pages in a reasonable place.  It will not nroff the man
+pages, however.  You may need to be root to run B<make install>.  If you
+are not root, you must own the directories in question and you should
+ignore any messages about chown not working.
+
+=head2 Installing perl under different names
+
+If you want to install perl under a name other than "perl" (for example,
+when installing perl with special features enabled, such as debugging),
+indicate the alternate name on the "make install" line, such as:
+
+    make install PERLNAME=myperl
+
+=head2 Installed files
+
+If you want to see exactly what will happen without installing
+anything, you can run
+
+	./perl installperl -n
+	./perl installman -n
+
+make install will install the following:
+
+	perl,
+	    perl5.nnn	where nnn is the current release number.  This
+			will be a link to perl.
+	suidperl,
+	    sperl5.nnn	If you requested setuid emulation.
+	a2p          	awk-to-perl translator
+	cppstdin	This is used by perl -P, if your cc -E can't
+			read from stdin.
+	c2ph, pstruct	Scripts for handling C structures in header files.
+	s2p		sed-to-perl translator
+	find2perl	find-to-perl translator
+	h2ph		Extract constants and simple macros from C headers
+	h2xs		Converts C .h header files to Perl extensions.
+	perlbug		Tool to report bugs in Perl.
+	perldoc		Tool to read perl's pod documentation.
+	pl2pm		Convert Perl 4 .pl files to Perl 5 .pm modules
+	pod2html,	Converters from perl's pod documentation format
+	pod2latex, 	to other useful formats.
+	pod2man, and
+	pod2text
+	splain		Describe Perl warnings and errors
+
+	library files	in $privlib and $archlib specified to
+			Configure, usually under /usr/local/lib/perl5/.
+	man pages	in the location specified to Configure, usually
+			something like /usr/local/man/man1.
+	module		in the location specified to Configure, usually
+	man pages	under /usr/local/lib/perl5/man/man3.
+	pod/*.pod	in $privlib/pod/.
+
+Installperl will also create the library directories $siteperl and
+$sitearch listed in config.sh.  Usually, these are something like
+
+	/usr/local/lib/perl5/site_perl/5.005
+	/usr/local/lib/perl5/site_perl/5.005/archname
+
+where archname is something like sun4-sunos.  These directories
+will be used for installing extensions.
+
+Perl's *.h header files and the libperl.a library are also installed
+under $archlib so that any user may later build new extensions, run the
+optional Perl compiler, or embed the perl interpreter into another
+program even if the Perl source is no longer available.
+
+=head1 Coexistence with earlier versions of perl5
+
+WARNING:  The upgrade from 5.004_0x to 5.005 is going to be a bit
+tricky.  See L<"Upgrading from 5.004 to 5.005">  below.
+
+In general, you can usually safely upgrade from one version of Perl (e.g.
+5.004_04) to another similar version (e.g. 5.004_05) without re-compiling
+all of your add-on extensions.  You can also safely leave the old version
+around in case the new version causes you problems for some reason.
+For example, if you want to be sure that your script continues to run
+with 5.004_04, simply replace the '#!/usr/local/bin/perl' line at the
+top of the script with the particular version you want to run, e.g.
+#!/usr/local/bin/perl5.00404.
+
+Most extensions will probably not need to be recompiled to use
+with a newer version of perl.   Here is how it is supposed to work.
+(These examples assume you accept all the Configure defaults.)
+
+The directories searched by version 5.005 will be
+
+    Configure variable		Default value
+	$archlib 	/usr/local/lib/perl5/5.005/archname
+	$privlib	/usr/local/lib/perl5/5.005
+	$sitearch	/usr/local/lib/perl5/site_perl/5.005/archname
+	$sitelib	/usr/local/lib/perl5/site_perl/5.005
+
+while the directories searched by version 5.005_01 will be
+
+	$archlib 	/usr/local/lib/perl5/5.00501/archname
+	$privlib	/usr/local/lib/perl5/5.00501
+	$sitearch	/usr/local/lib/perl5/site_perl/5.005/archname
+	$sitelib	/usr/local/lib/perl5/site_perl/5.005
+
+When you install an add-on extension, it gets installed into $sitelib (or
+$sitearch if it is architecture-specific).  This directory deliberately
+does NOT include the sub-version number (01) so that both 5.005 and
+5.005_01 can use the extension.  Only when a perl version changes to
+break backwards compatibility will the default suggestions for the
+$sitearch and $sitelib version numbers be increased.
+
+However, if you do run into problems, and you want to continue to use the
+old version of perl along with your extension, move those extension files
+to the appropriate version directory, such as $privlib (or $archlib).
+(The extension's .packlist file lists the files installed with that
+extension.  For the Tk extension, for example, the list of files installed
+is in $sitearch/auto/Tk/.packlist.)  Then use your newer version of perl
+to rebuild and re-install the extension into $sitelib.  This way, Perl
+5.005 will find your files in the 5.005 directory, and newer versions
+of perl will find your newer extension in the $sitelib directory.
+(This is also why perl searches the site-specific libraries last.)
+
+Alternatively, if you are willing to reinstall all your extensions
+every time you upgrade perl, then you can include the subversion
+number in $sitearch and $sitelib when you run Configure.
+
+=head2 Maintaining completely separate versions
+
+Many users prefer to keep all versions of perl in completely
+separate directories.  One convenient way to do this is by
+using a separate prefix for each version, such as
+
+	sh Configure -Dprefix=/opt/perl5.004
+
+and adding /opt/perl5.004/bin to the shell PATH variable.  Such users
+may also wish to add a symbolic link /usr/local/bin/perl so that
+scripts can still start with #!/usr/local/bin/perl.
+
+Others might share a common directory for maintenance sub-versions
+(e.g. 5.004 for all 5.004_0x versions), but change directory with
+each major version.
+
+If you are installing a development subversion, you probably ought to
+seriously consider using a separate directory, since development
+subversions may not have all the compatibility wrinkles ironed out
+yet.
+
+=head2 Upgrading from 5.004 to 5.005
+
+Extensions built and installed with versions of perl prior to 5.004_50
+will need to be recompiled to be used with 5.004_50 and later.  You will,
+however, be able to continue using 5.004 even after you install 5.005.
+The 5.004 binary will still be able to find the extensions built under
+5.004; the 5.005 binary will look in the new $sitearch and $sitelib
+directories, and will not find them.
+
+=head1 Coexistence with perl4
+
+You can safely install perl5 even if you want to keep perl4 around.
+
+By default, the perl5 libraries go into /usr/local/lib/perl5/, so
+they don't override the perl4 libraries in /usr/local/lib/perl/.
+
+In your /usr/local/bin directory, you should have a binary named
+perl4.036.  That will not be touched by the perl5 installation
+process.  Most perl4 scripts should run just fine under perl5.
+However, if you have any scripts that require perl4, you can replace
+the #! line at the top of them by #!/usr/local/bin/perl4.036
+(or whatever the appropriate pathname is).  See pod/perltrap.pod
+for possible problems running perl4 scripts under perl5.
+
+=head1 cd /usr/include; h2ph *.h sys/*.h
+
+Some perl scripts need to be able to obtain information from
+the system header files.  This command will convert the most commonly used
+header files in /usr/include into files that can be easily interpreted
+by perl.  These files will be placed in the architecture-dependent library
+($archlib) directory you specified to Configure.
+
+Note:  Due to differences in the C and perl languages, the
+conversion of the header files is not perfect.  You will probably have
+to hand-edit some of the converted files to get them to parse
+correctly.  For example, h2ph breaks spectacularly on type casting and
+certain structures.
+
+=head1 installhtml --help
+
+Some sites may wish to make perl documentation available in HTML
+format.  The installhtml utility can be used to convert pod
+documentation into linked HTML files and install them.
+
+The following command-line is an example of one used to convert
+perl documentation:
+
+  ./installhtml                   \
+      --podroot=.                 \
+      --podpath=lib:ext:pod:vms   \
+      --recurse                   \
+      --htmldir=/perl/nmanual     \
+      --htmlroot=/perl/nmanual    \
+      --splithead=pod/perlipc     \
+      --splititem=pod/perlfunc    \
+      --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
+      --verbose
+
+See the documentation in installhtml for more details.  It can take
+many minutes to execute a large installation and you should expect to
+see warnings like "no title", "unexpected directive" and "cannot
+resolve" as the files are processed. We are aware of these problems
+(and would welcome patches for them).
+
+You may find it helpful to run installhtml twice. That should reduce
+the number of "cannot resolve" warnings.
+
+=head1 cd pod && make tex && (process the latex files)
+
+Some sites may also wish to make the documentation in the pod/ directory
+available in TeX format.  Type
+
+	(cd pod && make tex && <process the latex files>)
+
+=head1 Reporting Problems
+
+If you have difficulty building perl, and none of the advice in this file
+helps, and careful reading of the error message and the relevant manual
+pages on your system doesn't help either, then you should send a message
+to either the comp.lang.perl.misc newsgroup or to perlbug@perl.com with
+an accurate description of your problem.
+
+Please include the output of the ./myconfig shell script that comes with
+the distribution.  Alternatively, you can use the perlbug program that
+comes with the perl distribution, but you need to have perl compiled
+before you can use it.  (If you have not installed it yet, you need to
+run C<./perl -Ilib utils/perlbug> instead of a plain C<perlbug>.)
+
+You might also find helpful information in the Porting directory of the
+perl distribution.
+
+=head1 DOCUMENTATION
+
+Read the manual entries before running perl.  The main documentation
+is in the pod/ subdirectory and should have been installed during the
+build process.  Type B<man perl> to get started.  Alternatively, you
+can type B<perldoc perl> to use the supplied perldoc script.  This is
+sometimes useful for finding things in the library modules.
+
+Under UNIX, you can produce a documentation book in postscript form,
+along with its table of contents, by going to the pod/ subdirectory and
+running (either):
+
+	./roffitall -groff		# If you have GNU groff installed
+	./roffitall -psroff		# If you have psroff
+
+This will leave you with two postscript files ready to be printed.
+(You may need to fix the roffitall command to use your local troff
+set-up.)
+
+Note that you must have performed the installation already before running
+the above, since the script collects the installed files to generate
+the documentation.
+
+=head1 AUTHOR
+
+Original author:  Andy Dougherty doughera@lafayette.edu , borrowing very
+heavily from the original README by Larry Wall, with lots of helpful
+feedback and additions from the perl5-porters@perl.org folks.
+
+If you have problems, corrections, or questions, please see
+L<"Reporting Problems"> above.
+
+=head1 REDISTRIBUTION
+
+This document is part of the Perl package and may be distributed under
+the same terms as perl itself.
+
+If you are distributing a modified version of perl (perhaps as part of
+a larger package) please do modify these installation instructions and
+the contact information to match your distribution.
+
+=head1 LAST MODIFIED
+
+$Id: INSTALL,v 1.42 1998/07/15 18:04:44 doughera Released $