+If you read this file _as_is_, just ignore the funny characters you see.
+It is written in the POD format (see pod/perlpod.pod) which is specially
+designed to be readable as is.
+
=head1 NAME
-Install - Build and Installation guide for perl5.
+Install - Build and Installation guide for perl 5.
=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/>.
+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
+odd-numbered subreleases (like 5.7.x and 5.9.x) are unstable
+development releases. Development releases should not be used in
+production environments. Fixes and new features are first carefully
+tested in development releases and only if they prove themselves to be
+worthy will they be migrated to the maintenance releases.
-The basic steps to build and install perl5 on a Unix system
-with all the defaults are:
+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:
- 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 uses a version
-scheme where even-numbered subreleases (like 5.6 and 5.8) 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 some other
platform-specific directory -- see the appropriate file in hints/.)
-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 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
+"make install PERLNAME=myperl".
-If "make install" just says "`install' is up to date" or something
-similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
-and you should say "make install-all". (This confusion is brought to you
-by the Perl distribution having a file called INSTALL.)
+These options, and many more, are explained in further detail 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.
+pod/perl5110delta.pod file. For more information about how to find more
+specific detail about changes, see the Changes file.
=head1 DESCRIPTION
B<text> embolden text, used for switches, programs or commands
C<code> literal code
L<name> A link (cross reference) to name
+ F<file> A filename
Although most of the defaults are probably fine for most users,
-you should probably at least skim through this entire document before
+you should probably at least skim through this 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. There
-are also README files for several flavors of Unix systems, such as
-Solaris, HP-UX, and AIX; if you have one of those systems, you should
-also read the README file specific to that system.
-
-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.)
-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 rather old
-extensions that have not been updated for the current naming convention
-with:
-
- perl Makefile.PL POLLUTE=1
+In addition to this file, check if there is a README file specific to
+your operating system, since it may provide additional or different
+instructions for building Perl. If there is a hint file for your
+system (in the hints/ directory) you might also want to read it
+for even more information.
-Alternatively, you can enable CPP symbol pollution wholesale by
-building perl itself with:
+For additional information about porting Perl, see the section on
+L<"Porting information"> below, and look at the files in the Porting/
+directory.
- sh Configure -Accflags=-DPERL_POLLUTE
+=head1 PRELIMINARIES
-pod/perl56delta.pod contains more details about this.
+=head2 Changes and Incompatibilities
-=head1 WARNING: This version is not binary compatible with releases of
-Perl prior to 5.8.0.
+Please see pod/perl5110delta.pod for a description of the changes and
+potential incompatibilities introduced with this release. A few of
+the most important issues are listed below, but you should refer
+to pod/perl5110delta.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 discussions below on
-L<"Coexistence with earlier versions of perl5"> and
-L<"Upgrading from 5.005 or 5.6 to 5.8.0"> for more details.
+without reinstallation. See the discussion below on
+L<"Coexistence with earlier versions of perl 5"> 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 the earlier pod/perl5Xdelta.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 a couple of 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.
-
-=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 50 MB of disk space.
-After completing make, it takes up roughly 100 MB, though the actual
-total is likely to be quite system-dependent. The installation
-directories need something on the order of 45 MB, though again that
-value is system-dependent.
-
-=head1 Start with a Fresh Distribution
-
-If you have built perl before, you should clean out the build directory
-with the command
-
- make distclean
-
-or
-
- make realclean
-
-The only difference between the two is that make distclean also removes
-your old config.sh and Policy.sh files.
-
-The results of a Configure run are stored in the config.sh and Policy.sh
-files. If you are upgrading from a previous version of perl, or if you
-change systems or compilers or make other significant changes, or if
-you are experiencing difficulties building perl, you should probably
-not re-use your old config.sh. Simply remove it
-
- rm -f config.sh
-
-If you wish to use your old config.sh, be especially attentive to the
-version and architecture-specific questions and answers. For example,
-the default directory for architecture-dependent library modules
-includes the version name. By default, Configure will reuse your old
-name (e.g. /opt/perl/lib/i86pc-solaris/5.003) even if you're running
-Configure for a different version, e.g. 5.004. Yes, Configure should
-probably check and correct for this, but it doesn't.
-Similarly, if you used a shared libperl.so (see below) with version
-numbers, you will probably want to adjust them as well.
-
-Also, be careful to check your architecture name. For example, some
-Linux distributions use i386, while others may use i486. If you build
-it yourself, Configure uses the output of the arch command, which
-might be i586 or i686 instead. If you pick up a precompiled binary, or
-compile extensions on different systems, they might not all agree on
-the architecture name.
-
-In short, if you wish to use your old config.sh, I recommend running
-Configure interactively rather than blindly accepting the defaults.
-
-If your reason to reuse your old config.sh is to save your particular
-installation choices, then you can probably achieve the same effect by
-using the Policy.sh file. See the section on L<"Site-wide Policy
-settings"> below. If you wish to start with a fresh distribution, you
-also need to remove any old Policy.sh files you may have with
-
- rm -f Policy.sh
+On a related issue, old modules may possibly be affected by the changes
+in the Perl language in the current release. Please see
+pod/perl5110delta.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 Run Configure
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
+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 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. 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
+The results of a Configure run are stored in the config.sh and Policy.sh
+files.
- make all test
+=head2 Common Configure options
-and Perl will be built and tested, all in /tmp/perl/build/directory.
+Configure supports a number of useful options. Run
-=head2 Common Configure options
+ Configure -h
-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
+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
+=item C compiler
-To compile with gcc you should run
+To compile with gcc, if it's not the default compiler on your
+system, you should run
sh Configure -Dcc=gcc
-This is the preferred way to specify gcc (or another alternative
+This is the preferred way to specify gcc (or any 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
+and L<"Coexistence with earlier versions of perl 5"> 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
+directory when Configure prompts you, or by using the Configure command
line option -Dprefix='/some/directory', e.g.
sh Configure -Dprefix=/opt/perl
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.
+vendor unless you are sure you know what you are doing. If you insist
+on replacing your vendor's perl, useful information on how it was
+configured may be found with
-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
+ perl -V:config_args
- Configure -Uinstallusrbinperl
+(Check the output carefully, however, since this doesn't preserve
+spaces in arguments to Configure. For that, you have to look carefully
+at config_arg1, config_arg2, etc.)
-or by answering 'no' to the appropriate Configure prompt.
+By default, Configure will not try to link /usr/bin/perl to the current
+version of perl. You can turn on that behavior by running
-In any case, system administrators are strongly encouraged to
-put (symlinks to) perl and its accompanying utilities, such as perldoc,
+ Configure -Dinstallusrbinperl
+
+or by answering 'yes' to the appropriate Configure prompt.
+
+In any case, system administrators are strongly encouraged to put
+(symlinks to) perl and its accompanying utilities, such as perldoc,
into a directory typically found along a user's PATH, or in another
obvious and convenient place.
-=item Overriding an old config.sh
+=item Building a development release
-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>.
+For development releases (odd subreleases, like 5.9.x) if you want to
+use Configure -d, you will also need to supply -Dusedevel to Configure,
+because the default answer to the question "do you really want to
+Configure a development version?" is "no". The -Dusedevel skips that
+sanity check.
=back
sh Configure -des
-Note: for development releases (odd subreleases, like 5.9, as opposed
-to maintenance releases which have even subreleases, like 5.6 and 5.8)
-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.
+=head2 Altering Configure variables for C compiler switches etc.
-For example for my Solaris system, I usually use
+For most users, most of the Configure defaults are fine, or can easily
+be set on the Configure command line. However, if Configure doesn't
+have an option to do what you want, you can change Configure variables
+after the platform hints have been run by using Configure's -A switch.
+For example, here's how to add a couple of extra flags to C compiler
+invocations:
- sh Configure -Dprefix=/opt/perl -Doptimize='-xpentium -xO4' -des
+ sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
-=head2 GNU-style configure
+To clarify, those ccflags values are not Configure options; if passed to
+Configure directly, they won't do anything useful (they will define a
+variable in config.sh, but without taking any action based upon it).
+But when passed to the compiler, those flags will activate #ifdefd code.
-If you prefer the GNU-style configure command line interface, you can
-use the supplied configure.gnu command, e.g.
+For more help on Configure switches, run
- CC=gcc ./configure.gnu
+ sh Configure -h
-The configure.gnu script emulates a few of the more common configure
-options. Try
+=head2 Major Configure-time Build Options
- ./configure.gnu --help
+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.
-for a listing.
+=head3 Threads
-(The file is called configure.gnu to avoid problems on systems
-that would not distinguish the files "Configure" and "configure".)
+On some platforms, perl can be compiled with support for threads. To
+enable this, run
+
+ sh Configure -Dusethreads
+
+The default is to compile without thread support.
+
+Perl used to have two different internal threads implementations. The current
+model (available internally since 5.6, and as a user-level module since 5.8) is
+called interpreter-based implementation (ithreads), with one interpreter per
+thread, and explicit sharing of data. The (deprecated) 5.005 version
+(5005threads) was removed for release 5.10.
+
+The 'threads' module is for use with the ithreads implementation. The
+'Thread' module emulates the old 5005threads interface on top of the current
+ithreads model.
+
+When using threads, perl uses a dynamically-sized buffer for some of
+the thread-safe library calls, such as those in the getpw*() family.
+This buffer starts small, but it will keep growing until the result
+fits. To get a fixed upper limit, you should compile Perl with
+PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want. One
+way to do this is to run Configure with
+C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
+
+=head3 Large file support
+
+Since Perl 5.6.0, Perl has supported large files (files larger than
+2 gigabytes), and in many common platforms like Linux or Solaris this
+support is on by default.
+
+This is both good and bad. It is good in that you can use large files,
+seek(), stat(), and -s them. It is bad in that if you are interfacing Perl
+using some extension, the components you are connecting to must also
+be large file aware: if Perl thinks files can be large but the other
+parts of the software puzzle do not understand the concept, bad things
+will happen.
+
+There's also one known limitation with the current large files
+implementation: unless you also have 64-bit integers (see the next
+section), you cannot use the printf/sprintf non-decimal integer formats
+like C<%x> to print filesizes. You can use C<%d>, though.
+
+If you want to compile perl without large file support, use
+
+ sh Configure -Uuselargefiles
+
+=head3 64 bit support
+
+If your platform does not run natively at 64 bits, but can simulate
+them with compiler flags and/or C<long long> or C<int64_t>,
+you can build a perl that uses 64 bits.
+
+There are actually two modes of 64-bitness: the first one is achieved
+using Configure -Duse64bitint and the second one using Configure
+-Duse64bitall. The difference is that the first one is minimal and
+the second one maximal. The first works in more places than the second.
+
+The C<use64bitint> option does only as much as is required to get
+64-bit integers into Perl (this may mean, for example, using "long
+longs") while your memory may still be limited to 2 gigabytes (because
+your pointers could still be 32-bit). Note that the name C<64bitint>
+does not imply that your C compiler will be using 64-bit C<int>s (it
+might, but it doesn't have to). The C<use64bitint> simply means that
+you will be able to have 64 bit-wide scalar values.
+
+The C<use64bitall> option goes all the way by attempting to switch
+integers (if it can), longs (and pointers) to being 64-bit. This may
+create an even more binary incompatible Perl than -Duse64bitint: the
+resulting executable may not run at all in a 32-bit box, or you may
+have to reboot/reconfigure/rebuild your operating system to be 64-bit
+aware.
+
+Natively 64-bit systems 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
+
+In some systems you may be able to use long doubles to enhance the
+range and precision of your double precision floating point numbers
+(that is, Perl's numbers). Use Configure -Duselongdouble to enable
+this support (if it is available).
+
+=head3 "more bits"
+
+You can "Configure -Dusemorebits" to turn on both the 64-bit support
+and the long double support.
+
+=head3 Algorithmic Complexity Attacks on Hashes
+
+In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
+Processing such hashes would consume large amounts of CPU time,
+enabling a "Denial of Service" attack against Perl. Such hashes may be
+a problem for example for mod_perl sites, sites with Perl CGI scripts
+and web services, that process data originating from external sources.
+
+In Perl 5.8.1 a security feature was introduced to make it harder to
+create such degenerate hashes. A visible side effect of this was that
+the keys(), values(), and each() functions may return the hash elements
+in different order between different runs of Perl even with the same
+data. It also had unintended binary incompatibility issues with
+certain modules compiled against Perl 5.8.0.
+
+In Perl 5.8.2 an improved scheme was introduced. Hashes will return
+elements in the same order as Perl 5.8.0 by default. On a hash by hash
+basis, if pathological data is detected during a hash key insertion,
+then that hash will switch to an alternative random hash seed. As
+adding keys can always dramatically change returned hash element order,
+existing programs will not be affected by this, unless they
+specifically test for pre-recorded hash return order for contrived
+data. (eg the list of keys generated by C<map {"\0"x$_} 0..15> trigger
+randomisation) In effect the new implementation means that 5.8.1 scheme
+is only being used on hashes which are under attack.
+
+One can still revert to the old guaranteed repeatable order (and be
+vulnerable to attack by wily crackers) by setting the environment
+variable PERL_HASH_SEED, see L<perlrun/PERL_HASH_SEED>. Another option
+is to add -DUSE_HASH_SEED_EXPLICIT to the compilation flags (for
+example by using C<Configure -Accflags=-DUSE_HASH_SEED_EXPLICIT>), in
+which case one has to explicitly set the PERL_HASH_SEED environment
+variable to enable the security feature, or by adding -DNO_HASH_SEED to
+the compilation flags to completely disable the randomisation feature.
+
+B<Perl has never guaranteed any ordering of the hash keys>, and the
+ordering has already changed several times during the lifetime of Perl
+5. Also, the ordering of hash keys has always been, and continues to
+be, affected by the insertion order. Note that because of this
+randomisation for example the Data::Dumper results will be different
+between different runs of Perl, since Data::Dumper by default dumps
+hashes "unordered". The use of the Data::Dumper C<Sortkeys> option is
+recommended.
+
+=head3 SOCKS
+
+Perl can be configured to be 'socksified', that is, to use the SOCKS
+TCP/IP proxy protocol library. SOCKS is used to give applications
+access to transport layer network proxies. Perl supports only SOCKS
+Version 5. The corresponding Configure option is -Dusesocks.
+You can find more about SOCKS from wikipedia at
+L<http://en.wikipedia.org/wiki/SOCKS>.
+
+=head3 Dynamic Loading
+
+By default, Configure will compile perl to use dynamic loading.
+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
+
+Currently, for most systems, the main perl executable is built by
+linking the "perl library" libperl.a with perlmain.o, your static
+extensions, and various extra libraries, such as -lm.
+
+On 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.5.8.8 (for Perl 5.8.8), or libperl.so.588, 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.
+
+You can elect to build a shared libperl by
+
+ sh Configure -Duseshrplib
+
+To build a shared libperl, the environment variable controlling shared
+library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
+NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
+for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
+the Perl build directory because that's where the shared libperl will
+be created. Configure arranges makefile to have the correct shared
+library search settings. You can find the name of the environment
+variable Perl thinks works in your your system by
+
+ grep ldlibpthname config.sh
+
+However, there are some special cases where manually setting the
+shared library path might be required. For example, if you want to run
+something like the following with the newly-built but not-yet-installed
+./perl:
+
+ cd t; ./perl -MTestInit misc/failing_test.t
+
+or
+
+ ./perl -Ilib ~/my_mission_critical_test
+
+then you need to set up the shared library path explicitly.
+You can do this with
+
+ LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
+
+for Bourne-style shells, or
+
+ setenv LD_LIBRARY_PATH `pwd`
+
+for Csh-style shells. (This procedure may also be needed if for some
+unexpected reason Configure fails to set up makefile correctly.) (And
+again, it may be something other than LD_LIBRARY_PATH for you, see above.)
+
+You can often recognize failures to build/use a shared libperl from error
+messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
+for example:
+
+ 18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
+
+There is also an potential problem with the shared perl library if you
+want to have more than one "flavor" of the same version of perl (e.g.
+with and without -DDEBUGGING). For example, suppose you build and
+install a standard Perl 5.10.0 with a shared library. Then, suppose you
+try to build Perl 5.10.0 with -DDEBUGGING enabled, but everything else
+the same, including all the installation directories. How can you
+ensure that your newly built perl will link with your newly built
+libperl.so.8 rather with the installed libperl.so.8? The answer is
+that you might not be able to. The installation directory is encoded
+in the perl binary with the LD_RUN_PATH environment variable (or
+equivalent ld command-line option). On Solaris, you can override that
+with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
+LD_PRELOAD, specifying the exact filename you wish to be used; and on
+Digital Unix, you can override LD_LIBRARY_PATH by setting the
+_RLD_ROOT environment variable to point to the perl build directory.
+
+In other words, it is generally not a good idea to try to build a perl
+with a shared library if $archlib/CORE/$libperl already exists from a
+previous build.
+
+A good workaround is to specify a different directory for the
+architecture-dependent library for your -DDEBUGGING version of perl.
+You can do this by changing all the *archlib* variables in config.sh to
+point to your new architecture-dependent library.
+
+=head3 Environment access
-See L<Cross-compilation> below for information on cross-compiling.
+Perl often needs to write to the program's environment, such as when C<%ENV>
+is assigned to. Many implementations of the C library function C<putenv()>
+leak memory, so where possible perl will manipulate the environment directly
+to avoid these leaks. The default is now to perform direct manipulation
+whenever perl is running as a stand alone interpreter, and to call the safe
+but potentially leaky C<putenv()> function when the perl interpreter is
+embedded in another application. You can force perl to always use C<putenv()>
+by compiling with -DPERL_USE_SAFE_PUTENV. You can force an embedded perl to
+use direct manipulation by setting C<PL_use_safe_putenv = 0;> after the
+C<perl_construct()> call.
=head2 Installation Directories
The installation directories can all be changed by answering the
-appropriate questions in Configure. For convenience, all the
-installation questions are near the beginning of Configure.
-Do not include trailing slashes on directory names.
-
-I highly recommend running Configure interactively to be sure it puts
-everything where you want it. At any point during the Configure
-process, you can answer a question with &-d and Configure will use
-the defaults from then on. Alternatively, you can
+appropriate questions in Configure. For convenience, all the installation
+questions are near the beginning of Configure. Do not include trailing
+slashes on directory names. At any point during the Configure process,
+you can answer a question with &-d and Configure will use the defaults
+from then on. Alternatively, you can
grep '^install' config.sh
=item Directories for the perl distribution
-By default, Configure will use the following directories for 5.8.0.
+By default, Configure will use the following directories for 5.11.0.
$version is the full perl version number, including subversion, e.g.
-5.8.0 or 5.8.1, and $archname is a string like sun4-sunos,
+5.11.0 or 5.9.5, 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)
+ $prefixexp /usr/local
+ $binexp $prefixexp/bin
+ $scriptdirexp $prefixexp/bin
+ $privlibexp $prefixexp/lib/perl5/$version
+ $archlibexp $prefixexp/lib/perl5/$version/$archname
+ $man1direxp $prefixexp/man/man1
+ $man3direxp $prefixexp/man/man3
+ $html1direxp (none)
+ $html3direxp (none)
+
+$prefixexp is generated from $prefix, with ~ expansion done to convert home
+directories into absolute paths. Similarly for the other variables listed. As
+file system calls do not do this, you should always reference the ...exp
+variables, to support users who build perl in their home directory.
Actually, Configure recognizes the SVR3-style
/usr/local/man/l_man/man1 directories, if present, and uses those
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)
+ $siteprefixexp $prefixexp
+ $sitebinexp $siteprefixexp/bin
+ $sitescriptexp $siteprefixexp/bin
+ $sitelibexp $siteprefixexp/lib/perl5/site_perl/$version
+ $sitearchexp $siteprefixexp/lib/perl5/site_perl/$version/$archname
+ $siteman1direxp $siteprefixexp/man/man1
+ $siteman3direxp $siteprefixexp/man/man3
+ $sitehtml1direxp (none)
+ $sitehtml3direxp (none)
By default, ExtUtils::MakeMaker will install architecture-independent
modules into $sitelib and architecture-dependent modules into $sitearch.
for you to use to distribute add-on modules.
Configure variable Default value
- $vendorprefix (none)
+ $vendorprefixexp (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)
+ $vendorbinexp $vendorprefixexp/bin
+ $vendorscriptexp $vendorprefixexp/bin
+ $vendorlibexp
+ $vendorprefixexp/lib/perl5/vendor_perl/$version
+ $vendorarchexp
+ $vendorprefixexp/lib/perl5/vendor_perl/$version/$archname
+ $vendorman1direxp $vendorprefixexp/man/man1
+ $vendorman3direxp $vendorprefixexp/man/man3
+ $vendorhtml1direxp (none)
+ $vendorhtml3direxp (none)
These are normally empty, but may be set as needed. For example,
a vendor might choose the following settings:
- $prefix /usr
- $siteprefix /usr/local
- $vendorprefix /usr
+ $prefix /usr
+ $siteprefix /usr/local
+ $vendorprefix /usr
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
+ $binexp /usr/bin
+ $scriptdirexp /usr/bin
+ $privlibexp /usr/lib/perl5/$version
+ $archlibexp /usr/lib/perl5/$version/$archname
+ $man1direxp /usr/man/man1
+ $man3direxp /usr/man/man3
+
+ $sitebinexp /usr/local/bin
+ $sitescriptexp /usr/local/bin
+ $sitelibexp /usr/local/lib/perl5/site_perl/$version
+ $sitearchexp /usr/local/lib/perl5/site_perl/$version/$archname
+ $siteman1direxp /usr/local/man/man1
+ $siteman3direxp /usr/local/man/man3
+
+ $vendorbinexp /usr/bin
+ $vendorscriptexp /usr/bin
+ $vendorlibexp /usr/lib/perl5/vendor_perl/$version
+ $vendorarchexp /usr/lib/perl5/vendor_perl/$version/$archname
+ $vendorman1direxp /usr/man/man1
+ $vendorman3direxp /usr/man/man3
Note how in this example, the vendor-supplied directories are in the
/usr hierarchy, while the directories reserved for the end-user are in
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
Perl will search these directories (including architecture and
version-specific subdirectories) for add-on modules and extensions.
-For example, if you have a bundle of perl libraries from a previous
+For example, if you have a bundle of perl libraries from a previous
installation, perhaps in a strange place:
- Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.6.1
+ Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
=item APPLLIB_EXP
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
+=item usesitecustomize
-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.
+Run-time customization of @INC can be enabled with:
-You can continue to use the old default from the command line with
+ sh Configure -Dusesitecustomize
- sh Configure -Dman3dir=/usr/local/lib/perl5/5.8.0/man/man3
+which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
+When enabled, this makes perl run F<$sitelibexp/sitecustomize.pl> before
+anything else. This script can then be set up to add additional
+entries to @INC.
-Some users also prefer to use a .3pm suffix. You can do that with
+=item Man Pages
- sh Configure -Dman3ext=3pm
+By default, man pages will be installed in $man1dir and $man3dir, which
+are normally /usr/local/man/man1 and /usr/local/man/man3. If you
+want to use a .3pm suffix for perl man pages, you can do that with
-Again, these are just the defaults, and can be changed as you run
-Configure.
+ sh Configure -Dman3ext=3pm
=item HTML pages
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
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.8.0 are
+-Dprefix=/opt/perl, then the default library directories for 5.9.0 are
Configure variable Default value
- $privlib /opt/perl/lib/5.8.0
- $archlib /opt/perl/lib/5.8.0/$archname
- $sitelib /opt/perl/lib/site_perl/5.8.0
- $sitearch /opt/perl/lib/site_perl/5.8.0/$archname
+ $privlib /opt/perl/lib/5.9.0
+ $archlib /opt/perl/lib/5.9.0/$archname
+ $sitelib /opt/perl/lib/site_perl/5.9.0
+ $sitearch /opt/perl/lib/site_perl/5.9.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
+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
-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:
+=item installprefix
- sh Configure -Dinstallprefix=/tmp/perl5
+To install perl under the /tmp/perl5 directory, 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.
+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 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:
+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. One way to do that is by
+using the DESTDIR variable during C<make install>. The DESTDIR is
+automatically prepended to all the installation paths. Thus you
+simply do:
- # 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
+ sh Configure -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
+ make install DESTDIR=/tmp/perl5
+ cd /tmp/perl5/opt/perl
+ tar cvf /tmp/perl5-archive.tar .
+
+=back
+
+=head2 Relocatable @INC
+
+To create a relocatable perl tree, use the following command line:
+
+ sh Configure -Duserelocatableinc
+
+Then the paths in @INC (and everything else in %Config) can be
+optionally located via the path of the perl executable.
+
+That means that, if the string ".../" is found at the start of any
+path, it's substituted with the directory of $^X. So, the relocation
+can be configured on a per-directory basis, although the default with
+"-Duserelocatableinc" is that everything is relocated. The initial
+install is done to the original configured prefix.
=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.
+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
+example, your new target may not keep its man pages in the same place
+as the system on which the file was generated.
Alternatively, if you wish to change some or all of those policy
answers, you should
to contain any valid shell commands. It will be run just after the
platform-specific hints files.
-=head2 Configure-time Options
+=head2 Disabling older versions of Perl
-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.
+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 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.
-=head2 Threads
+To disable this use of older perl modules, even completely valid pure perl
+modules, you can specify to not include the paths found:
-On some platforms, perl can be compiled with
-support for threads. To enable this, run
+ sh Configure -Dinc_version_list=none ...
- sh Configure -Dusethreads
-
-Currently, you need to specify -Dusethreads on the Configure command
-line so that the hint files can make appropriate adjustments.
-
-The default is to compile without thread support.
-
-Perl has two different internal threads implementations. The current
-model (available internally since 5.6, and as a user-level module
-since 5.8) is called interpreter-based implementation (ithreads),
-with one interpreter per thread, and explicit sharing of data.
-
-The 5.005 version (5005threads) is considered obsolete, buggy, and
-unmaintained.
-
-By default, Configure selects ithreads if -Dusethreads is specified.
-
-(You need to also use the PerlIO layer, explained later, if you decide
-to use ithreads, to guarantee the good interworking of threads and I/O.)
-
-However, if you wish, you can select the unsupported old 5005threads behavior
-
- sh Configure -Dusethreads -Duse5005threads
-
-If you decide to use ithreads, the 'threads' module allows their use,
-and the 'Thread' module offers an interface to both 5005threads and
-ithreads (whichever has been configured).
-
-When building threaded for certain library calls like the getgr*() and
-the getpw*() there is a dynamically sized result buffer: the buffer
-starts small but Perl will keep growing the buffer until the result fits.
-To get a fixed upper limit you will have to recompile Perl with
-PERL_REENTRANT_MAXSIZE defined to be the number of bytes you want.
-One way to do this is to run Configure with
-C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>
-
-=head2 Large file support.
-
-Since Perl 5.6.0, Perl has supported large files (files larger than
-2 gigabytes), and in many common platforms like Linux or Solaris this
-support is on by default.
-
-This is both good and bad. It is good in that you can use large files,
-seek(), stat(), and -s them. It is bad in that if you are interfacing Perl
-using some extension, the components you are connecting to must also
-be large file aware: if Perl thinks files can be large but the other
-parts of the software puzzle do not understand the concept, bad things
-will happen. One popular extension suffering from this ailment is the
-Apache extension mod_perl.
-
-There's also one known limitation with the current large files
-implementation: unless you also have 64-bit integers (see the next
-section), you cannot use the printf/sprintf non-decimal integer
-formats like C<%x> to print filesizes. You can use C<%d>, though.
-
-=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
-
-Executive summary: in Perl 5.8, you should use the default "PerlIO"
-as the IO mechanism unless you have a good reason not to.
-
-In more detail: previous versions of perl used the standard IO
-mechanisms as defined in stdio.h. Versions 5.003_02 and later of perl
-introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
-until and including Perl 5.6, the stdio mechanism was still the default
-and the only supported mechanism.
-
-Starting from Perl 5.8, the default mechanism is to use the PerlIO
-abstraction, because it allows better control of I/O mechanisms,
-instead of having to work with (often, work around) vendors' I/O
-implementations.
-
-This PerlIO abstraction can be (but again, unless you know what you
-are doing, should not be) disabled either on the Configure command
-line with
-
- sh Configure -Uuseperlio
-
-or interactively at the appropriate Configure prompt.
-
-With the PerlIO abstraction layer, there is another possibility for
-the underlying IO calls, AT&T's "sfio". This has superior performance
-to stdio.h in many cases, and is extensible by the use of "discipline"
-modules ("Native" PerlIO has them too). Sfio currently only builds on
-a subset of the UNIX platforms perl supports. Because the data
-structures are completely different from stdio, perl extension modules
-or external libraries may not work. This configuration exists to
-allow these issues to be worked on.
-
-This option requires the 'sfio' package to have been built and installed.
-The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
-
-You select this option by
-
- sh Configure -Duseperlio -Dusesfio
-
-If you have already selected -Duseperlio, and if Configure detects
-that you have sfio, then sfio will be the default suggested by
-Configure.
-
-Note: On some systems, sfio's iffe configuration script fails to
-detect that you have an atexit function (or equivalent). Apparently,
-this is a problem at least for some versions of Linux and SunOS 4.
-Configure should detect this problem and warn you about problems with
-_exit vs. exit. If you have this problem, the fix is to go back to
-your sfio sources and correct iffe's guess about atexit.
+When using the newer perl, you can add these paths again in the
+$PERL5LIB environment variable or with perl's -I runtime option.
-=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 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.
+=head2 Building Perl outside of the source directory
-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.
+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. You can do this (if your file system supports symbolic
+links) by
-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.
+ mkdir /tmp/perl/build/directory
+ cd /tmp/perl/build/directory
+ sh /path/to/perl/source/Configure -Dmksymlinks ...
-For some systems (mostly SVR4), building a shared libperl is required
-for dynamic loading to work, and hence is already the default.
+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
-You can elect to build a shared libperl by
+ make
+ make test
+ make install
- sh Configure -Duseshrplib
+as usual, and Perl will be built in /tmp/perl/build/directory.
-To build a shared libperl, the environment variable controlling shared
-library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
-NeXTSTEP/OPENSTEP/Darwin, LIBRARY_PATH for BeOS, LD_LIBRARY_PATH/SHLIB_PATH
-for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
-the Perl build directory because that's where the shared libperl will
-be created. Configure arranges makefile to have the correct shared
-library search settings. You can find the name of the environment
-variable Perl thinks works in your your system by
+=head2 Building a debugging perl
- grep ldlibpthname config.sh
+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 have support for perl internal debugging code
+(activated by adding -DDEBUGGING to ccflags), and/or support for the
+system debugger by adding -g to the optimisation flags. For that,
+use the parameter:
-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:
+ sh Configure -DDEBUGGING
- cd t; ./perl misc/failing_test.t
or
- ./perl -Ilib ~/my_mission_critical_test
-then you need to set up the shared library path explicitly.
-You can do this with
-
- LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
-
-for Bourne-style shells, or
-
- setenv LD_LIBRARY_PATH `pwd`
-
-for Csh-style shells. (This procedure may also be needed if for some
-unexpected reason Configure fails to set up makefile correctly.) (And
-again, it may be something other than LD_LIBRARY_PATH for you, see above.)
-
-You can often recognize failures to build/use a shared libperl from error
-messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
-for example:
-18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
-
-There is also an potential problem with the shared perl library if you
-want to have more than one "flavor" of the same version of perl (e.g.
-with and without -DDEBUGGING). For example, suppose you build and
-install a standard Perl 5.8.0 with a shared library. Then, suppose you
-try to build Perl 5.8.0 with -DDEBUGGING enabled, but everything else
-the same, including all the installation directories. How can you
-ensure that your newly built perl will link with your newly built
-libperl.so.8 rather with the installed libperl.so.8? The answer is
-that you might not be able to. The installation directory is encoded
-in the perl binary with the LD_RUN_PATH environment variable (or
-equivalent ld command-line option). On Solaris, you can override that
-with LD_LIBRARY_PATH; on Linux, you can only override at runtime via
-LD_PRELOAD, specifying the exact filename you wish to be used; and on
-Digital Unix, you can override LD_LIBRARY_PATH by setting the
-_RLD_ROOT environment variable to point to the perl build directory.
-
-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
+ sh Configure -DDEBUGGING=<mode>
-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.
+For a more eye appealing call, -DEBUGGING is defined to be an alias
+for -DDEBUGGING. For both, the -U calls are also supported, in order
+to be able to overrule the hints or Policy.sh settings.
-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.)
+Here are the DEBUGGING modes:
=over 4
-=item Using the system malloc
+=item -DDEBUGGING
-To build without perl's malloc, you can use the Configure command
+=item -DEBUGGING
- sh Configure -Uusemymalloc
+=item -DEBUGGING=both
-or you can answer 'n' at the appropriate interactive Configure prompt.
+Sets both -DDEBUGGING in the ccflags, and adds -g to optimize.
-=item -DPERL_POLLUTE_MALLOC
+You can actually specify -g and -DDEBUGGING independently (see below),
+but usually it's convenient to have both.
-NOTE: This flag is enabled automatically on some platforms if you just
-run Configure to accept all the defaults on those platforms.
+=item -DEBUGGING=-g
-Perl's malloc family of functions are normally called Perl_malloc(),
-Perl_realloc(), Perl_calloc() and Perl_mfree().
-These names do not clash with the system versions of these functions.
-
-If this flag is enabled, however, Perl's malloc family of functions
-will have the same names as the system versions. This may be required
-sometimes if you have libraries that like to free() data that may have
-been allocated by Perl_malloc() and vice versa.
+=item -Doptimize=-g
-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.
+Adds -g to optimize, but does not set -DDEBUGGING.
-=item -DPERL_DEBUGGING_MSTATS
+(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.)
-This flag enables debugging mstats, which is required to use the
-Devel::Peek::mstat() function. You cannot enable this unless you are
-using Perl's malloc, so a typical Configure command would be
+=item -DEBUGGING=none
- sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc='y'
+=item -UDEBUGGING
-to enable this option.
+Removes -g from optimize, and -DDEBUGGING from ccflags.
=back
-=head2 Building a debugging perl
+If you are using a shared libperl, see the warnings about multiple
+versions of perl under L<Building a shared Perl library>.
-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
+Note that a perl built with -DDEBUGGING will be bigger and will run more
+slowly than a standard perl.
- sh Configure -Doptimize='-g'
+=head2 DTrace support
-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.)
+On platforms where DTrace is available, it may be enabled by
+using the -Dusedtrace option to Configure. DTrace probes are available for
+subroutine entry (sub-entry) and subroutine exit (sub-exit). Here's a
+simple D script that uses them:
-You can actually specify -g and -DDEBUGGING independently, but usually
-it's convenient to have both.
+ perl$target:::sub-entry, perl$target:::sub-return {
+ printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-",
+ copyinstr(arg0), copyinstr(arg1), arg2);
+ }
-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.)
-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.
+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
+a space-separated list of extensions. The extensions listed in
+C<noextensions> are removed from the list of extensions to build, while
+the C<onlyextensions> is rather more severe and builds only the listed
+extensions. The latter should be used with extreme caution since
+certain extensions are used by many other extensions and modules:
+examples of such modules include Fcntl and IO. The order of processing
+these options is first C<only> (if present), then C<no> (if present).
+
+Of course, you may always run Configure interactively and select only
+the extensions you want.
If you unpack any additional extensions in the ext/ directory before
running Configure, then Configure will offer to build those additional
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.
-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.)
-
-To disable certain extensions so that they are not built, use
-the -Dnoextensions=... and -Donlyextensions=... options. They both
-accept a space-separated list of extensions. The extensions listed
-in C<noextensions> are removed from the list of extensions to build,
-while the C<onlyextensions> is rather more severe and builds only
-the listed extensions. The latter should be used with extreme caution
-since certain extensions are used by many other extensions and modules:
-such modules include Fcntl and IO. The order of processing these
-options is first C<only> (if present), then C<no> (if present).
-
-Another, older way to turn off various extensions (which is still good
-to know if you have to work with older Perl) exists. Here are the
-Configure command-line variables you can set to turn off various
-extensions. All others are included by default.
-
- DB_File i_db
- DynaLoader (Must always be included as a static extension)
- GDBM_File i_gdbm
- NDBM_File i_ndbm
- ODBM_File i_dbm
- POSIX useposix
- Opcode useopcode
- Socket d_socket
- Threads use5005threads
-
-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
+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.
+automatically include that extension. The threading extension needs
+to be specified explicitely (see L<Threads>).
-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.
+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.
-=head2 Examples
+=head3 Examples
=over 4
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
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
+=item BerkeleyDB in /usr/local/BerkeleyDB
+
+The version of BerkeleyDB distributed by sleepycat.com installs in a
+version-specific directory by default, typically something like
+/usr/local/BerkeleyDB.4.7. To have Configure find that, you need to add
+-I/usr/local/BerkeleyDB.4.7/include to cc flags, as in the previous example,
+and you will also have to take extra steps to help Configure find -ldb.
+Specifically, when Configure prompts you for library directories,
+add /usr/local/BerkeleyDB.4.7/lib to the list. Also, you will need to
+add appropriate linker flags to tell the runtime linker where to find the
+BerkeleyDB shared libraries.
+
+It is possible to specify this from the command line (all on one
+line):
+
+ sh Configure -de \
+ -Dlocincpth='/usr/local/BerkeleyDB.4.7/include /usr/local/include' \
+ -Dloclibpth='/usr/local/BerkeleyDB.4.7/lib /usr/local/lib' \
+ -Aldflags='-R/usr/local/BerkeleyDB.4.7/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.
+
+The addition to ldflags is so that the dynamic linker knows where to find
+the BerkeleyDB libraries. For Linux and Solaris, the -R option does that.
+Other systems may use different flags. Use the appropriate flag for your
+system.
+
+=back
+
+=head2 Overriding an old config.sh
+
+If you want to use an old config.sh produced by a previous run of
+Configure, but override some of the items with command line options, you
+need to use B<Configure -O>.
+
+=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.
+
+(The file is called configure.gnu to avoid problems on systems
+that would not distinguish the files "Configure" and "configure".)
+
+=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
-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.
+=item Using the system malloc
-It is possible to specify this from the command line too (all on one
-line):
+To build without perl's malloc, you can use the Configure command
- sh Configure -de \
- -Dlocincpth="/usr/you/include" \
- -Dloclibpth="/usr/you/lib"
+ sh Configure -Uusemymalloc
-locincpth is a space-separated list of include directories to search.
-Configure will automatically add the appropriate -I directives.
+or you can answer 'n' at the appropriate interactive Configure prompt.
-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
+Note that Perl's malloc isn't always used by default; that actually
+depends on your system. For example, on Linux and FreeBSD (and many more
+systems), Configure chooses to use the system's malloc by default.
+See the appropriate file in the F<hints/> directory to see how the
+default is set.
- sh Configure -de \
- -Dlocincpth="/usr/you/include /usr/local/include" \
- -Dloclibpth="/usr/you/lib /usr/local/lib"
+=item -DPERL_POLLUTE_MALLOC
-=back
+NOTE: This flag is enabled automatically on some platforms if you just
+run Configure to accept all the defaults.
-=head2 Building DB, NDBM, and ODBM interfaces with Berkeley DB 3
+Perl's malloc family of functions are normally called Perl_malloc(),
+Perl_realloc(), Perl_calloc() and Perl_mfree().
+These names do not clash with the system versions of these functions.
-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.
+If this flag is enabled, however, Perl's malloc family of functions
+will have the same names as the system versions. This may be required
+sometimes if you have libraries that like to free() data that may have
+been allocated by Perl_malloc() and vice versa.
-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):
+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.
- 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
+=item -DPERL_DEBUGGING_MSTATS
-Optionally, if you have compiled with --enable-compat185 (not needed
-for ODBM/NDBM):
+This flag enables debugging mstats, which is required to use the
+Devel::Peek::mstat() function. You cannot enable this unless you are
+using Perl's malloc, so a typical Configure command would be
- ln -s libdb-3.so /usr/lib/libdb1.so
- ln -s libdb-3.so /usr/lib/libdb.so
+ sh Configure -Accflags=-DPERL_DEBUGGING_MSTATS -Dusemymalloc
-ODBM emulation seems not to be perfect, but is quite usable,
-using DB 3.1.17:
+to enable this option.
- lib/odbm.............FAILED at test 9
- Failed 1/64 tests, 98.44% okay
+=back
=head2 What if it doesn't work?
=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.
+Hint files tell Configure about a number of things:
+
+=over 4
+
+=item o
+
+The peculiarities or conventions of particular platforms -- non-standard
+library locations and names, default installation locations for binaries,
+and so on.
+
+=item o
+
+The deficiencies of the platform -- for example, library functions that,
+although present, are too badly broken to be usable; or limits on
+resources that are generously available on most platforms.
+
+=item o
+
+How best to optimize for the platform, both in terms of binary size and/or
+speed, and for Perl feature support. Because of wide variations in the
+implementation of shared libraries and of threading, for example, Configure
+often needs hints in order to be able to use these features.
+
+=back
+
+The perl distribution includes many system-specific hints files
+in the hints/ directory. If one of them matches your system, Configure
+will offer to use that hint file. Unless you have a very good reason
+not to, you should accept its offer.
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!!! ***
+file, which also explains hint files known as callback-units.
-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:
+Note that any hint file is read before any Policy file, meaning that
+Policy overrides hints -- see L</Site-wide Policy settings>.
- *** 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.
+=item WHOA THERE!!!
-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.
+If you are re-using an old config.sh, it's possible that Configure detects
+different values from the ones specified in this file. 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
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.
+rename it, then rerun Configure with the options you want to use.
=item Propagating your changes to config.sh
You'll probably also have to extensively modify the extension building
mechanism.
-=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, Plan 9, 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.
+subdirectory. Porting/Glossary should especially come in handy.
Ports for other systems may also be available. You should check out
http://www.cpan.org/ports for current information on ports to
various other operating systems.
-If you plan to port Perl to a new architecture study carefully the
+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 Adding extra modules to the build
+=head2 Adding extra modules to the build
You can specify extra modules or module bundles to be fetched from the
CPAN and installed as part of the Perl build. Either use the -Dextras=...
command line parameter to Configure, for example like this:
- Configure -Dextras="Compress::Zlib Bundle::LWP DBI"
+ Configure -Dextras="Bundle::LWP DBI"
or answer first 'y' to the question 'Install any extra modules?' and
-then answer "Compress::Zlib Bundle::LWP DBI" to the 'Extras?' question.
+then answer "Bundle::LWP DBI" to the 'Extras?' question.
The module or the bundle names are as for the CPAN module 'install' command.
+This will only work if those modules are to be built as dynamic
+extensions. If you wish to include those extra modules as static
+extensions, see L<"Extensions"> above.
Notice that because the CPAN module will be used to fetch the extra
modules, you will need access to the CPAN, either via the Internet,
Also notice that you yourself are responsible for satisfying any extra
dependencies such as external headers or libraries BEFORE trying the build.
-For example: you will need to have the zlib.h header and the libz
-library installed for the Compress::Zlib, or the Foo database specific
+For example: you will need to have the Foo database specific
headers and libraries installed for the DBD::Foo module. The Configure
process or the Perl build process will not help you with these.
-=head1 suidperl
+=head2 suidperl
-suidperl is an optional component, which is built or installed by default.
-From perlfaq1:
+suidperl is an optional component, which is normally neither built
+nor installed by default. From perlfaq1:
On some systems, setuid and setgid scripts (scripts written
in the C shell, Bourne shell, or Perl, for example, with the
of properly security auditing as large and complex piece of
software as Perl, we cannot recommend using suidperl and the feature
should be considered deprecated.
-Instead use for example 'sudo': http://www.courtesan.com/sudo/
+
+Instead, use a tool specifically designed to handle changes in
+privileges, such as B<sudo>.
=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.
+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.)
This will attempt to make perl in the current directory.
+=head2 Expected errors
+
+These error reports are normal, and can be ignored:
+
+ ...
+ make: [extra.pods] Error 1 (ignored)
+ ...
+ make: [extras.make] Error 1 (ignored)
+
=head2 What if it doesn't work?
If you can't compile successfully, try some of the following ideas.
=item extensions
If you can successfully build miniperl, but the process crashes
-during the building of extensions, you should run
+during the building of extensions, run
make minitest
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.
+whole L<perllocale/"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.
at Perl startup.
+=item other environment variables
+
+Configure does not check for environment variables that can sometimes
+have a major influence on how perl is built or tested. For example,
+OBJECT_MODE on AIX determines the way the compiler and linker deal with
+their objects, but this is a variable that only influences build-time
+behaviour, and should not affect the perl scripts that are eventually
+executed by the perl binary. Other variables, like PERL_UNICODE,
+PERL5LIB, and PERL5OPT will influence the behaviour of the test suite.
+So if you are getting strange test failures, you may want to try
+retesting with the various PERL variables unset.
+
=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
+in config.sh. The problem is usually solved by installing gcc
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.
with BIND 8.1 or rename /usr/local/bin/arpa/inet.h during the Perl build and
test process to avoid the problem.
-=item *_r() prototype NOT found
+=item .*_r() prototype NOT found
On a related note, if you see a bunch of complaints like the above about
reentrant functions - specifically networking-related ones - being present
other BIND 8 versions) is (or has been) installed. They install
header files such as netdb.h into places such as /usr/local/include (or into
another directory as specified at build/install time), at least optionally.
-Remove them or put them in someplace that isn't in the C preprocessor's
+Remove them or put them in someplace that isn't in the C preprocessor's
header file include search path (determined by -I options plus defaults,
normally /usr/include).
then propagate your changes with B<sh Configure -S> and rebuild
with B<make depend; make>.
-=item Missing functions
+=item Missing functions and Undefined symbols
+
+If the build of miniperl fails with a long list of missing functions or
+undefined symbols, check the libs variable in the config.sh file. It
+should look something like
+
+ libs='-lsocket -lnsl -ldl -lm -lc'
+
+The exact libraries will vary from system to system, but you typically
+need to include at least the math library -lm. Normally, Configure
+will suggest the correct defaults. If the libs variable is empty, you
+need to start all over again. Run
+
+ make distclean
+
+and start from the very beginning. This time, unless you are sure of
+what you are doing, accept the default list of libraries suggested by
+Configure.
+
+If the libs variable looks correct, you might have the
+L<"nm extraction"> problem discussed above.
-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.
+If you stil have missing routines or undefined symbols, 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. If
+you used a hint file, see if it has any relevant advice. You can also
+look through through config.h for likely suspects.
=item toke.c
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.
+Most users will see warnings for the ones 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
=item invalid token: ##
-You are using a non-ANSI-compliant C compiler. See L<WARNING: This
-version requires a compiler that supports ANSI C>.
+You are using a non-ANSI-compliant C compiler. To compile Perl, you
+need to use a compiler that supports ANSI C. If there is a README
+file for your system, it may have further details on your compiler
+options.
=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.
FreeBSD can fail the ext/IPC/SysV/t/sem.t test if SysV IPC has not been
configured in the kernel. Perl tries to detect this, though, and
-you will get a message telling 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).
+you will get a message telling you what to do.
Building Perl on a system that has also BIND (headers and libraries)
installed may run into troubles because BIND installs its own netdb.h
=head2 Cross-compilation
-Starting from Perl 5.8 Perl has the beginnings of cross-compilation
-support. What is known to work is running Configure in a
-cross-compilation environment and building the miniperl executable.
-What is known not to work is building the perl executable because
-that would require building extensions: Dynaloader statically and
-File::Glob dynamically, for extensions one needs MakeMaker and
-MakeMaker is not yet cross-compilation aware, and neither is
-the main Makefile.
-
-Since the functionality is so lacking, it must be considered
-highly experimental. It is so experimental that it is not even
-mentioned during an interactive Configure session, a direct command
-line invocation (detailed shortly) is required to access the
-functionality.
-
- NOTE: Perl is routinely built using cross-compilation
- in the EPOC environment, in the WinCE, and in the OpenZaurus
- project, but all those use something slightly different setup
- than what described here. For the WinCE setup, read the
- wince/README.compile. For the OpenZaurus setup, read the
- Cross/README.
-
-The one environment where this cross-compilation setup has
-successfully been used as of this writing is the Compaq iPAQ running
-ARM Linux. The build host was Intel Linux, the networking setup was
-PPP + SSH. The exact setup details are beyond the scope of this
-document, see http://www.handhelds.org/ for more information.
-
-To run Configure in cross-compilation mode the basic switch is
-C<-Dusecrosscompile>.
+Perl can be cross-compiled. It is just not trivial, cross-compilation
+rarely is. Perl is routinely cross-compiled for many platforms (as of
+June 2005 at least PocketPC aka WinCE, Open Zaurus, EPOC, Symbian, and
+the IBM OS/400). These platforms are known as the B<target> platforms,
+while the systems where the compilation takes place are the B<host>
+platforms.
+
+What makes the situation difficult is that first of all,
+cross-compilation environments vary significantly in how they are set
+up and used, and secondly because the primary way of configuring Perl
+(using the rather large Unix-tool-dependent Configure script) is not
+awfully well suited for cross-compilation. However, starting from
+version 5.8.0, the Configure script also knows one way of supporting
+cross-compilation support, please keep reading.
+
+See the following files for more information about compiling Perl for
+the particular platforms:
+
+=over 4
+
+=item WinCE/PocketPC
+
+README.ce
+
+=item Open Zaurus
+
+Cross/README
+
+=item EPOC
+
+README.epoc
+
+=item Symbian
+
+README.symbian
+
+=item OS/400
+
+README.os400
+
+=back
+
+Packaging and transferring either the core Perl modules or CPAN
+modules to the target platform is also left up to the each
+cross-compilation environment. Often the cross-compilation target
+platforms are somewhat limited in diskspace: see the section
+L<Minimizing the Perl installation> to learn more of the minimal set
+of files required for a functional Perl installation.
+
+For some cross-compilation environments the Configure option
+C<-Dinstallprefix=...> might be handy, see L<Changing the installation
+directory>.
+
+About the cross-compilation support of Configure: what is known to
+work is running Configure in a cross-compilation environment and
+building the miniperl executable. What is known not to work is
+building the perl executable because that would require building
+extensions: Dynaloader statically and File::Glob dynamically, for
+extensions one needs MakeMaker and MakeMaker is not yet
+cross-compilation aware, and neither is the main Makefile.
+
+The cross-compilation setup of Configure has successfully been used in
+at least two Linux cross-compilation environments. The setups were
+both such that the host system was Intel Linux with a gcc built for
+cross-compiling into ARM Linux, and there was a SSH connection to the
+target system.
+
+To run Configure in cross-compilation mode the basic switch that
+has to be used is C<-Dusecrosscompile>.
sh ./Configure -des -Dusecrosscompile -D...
This will make the cpp symbol USE_CROSS_COMPILE and the %Config
-symbol C<usecrosscompile> available.
+symbol C<usecrosscompile> available, and C<xconfig.h> will be used
+for cross-compilation.
During the Configure and build, certain helper scripts will be created
into the Cross/ subdirectory. The scripts are used to execute a
-Dlibpth=/skiff/local/arm-linux/lib \
-D...
-or if you are happy with the defaults
+or if you are happy with the defaults:
sh ./Configure -des -Dusecrosscompile \
-Dtargethost=so.me.ho.st \
-Dcc=arm-linux-gcc \
-D...
+Another example where the cross-compiler has been installed under
+F</usr/local/arm/2.95.5>:
+
+ sh ./Configure -des -Dusecrosscompile \
+ -Dtargethost=so.me.ho.st \
+ -Dcc=/usr/local/arm/2.95.5/bin/arm-linux-gcc \
+ -Dincpth=/usr/local/arm/2.95.5/include \
+ -Dusrinc=/usr/local/arm/2.95.5/include \
+ -Dlibpth=/usr/local/arm/2.95.5/lib
+
=head1 make test
This will run the regression tests on the perl you just made. If
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
+ cd t ; ./perl -MTestInit 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
+ cd t ; ./perl harness <list of tests>
(this assumes that most basic tests succeed, since harness uses
-complicated constructs). For extension and library tests you
-need a little bit more: you need to setup your environment variable
-PERL_CORE to a true value (like "1"), and you need to supply the
-right Perl library path:
+complicated constructs). If no list of tests is provided, harness
+will run all tests.
- setenv PERL_CORE 1
- ./perl -I../lib ../ext/Socket/Socket.t
- ./perl -I../lib ../lib/less.t
-
-(For csh-like shells on UNIX; adjust appropriately for other platforms.)
You should also read the individual tests to see if there are any helpful
comments that apply to your system. You may also need to setup your
shared library path if you get errors like:
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
+'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.
these tests might fail. If possible, try running the tests again
with the system under a lighter load. These timing-sensitive
and load-sensitive tests include F<t/op/alarm.t>,
-F<ext/Time/HiRes/HiRes.t>, F<lib/Benchmark.t>,
+F<ext/Time-HiRes/t/HiRes.t>, F<ext/threads-shared/t/waithires.t>,
+F<ext/threads-shared/t/stress.t>, F<lib/Benchmark.t>,
F<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
+You might also experience some failures in F<t/op/stat.t> if you build
+perl on an NFS filesystem, if the remote clock and the system clock are
+different.
+
=item Out of memory
On some systems, particularly those with smaller amounts of RAM, some
Try stopping other jobs on the system and then running the test by itself:
- cd t; ./perl op/pat.t
+ cd t; ./perl -MTestInit 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 libgcc_s.so.1: cannot open shared object file
+
+This message has been reported on gcc-3.2.3 and earlier installed with
+a non-standard prefix. Setting the LD_LIBRARY_PATH environment variable
+(or equivalent) to include gcc's lib/ directory with the libgcc_s.so.1
+shared library should fix the problem.
+
=item Failures from lib/File/Temp/t/security saying "system possibly insecure"
First, such warnings are not necessarily serious or indicative of a
=back
+The core distribution can now run its regression tests in parallel on
+Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in
+your environment to the number of tests to run in parallel, and run
+C<make test_harness>. On a Bourne-like shell, this can be done as
+
+ TEST_JOBS=3 make test_harness # Run 3 tests in parallel
+
+An environment variable is used, rather than parallel make itself, because
+L<TAP::Harness> needs to be able to schedule individual non-conflicting test
+scripts itself, and there is no standard interface to C<make> utilities to
+interact with their job schedulers.
+
=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.
+are not root, you must still have permission to install into the directories
+in question and you should ignore any messages about chown not working.
+
+If "make install" just says "`install' is up to date" or something
+similar, you may be on a case-insensitive filesystems such as Mac's HFS+,
+and you should say "make install-all". (This confusion is brought to you
+by the Perl distribution having a file called INSTALL.)
=head2 Installing perl under different names
make install PERLNAME=myperl
You can separately change the base used for versioned names (like
-"perl5.005") by setting PERLNAME_VERBASE, like
+"perl5.8.9") by setting PERLNAME_VERBASE, like
make install PERLNAME=perl5 PERLNAME_VERBASE=perl
This can be useful if you have to install perl as "perl5" (e.g. to
avoid conflicts with an ancient version in /usr/bin supplied by your vendor).
-Without this the versioned binary would be called "perl55.005".
+Without this the versioned binary would be called "perl55.8.8".
+
+=head2 Installing perl under a different directory
+
+You can install perl under a different destination directory by using
+the DESTDIR variable during C<make install>, with a command like
+
+ make install DESTDIR=/tmp/perl5
+
+DESTDIR is automatically prepended to all the installation paths. See
+the example in L<"DESTDIR"> above.
=head2 Installed files
binaries
perl,
- perl5.nnn where nnn is the current release number. This
+ perl5.n.n where 5.n.n is the current release number. This
will be a link to perl.
suidperl,
- sperl5.nnn If you requested setuid emulation.
+ sperl5.n.n 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.
+ cppstdin This is used by the deprecated switch 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
+ config_data Manage Module::Build-like module configuration
+ corelist Shows versions of modules that come with different
+ versions of perl
+ cpan The CPAN shell
+ cpan2dist The CPANPLUS distribution creator
+ cpanp The CPANPLUS shell
+ cpanp-run-perl An helper for cpanp
+ dprofpp Perl code profiler post-processor
+ enc2xs Encoding module generator
find2perl find-to-perl translator
h2ph Extract constants and simple macros from C headers
h2xs Converts C .h header files to Perl extensions.
+ instmodsh A shell to examine installed modules.
+ libnetcfg Configure libnet.
perlbug Tool to report bugs in Perl.
perldoc Tool to read perl's pod documentation.
+ perlivp Perl Installation Verification Procedure
+ piconv A Perl implementation of the encoding conversion
+ utility iconv
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
+ podchecker POD syntax checker
+ podselect Prints sections of POD documentation
+ prove A command-line tool for running tests
+ psed A Perl implementation of sed
+ ptar A Perl implementation of tar
+ ptardiff A diff for tar archives
+ s2p sed-to-perl translator
+ shasum A tool to print or check SHA checksums
splain Describe Perl warnings and errors
- dprofpp Perl code profile post-processor
+ xsubpp Compiler to convert Perl XS code into C code
library files
pages in $man3dir, usually /usr/local/man/man3.
pod/*.pod in $privlib/pod/.
-Installperl will also create the directories listed above
+installperl will also create the directories listed above
in L<"Installation Directories">.
Perl's *.h header files and the libperl library are also installed
optional Perl compiler, or embed the perl interpreter into another
program even if the Perl source is no longer available.
+=head2 Installing only version-specific parts
+
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
+perl alongside an already installed production version without
disabling installation of new modules for the production version.
To only install the version-specific parts of the perl installation, 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
+=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>)
-Perl 5.8 is not binary compatible with earlier versions of Perl.
+=head1 Starting all over again
+
+If you wish to re-build perl from the same build directory, you should
+clean it out 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.
+
+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 not re-use
+your old config.sh.
+
+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"> above.
+
+=head1 Reporting Problems
+
+Wherever possible please use the perlbug tool supplied with this Perl
+to report problems, as it automatically includes summary configuration
+information about your perl, which may help us track down problems far
+more quickly. But first you should read the advice in this file,
+carefully re-read the error message and check the relevant manual pages
+on your system, as these may help you find an immediate solution. If
+you are not sure whether what you are seeing is a bug, you can send a
+message describing the problem to the comp.lang.perl.misc newsgroup to
+get advice.
+
+The perlbug tool is installed along with perl, so after you have
+completed C<make install> it should be possible to run it with plain
+C<perlbug>. If the install fails, or you want to report problems with
+C<make test> without installing perl, then you can use C<make nok> to
+run perlbug to report the problem, or run it by hand from this source
+directory with C<./perl -Ilib utils/perlbug>
+
+If the build fails too early to run perlbug uninstalled, then please
+B<run> the C<./myconfig> shell script, and mail its output along with
+an accurate description of your problem to perlbug@perl.org
+
+If Configure itself fails, and does not generate a config.sh file
+(needed to run C<./myconfig>), then please mail perlbug@perl.org the
+description of how Configure fails along with details of your system
+- for example the output from running C<uname -a>
+
+Please try to make your message brief but clear. Brief, clear bug
+reports tend to get answered more quickly. Please don't worry if your
+written English is not great - what matters is how well you describe
+the important technical details of the problem you have encountered,
+not whether your grammar and spelling is flawless.
+
+Trim out unnecessary information. Do not include large files (such as
+config.sh or a complete Configure or make log) unless absolutely
+necessary. Do not include a complete transcript of your build
+session. Just include the failing commands, the relevant error
+messages, and whatever preceding commands are necessary to give the
+appropriate context. Plain text should usually be sufficient--fancy
+attachments or encodings may actually reduce the number of people who
+read your message. Your message will get relayed to over 400
+subscribers around the world so please try to keep it brief but clear.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for security
+issues in the Perl core, not for modules independently distributed on CPAN.
+
+If you are unsure what makes a good bug report please read "How to
+report Bugs Effectively" by Simon Tatham:
+http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
+
+=head1 Coexistence with earlier versions of perl 5
+
+Perl 5.11 is not binary compatible with earlier versions of Perl.
In other words, you will have to recompile your XS modules.
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.
-
-Usually, most extensions will probably not need to be recompiled to
-use with a newer version of Perl (the Perl 5.6 to Perl 5.8 transition
-being an exception). 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
+5.X.Y) to another similar minor version (e.g. 5.X.(Y+1))) without
+re-compiling all of your extensions. You can also safely leave the old
+version around in case the new version causes you problems for some reason.
+
+Usually, most extensions will probably not need to be recompiled to be
+used 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.8.7 installed. The directories
+searched by 5.8.7 are typically like:
+
+ /usr/local/lib/perl5/5.8.7/$archname
+ /usr/local/lib/perl5/5.8.7
+ /usr/local/lib/perl5/site_perl/5.8.7/$archname
+ /usr/local/lib/perl5/site_perl/5.8.7
+
+Now, suppose you install version 5.8.8. The directories
+searched by version 5.8.8 will be:
+
+ /usr/local/lib/perl5/5.8.8/$archname
+ /usr/local/lib/perl5/5.8.8
+ /usr/local/lib/perl5/site_perl/5.8.8/$archname
+ /usr/local/lib/perl5/site_perl/5.8.8
+
+ /usr/local/lib/perl5/site_perl/5.8.7/$archname
+ /usr/local/lib/perl5/site_perl/5.8.7
/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,
+directories. This way, modules installed under 5.8.7 will continue
+to be usable by 5.8.7 but will also accessible to 5.8.8. 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.
+present only in 5.8.8. That new module will get installed into
+/usr/local/lib/perl5/site_perl/5.8.8 and will be available to 5.8.8,
+but will not interfere with the 5.8.7 version.
The last entry, /usr/local/lib/perl5/site_perl/, is there so that
5.6.0 and above will look for 5.004-era pure perl modules.
-Lastly, suppose you now install 5.8.0, which is not binary compatible
-with 5.6.0. The directories searched by 5.8.0 (if you don't change the
+Lastly, suppose you now install 5.10.0, which is not binary compatible
+with 5.8.x. The directories searched by 5.10.0 (if you don't change the
Configure defaults) will be:
- /usr/local/lib/perl5/5.8.0/$archname
- /usr/local/lib/perl5/5.8.0
- /usr/local/lib/perl5/site_perl/5.8.0/$archname
- /usr/local/lib/perl5/site_perl/5.8.0
+ /usr/local/lib/perl5/5.10.0/$archname
+ /usr/local/lib/perl5/5.10.0
+ /usr/local/lib/perl5/site_perl/5.10.0/$archname
+ /usr/local/lib/perl5/site_perl/5.10.0
- /usr/local/lib/perl5/site_perl/5.6.0
+ /usr/local/lib/perl5/site_perl/5.8.8
- /usr/local/lib/perl5/site_perl/5.005
+ /usr/local/lib/perl5/site_perl/5.8.7
/usr/local/lib/perl5/site_perl/
Note that the earlier $archname entries are now gone, but pure perl
modules from earlier versions will still be found.
-Assuming the users in your site are still actively using perl 5.6.0 and
-5.005 after you installed 5.8.0, you can continue to install add-on
-extensions using any of perl 5.8.0, 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
-compatible site libraries of the older ones. This means that
-installing a new XS extension with 5.005 will make it visible to both
-5.005 and 5.6.0, but not to 5.8.0. Installing a pure perl module with
-5.005 will make it visible to all three versions. Later, if you
-install the same extension using, say, perl 5.8.0, it will override the
-5.005-installed version, but only for perl 5.8.0.
-
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.
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
+ sh Configure -Dprefix=/opt/perl5.11.0
-and adding /opt/perl5.004/bin to the shell PATH variable. Such users
+and adding /opt/perl5.11.0/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.8 for all 5.8.x versions), but change directory with
+(e.g. 5.10 for all 5.10.x versions), but change directory with
each major version.
If you are installing a development subversion, you probably ought to
subversions may not have all the compatibility wrinkles ironed out
yet.
-=head2 Upgrading from 5.005 or 5.6 to 5.8.0
+=head2 Upgrading from 5.10.x or earlier
-B<Perl 5.8.0 is binary incompatible with Perl 5.6.1, 5.6.0, 5.005,
-and any earlier Perl release.> Perl modules having binary parts
+B<Perl 5.11.0 is binary incompatible with Perl 5.10.x and any earlier
+Perl release.> Perl modules having binary parts
(meaning that a C compiler is used) will have to be recompiled to be
-used with 5.8.0. If you find you do need to rebuild an extension with
-5.8.0, you may safely do so without disturbing the 5.005 or 5.6.0
-installations. (See L<"Coexistence with earlier versions of perl5">
+used with 5.11.0. If you find you do need to rebuild an extension with
+5.11.0, you may safely do so without disturbing the older
+installations. (See L<"Coexistence with earlier versions of perl 5">
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 Minimizing the Perl installation
The following section is meant for people worrying about squeezing the
print("$f\n");
}
-in Solaris is as follows (under $Config{prefix}):
+in Linux is as follows (under $Config{prefix}):
./bin/perl
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/autosplit.ix
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_expandspec.al
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_find_symbol_anywhere.al
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/DynaLoader/dl_findfile.al
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/Glob.so
- ./lib/perl5/5.6.1/sun4-solaris-64int/auto/File/Glob/autosplit.ix
- ./lib/perl5/5.6.1/sun4-solaris-64int/Config.pm
- ./lib/perl5/5.6.1/sun4-solaris-64int/XSLoader.pm
- ./lib/perl5/5.6.1/sun4-solaris-64int/DynaLoader.pm
- ./lib/perl5/5.6.1/sun4-solaris-64int/CORE/libperl.so
- ./lib/perl5/5.6.1/strict.pm
- ./lib/perl5/5.6.1/warnings.pm
- ./lib/perl5/5.6.1/Carp.pm
- ./lib/perl5/5.6.1/Exporter.pm
- ./lib/perl5/5.6.1/File/Glob.pm
- ./lib/perl5/5.6.1/AutoLoader.pm
- ./lib/perl5/5.6.1/vars.pm
- ./lib/perl5/5.6.1/warnings/register.pm
- ./lib/perl5/5.6.1/Carp/Heavy.pm
- ./lib/perl5/5.6.1/Exporter/Heavy.pm
+ ./lib/perl5/5.9.3/strict.pm
+ ./lib/perl5/5.9.3/warnings.pm
+ ./lib/perl5/5.9.3/i686-linux/File/Glob.pm
+ ./lib/perl5/5.9.3/i686-linux/XSLoader.pm
+ ./lib/perl5/5.9.3/i686-linux/auto/File/Glob/Glob.so
Secondly, Debian perl-base package contains the following files,
-size about 1.2MB in its i386 version:
+size about 1.9MB in its i386 version:
- /usr/share/doc/perl/Documentation
- /usr/share/doc/perl/README.Debian
- /usr/share/doc/perl/copyright
+ /usr/bin/perl
+ /usr/bin/perl5.8.4
+ /usr/lib/perl/5.8
+ /usr/lib/perl/5.8.4/B.pm
+ /usr/lib/perl/5.8.4/B/Deparse.pm
+ /usr/lib/perl/5.8.4/Config.pm
+ /usr/lib/perl/5.8.4/Cwd.pm
+ /usr/lib/perl/5.8.4/Data/Dumper.pm
+ /usr/lib/perl/5.8.4/DynaLoader.pm
+ /usr/lib/perl/5.8.4/Errno.pm
+ /usr/lib/perl/5.8.4/Fcntl.pm
+ /usr/lib/perl/5.8.4/File/Glob.pm
+ /usr/lib/perl/5.8.4/IO.pm
+ /usr/lib/perl/5.8.4/IO/File.pm
+ /usr/lib/perl/5.8.4/IO/Handle.pm
+ /usr/lib/perl/5.8.4/IO/Pipe.pm
+ /usr/lib/perl/5.8.4/IO/Seekable.pm
+ /usr/lib/perl/5.8.4/IO/Select.pm
+ /usr/lib/perl/5.8.4/IO/Socket.pm
+ /usr/lib/perl/5.8.4/POSIX.pm
+ /usr/lib/perl/5.8.4/Socket.pm
+ /usr/lib/perl/5.8.4/XSLoader.pm
+ /usr/lib/perl/5.8.4/auto/Cwd/Cwd.bs
+ /usr/lib/perl/5.8.4/auto/Cwd/Cwd.so
+ /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.bs
+ /usr/lib/perl/5.8.4/auto/Data/Dumper/Dumper.so
+ /usr/lib/perl/5.8.4/auto/DynaLoader/DynaLoader.a
+ /usr/lib/perl/5.8.4/auto/DynaLoader/autosplit.ix
+ /usr/lib/perl/5.8.4/auto/DynaLoader/dl_expandspec.al
+ /usr/lib/perl/5.8.4/auto/DynaLoader/dl_find_symbol_anywhere.al
+ /usr/lib/perl/5.8.4/auto/DynaLoader/dl_findfile.al
+ /usr/lib/perl/5.8.4/auto/DynaLoader/extralibs.ld
+ /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.bs
+ /usr/lib/perl/5.8.4/auto/Fcntl/Fcntl.so
+ /usr/lib/perl/5.8.4/auto/File/Glob/Glob.bs
+ /usr/lib/perl/5.8.4/auto/File/Glob/Glob.so
+ /usr/lib/perl/5.8.4/auto/IO/IO.bs
+ /usr/lib/perl/5.8.4/auto/IO/IO.so
+ /usr/lib/perl/5.8.4/auto/POSIX/POSIX.bs
+ /usr/lib/perl/5.8.4/auto/POSIX/POSIX.so
+ /usr/lib/perl/5.8.4/auto/POSIX/autosplit.ix
+ /usr/lib/perl/5.8.4/auto/POSIX/load_imports.al
+ /usr/lib/perl/5.8.4/auto/Socket/Socket.bs
+ /usr/lib/perl/5.8.4/auto/Socket/Socket.so
+ /usr/lib/perl/5.8.4/lib.pm
+ /usr/lib/perl/5.8.4/re.pm
+ /usr/share/doc/perl-base
/usr/share/doc/perl/AUTHORS.gz
+ /usr/share/doc/perl/Documentation
+ /usr/share/doc/perl/README.Debian.gz
/usr/share/doc/perl/changelog.Debian.gz
+ /usr/share/doc/perl/copyright
/usr/share/man/man1/perl.1.gz
- /usr/share/perl/5.6.1/AutoLoader.pm
- /usr/share/perl/5.6.1/Carp.pm
- /usr/share/perl/5.6.1/Carp/Heavy.pm
- /usr/share/perl/5.6.1/Cwd.pm
- /usr/share/perl/5.6.1/Exporter.pm
- /usr/share/perl/5.6.1/Exporter/Heavy.pm
- /usr/share/perl/5.6.1/File/Spec.pm
- /usr/share/perl/5.6.1/File/Spec/Unix.pm
- /usr/share/perl/5.6.1/FileHandle.pm
- /usr/share/perl/5.6.1/Getopt/Long.pm
- /usr/share/perl/5.6.1/IO/Socket/INET.pm
- /usr/share/perl/5.6.1/IO/Socket/UNIX.pm
- /usr/share/perl/5.6.1/IPC/Open2.pm
- /usr/share/perl/5.6.1/IPC/Open3.pm
- /usr/share/perl/5.6.1/SelectSaver.pm
- /usr/share/perl/5.6.1/Symbol.pm
- /usr/share/perl/5.6.1/Text/Tabs.pm
- /usr/share/perl/5.6.1/Text/Wrap.pm
- /usr/share/perl/5.6.1/attributes.pm
- /usr/share/perl/5.6.1/auto/Getopt/Long/GetOptions.al
- /usr/share/perl/5.6.1/auto/Getopt/Long/FindOption.al
- /usr/share/perl/5.6.1/auto/Getopt/Long/Configure.al
- /usr/share/perl/5.6.1/auto/Getopt/Long/config.al
- /usr/share/perl/5.6.1/auto/Getopt/Long/Croak.al
- /usr/share/perl/5.6.1/auto/Getopt/Long/autosplit.ix
- /usr/share/perl/5.6.1/base.pm
- /usr/share/perl/5.6.1/constant.pm
- /usr/share/perl/5.6.1/fields.pm
- /usr/share/perl/5.6.1/integer.pm
- /usr/share/perl/5.6.1/lib.pm
- /usr/share/perl/5.6.1/locale.pm
- /usr/share/perl/5.6.1/overload.pm
- /usr/share/perl/5.6.1/strict.pm
- /usr/share/perl/5.6.1/vars.pm
- /usr/share/perl/5.6.1/warnings.pm
- /usr/share/perl/5.6.1/warnings/register.pm
- /usr/bin/perl
- /usr/lib/perl/5.6.1/Config.pm
- /usr/lib/perl/5.6.1/Data/Dumper.pm
- /usr/lib/perl/5.6.1/DynaLoader.pm
- /usr/lib/perl/5.6.1/Errno.pm
- /usr/lib/perl/5.6.1/Fcntl.pm
- /usr/lib/perl/5.6.1/File/Glob.pm
- /usr/lib/perl/5.6.1/IO.pm
- /usr/lib/perl/5.6.1/IO/File.pm
- /usr/lib/perl/5.6.1/IO/Handle.pm
- /usr/lib/perl/5.6.1/IO/Pipe.pm
- /usr/lib/perl/5.6.1/IO/Seekable.pm
- /usr/lib/perl/5.6.1/IO/Select.pm
- /usr/lib/perl/5.6.1/IO/Socket.pm
- /usr/lib/perl/5.6.1/POSIX.pm
- /usr/lib/perl/5.6.1/Socket.pm
- /usr/lib/perl/5.6.1/XSLoader.pm
- /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.so
- /usr/lib/perl/5.6.1/auto/Data/Dumper/Dumper.bs
- /usr/lib/perl/5.6.1/auto/DynaLoader/dl_findfile.al
- /usr/lib/perl/5.6.1/auto/DynaLoader/dl_expandspec.al
- /usr/lib/perl/5.6.1/auto/DynaLoader/dl_find_symbol_anywhere.al
- /usr/lib/perl/5.6.1/auto/DynaLoader/autosplit.ix
- /usr/lib/perl/5.6.1/auto/DynaLoader/DynaLoader.a
- /usr/lib/perl/5.6.1/auto/DynaLoader/extralibs.ld
- /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.so
- /usr/lib/perl/5.6.1/auto/Fcntl/Fcntl.bs
- /usr/lib/perl/5.6.1/auto/File/Glob/Glob.bs
- /usr/lib/perl/5.6.1/auto/File/Glob/Glob.so
- /usr/lib/perl/5.6.1/auto/File/Glob/autosplit.ix
- /usr/lib/perl/5.6.1/auto/IO/IO.so
- /usr/lib/perl/5.6.1/auto/IO/IO.bs
- /usr/lib/perl/5.6.1/auto/POSIX/POSIX.bs
- /usr/lib/perl/5.6.1/auto/POSIX/POSIX.so
- /usr/lib/perl/5.6.1/auto/POSIX/autosplit.ix
- /usr/lib/perl/5.6.1/auto/POSIX/load_imports.al
- /usr/lib/perl/5.6.1/auto/Socket/Socket.so
- /usr/lib/perl/5.6.1/auto/Socket/Socket.bs
-
-=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.
+ /usr/share/perl/5.8
+ /usr/share/perl/5.8.4/AutoLoader.pm
+ /usr/share/perl/5.8.4/Carp.pm
+ /usr/share/perl/5.8.4/Carp/Heavy.pm
+ /usr/share/perl/5.8.4/Exporter.pm
+ /usr/share/perl/5.8.4/Exporter/Heavy.pm
+ /usr/share/perl/5.8.4/File/Spec.pm
+ /usr/share/perl/5.8.4/File/Spec/Unix.pm
+ /usr/share/perl/5.8.4/FileHandle.pm
+ /usr/share/perl/5.8.4/Getopt/Long.pm
+ /usr/share/perl/5.8.4/IO/Socket/INET.pm
+ /usr/share/perl/5.8.4/IO/Socket/UNIX.pm
+ /usr/share/perl/5.8.4/IPC/Open2.pm
+ /usr/share/perl/5.8.4/IPC/Open3.pm
+ /usr/share/perl/5.8.4/List/Util.pm
+ /usr/share/perl/5.8.4/Scalar/Util.pm
+ /usr/share/perl/5.8.4/SelectSaver.pm
+ /usr/share/perl/5.8.4/Symbol.pm
+ /usr/share/perl/5.8.4/Text/ParseWords.pm
+ /usr/share/perl/5.8.4/Text/Tabs.pm
+ /usr/share/perl/5.8.4/Text/Wrap.pm
+ /usr/share/perl/5.8.4/attributes.pm
+ /usr/share/perl/5.8.4/base.pm
+ /usr/share/perl/5.8.4/bytes.pm
+ /usr/share/perl/5.8.4/bytes_heavy.pl
+ /usr/share/perl/5.8.4/constant.pm
+ /usr/share/perl/5.8.4/fields.pm
+ /usr/share/perl/5.8.4/integer.pm
+ /usr/share/perl/5.8.4/locale.pm
+ /usr/share/perl/5.8.4/overload.pm
+ /usr/share/perl/5.8.4/strict.pm
+ /usr/share/perl/5.8.4/utf8.pm
+ /usr/share/perl/5.8.4/utf8_heavy.pl
+ /usr/share/perl/5.8.4/vars.pm
+ /usr/share/perl/5.8.4/warnings.pm
+ /usr/share/perl/5.8.4/warnings/register.pm
+
+A nice trick to find out the minimal set of Perl library files you will
+need to run a Perl program is
+
+ perl -e 'do "prog.pl"; END { print "$_\n" for sort keys %INC }'
+
+(this will not find libraries required in runtime, unfortunately, but
+it's a minimal set) and if you want to find out all the files you can
+use something like the below
+
+ strace perl -le 'do "x.pl"' 2>&1 | perl -nle '/^open\(\"(.+?)"/ && print $1'
+
+(The 'strace' is Linux-specific, other similar utilities include 'truss'
+and 'ktrace'.)
+
+=head2 C<-DNO_MATHOMS>
+
+If you configure perl with C<-Accflags=-DNO_MATHOMS>, the functions from
+F<mathoms.c> will not be compiled in. Those functions are no longer used
+by perl itself; for source compatibility reasons, though, they weren't
+completely removed.
=head1 DOCUMENTATION
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
https://perl5.git.perl.org / perl5.git / blobdiff