source: trunk/essentials/dev-lang/perl/INSTALL@ 3188

If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.

=head1 NAME

Install - Build and Installation guide for perl5.

=head1 Reporting Problems

Wherever possible please use the perlbug tool supplied with this Perl
to report problems, as it automatically includes summary configuration
information about your perl, which may help us track down problems far
more quickly. But first you should read the advice in this file,
carefully re-read the error message and check the relevant manual pages
on your system, as these may help you find an immediate solution.  If
you are not sure whether what you are seeing is a bug, you can send a
message describing the problem to the comp.lang.perl.misc newsgroup to
get advice.

The perlbug tool is installed along with perl, so after you have
completed C<make install> it should be possible to run it with plain
C<perlbug>.  If the install fails, or you want to report problems with
C<make test> without installing perl, then you can use C<make nok> to
run perlbug to report the problem, or run it by hand from this source
directory with C<./perl -Ilib utils/perlbug>

If the build fails too early to run perlbug uninstalled, then please
B<run> the C<./myconfig> shell script, and mail its output along with
an accurate description of your problem to [email protected]

If Configure itself fails, and does not generate a config.sh file
(needed to run C<./myconfig>), then please mail [email protected] the
description of how Configure fails along with details of your system
- for example the output from running C<uname -a>

Please try to make your message brief but clear.  Brief, clear bug
reports tend to get answered more quickly.  Please don't worry if your
written English is not great - what matters is how well you describe
the important technical details of the problem you have encountered,
not whether your grammar and spelling is flawless.

Trim out unnecessary information.  Do not include large files (such as
config.sh or a complete Configure or make log) unless absolutely
necessary.  Do not include a complete transcript of your build
session.  Just include the failing commands, the relevant error
messages, and whatever preceding commands are necessary to give the
appropriate context.  Plain text should usually be sufficient--fancy
attachments or encodings may actually reduce the number of people who
read your message.  Your message will get relayed to over 400
subscribers around the world so please try to keep it brief but clear.

If you are unsure what makes a good bug report please read "How to
report Bugs Effectively" by Simon Tatham:
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

=head1 SYNOPSIS

First, make sure you have an up-to-date version of Perl.   If you
didn't get your Perl source from CPAN, check the latest version at
http://www.cpan.org/src/.  Perl uses a version scheme where even-numbered
subreleases (like 5.6.x and 5.8.x) are stable maintenance releases and
odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
development releases.  Development releases should not be used in
production environments.  Fixes and new features are first carefully
tested in development releases and only if they prove themselves to be
worthy will they be migrated to the maintenance releases.

The basic steps to build and install perl5 on a Unix system with all
the defaults are:

        rm -f config.sh Policy.sh
        sh Configure -de
        make
        make test
        make install

Each of these is explained in further detail below.

The above commands will install Perl to /usr/local (or some other
platform-specific directory -- see the appropriate file in hints/.)
If that's not okay with you, can run Configure interactively and use

        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>)

or you can use some of the Configure options described below.

If you have problems, corrections, or questions, please see
L<"Reporting Problems"> above.

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
    F<file>     A filename

Although most of the defaults are probably fine for most users,
you should probably at least skim through this document before
proceeding.

In addition to this file, check if there is a README file specific to
your operating system, since it 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 even more information.  (Unixware users should use the svr4.sh or
the svr5.sh hint file.)

For additional information about porting Perl, see the section on
L<"Porting information"> below, and look at the files in the Porting/
directory.

=head1 PRELIMINARIES

=head2 Changes and Incompatibilities

Please see pod/perldelta.pod for a description of the changes and
potential incompatibilities introduced with this release.  A few of
the most important issues are listed below, but you should refer
to pod/perldelta.pod for more detailed information.

=head3 WARNING:  This version is not binary compatible with releases of
Perl prior to 5.8.0.

If you have built extensions (i.e. modules that include C code)
using an earlier version of Perl, you will need to rebuild and reinstall
those extensions.

Pure perl modules without XS or C code should continue to work fine
without reinstallation.  See the discussions below on
L<"Coexistence with earlier versions of perl5"> and
L<"Upgrading from 5.005 or 5.6 to 5.8.0"> for more details.

The standard extensions supplied with Perl will be handled automatically.

On a related issue, old modules 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.  See your
installed copy of the perllocal.pod file for a (possibly incomplete)
list of locally installed modules.  Also see CPAN::autobundle for one
way to make a "bundle" of your currently installed modules.

