L<"Reporting Problems"> below.
For information on what's new in this release, see the
-pod/perl5100delta.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
=head2 Changes and Incompatibilities
-Please see pod/perl5100delta.pod for a description of the changes and
+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/perl5100delta.pod for more detailed information.
+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)
On a related issue, old modules may possibly be affected by the changes
in the Perl language in the current release. Please see
-pod/perl5100delta.pod for a description of what's changed. See your
+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.
directories ahead of those in APPLLIB_EXP by using any of the standard
run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
-=item USE_SITECUSTOMIZE
+=item usesitecustomize
Run-time customization of @INC can be enabled with:
sh Configure -Dusesitecustomize
-Which will define USE_SITECUSTOMIZE and $Config{usesitecustomize}.
-When enabled, make perl run F<$sitelibexp/sitecustomize.pl> before
+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.
=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"
If you are using a shared libperl, see the warnings about multiple
versions of perl under L<Building a shared Perl library>.
+Note that a perl built with -DDEBUGGING will be bigger and will run more
+slowly than a standard perl.
+
+=head2 DTrace support
+
+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:
+
+ perl$target:::sub-entry, perl$target:::sub-return {
+ printf("%s %s (%s:%d)\n", probename == "sub-entry" ? "->" : "<-",
+ copyinstr(arg0), copyinstr(arg1), arg2);
+ }
+
+
=head2 Extensions
Perl ships with a number of standard extensions. These are contained
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
-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.
+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 too (all on one
+It is possible to specify this from the command line (all on one
line):
sh Configure -de \
- -Dlocincpth="/usr/you/include" \
- -Dloclibpth="/usr/you/lib"
+ -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. If
-you have some libraries under /usr/local/ and others under
-/usr/you, then you have to include both, namely
+Configure will automatically add the appropriate -L directives.
- sh Configure -de \
- -Dlocincpth="/usr/you/include /usr/local/include" \
- -Dloclibpth="/usr/you/lib /usr/local/lib"
+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
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
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
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
See also L<"Maintaining completely separate versions"> for another
approach.
+=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 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
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
incomplete) list of locally installed modules. Note that you want
perllocal.pod, not perllocale.pod, for installed module information.
-=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 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 probably
-not re-use your old config.sh. Simply remove it:
-
- rm -f config.sh
-
-If you wish to re-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. 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, 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.
-
-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. If you wish to start with a fresh distribution, you
-also need to remove any old Policy.sh files you may have with
-
- rm -f Policy.sh
-
=head1 Minimizing the Perl installation
The following section is meant for people worrying about squeezing the
(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
Read the manual entries before running perl. The main 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