First, make sure you have an up-to-date version of Perl. If you
didn't get your Perl source from CPAN, check the latest version at
http://www.cpan.org/src/. Perl uses a version scheme where even-numbered
-subreleases (like 5.6.x and 5.8.x) are stable maintenance releases and
+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
# You may also wish to add these:
(cd /usr/include && h2ph *.h sys/*.h)
(installhtml --help)
- (cd pod && make tex && <process the latex files>)
+ (cd pod && make tex && <process the latex files>)
or you can use some of the Configure options described below.
L<"Reporting Problems"> above.
For information on what's new in this release, see the
-pod/perldelta.pod file. For more detailed information about specific
+pod/perl5100delta.pod file. For more detailed information about specific
changes, see the Changes file.
=head1 DESCRIPTION
=head2 Changes and Incompatibilities
-Please see pod/perldelta.pod for a description of the changes and
+Please see pod/perl5100delta.pod for a description of the changes and
potential incompatibilities introduced with this release. A few of
the most important issues are listed below, but you should refer
-to pod/perldelta.pod for more detailed information.
+to pod/perl5100delta.pod for more detailed information.
-=head3 WARNING: This version is not binary compatible with releases of
-Perl prior to 5.9.0.
+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
On a related issue, old modules may possibly be affected by the changes
in the Perl language in the current release. Please see
-pod/perldelta.pod for a description of what's changed. See your
+pod/perl5100delta.pod for a description of what's changed. See your
installed copy of the perllocal.pod file for a (possibly incomplete)
list of locally installed modules. Also see CPAN::autobundle for one
way to make a "bundle" of your currently installed modules.
-=head2 Space Requirements
-
-The complete perl5 source tree takes up about 60 MB of disk space.
-After completing make, it takes up roughly 100 MB, though the actual
-total is likely to be quite system-dependent. The installation
-directories need something on the order of 45 MB, though again that
-value is system-dependent. A perl build with debug symbols and
--DDEBUGGING will require something on the order of 10 MB extra.
-
=head1 Start with a Fresh Distribution
If you have built perl before, you should clean out the build directory
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.
+Configure for a different version, e.g. 5.004. 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.
+Linux distributions use i386, but Configure uses the output of the arch
+command, which might be 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.
=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
For example, here's how to add a couple of extra flags to C compiler
invocations:
- sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DPERL_POLLUTE_MALLOC"
+ sh Configure -Accflags="-DPERL_EXTERNAL_GLOB -DNO_HASH_SEED"
+
+To clarify, those ccflags values are not Configure options; if passed to
+Configure directly, they won't do anything useful (that will define a config.sh
+variable, but without taking any action based upon it). When passed to the
+compiler, those flags will activate #ifdefd code.
For more help on Configure switches, run
The default is to compile without thread support.
-Perl has two different internal threads implementations. The current
-model (available internally since 5.6, and as a user-level module since
-5.8) is called interpreter-based implementation (ithreads), with one
-interpreter per thread, and explicit sharing of data. The 5.005
-version (5005threads) is considered obsolete, buggy, and unmaintained.
-
-By default, Configure selects ithreads if -Dusethreads is specified.
-
-However, if you insist, you can select the unsupported old 5005threads behavior
-
- sh Configure -Dusethreads -Duse5005threads
+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) has been removed for release 5.10.
The 'threads' module is for use with the ithreads implementation. The
-'Thread' module offers an interface to either 5005threads or ithreads
-(whichever has been configured).
+'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.
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>
+C<-Accflags=-DPERL_REENTRANT_MAXSIZE=65536>.
-=head3 Large file support.
+=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
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.
+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.
-=head3 64 bit support.
+=head3 64 bit support
-If your platform does not have run natively at 64 bits, but can
-simulate them with compiler flags and/or C<long long> or C<int64_t>,
+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
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.
+Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
=head3 Long doubles
You can "Configure -Dusemorebits" to turn on both the 64-bit support
and the long double support.
-=head3 Selecting File IO mechanisms
-
-Executive summary: as of Perl 5.8, you should use the default "PerlIO"
-as the IO mechanism unless you have a good reason not to.
-
-In more detail: previous versions of perl used the standard IO
-mechanisms as defined in stdio.h. Versions 5.003_02 and later of perl
-introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
-until and including Perl 5.6, the stdio mechanism was still the default
-and the only supported mechanism.
-
-Starting from Perl 5.8, the default mechanism is to use the PerlIO
-abstraction, because it allows better control of I/O mechanisms,
-instead of having to work with (often, work around) vendors' I/O
-implementations.
-
-This PerlIO abstraction can be (but again, unless you know what you
-are doing, should not be) disabled either on the Configure command
-line with
-
- sh Configure -Uuseperlio
-
-or interactively at the appropriate Configure prompt.
-
-With the PerlIO abstraction layer, there is another possibility for
-the underlying IO calls, AT&T's "sfio". This has superior performance
-to stdio.h in many cases, and is extensible by the use of "discipline"
-modules ("Native" PerlIO has them too). Sfio currently only builds on
-a subset of the UNIX platforms perl supports. Because the data
-structures are completely different from stdio, perl extension modules
-or external libraries may not work. This configuration exists to
-allow these issues to be worked on.
-
-This option requires the 'sfio' package to have been built and installed.
-The latest sfio is available from http://www.research.att.com/sw/tools/sfio/
-
-You select this option by
-
- sh Configure -Duseperlio -Dusesfio
-
-If you have already selected -Duseperlio, and if Configure detects
-that you have sfio, then sfio will be the default suggested by
-Configure.
-
-Note: On some systems, sfio's iffe configuration script fails to
-detect that you have an atexit function (or equivalent). Apparently,
-this is a problem at least for some versions of Linux and SunOS 4.
-Configure should detect this problem and warn you about problems with
-_exit vs. exit. If you have this problem, the fix is to go back to
-your sfio sources and correct iffe's guess about atexit.
-
=head3 Algorithmic Complexity Attacks on Hashes
In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
B<Perl has never guaranteed any ordering of the hash keys>, and the
ordering has already changed several times during the lifetime of Perl
5. Also, the ordering of hash keys has always been, and continues to
-be, affected by the insertion order. It is likely that Perl 5.10 and
-Perl 6 will randomise all hashes. Note that because of this
+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
+between different runs of Perl, since Data::Dumper by default dumps
hashes "unordered". The use of the Data::Dumper C<Sortkeys> option is
recommended.
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.
+extensions, and various extra libraries, such as -lm.
-On some systems that support dynamic loading, it may be possible to
+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
results.
The default name for the shared library is typically something like
-libperl.so.6.2 (for Perl 5.6.2), or libperl.so.602, or simply
+libperl.so.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.
-For some systems (mostly SVR4), building a shared libperl is required
-for dynamic loading to work, and hence is already the default.
-
You can elect to build a shared libperl by
sh Configure -Duseshrplib
something like the following with the newly-built but not-yet-installed
./perl:
- cd t; ./perl misc/failing_test.t
+ 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 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
+
+ 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
+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
=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.9.0.
+By default, Configure will use the following directories for 5.10.0.
$version is the full perl version number, including subversion, e.g.
-5.9.0 or 5.9.1, and $archname is a string like sun4-sunos,
+5.10.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.
=item Man Pages
-In versions 5.005_57 and earlier, the default was to store module man
-pages in a version-specific directory, such as
-/usr/local/lib/perl5/$version/man/man3. The default for 5.005_58 and
-after is /usr/local/man/man3 so that most users can find the man pages
-without resetting MANPATH.
-
-You can continue to use the old default from the command line with
-
- sh Configure -Dman3dir=/usr/local/lib/perl5/5.9.0/man/man3
-
-Some users also prefer to use a .3pm suffix. You can do that with
+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
sh Configure -Dman3ext=3pm
-Again, these are just the defaults, and can be changed as you run
-Configure.
-
=item HTML pages
Currently, the standard perl installation does not do anything with
management software to move perl to its final destination. This
section describes how to do that.
-Suppose you want to install perl under the /tmp/perl5 directory. You
-could edit config.sh and change all the install* variables to point to
-/tmp/perl5 instead of /usr/local, or you could simply use the
-following command line:
+To install perl under the /tmp/perl5 directory, use the following
+command line:
sh Configure -Dinstallprefix=/tmp/perl5
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.
+hint file for your system. 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
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
+you probably want to have support for perl internal debugging code
+(activated by adding -DDEBUGGING to ccflags), and/or support for the
+system debugger by adding -g to optimize.
+
+ sh Configure -DDEBUGGING
+
+or
+
+ sh Configure -DDEBUGGING=<mode>
+
+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.
+
+=over 4
+
+=item -DEBUGGING=old
+
+Which is the default, and supports the old convention of
sh Configure -Doptimize='-g'
You can actually specify -g and -DDEBUGGING independently, but usually
it's convenient to have both.
+=item -DDEBUGGING
+
+=item -DEBUGGING
+
+=item -DEBUGGING=both
+
+Sets both -DDEBUGGING in the ccflags, and add -g to optimize.
+
+=item -DEBUGGING=-g
+
+Adds -g to optimize, but does not set -DDEBUGGING.
+
+=item -DEBUGGING=none
+
+Removes -g from optimize, and -DDEBUGGING from ccflags.
+
+=back
+
If you are using a shared libperl, see the warnings about multiple
versions of perl under L<Building a shared Perl library>.
=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!!! ***
-
-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:
+file, which also explains hint files known as callback-units.
- *** WHOA THERE!!! ***
- The recommended value for $d_tzname on this machine was "undef"!
- Keep the recommended value? [y]
+Note that any hint file is read before any Policy file, meaning that
+Policy overrides hints -- see L</Site-wide Policy settings>.
-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
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
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.
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 a tool specifically designed to handle changes in
-privileges, such as B<sudo>, http://www.courtesan.com/sudo/ .
+privileges, such as B<sudo>.
=head1 make depend
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.
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
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
DESTDIR is automatically prepended to all the installation paths. See
the example in L<"Creating an installable tar archive"> above.
-
=head2 Installed files
If you want to see exactly what will happen without installing
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
=head1 Coexistence with earlier versions of perl5
-Perl 5.9 is not binary compatible with earlier versions of Perl.
+Perl 5.10 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.
top of the script with the particular version you want to run, e.g.
#!/usr/local/bin/perl5.8.2.
-Usually, most extensions will probably not need to be recompiled to use
-with a newer version of Perl Here is how it is supposed to work.
+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.005_03 installed. The directories
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 L<perltrap> 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
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 }'
+ 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