=head1 NAME
-Install - Build and Installation guide for perl5.
+Install - Build and Installation guide for perl 5.
=head1 SYNOPSIS
-First, make sure you have an up-to-date version of Perl. If you
+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.8.x and 5.10.x) are stable maintenance releases and
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 basic steps to build and install perl 5 on a Unix system with all
the defaults are to run, from a freshly unpacked source tree:
sh Configure -de
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, by
+If that's not okay with you, you can run Configure interactively, by
just typing "sh Configure" (without the -de args). You can also specify
any prefix location by adding "-Dprefix='/some/dir'" to Configure's args.
To explicitly name the perl binary, use the command
to pod/perl5100delta.pod for more detailed information.
B<WARNING:> This version is not binary compatible with prior releases of Perl.
-
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 discussion below on
-L<"Coexistence with earlier versions of perl5"> for more details.
+L<"Coexistence with earlier versions of perl 5"> for more details.
The standard extensions supplied with Perl will be handled automatically.
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
+and L<"Coexistence with earlier versions of perl 5"> below for
further details.)
You can specify a different 'prefix' for the default installation
aware.
Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
+On these systems, it might be the default compilation mode, and there
+is currently no guarantee that passing no use64bitall option to the
+Configure process will build a 32bit perl. Implementing -Duse32bit*
+options is planned for perl 5.12.
=head3 Long doubles
If you want to force perl to be compiled completely
statically, you can either choose this when Configure prompts you or
you can use the Configure command line option -Uusedl.
+With this option, you won't be able to use any new extension
+(XS) module without recompiling perl itself.
=head3 Building a shared Perl library
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
+See L<"Coexistence with earlier versions of perl 5"> 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
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.
+discussed in L<"Coexistence with earlier versions of perl 5"> below.
If you specify a prefix that contains the string "perl", then the
library directory structure is slightly simplified. Instead of
=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
+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.
+However, sites that use package management software such as rpm or
+dpkg, or users building binary packages for distribution may also
+wish to install perl into a different directory before moving perl
+to its final destination. There are two ways to do that:
+
+=over 4
+
+=item installprefix
To install perl under the /tmp/perl5 directory, use the following
command line:
- sh Configure -Dinstallprefix=/tmp/perl5
+ 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.
+follow this example. That's why it's usually better to use DESTDIR,
+as shown in the next section.
-=head2 Creating an installable tar archive
+=item DESTDIR
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
cd /tmp/perl5/opt/perl
tar cvf /tmp/perl5-archive.tar .
+=back
+
=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. This will work even if Policy.sh was
+answers (such as installation directories) 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's perl build
+directory, and Configure will use it. This will work even if Policy.sh was
generated for another version of Perl, or on a system with a
different architecture and/or operating system. However, in such cases,
you should review the contents of the file before using it: for
=head2 Disabling older versions of Perl
Configure will search for binary compatible versions of previously
-installed perl binaries in the tree that is specified as target tree
-and these will be used by the perl being built.
-See L<"Coexistence with earlier versions of perl5"> for more details.
+installed perl binaries in the tree that is specified as target tree,
+and these will be used as locations to search for modules by the perl
+being built. The list of perl versions found will be put in the Configure
+variable inc_version_list.
To disable this use of older perl modules, even completely valid pure perl
modules, you can specify to not include the paths found:
unaffected. After Configure has finished you can just say
make
+ make test
+ make install
as usual, and Perl will be built in /tmp/perl/build/directory.
B<perl -d your_script>. If, however, you want to debug perl itself,
you probably want to have support for perl internal debugging code
(activated by adding -DDEBUGGING to ccflags), and/or support for the
-system debugger by adding -g to optimize.
+system debugger by adding -g to the optimisation flags. For that,
+use the parameter:
sh Configure -DDEBUGGING
for -DDEBUGGING. For both, the -U calls are also supported, in order
to be able to overrule the hints or Policy.sh settings.
-=over 4
-
-=item -DEBUGGING=old
-
-Which is the default, and supports the old convention of
-
- sh Configure -Doptimize='-g'
+Here are the DEBUGGING modes:
-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.
+=over 4
=item -DDEBUGGING
=item -DEBUGGING=both
-Sets both -DDEBUGGING in the ccflags, and add -g to optimize.
+Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
+
+You can actually specify -g and -DDEBUGGING independently (see below),
+but usually it's convenient to have both.
=item -DEBUGGING=-g
+=item -Doptimize=-g
+
Adds -g to optimize, but does not set -DDEBUGGING.
+(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.)
+
=item -DEBUGGING=none
+=item -UDEBUGGING
+
Removes -g from optimize, and -DDEBUGGING from ccflags.
=back
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.)
-Configure does not contain code to test for POSIX compliance, so POSIX
-is always built by default. If you wish to skip POSIX, you can
-set the Configure variable useposix=false from the Configure 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.)
-
-If you have dynamic loading, another way of specifying extra modules
-is described in L<"Adding extra modules to the build"> below.
-
-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.
+only if it is able to find the gdbm library.
To disable certain extensions so that they are not built, use the
-Dnoextensions=... and -Donlyextensions=... options. They both accept
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 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.)
+Another way of specifying extra modules is described in
+L<"Adding extra modules to the build"> below.
If you re-use an 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 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
+Perl comes with interfaces to number of libraries, including threads,
+dbm, ndbm, gdbm, and Berkeley db. For the *db* 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 libraries 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.
+automatically include that extension. The threading extension needs
+to be specified explicitely (see L<Threads>).
+
+Those libraries are not distributed with perl. If your header (.h) files
+for those libraries 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 libraries 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.
=head3 Examples
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.
+your C compiler, you should include -I/usr/local/include, if it's
+not here yet. Similarly, 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
=item gdbm in /usr/you
-Suppose you have gdbm installed in some place other than /usr/local/,
+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
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"
+ 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.
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"
+ 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
-
-A Perl interface for DB3 is part of Berkeley DB, but if you want to
-compile the 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 the DB_File interface) and without
-links to compatibility files. So if you want to use packages written
-for the 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 Overriding an old config.sh
If you want to use an old config.sh produced by a previous run of
(The file is called configure.gnu to avoid problems on systems
that would not distinguish the files "Configure" and "configure".)
-See L<Cross-compilation> below for information on cross-compiling.
-
=head2 Malloc Issues
Perl relies heavily on malloc(3) to grow data structures as needed,
=item -DPERL_POLLUTE_MALLOC
NOTE: This flag is enabled automatically on some platforms if you just
-run Configure to accept all the defaults on those platforms.
+run Configure to accept all the defaults.
Perl's malloc family of functions are normally called Perl_malloc(),
Perl_realloc(), Perl_calloc() and Perl_mfree().
Devel::Peek::mstat() function. You cannot enable this unless you are
using Perl's malloc, so a typical Configure command would be
- sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc='y'
+ sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
to enable this option.
You'll probably also have to extensively modify the extension building
mechanism.
-=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, Plan 9, VMS and Win32 ports is in the
=item Miscellaneous
-Some additional things that have been reported for either perl4 or perl5:
+Some additional things that have been reported:
Genix may need to use libc rather than libc_s, or #undef VARARGS.
configured in the kernel. Perl tries to detect this, though, and
you will get a message telling you what to do.
-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).
-
Building Perl on a system that has also BIND (headers and libraries)
installed may run into troubles because BIND installs its own netdb.h
and socket.h, which may not agree with the operating system's ideas of
make install DESTDIR=/tmp/perl5
DESTDIR is automatically prepended to all the installation paths. See
-the example in L<"Creating an installable tar archive"> above.
+the example in L<"DESTDIR"> above.
=head2 Installed files
report Bugs Effectively" by Simon Tatham:
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
-=head1 Coexistence with earlier versions of perl5
+=head1 Coexistence with earlier versions of perl 5
Perl 5.10 is not binary compatible with earlier versions of Perl.
In other words, you will have to recompile your XS modules.
(meaning that a C compiler is used) will have to be recompiled to be
used with 5.10.0. If you find you do need to rebuild an extension with
5.10.0, you may safely do so without disturbing the older
-installations. (See L<"Coexistence with earlier versions of perl5">
+installations. (See L<"Coexistence with earlier versions of perl 5">
above.)
See your installed copy of the perllocal.pod file for a (possibly
projects / p5sagit/p5-mst-13.2.git / blobdiff