+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.12 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.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.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.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.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.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.8.8
+
+ /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.
+
+This way, you can choose to share compatible extensions, but also upgrade
+to a newer version of an extension that may be incompatible with earlier
+versions, without breaking the earlier versions' installations.
+
+=head2 Maintaining completely separate versions
+
+Many users prefer to keep all versions of perl in completely
+separate directories. This guarantees that an update to one version
+won't interfere with another version. (The defaults guarantee this for
+libraries after 5.6.0, but not for executables. TODO?) One convenient
+way to do this is by using a separate prefix for each version, such as
+
+ sh Configure -Dprefix=/opt/perl5.13.7
+
+and adding /opt/perl5.13.7/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.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
+seriously consider using a separate directory, since development
+subversions may not have all the compatibility wrinkles ironed out
+yet.
+
+=head2 Upgrading from 5.13.4 or earlier
+
+B<Perl 5.13.7 is binary incompatible with Perl 5.13.5 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.13.7. If you find you do need to rebuild an extension with
+5.13.7, 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 Minimizing the Perl installation
+
+The following section is meant for people worrying about squeezing the
+Perl installation into minimal systems (for example when installing
+operating systems, or in really small filesystems).
+
+Leaving out as many extensions as possible is an obvious way:
+Encode, with its big conversion tables, consumes a lot of
+space. On the other hand, you cannot throw away everything. The
+Fcntl module is pretty essential. If you need to do network
+programming, you'll appreciate the Socket module, and so forth: it all
+depends on what do you need to do.
+
+In the following we offer two different slimmed down installation
+recipes. They are informative, not normative: the choice of files
+depends on what you need.
+
+Firstly, the bare minimum to run this script
+
+ use strict;
+ use warnings;
+ foreach my $f (</*>) {
+ print("$f\n");
+ }
+
+in Linux is as follows (under $Config{prefix}):
+
+ ./bin/perl
+ ./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.9MB in its i386 version:
+
+ /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.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.