=head2 Space Requirements

The complete perl5 source tree takes up about 60 MB of disk space.
After completing make, it takes up roughly 100 MB, though the actual
total is likely to be quite system-dependent.  The installation
directories need something on the order of 45 MB, though again that
value is system-dependent.  A perl build with debug symbols and
-DDEBUGGING will require something on the order of 10 MB extra.

=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

        rm -f config.sh

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.  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.  For example, some
Linux distributions use i386, while others may use i486.  If you build
it yourself, Configure uses the output of the arch command, which
might be i586 or i686 instead.  If you pick up a precompiled binary, or
compile extensions on different systems, they might not all agree on
the architecture 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 Policy.sh file.  See the section on L<"Site-wide Policy
settings"> below.  If you wish to start with a fresh distribution, you
also need to remove any old Policy.sh files you may have with

        rm -f Policy.sh

=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.  It is normal for some things to be "NOT found",
since Configure often searches for many different ways of performing
the same function.

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.

=head2 Common Configure options

Configure supports a number of useful options.  Run

        Configure -h

to get a listing.  See the Porting/Glossary file for a complete list of
Configure variables you can set and their definitions.

=over 4

=item gcc

To compile with gcc 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.

=item Installation prefix

By default, for most systems, perl will be installed in
/usr/local/{bin, lib, man}.  (See L<"Installation Directories">
and L<"Coexistence with earlier versions of perl5"> below for
further details.)

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 suggested
directory structure is simplified.  For example, if you use
prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
/opt/perl/lib/perl5/.  Again, see L<"Installation Directories"> below
for more details.  Do not include a trailing slash, (i.e. /opt/perl/)
or you may experience odd test failures.

NOTE:  You must not specify an installation directory that is the same
as or below your perl source directory.  If you do, installperl will
attempt infinite recursion.

=item /usr/bin/perl

It may seem obvious, 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, not to overwrite a version of perl supplied by your
vendor unless you are sure you know what you are doing.  If you insist
on replacing your vendor's perl, useful information on how it was
configured may be found with

        perl -V:config_args

(Check the output carefully, however, since this doesn't preserve
spaces in arguments to Configure.  For that, you have to look carefully
at config_arg1, config_arg2, etc.)

By default, Configure will not try to link /usr/bin/perl to the current
version of perl.  You can turn on that behavior by running

        Configure -Dinstallusrbinperl

or by answering 'yes' to the appropriate Configure prompt.

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.

=item Building a development release.

For development releases (odd subreleases, like 5.9.x) if you want to
use Configure -d, you will also need to supply -Dusedevel to Configure,
because the default answer to the question "do you really want to
Configure a development version?" is "no".  The -Dusedevel skips that
sanity check.

=back

If you are willing to accept all the defaults, and you want terse
output, you can run

        sh Configure -des

For example for my Solaris/x86 system, I usually use

        sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des

=head2 Altering config.sh variables for C compiler switches etc.

For most users, most of the Configure defaults are fine, or can easily
be set on the Configure command line.  However, if Configure doesn't
have an option to do what you want, you can change Configure variables
after the platform hints have been run by using Configure's -A switch.
For example, here's how to add a couple of extra flags to C compiler
invocations:

        sh Configure -Accflags="-DPERL_Y2KWARN -DPERL_POLLUTE_MALLOC"

For more help on Configure switches, run

        sh Configure -h

=head2 Major Configure-time Build 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.

=head3 Threads

On some platforms, perl can be compiled with support for threads.  To
enable this, run

        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.

Perl has two different internal threads implementations.  The current
model (available internally since 5.6, and as a user-level module since
5.8) is called interpreter-based implementation (ithreads), with one
interpreter per thread, and explicit sharing of data.  The 5.005
version (5005threads) is considered obsolete, buggy, and unmaintained.

By default, Configure selects ithreads if -Dusethreads is specified.

However, if you insist, you can select the unsupported old 5005threads behavior

        sh Configure -Dusethreads -Duse5005threads

The 'threads' module is for use with the ithreads implementation.  The
'Thread' module offers an interface to either 5005threads or ithreads
(whichever has been configured).

When using threads, perl uses a dynamically-sized buffer for some of
the thread-safe library calls, such as those in the getpw*() family.
This buffer starts small, but it will keep growing until the result
fits.  To get a fixed upper limit, you should compile Perl with
PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want.  One
way to do this is to run Configure with
C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>

=head3 Large file support.

