2168 lines
83 KiB
Plaintext
2168 lines
83 KiB
Plaintext
=head1 NAME
|
|
|
|
Install - Build and Installation guide for perl5.
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
First, make sure you are installing an up-to-date version of Perl. If
|
|
you didn't get your Perl source from CPAN, check the latest version at
|
|
<URL:http://www.cpan.org/src/>.
|
|
|
|
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
|
|
|
|
# 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.
|
|
|
|
B<NOTE>: starting from the release 5.6.0 Perl will use a version
|
|
scheme where even-numbered subreleases (like 5.6) are stable
|
|
maintenance releases and odd-numbered subreleases (like 5.7) 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 above commands will install Perl to /usr/local or /opt, depending
|
|
on the platform. If that's not okay with you, use
|
|
|
|
rm -f config.sh Policy.sh
|
|
sh Configure
|
|
make
|
|
make test
|
|
make install
|
|
|
|
For information on non-Unix systems, see the section on
|
|
L<"Porting information"> below.
|
|
|
|
If you have problems, corrections, or questions, please see
|
|
L<"Reporting Problems"> 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
|
|
|
|
Although most of the defaults are probably fine for most users,
|
|
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.) If
|
|
there is a README file for your platform, then you should read
|
|
that too. Additional information is in the Porting/ directory.
|
|
|
|
=head1 WARNING: This version requires an extra step to build old extensions.
|
|
|
|
5.005_53 and later releases do not export unadorned
|
|
global symbols anymore. This means you may need to build older
|
|
extensions that have not been updated for the new naming convention
|
|
with:
|
|
|
|
perl Makefile.PL POLLUTE=1
|
|
|
|
Alternatively, you can enable CPP symbol pollution wholesale by
|
|
building perl itself with:
|
|
|
|
sh Configure -Accflags=-DPERL_POLLUTE
|
|
|
|
pod/perldelta.pod contains more details about this.
|
|
|
|
=head1 WARNING: This version may not be binary compatible with Perl 5.005.
|
|
|
|
Using the default Configure options for building perl should get you
|
|
a perl that will be binary compatible with the 5.005 release.
|
|
|
|
However, if you run Configure with any custom options, such as
|
|
-Dusethreads, -Dusemultiplicity, -Dusemymalloc, -Ubincompat5005 etc.,
|
|
the resulting perl will not be binary compatible. Under these
|
|
circumstances, if you have dynamically loaded extensions that were
|
|
built under perl 5.005, you will need to rebuild and reinstall all
|
|
those extensions to use them with 5.6.
|
|
|
|
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 to 5.6"> 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 (and pod/perl500Xdelta.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.
|
|
|
|
=head1 WARNING: This version requires a compiler that supports ANSI C.
|
|
|
|
Most C compilers are now ANSI-compliant. However, a few current
|
|
computers are delivered with an older C compiler expressly for
|
|
rebuilding the system kernel, or for some other historical reason.
|
|
Alternatively, you may have an old machine which was shipped before
|
|
ANSI compliance became widespread. Such compilers are not suitable
|
|
for building Perl.
|
|
|
|
If you find that your default C compiler is not ANSI-capable, but you
|
|
know that an ANSI-capable compiler is installed on your system, you
|
|
can tell F<Configure> to use the correct compiler by means of the
|
|
C<-Dcc=> command-line option -- see L<"gcc">.
|
|
|
|
If do not have an ANSI-capable compiler there are several avenues open
|
|
to you:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
You may try obtaining GCC, available from GNU mirrors worldwide,
|
|
listed at <URL:http://www.gnu.org/order/ftp.html>. If, rather than
|
|
building gcc from source code, you locate a binary version configured
|
|
for your platform, be sure that it is compiled for the version of the
|
|
operating system that you are using.
|
|
|
|
=item *
|
|
|
|
You may purchase a commercial ANSI C compiler from your system
|
|
supplier or elsewhere. (Or your organization may already have
|
|
licensed such software -- ask your colleagues to find out how to
|
|
access it.) If there is a README file for your system in the Perl
|
|
distribution (for example, F<README.hpux>), it may contain advice on
|
|
suitable compilers.
|
|
|
|
=item *
|
|
|
|
Another alternative may be to use a tool like ansi2knr to convert the
|
|
sources back to K&R style, but there is no guarantee this route will get
|
|
you anywhere, since the prototypes are not the only ANSI features used
|
|
in the Perl sources. ansi2knr is usually found as part of the freely
|
|
available Ghostscript distribution. Another similar tool is
|
|
unprotoize, distributed with GCC. Since unprotoize requires GCC to
|
|
run, you may have to run it on a platform where GCC is available, and move
|
|
the sources back to the platform without GCC.
|
|
|
|
If you succeed in automatically converting the sources to a K&R compatible
|
|
form, be sure to email perlbug@perl.org to let us know the steps you
|
|
followed. This will enable us to officially support this option.
|
|
|
|
=back
|
|
|
|
Although Perl can be compiled using a C++ compiler, the Configure script
|
|
does not work with some C++ compilers.
|
|
|
|
=head1 Space Requirements
|
|
|
|
The complete perl5 source tree takes up about 20 MB of disk space.
|
|
After completing make, it takes up roughly 30 MB, though the actual
|
|
total is likely to be quite system-dependent. The installation
|
|
directories need something on the order of 20 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
|
|
|
|
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, 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. 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 Altering config.sh variables for C compiler switches etc.
|
|
|
|
For most users, all of the Configure defaults are fine. Configure
|
|
also has several convenient options which are all described below.
|
|
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 Building Perl outside of the source directory
|
|
|
|
Sometimes it is desirable to build Perl in a directory different from
|
|
where the sources are, for example if you want to keep your sources
|
|
read-only, or if you want to share the sources between different binary
|
|
architectures.
|
|
|
|
Starting from Perl 5.6.1 you can do this (if your file system supports
|
|
symbolic links) by
|
|
|
|
mkdir /tmp/perl/build/directory
|
|
cd /tmp/perl/build/directory
|
|
sh /path/to/perl/source/Configure -Dmksymlinks ...
|
|
|
|
This will create in /tmp/perl/build/directory a tree of symbolic links
|
|
pointing to files in /path/to/perl/source. The original files are left
|
|
unaffected. After Configure has finished you can just say
|
|
|
|
make all test
|
|
|
|
and Perl will be built and tested, all in /tmp/perl/build/directory.
|
|
|
|
=head2 Common Configure options
|
|
|
|
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.
|
|
|
|
=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.
|
|
|
|
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.
|
|
|
|
By default, Configure will arrange for /usr/bin/perl to be linked to
|
|
the current version of perl. You can turn off that behavior by running
|
|
|
|
Configure -Uinstallusrbinperl
|
|
|
|
or by answering 'no' 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 Overriding an old config.sh
|
|
|
|
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>.
|
|
|
|
=back
|
|
|
|
If you are willing to accept all the defaults, and you want terse
|
|
output, you can run
|
|
|
|
sh Configure -des
|
|
|
|
Note: for development releases (odd subreleases, like 5.7, as opposed
|
|
to maintenance releases which have even subreleases, like 5.6)
|
|
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.
|
|
|
|
For example 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 and compiling in a different directory are not supported.
|
|
|
|
(The file is called configure.gnu to avoid problems on systems
|
|
that would not distinguish the files "Configure" and "configure".)
|
|
|
|
=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.
|
|
Further, there are a number of additions to the installation
|
|
directories since 5.005, so reusing your old config.sh may not
|
|
be sufficient to put everything where you want it.
|
|
|
|
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.
|
|
|
|
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.6.0.
|
|
$version is the full perl version number, including subversion, e.g.
|
|
5.6.0 or 5.6.1, 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
|
|
$prefix /usr/local
|
|
$bin $prefix/bin
|
|
$scriptdir $prefix/bin
|
|
$privlib $prefix/lib/perl5/$version
|
|
$archlib $prefix/lib/perl5/$version/$archname
|
|
$man1dir $prefix/man/man1
|
|
$man3dir $prefix/man/man3
|
|
$html1dir (none)
|
|
$html3dir (none)
|
|
|
|
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
|
|
$siteprefix $prefix
|
|
$sitebin $siteprefix/bin
|
|
$sitescript $siteprefix/bin
|
|
$sitelib $siteprefix/lib/perl5/site_perl/$version
|
|
$sitearch $siteprefix/lib/perl5/site_perl/$version/$archname
|
|
$siteman1 $siteprefix/man/man1
|
|
$siteman3 $siteprefix/man/man3
|
|
$sitehtml1 (none)
|
|
$sitehtml3 (none)
|
|
|
|
By default, ExtUtils::MakeMaker will install architecture-independent
|
|
modules into $sitelib and architecture-dependent modules into $sitearch.
|
|
|
|
NOTE: As of 5.6.0, ExtUtils::MakeMaker will use $sitelib and $sitearch,
|
|
but will not use the other site-specific directories. Volunteers to
|
|
fix this are needed.
|
|
|
|
=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
|
|
$vendorprefix (none)
|
|
(The next ones are set only if vendorprefix is set.)
|
|
$vendorbin $vendorprefix/bin
|
|
$vendorscript $vendorprefix/bin
|
|
$vendorlib $vendorprefix/lib/perl5/vendor_perl/$version
|
|
$vendorarch $vendorprefix/lib/perl5/vendor_perl/$version/$archname
|
|
$vendorman1 $vendorprefix/man/man1
|
|
$vendorman3 $vendorprefix/man/man3
|
|
$vendorhtml1 (none)
|
|
$vendorhtml3 (none)
|
|
|
|
These are normally empty, but may be set as needed. For example,
|
|
a vendor might choose the following settings:
|
|
|
|
$prefix /usr/bin
|
|
$siteprefix /usr/local/bin
|
|
$vendorprefix /usr/bin
|
|
|
|
This would have the effect of setting the following:
|
|
|
|
$bin /usr/bin
|
|
$scriptdir /usr/bin
|
|
$privlib /usr/lib/perl5/$version
|
|
$archlib /usr/lib/perl5/$version/$archname
|
|
$man1dir /usr/man/man1
|
|
$man3dir /usr/man/man3
|
|
|
|
$sitebin /usr/local/bin
|
|
$sitescript /usr/local/bin
|
|
$sitelib /usr/local/lib/perl5/site_perl/$version
|
|
$sitearch /usr/local/lib/perl5/site_perl/$version/$archname
|
|
$siteman1 /usr/local/man/man1
|
|
$siteman3 /usr/local/man/man3
|
|
|
|
$vendorbin /usr/bin
|
|
$vendorscript /usr/bin
|
|
$vendorlib /usr/lib/perl5/vendor_perl/$version
|
|
$vendorarch /usr/lib/perl5/vendor_perl/$version/$archname
|
|
$vendorman1 /usr/man/man1
|
|
$vendorman3 /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.
|
|
|
|
NOTE: As of 5.6.0, ExtUtils::MakeMaker does not use these directories.
|
|
Volunteers to fix this are needed.
|
|
|
|
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.
|
|
|
|
Of course you may use these directories however you see fit. For
|
|
example, you may wish to use $siteprefix for site-specific files that
|
|
are stored locally on your own disk and use $vendorprefix for
|
|
site-specific files that are stored elsewhere on your organization's
|
|
network. One way to do that would be something like
|
|
|
|
sh Configure -Dsiteprefix=/usr/local -Dvendorprefix=/usr/share/perl
|
|
|
|
=item otherlibdirs
|
|
|
|
As a final catch-all, Configure also offers an $otherlibdirs
|
|
variable. This variable contains a colon-separated list of additional
|
|
directories to add to @INC. By default, it will be empty.
|
|
Perl will search these directories (including architecture and
|
|
version-specific subdirectories) for add-on modules and extensions.
|
|
|
|
=item APPLLIB_EXP
|
|
|
|
There is one other way of adding paths to @INC at perl build time, and
|
|
that is by setting the APPLLIB_EXP C pre-processor token to a colon-
|
|
separated list of directories, like this
|
|
|
|
sh Configure -Accflags='-DAPPLLIB_EXP=\"/usr/libperl\"'
|
|
|
|
The directories defined by APPLLIB_EXP get added to @INC I<first>,
|
|
ahead of any others, and so provide a way to override the standard perl
|
|
modules should you, for example, want to distribute fixes without
|
|
touching the perl distribution proper. And, like otherlib dirs,
|
|
version and architecture specific subdirectories are also searched, if
|
|
present, at run time. Of course, you can still search other @INC
|
|
directories ahead of those in APPLLIB_EXP by using any of the standard
|
|
run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
|
|
|
|
=item Man Pages
|
|
|
|
In versions 5.005_57 and earlier, the default was to store module man
|
|
pages in a version-specific directory, such as
|
|
/usr/local/lib/perl5/$version/man/man3. The default for 5.005_58 and
|
|
after is /usr/local/man/man3 so that most users can find the man pages
|
|
without resetting MANPATH.
|
|
|
|
You can continue to use the old default from the command line with
|
|
|
|
sh Configure -Dman3dir=/usr/local/lib/perl5/5.6.0/man/man3
|
|
|
|
Some users also prefer to use a .3pm suffix. You can do that with
|
|
|
|
sh Configure -Dman3ext=3pm
|
|
|
|
Again, these are just the defaults, and can be changed as you run
|
|
Configure.
|
|
|
|
=item HTML pages
|
|
|
|
As of perl5.005_57, the standard perl installation does not do
|
|
anything with HTML documentation, but that may change in the future.
|
|
Further, some add-on modules may wish to install HTML documents. The
|
|
html Configure variables listed above are provided if you wish to
|
|
specify where such documents should be placed. The default is "none",
|
|
but will likely eventually change to something useful based on user
|
|
feedback.
|
|
|
|
=back
|
|
|
|
Some users prefer to append a "/share" to $privlib and $sitelib
|
|
to emphasize that those directories can be shared among different
|
|
architectures.
|
|
|
|
Note that these are just the defaults. You can actually structure the
|
|
directories any way you like. They don't even have to be on the same
|
|
filesystem.
|
|
|
|
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.
|
|
|
|
If you specify a prefix that contains the string "perl", then the
|
|
library directory structure is slightly simplified. Instead of
|
|
suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
|
|
|
|
Thus, for example, if you Configure with
|
|
-Dprefix=/opt/perl, then the default library directories for 5.6.0 are
|
|
|
|
Configure variable Default value
|
|
$privlib /opt/perl/lib/5.6.0
|
|
$archlib /opt/perl/lib/5.6.0/$archname
|
|
$sitelib /opt/perl/lib/site_perl/5.6.0
|
|
$sitearch /opt/perl/lib/site_perl/5.6.0/$archname
|
|
|
|
=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, or users building binary packages for distribution 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 that.
|
|
|
|
Suppose you want to install perl under the /tmp/perl5 directory. You
|
|
could edit config.sh and change all the install* variables to point to
|
|
/tmp/perl5 instead of /usr/local, or you could simply use the
|
|
following command line:
|
|
|
|
sh Configure -Dinstallprefix=/tmp/perl5
|
|
|
|
(replace /tmp/perl5 by a directory of your choice).
|
|
|
|
Beware, though, that if you go to try to install new add-on
|
|
modules, 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. Suppose, for example, that you want to
|
|
create an archive that can be installed in /opt/perl.
|
|
Here's one way to do that:
|
|
|
|
# Set up to install perl into a different directory,
|
|
# e.g. /tmp/perl5 (see previous part).
|
|
sh Configure -Dinstallprefix=/tmp/perl5 -Dprefix=/opt/perl -des
|
|
make
|
|
make test
|
|
make install # This will install everything into /tmp/perl5.
|
|
cd /tmp/perl5
|
|
# Edit $archlib/Config.pm and $archlib/.packlist to change all the
|
|
# install* variables back to reflect where everything will
|
|
# really be installed. (That is, change /tmp/perl5 to /opt/perl
|
|
# everywhere in those files.)
|
|
# Check the scripts in $scriptdir to make sure they have the correct
|
|
# #!/wherever/perl line.
|
|
tar cvf ../perl5-archive.tar .
|
|
# Then, on each machine where you want to install perl,
|
|
cd /opt/perl # 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.
|
|
|
|
If the generated Policy.sh file is unsuitable, you may freely edit it
|
|
to contain any valid shell commands. It will be run just after the
|
|
platform-specific hints files.
|
|
|
|
Note: Since the directory hierarchy for 5.6.0 contains a number of
|
|
new vendor* and site* entries, your Policy.sh file will probably not
|
|
set them to your desired values. I encourage you to run Configure
|
|
interactively to be sure it puts things where you want them.
|
|
|
|
=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 and later can be compiled with
|
|
experimental support for 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.
|
|
|
|
As of v5.5.64, perl has two different internal threads implementations.
|
|
The 5.005 version (5005threads) and an interpreter-based implementation
|
|
(ithreads) with one interpreter per thread. By default, Configure selects
|
|
ithreads if -Dusethreads is specified. However, you can select the old
|
|
5005threads behavior instead by either
|
|
|
|
sh Configure -Dusethreads -Duse5005threads
|
|
|
|
or by
|
|
sh Configure -Dusethreads -Uuseithreads
|
|
|
|
Eventually (by perl v5.6.0) this internal confusion ought to disappear,
|
|
and these options may disappear as well.
|
|
|
|
=head2 64 bit support.
|
|
|
|
If your platform does not have 64 bits natively, 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> 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> means that you will be
|
|
able to have 64 bits wide scalar values.
|
|
|
|
The C<use64bitall> goes all the way by attempting to switch also
|
|
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.
|
|
|
|
=head2 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).
|
|
|
|
=head2 "more bits"
|
|
|
|
You can "Configure -Dusemorebits" to turn on both the 64-bit support
|
|
and the long double 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.
|
|
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.
|
|
|
|
=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 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/
|
|
|
|
=head2 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.
|
|
|
|
=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 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, 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.
|
|
|
|
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.)
|
|
|
|
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.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 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 has been optimized for the typical requests from
|
|
perl, so there's a chance that it may be both faster and use less memory
|
|
than your system malloc.
|
|
|
|
However, 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 should probably use your system's malloc.
|
|
(Or, you might wish to explore the malloc flags discussed below.)
|
|
|
|
=over 4
|
|
|
|
=item Using the system malloc
|
|
|
|
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.
|
|
|
|
=item -DPERL_POLLUTE_MALLOC
|
|
|
|
NOTE: This flag is enabled automatically on some platforms if you
|
|
asked for binary compatibility with version 5.005, or if you just
|
|
run Configure to accept all the defaults on those platforms. You
|
|
can refuse the automatic binary compatibility flags wholesale by
|
|
running:
|
|
|
|
sh Configure -Ubincompat5005
|
|
|
|
or by answering 'n' at the appropriate prompt.
|
|
|
|
Perl's malloc family of functions are called Perl_malloc(),
|
|
Perl_realloc(), Perl_calloc() and Perl_mfree(). When this flag is
|
|
not enabled, the names do not clash with the system versions of
|
|
these functions.
|
|
|
|
If enabled, Perl's malloc family of functions will have the same
|
|
names as the system versions. This may be sometimes required when you
|
|
have libraries that like to free() data that may have been allocated
|
|
by Perl_malloc() and vice versa.
|
|
|
|
Note that enabling this option may sometimes lead to duplicate symbols
|
|
from the linker for malloc et al. In such cases, the system probably
|
|
does not allow its malloc functions to be fully replaced with custom
|
|
versions.
|
|
|
|
=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 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.
|
|
|
|
If you unpack any additional extensions in the ext/ directory before
|
|
running Configure, then Configure will offer to build those additional
|
|
extensions as well. Most users probably shouldn't have to do this --
|
|
it is usually easier to build additional extensions later after perl
|
|
has been installed. However, if you wish to have those additional
|
|
extensions statically linked into the perl binary, then this offers a
|
|
convenient way to do that in one step. (It is not necessary, however;
|
|
you can build and install extensions just fine even if you don't have
|
|
dynamic loading. See lib/ExtUtils/MakeMaker.pm for more details.)
|
|
|
|
You can learn more about each of the supplied 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 use5005threads
|
|
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 earlier
|
|
releases of 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.
|
|
|
|
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 example 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. This should also 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 -de \
|
|
-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 -de \
|
|
-Dlocincpth="/usr/you/include /usr/local/include" \
|
|
-Dloclibpth="/usr/you/lib /usr/local/lib"
|
|
|
|
=back
|
|
|
|
=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
|
|
|
|
Perl interface for DB3 is part of Berkeley DB, but if you want to
|
|
compile standard Perl DB/ODBM/NDBM interfaces, you must follow
|
|
following instructions.
|
|
|
|
Berkeley DB3 from Sleepycat Software is by default installed without
|
|
DB1 compatibility code (needed for DB_File interface) and without
|
|
links to compatibility files. So if you want to use packages written
|
|
for DB/ODBM/NDBM interfaces, you need to configure DB3 with
|
|
--enable-compat185 (and optionally with --enable-dump185) and create
|
|
additional references (suppose you are installing DB3 with
|
|
--prefix=/usr):
|
|
|
|
ln -s libdb-3.so /usr/lib/libdbm.so
|
|
ln -s libdb-3.so /usr/lib/libndbm.so
|
|
echo '#define DB_DBM_HSEARCH 1' >dbm.h
|
|
echo '#include <db.h>' >>dbm.h
|
|
install -m 0644 dbm.h /usr/include/dbm.h
|
|
install -m 0644 dbm.h /usr/include/ndbm.h
|
|
|
|
Optionally, if you have compiled with --enable-compat185 (not needed
|
|
for ODBM/NDBM):
|
|
|
|
ln -s libdb-3.so /usr/lib/libdb1.so
|
|
ln -s libdb-3.so /usr/lib/libdb.so
|
|
|
|
ODBM emulation seems not to be perfect, but is quite usable,
|
|
using DB 3.1.17:
|
|
|
|
lib/odbm.............FAILED at test 9
|
|
Failed 1/64 tests, 98.44% okay
|
|
|
|
=head2 What if it doesn't work?
|
|
|
|
If you run into problems, try some of the following ideas.
|
|
If none of them help, then see L<"Reporting Problems"> below.
|
|
|
|
=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.
|
|
|
|
=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.sh to config.sh and edit your config.sh to reflect your
|
|
system's peculiarities. See Porting/pumpkin.pod for more information.
|
|
You'll probably also have to extensively modify the extension building
|
|
mechanism.
|
|
|
|
=item Environment variable clashes
|
|
|
|
Configure uses a CONFIG variable that is reported to cause trouble on
|
|
ReliantUnix 5.44. If your system sets this variable, you can try
|
|
unsetting it before you run Configure. Configure should eventually
|
|
be fixed to avoid polluting the namespace of the environment.
|
|
|
|
=item Digital UNIX/Tru64 UNIX and BIN_SH
|
|
|
|
In Digital UNIX/Tru64 UNIX, Configure might abort with
|
|
|
|
Build a threading Perl? [n]
|
|
Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
|
|
|
|
This indicates that Configure is being run with a broken Korn shell
|
|
(even though you think you are using a Bourne shell by using
|
|
"sh Configure" or "./Configure"). The Korn shell bug has been reported
|
|
to Compaq as of February 1999 but in the meanwhile, the reason ksh is
|
|
being used is that you have the environment variable BIN_SH set to
|
|
'xpg4'. This causes /bin/sh to delegate its duties to /bin/posix/sh
|
|
(a ksh). Unset the environment variable and rerun Configure.
|
|
|
|
=item HP-UX 11, pthreads, and libgdbm
|
|
|
|
If you are running Configure with -Dusethreads in HP-UX 11, be warned
|
|
that POSIX threads and libgdbm (the GNU dbm library) compiled before
|
|
HP-UX 11 do not mix. This will cause a basic test run by Configure to
|
|
fail
|
|
|
|
Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
|
|
Return Pointer is 0xc082bf33
|
|
sh: 5345 Quit(coredump)
|
|
|
|
and Configure will give up. The cure is to recompile and install
|
|
libgdbm under HP-UX 11.
|
|
|
|
=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. Especially Porting/Glossary should come in handy.
|
|
|
|
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.
|
|
|
|
If you plan to port Perl to a new architecture study carefully the
|
|
section titled "Philosophical Issues in Patching and Porting Perl"
|
|
in the file Porting/pumpkin.pod and the file Porting/patching.pod.
|
|
Study also how other non-UNIX ports have solved problems.
|
|
|
|
=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.
|
|
|
|
=head2 What if it doesn't work?
|
|
|
|
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,
|
|
then 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 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 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 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 #error "No DATAMODEL_NATIVE specified"
|
|
|
|
This is a common error when trying to build perl on Solaris 2.6 with a
|
|
gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files
|
|
changed, so you need to update your gcc installation. You can either
|
|
rerun the fixincludes script from gcc or take the opportunity to
|
|
update your gcc installation.
|
|
|
|
=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:
|
|
|
|
sh Configure -Accflags=-DCRIPPLED_CC
|
|
|
|
This flag simplifies some complicated expressions for compilers that get
|
|
indigestion easily. (Just because you get no errors doesn't mean it
|
|
compiled right!)
|
|
|
|
=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 GNU binutils
|
|
|
|
If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
|
|
tools you may be in for some trouble. For example creating archives
|
|
with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
|
|
may lead into linking problems. Either recompile your GNU binutils
|
|
under your current operating system release, or modify your PATH not
|
|
to include the GNU utils before running Configure, or specify the
|
|
vendor-supplied utilities explicitly to Configure, for example by
|
|
Configure -Dar=/bin/ar.
|
|
|
|
=item THIS PACKAGE SEEMS TO BE INCOMPLETE
|
|
|
|
The F<Configure> program has not been able to find all the files which
|
|
make up the complete Perl distribution. You may have a damaged source
|
|
archive file (in which case you may also have seen messages such as
|
|
C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
|
|
archive file>), or you may have obtained a structurally-sound but
|
|
incomplete archive. In either case, try downloading again from the
|
|
official site named at the start of this document. If you do find
|
|
that any site is carrying a corrupted or incomplete source code
|
|
archive, please report it to the site's maintainer.
|
|
|
|
=item invalid token: ##
|
|
|
|
You are using a non-ANSI-compliant C compiler. See L<WARNING: This
|
|
version requires a compiler that supports ANSI C>.
|
|
|
|
=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
|
|
|
|
HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
|
|
Patch Bundle" has been reported to break the io/fs test #18 which
|
|
tests whether utime() can change timestamps. The Y2K patch seems to
|
|
break utime() so that over NFS the timestamps do not get changed
|
|
(on local filesystems utime() still works).
|
|
|
|
=back
|
|
|
|
=head1 make test
|
|
|
|
This will run the regression tests on the perl you just made. 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.
|
|
For example, on my SparcStation IPC with 12 MB of RAM, in perl5.5.670,
|
|
test 85 will fail if run under either t/TEST or t/harness.
|
|
|
|
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.
|
|
|
|
=item Test failures from lib/ftmp-security saying "system possibly insecure"
|
|
|
|
Firstly, test failures from the ftmp-security are not necessarily
|
|
serious or indicative of a real security threat. That being said,
|
|
they bear investigating.
|
|
|
|
The tests may fail for the following reasons. Note that each of the
|
|
tests is run both in the building directory and the temporary
|
|
directory, as returned by File::Spec->tmpdir().
|
|
|
|
(1) If the directory the tests are being run is owned by somebody else
|
|
than the user running the tests, or root (uid 0). This failure can
|
|
happen if the Perl source code distribution is unpacked in a way that
|
|
the user ids in the distribution package are used as-is. Some tar
|
|
programs do this.
|
|
|
|
(2) If the directory the test are being run in is writable by group
|
|
or by other (remember: with UNIX/POSIX semantics, write access to
|
|
a directory means the right to add/remove files in that directory),
|
|
and there is no sticky bit set in the directory. 'Sticky bit' is
|
|
a feature used in some UNIXes to give extra protection to files: if
|
|
the bit is on a directory, no one but the owner (or the root) can remove
|
|
that file even if the permissions of the directory would allow file
|
|
removal by others. This failure can happen if the permissions in the
|
|
directory simply are a bit too liberal for the tests' liking. This
|
|
may or may not be a real problem: it depends on the permissions policy
|
|
used on this particular directory/project/system/site. This failure
|
|
can also happen if the system either doesn't support the sticky bit
|
|
(this is the case with many non-UNIX platforms: in principle the
|
|
File::Temp should know about these platforms and skip the tests), or
|
|
if the system supports the sticky bit but for some reason or reasons
|
|
it is not being used. This is for example the case with HP-UX: as of
|
|
HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
|
|
doesn't use it on its /tmp directory as shipped. Also as with the
|
|
permissions, some local policy might dictate that the stickiness is
|
|
not used.
|
|
|
|
(3) If the system supports the POSIX 'chown giveaway' feature and if
|
|
any of the parent directories of the temporary file back to the root
|
|
directory are 'unsafe', using the definitions given above in (1) and
|
|
(2).
|
|
|
|
See the documentation for the File::Temp module for more information
|
|
about the various security aspects.
|
|
|
|
=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
|
|
|
|
You can separately change the base used for versioned names (like
|
|
"perl5.005") by setting PERLNAME_VERBASE, like
|
|
|
|
make install PERLNAME=perl5 PERLNAME_VERBASE=perl
|
|
|
|
This can be useful if you have to install perl as "perl5" (due to an
|
|
ancient version in /usr/bin supplied by your vendor, eg). Without this
|
|
the versioned binary would be called "perl55.005".
|
|
|
|
=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:
|
|
|
|
binaries
|
|
|
|
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
|
|
|
|
scripts
|
|
|
|
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,
|
|
pod2text,
|
|
pod2checker,
|
|
pod2select,
|
|
pod2usage
|
|
splain Describe Perl warnings and errors
|
|
dprofpp Perl code profile post-processor
|
|
|
|
library files
|
|
|
|
in $privlib and $archlib specified to
|
|
Configure, usually under /usr/local/lib/perl5/.
|
|
|
|
documentation
|
|
|
|
man pages in $man1dir, usually /usr/local/man/man1.
|
|
module man
|
|
pages in $man3dir, usually /usr/local/man/man3.
|
|
pod/*.pod in $privlib/pod/.
|
|
|
|
Installperl will also create the directories listed above
|
|
in L<"Installation Directories">.
|
|
|
|
Perl's *.h header files and the libperl library are also installed
|
|
under $archlib so that any user may later build new modules, run the
|
|
optional Perl compiler, or embed the perl interpreter into another
|
|
program even if the Perl source is no longer available.
|
|
|
|
Sometimes you only want to install the version-specific parts of the perl
|
|
installation. For example, you may wish to install a newer version of
|
|
perl alongside an already installed production version of perl without
|
|
disabling installation of new modules for the production version.
|
|
To only install the version-specific parts of the perl installation, run
|
|
|
|
Configure -Dversiononly
|
|
|
|
or answer 'y' to the appropriate Configure prompt. Alternatively,
|
|
you can just manually run
|
|
|
|
./perl installperl -v
|
|
|
|
and skip installman altogether.
|
|
See also L<"Maintaining completely separate versions"> for another
|
|
approach.
|
|
|
|
=head1 Coexistence with earlier versions of perl5
|
|
|
|
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.)
|
|
|
|
Suppose you already have version 5.005_03 installed. The directories
|
|
searched by 5.005_03 are
|
|
|
|
/usr/local/lib/perl5/5.00503/$archname
|
|
/usr/local/lib/perl5/5.00503
|
|
/usr/local/lib/perl5/site_perl/5.005/$archname
|
|
/usr/local/lib/perl5/site_perl/5.005
|
|
|
|
Beginning with 5.6.0 the version number in the site libraries are
|
|
fully versioned. Now, suppose you install version 5.6.0. The directories
|
|
searched by version 5.6.0 will be
|
|
|
|
/usr/local/lib/perl5/5.6.0/$archname
|
|
/usr/local/lib/perl5/5.6.0
|
|
/usr/local/lib/perl5/site_perl/5.6.0/$archname
|
|
/usr/local/lib/perl5/site_perl/5.6.0
|
|
|
|
/usr/local/lib/perl5/site_perl/5.005/$archname
|
|
/usr/local/lib/perl5/site_perl/5.005
|
|
/usr/local/lib/perl5/site_perl/
|
|
|
|
Notice the last three entries -- Perl understands the default structure
|
|
of the $sitelib directories and will look back in older, compatible
|
|
directories. This way, modules installed under 5.005_03 will continue
|
|
to be usable by 5.005_03 but will also accessible to 5.6.0. Further,
|
|
suppose that you upgrade a module to one which requires features
|
|
present only in 5.6.0. That new module will get installed into
|
|
/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
|
|
but will not interfere with the 5.005_03 version.
|
|
|
|
The last entry, /usr/local/lib/perl5/site_perl/, is there so that
|
|
5.6.0 will look for 5.004-era pure perl modules.
|
|
|
|
Lastly, suppose you now install version 5.6.1, which we'll assume is
|
|
binary compatible with 5.6.0 and 5.005. The directories searched
|
|
by 5.6.1 (if you don't change the Configure defaults) will be:
|
|
|
|
/usr/local/lib/perl5/5.6.1/$archname
|
|
/usr/local/lib/perl5/5.6.1
|
|
/usr/local/lib/perl5/site_perl/5.6.1/$archname
|
|
/usr/local/lib/perl5/site_perl/5.6.1
|
|
|
|
/usr/local/lib/perl5/site_perl/5.6.0/$archname
|
|
/usr/local/lib/perl5/site_perl/5.6.0
|
|
|
|
/usr/local/lib/perl5/site_perl/5.005/$archname
|
|
/usr/local/lib/perl5/site_perl/5.005
|
|
/usr/local/lib/perl5/site_perl/
|
|
|
|
Assuming the users in your site are still actively using perl 5.6.0 and
|
|
5.005 after you installed 5.6.1, you can continue to install add-on
|
|
extensions using any of perl 5.6.1, 5.6.0, or 5.005. The installations
|
|
of these different versions remain distinct, but remember that the newer
|
|
versions of perl are automatically set up to search the site libraries of
|
|
the older ones. This means that installing a new extension with 5.005
|
|
will make it visible to all three versions. Later, if you install the
|
|
same extension using, say, perl 5.6.1, it will override the 5.005-installed
|
|
version, but only for perl 5.6.1.
|
|
|
|
This way, you can choose to share compatible extensions, but also upgrade
|
|
to a newer version of an extension that may be incompatible with earlier
|
|
versions, without breaking the earlier versions' installations.
|
|
|
|
=head2 Maintaining completely separate versions
|
|
|
|
Many users prefer to keep all versions of perl in completely
|
|
separate directories. This guarantees that an update to one version
|
|
won't interfere with another version. (The defaults guarantee this for
|
|
libraries after 5.6.0, but not for executables. TODO?) 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.005 to 5.6.0
|
|
|
|
Most extensions built and installed with versions of perl
|
|
prior to 5.005_50 will not need to be recompiled to be used with
|
|
5.6.0. If you find you do need to rebuild an extension with 5.6.0,
|
|
you may safely do so without disturbing the 5.005 installation.
|
|
(See L<"Coexistence with earlier versions of perl5"> above.)
|
|
|
|
See your installed copy of the perllocal.pod file for a (possibly
|
|
incomplete) list of locally installed modules. Note that you want
|
|
perllocal.pod not perllocale.pod for installed module information.
|
|
|
|
=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.
|
|
|
|
Currently, the supplied ./installhtml script does not make use of the
|
|
html Configure variables. This should be fixed in a future release.
|
|
|
|
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.org 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>.)
|
|
|
|
Please try to make your message brief but clear. 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.
|
|
|
|
=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, with the following additional request:
|
|
If you are distributing a modified version of perl (perhaps as part of
|
|
a larger package) please B<do> modify these installation instructions
|
|
and the contact information to match your distribution.
|
|
|
|
=head1 LAST MODIFIED
|
|
|
|
$Id: INSTALL,v 1.58 1999/07/23 14:43:00 doughera Exp $
|