Since Perl 5.6.0, Perl has supported large files (files larger than
2 gigabytes), and in many common platforms like Linux or Solaris this
support is on by default.

This is both good and bad. It is good in that you can use large files,
seek(), stat(), and -s them.  It is bad in that if you are interfacing Perl
using some extension, the components you are connecting to must also
be large file aware: if Perl thinks files can be large but the other
parts of the software puzzle do not understand the concept, bad things
will happen.  One popular extension suffering from this ailment is the
Apache extension mod_perl.

There's also one known limitation with the current large files
implementation: unless you also have 64-bit integers (see the next
section), you cannot use the printf/sprintf non-decimal integer formats
like C<%x> to print filesizes.  You can use C<%d>, though.

=head3 64 bit support.

If your platform does not have run natively at 64 bits, but can
simulate them with compiler flags and/or C<long long> or C<int64_t>,
you can build a perl that uses 64 bits.

There are actually two modes of 64-bitness: the first one is achieved
using Configure -Duse64bitint and the second one using Configure
-Duse64bitall.  The difference is that the first one is minimal and
the second one maximal.  The first works in more places than the second.

The C<use64bitint> option does only as much as is required to get
64-bit integers into Perl (this may mean, for example, using "long
longs") while your memory may still be limited to 2 gigabytes (because
your pointers could still be 32-bit).  Note that the name C<64bitint>
does not imply that your C compiler will be using 64-bit C<int>s (it
might, but it doesn't have to).  The C<use64bitint> simply means that
you will be able to have 64 bit-wide scalar values.

The C<use64bitall> option goes all the way by attempting to switch
integers (if it can), longs (and pointers) to being 64-bit.  This may
create an even more binary incompatible Perl than -Duse64bitint: the
resulting executable may not run at all in a 32-bit box, or you may
have to reboot/reconfigure/rebuild your operating system to be 64-bit
aware.

Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint
nor -Duse64bitall.

    NOTE: 64-bit support is still experimental on most platforms.
    Existing support only covers the LP64 data model.  In particular, the
    LLP64 data model is not yet supported.  64-bit libraries and system
    APIs on many platforms have not stabilized--your mileage may vary.

=head3 Long doubles

In some systems you may be able to use long doubles to enhance the
range and precision of your double precision floating point numbers
(that is, Perl's numbers).  Use Configure -Duselongdouble to enable
this support (if it is available).

=head3 "more bits"

You can "Configure -Dusemorebits" to turn on both the 64-bit support
and the long double support.

=head3 Selecting File IO mechanisms

Executive summary: as of Perl 5.8, you should use the default "PerlIO"
as the IO mechanism unless you have a good reason not to.

In more detail: previous versions of perl used the standard IO
mechanisms as defined in stdio.h.  Versions 5.003_02 and later of perl
introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
until and including Perl 5.6, the stdio mechanism was still the default
and the only supported mechanism.

Starting from Perl 5.8, the default mechanism is to use the PerlIO
abstraction, because it allows better control of I/O mechanisms,
instead of having to work with (often, work around) vendors' I/O
implementations.

This PerlIO abstraction can be (but again, unless you know what you
are doing, should not be) disabled either on the Configure command
line with

        sh Configure -Uuseperlio

or interactively at the appropriate Configure prompt.

With the PerlIO abstraction layer, there is another possibility for
the underlying IO calls, AT&T's "sfio".  This has superior performance
to stdio.h in many cases, and is extensible by the use of "discipline"
modules ("Native" PerlIO has them too).  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.
The latest sfio is available from http://www.research.att.com/sw/tools/sfio/

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.
Configure should detect this problem and warn you about problems with
_exit vs. exit.  If you have this problem, the fix is to go back to
your sfio sources and correct iffe's guess about atexit.

=head3 Algorithmic Complexity Attacks on Hashes

In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
Processing such hashes would consume large amounts of CPU time,
enabling a "Denial of Service" attack against Perl.  Such hashes may be
a problem for example for mod_perl sites, sites with Perl CGI scripts
and web services, that process data originating from external sources.

In Perl 5.8.1 a security feature was introduced to make it harder to
create such degenerate hashes. A visible side effect of this was that
the keys(), values(), and each() functions may return the hash elements
in different order between different runs of Perl even with the same
data.  It also had unintended binary incompatibility issues with
certain modules compiled against Perl 5.8.0.

In Perl 5.8.2 an improved scheme was introduced.  Hashes will return
elements in the same order as Perl 5.8.0 by default.  On a hash by hash
basis, if pathological data is detected during a hash key insertion,
then that hash will switch to an alternative random hash seed.  As
adding keys can always dramatically change returned hash element order,
existing programs will not be affected by this, unless they
specifically test for pre-recorded hash return order for contrived
data. (eg the list of keys generated by C<map {"\0"x$_} 0..15> trigger
randomisation) In effect the new implementation means that 5.8.1 scheme
is only being used on hashes which are under attack.

One can still revert to the old guaranteed repeatable order (and be
vulnerable to attack by wily crackers) by setting the environment
variable PERL_HASH_SEED, see L<perlrun/PERL_HASH_SEED>.  Another option
is to add -DUSE_HASH_SEED_EXPLICIT to the compilation flags (for
example by using C<Configure -Accflags=-DUSE_HASH_SEED_EXPLICIT>), in
which case one has to explicitly set the PERL_HASH_SEED environment
variable to enable the security feature, or by adding -DNO_HASH_SEED to
the compilation flags to completely disable the randomisation feature.

B<Perl has never guaranteed any ordering of the hash keys>, and the
ordering has already changed several times during the lifetime of Perl
5.  Also, the ordering of hash keys has always been, and continues to
be, affected by the insertion order.  It is likely that Perl 5.10 and
Perl 6 will randomise all hashes.  Note that because of this
randomisation for example the Data::Dumper results will be different
between different runs of Perl since Data::Dumper by default dumps
hashes "unordered".  The use of the Data::Dumper C<Sortkeys> option is
recommended.

=head3 SOCKS

Perl can be configured to be 'socksified', that is, to use the SOCKS
TCP/IP proxy protocol library.  SOCKS is used to give applications
access to transport layer network proxies.  Perl supports only SOCKS
Version 5.  You can find more about SOCKS from http://www.socks.nec.com/

=head3 Dynamic Loading

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.

=head3 Building a shared 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.6.2 (for Perl 5.6.2), or libperl.so.602, 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 build a shared libperl, the environment variable controlling shared
library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
the Perl build directory because that's where the shared libperl will
be created.  Configure arranges makefile to have the correct shared
library search settings.  You can find the name of the environment
variable Perl thinks works in your your system by

        grep ldlibpthname config.sh

However, there are some special cases where manually setting the
shared library path might be required.  For example, if you want to run
something like the following with the newly-built but not-yet-installed
./perl:

        cd t; ./perl misc/failing_test.t
or
        ./perl -Ilib ~/my_mission_critical_test

then you need to set up the shared library path explicitly.
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.  (This procedure may also be needed if for some
unexpected reason Configure fails to set up makefile correctly.) (And
again, it may be something other than LD_LIBRARY_PATH for you, see above.)

You can often recognize failures to build/use a shared libperl from error
messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
for example:
18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so

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.8.0 with a shared library.  Then, suppose you
try to build Perl 5.8.0 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.8 rather with the installed libperl.so.8?  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 only override at runtime via
LD_PRELOAD, specifying the exact filename you wish to be used; and on
Digital Unix, you can override LD_LIBRARY_PATH by setting the
_RLD_ROOT environment variable to point to the perl build directory.

In other words, it is generally not a good idea to try to build a perl
with a shared library if $archlib/CORE/$libperl already exists from a
previous build.

A good workaround is to 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 to
point to your new architecture-dependent library.

=head3 Environment access

Perl often needs to write to the program's environment, such as when C<%ENV>
is assigned to. Many implementations of the C library function C<putenv()>
leak memory, so where possible perl will manipulate the environment directly
to avoid these leaks. The default is now to perform direct manipulation
whenever perl is running as a stand alone interpreter, and to call the safe
but potentially leaky C<putenv()> function when the perl interpreter is
embedded in another application. You can force perl to always use C<putenv()>
by compiling with -DPERL_USE_SAFE_PUTENV. You can force an embedded perl to
use direct manipulation by setting C<PL_use_safe_putenv = 0;> after the
C<perl_construct()> call.

=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.
Do not include trailing slashes on directory names.

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.  Alternatively, you can

        grep '^install' config.sh

after Configure has run to verify the installation paths.

The defaults are intended to be reasonable and sensible for most
people building from sources.  Those who build and distribute binary
distributions or who export perl to a range of systems will probably
need to alter them.  If you are content to just accept the defaults,
you can safely skip the next section.

The directories set up by Configure fall into three broad categories.

=over 4

=item Directories for the perl distribution

By default, Configure will use the following directories for 5.8.x.
$version is the full perl version number, including subversion, e.g.
5.8.3 or 5.8.4, and $archname is a string like sun4-sunos,
determined by Configure.  The full definitions of all Configure
variables are in the file Porting/Glossary.

    Configure variable  Default value
    $prefixexp          /usr/local
    $binexp             $prefixexp/bin
    $scriptdirexp       $prefixexp/bin
    $privlibexp         $prefixexp/lib/perl5/$version
    $archlibexp         $prefixexp/lib/perl5/$version/$archname
    $man1direxp         $prefixexp/man/man1
    $man3direxp         $prefixexp/man/man3
    $html1direxp        (none)
    $html3direxp        (none)

$prefixexp is generated from $prefix, with ~ expansion done to convert home
directories into absolute paths. Similarly for the other variables listed. As
file system calls do not do this, you should always reference the ...exp
variables, to support users who build perl in their home directory.

Actually, Configure recognizes the SVR3-style
/usr/local/man/l_man/man1 directories, if present, and uses those
instead.  Also, if $prefix contains the string "perl", the library
directories are simplified as described below.  For simplicity, only
the common style is shown here.

=item Directories for site-specific add-on files

After perl is installed, you may later wish to add modules (e.g. from
CPAN) or scripts.  Configure will set up the following directories to
be used for installing those add-on modules and scripts.

    Configure variable  Default value
    $siteprefixexp      $prefixexp
    $sitebinexp         $siteprefixexp/bin
    $sitescriptexp      $siteprefixexp/bin
    $sitelibexp         $siteprefixexp/lib/perl5/site_perl/$version
    $sitearchexp        $siteprefixexp/lib/perl5/site_perl/$version/$archname
    $siteman1direxp     $siteprefixexp/man/man1
    $siteman3direxp     $siteprefixexp/man/man3
    $sitehtml1direxp    (none)
    $sitehtml3direxp    (none)

By default, ExtUtils::MakeMaker will install architecture-independent
modules into $sitelib and architecture-dependent modules into $sitearch.

=item Directories for vendor-supplied add-on files

Lastly, if you are building a binary distribution of perl for
distribution, Configure can optionally set up the following directories
for you to use to distribute add-on modules.

    Configure variable  Default value
    $vendorprefixexp    (none)
    (The next ones are set only if vendorprefix is set.)
    $vendorbinexp       $vendorprefixexp/bin
    $vendorscriptexp    $vendorprefixexp/bin
    $vendorlibexp
        $vendorprefixexp/lib/perl5/vendor_perl/$version
    $vendorarchexp
        $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
    $vendorman1direxp   $vendorprefixexp/man/man1
    $vendorman3direxp   $vendorprefixexp/man/man3
    $vendorhtml1direxp  (none)
    $vendorhtml3direxp  (none)

These are normally empty, but may be set as needed.  For example,
a vendor might choose the following settings:

    $prefix             /usr
    $siteprefix         /usr/local
    $vendorprefix       /usr

This would have the effect of setting the following:

    $binexp             /usr/bin
    $scriptdirexp       /usr/bin
    $privlibexp         /usr/lib/perl5/$version
    $archlibexp         /usr/lib/perl5/$version/$archname
    $man1direxp         /usr/man/man1
    $man3direxp         /usr/man/man3

    $sitebinexp         /usr/local/bin
    $sitescriptexp      /usr/local/bin
    $sitelibexp         /usr/local/lib/perl5/site_perl/$version
    $sitearchexp        /usr/local/lib/perl5/site_perl/$version/$archname
    $siteman1direxp     /usr/local/man/man1
    $siteman3direxp     /usr/local/man/man3

    $vendorbinexp       /usr/bin
    $vendorscriptexp    /usr/bin
    $vendorlibexp       /usr/lib/perl5/vendor_perl/$version
    $vendorarchexp      /usr/lib/perl5/vendor_perl/$version/$archname
    $vendorman1direxp   /usr/man/man1
    $vendorman3direxp   /usr/man/man3

Note how in this example, the vendor-supplied directories are in the
/usr hierarchy, while the directories reserved for the end-user are in
the /usr/local hierarchy.

The entire installed library hierarchy is installed in locations with
version numbers, keeping the installations of different versions distinct.
However, later installations of Perl can still be configured to search the
installed libraries corresponding to compatible earlier versions.
See L<"Coexistence with earlier versions of perl5"> below for more details
on how Perl can be made to search older version directories.