This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
msgrcv: properly downgrade the receive buffer
[perl5.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index e55d651..6f674eb 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,5 @@
 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
+It is written in the POD format (see F<pod/perlpod.pod>) which is specially
 designed to be readable as is.
 
 =head1 NAME
@@ -10,7 +10,7 @@ INSTALL - Build and Installation guide for perl 5.
 
 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
+L<https://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
@@ -28,11 +28,11 @@ the defaults are to run, from a freshly unpacked source tree:
 
 Each of these is explained in further detail below.
 
-The above commands will install Perl to /usr/local (or some other
-platform-specific directory -- see the appropriate file in hints/.)
+The above commands will install Perl to F</usr/local> (or some other
+platform-specific directory -- see the appropriate file in F<hints/>.)
 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.
+any prefix location by adding C<"-Dprefix='/some/dir'"> to Configure's args.
 To explicitly name the perl binary, use the command
 "make install PERLNAME=myperl".
 
@@ -44,20 +44,20 @@ rely on anything more than C89.
 These options, and many more, are explained in further detail below.
 
 If you're building perl from a git repository, you should also consult
-the documentation in pod/perlgit.pod for information on that special
+the documentation in F<pod/perlgit.pod> for information on that special
 circumstance.
 
 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 information about how to find more
+F<pod/perldelta.pod> file.  For more information about how to find more
 specific detail about changes, see the Changes file.
 
 =head1 DESCRIPTION
 
 This document is written in pod format as an easy way to indicate its
-structure.  The pod format is described in pod/perlpod.pod, but you can
+structure.  The pod format is described in F<pod/perlpod.pod>, but you can
 read it as is with any pager or editor.  Headings and items are marked
 by lines beginning with '='.  The other mark-up used is
 
@@ -73,21 +73,21 @@ proceeding.
 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
+system (in the F<hints/> directory) you might also want to read it
 for even more information.
 
 For additional information about porting Perl, see the section on
-L<"Porting information"> below, and look at the files in the Porting/
+L<"Porting information"> below, and look at the files in the F<Porting/>
 directory.
 
 =head1 PRELIMINARIES
 
 =head2 Changes and Incompatibilities
 
-Please see pod/perldelta.pod for a description of the changes and
+Please see F<pod/perldelta.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 F<pod/perldelta.pod> for more detailed information.
 
 B<WARNING:> This version is not binary compatible with earlier versions
 of Perl.  If you have built extensions (i.e. modules that include C code)
@@ -102,7 +102,7 @@ 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 for a description of what's changed.  See your
+F<pod/perldelta.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 the L<CPAN> module's
 C<autobundle> function for one way to make a "bundle" of your currently
@@ -132,7 +132,7 @@ Configure supports a number of useful options.  Run
 
        Configure -h
 
-to get a listing.  See the Porting/Glossary file for a complete list of
+to get a listing.  See the F<Porting/Glossary> file for a complete list of
 Configure variables you can set and their definitions.
 
 =over 4
@@ -150,32 +150,32 @@ 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">
+F</usr/local/>{F<bin>, F<lib>, F<man>}.  (See L<"Installation Directories">
 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
-line option -Dprefix='/some/directory', e.g.
+line option C<-Dprefix='/some/directory'>, e.g.
 
        sh Configure -Dprefix=/opt/perl
 
 If your prefix contains the string "perl", then the suggested
 directory structure is simplified.  For example, if you use
-prefix=/opt/perl, then Configure will suggest /opt/perl/lib instead of
-/opt/perl/lib/perl5/.  Again, see L<"Installation Directories"> below
-for more details.  Do not include a trailing slash, (i.e. /opt/perl/)
+C<prefix=/opt/perl>, then Configure will suggest F</opt/perl/lib> instead of
+F</opt/perl/lib/perl5/>.  Again, see L<"Installation Directories"> below
+for more details.  Do not include a trailing slash, (i.e. F</opt/perl/>)
 or you may experience odd test failures.
 
 NOTE:  You must not specify an installation directory that is the same
 as or below your perl source directory.  If you do, installperl will
 attempt infinite recursion.
 
-=item /usr/bin/perl
+=item F</usr/bin/perl>
 
 It may seem obvious, but Perl is useful only when users can easily
-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
+find it.  It's often a good idea to have both F</usr/bin/perl> and
+F</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.  If you insist
 on replacing your vendor's perl, useful information on how it was
@@ -187,7 +187,7 @@ configured may be found with
 spaces in arguments to Configure.  For that, you have to look carefully
 at config_arg1, config_arg2, etc.)
 
-By default, Configure will not try to link /usr/bin/perl to the current
+By default, Configure will not try to link F</usr/bin/perl> to the current
 version of perl.  You can turn on that behavior by running
 
        Configure -Dinstallusrbinperl
@@ -361,63 +361,84 @@ disabling them via environment variables.
 You can override various aspects of this feature by defining various
 symbols during configure. An example might be:
 
-    Configure -Accflags=-DPERL_HASH_FUNC_SIPHASH
+    sh Configure -Accflags=-DPERL_HASH_FUNC_SIPHASH
 
 B<Unless stated otherwise these options are considered experimental or
 insecure and are not recommended for production use.>
 
-Perl 5.18 includes support for multiple hash functions, and changed
-the default (to ONE_AT_A_TIME_HARD), you can choose a different
-algorithm by defining one of the following symbols. Note that as of
-Perl 5.18 we can only recommend use of the default or SIPHASH. All
-the others are known to have security issues and are for research
-purposes only.
+Since Perl 5.18 we have included support for multiple hash functions,
+although from time to time we change which functions we support,
+and which function is default (currently SBOX+STADTX on 64 bit builds
+and SBOX+ZAPHOD32 for 32 bit builds). You can choose a different
+algorithm by defining one of the following symbols during configure.
+Note that there security implications of which hash function you choose
+to use. The functions are listed roughly by how secure they are believed
+to be, with the one believed to be most secure at release time being PERL_HASH_FUNC_SIPHASH.
 
     PERL_HASH_FUNC_SIPHASH
-    PERL_HASH_FUNC_SDBM
-    PERL_HASH_FUNC_DJB2
-    PERL_HASH_FUNC_SUPERFAST
-    PERL_HASH_FUNC_MURMUR3
-    PERL_HASH_FUNC_ONE_AT_A_TIME
-    PERL_HASH_FUNC_ONE_AT_A_TIME_HARD
-    PERL_HASH_FUNC_ONE_AT_A_TIME_OLD
-
-Perl 5.18 randomizes the order returned by keys(), values(), and each(),
-and allows controlling this behavior by using of the PERL_PERTURB_KEYS
-option. You can disable this option entirely with the define:
+    PERL_HASH_FUNC_SIPHASH13
+    PERL_HASH_FUNC_ZAPHOD32
+    PERL_HASH_FUNC_STADTX
+
+In addition, these, (or custom hash functions), may be "fronted" by the
+SBOX32 hash function for keys under a chosen size. This hash function is
+special in that it has proven theoretical security properties, and is very
+fast to hash, but which by nature is restricted to a maximum key length,
+and which has rather expensive setup costs (relatively speaking), both in
+terms of performance and more importantly in terms of memory. SBOX32
+requires 1k of storage per character it can hash, and it must populate that
+storage with 256 32-bit random values as well. In practice the RNG we use
+for seeding the SBOX32 storage is very efficient and populating the table
+required for hashing even fairly long keys is negligible as we only do it
+during startup. By default we build with SBOX32 enabled, but you change that
+by setting
+
+   PERL_HASH_USE_SBOX32_ALSO
+
+to zero in configure. By default Perl will use SBOX32 to hash strings 24 bytes
+or shorter, you can change this length by setting
+
+    SBOX32_MAX_LEN
+
+to the desired length, with the maximum length being 256.
+
+As of Perl 5.18 the order returned by keys(), values(), and each() is
+non-deterministic and distinct per hash, and the insert order for
+colliding keys is randomized as well, and perl allows for controlling this
+by the PERL_PERTURB_KEYS environment setting. You can disable this behavior
+entirely with the define
 
     PERL_PERTURB_KEYS_DISABLED
 
-You can disable the environment variable checks and specify the type of
-key traversal randomization to be used by defining one of these:
+You can disable the environment variable checks and compile time specify
+the type of key traversal randomization to be used by defining one of these:
 
     PERL_PERTURB_KEYS_RANDOM
     PERL_PERTURB_KEYS_DETERMINISTIC
 
-In Perl 5.18 the seed used for the hash function is randomly selected
-at process start which can be overridden by specifying a seed by setting
+Since Perl 5.18 the seed used for the hash function is randomly selected
+at process start, which can be overridden by specifying a seed by setting
 the PERL_HASH_SEED environment variable.
 
-You can change this behavior by building perl with the
-
-   USE_HASH_SEED_EXPLICIT
-
-define, in which case one has to explicitly set the PERL_HASH_SEED
-environment variable to enable the security feature or by adding
+You can change this behavior so that your perl is built with a hard coded
+seed with the define
 
     NO_HASH_SEED
 
-to the compilation flags to completely disable the randomisation feature.
-Note these modes are poorly tested, insecure and not recommended.
+Note that if you do this you should modify the code in hv_func.h to specify
+your own key. In the future this define may be renamed and replaced with one
+that requires you to specify the key to use.
 
-B<Perl has never guaranteed any ordering of the hash keys>, and the
+B<NOTE WELL: 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.
+be, affected by the insertion order regardless of whether you build with
+or without the randomization features.  Note that because of this
+and especially with randomization that the key order of a hash is *undefined*
+and that things like Data::Dumper, for example, may produce different output
+between different runs of Perl, since Data::Dumper serializes the key in the
+native order for the hash.  The use of the Data::Dumper C<Sortkeys> option is
+recommended if you are comparing dumps between different invocations of perl.
 
 See L<perlrun/PERL_HASH_SEED> and L<perlrun/PERL_PERTURB_KEYS> for
 details on the environment variables, and L<perlsec/Algorithmic
@@ -437,7 +458,7 @@ 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>.
+L<https://en.wikipedia.org/wiki/SOCKS>.
 
 =head3 Dynamic Loading
 
@@ -485,7 +506,7 @@ You can elect to build a shared libperl by
 To build a shared libperl, the environment variable controlling shared
 library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
 Darwin, LD_LIBRARY_PATH/SHLIB_PATH
-for HP-UX, LIBPATH for AIX, PATH for Cygwin) must be set up to include
+for HP-UX, LIBPATH for AIX and z/OS, 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
@@ -498,7 +519,7 @@ 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:
 
-        ./perl -MTestInit t/misc/failing_test.t
+        ./perl -I. -MTestInit t/misc/failing_test.t
 
 or
 
@@ -563,6 +584,12 @@ variables for C compiler switches etc.">.  You can force an embedded perl
 to use direct manipulation by setting C<PL_use_safe_putenv = 0;> after
 the C<perl_construct()> call.
 
+=head3 External glob
+
+Before File::Glob entered core in 5.6.0 globbing was implemented by shelling
+out. If the environmental variable PERL_EXTERNAL_GLOB is defined and if the
+F<csh> shell is available, perl will still do this the old way.
+
 =head2 Installation Directories
 
 The installation directories can all be changed by answering the
@@ -588,7 +615,7 @@ The directories set up by Configure fall into three broad categories.
 
 =item Directories for the perl distribution
 
-By default, Configure will use the following directories for 5.25.10.
+By default, Configure will use the following directories for 5.33.5.
 $version is the full perl version number, including subversion, e.g.
 5.12.3, and $archname is a string like sun4-sunos,
 determined by Configure.  The full definitions of all Configure
@@ -721,7 +748,7 @@ version-specific subdirectories) for add-on modules and extensions.
 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.8.1
+       sh Configure -Dotherlibdirs=/usr/lib/perl5/site_perl/5.8.1
 
 =item APPLLIB_EXP
 
@@ -740,6 +767,16 @@ present, at run time.  Of course, you can still search other @INC
 directories ahead of those in APPLLIB_EXP by using any of the standard
 run-time methods: $PERLLIB, $PERL5LIB, -I, use lib, etc.
 
+=item default_inc_excludes_dot
+
+Since version 5.26.0, default perl builds no longer includes C<'.'> as the
+last element of @INC. The old behaviour can restored using
+
+       sh Configure -Udefault_inc_excludes_dot
+
+Note that this is likely to make programs run under such a perl
+interpreter less secure.
+
 =item usesitecustomize
 
 Run-time customization of @INC can be enabled with:
@@ -759,6 +796,10 @@ want to use a .3pm suffix for perl man pages, you can do that with
 
        sh Configure -Dman3ext=3pm
 
+You can disable installation of man pages completely using
+
+       sh Configure -Dman1dir=none -Dman3dir=none
+
 =item HTML pages
 
 Currently, the standard perl installation does not do anything with
@@ -984,7 +1025,7 @@ 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>.
+versions of perl under L</Building a shared Perl library>.
 
 Note that a perl built with -DDEBUGGING will be much bigger and will run
 much, much more slowly than a standard perl.
@@ -1005,7 +1046,7 @@ simple D script that uses them:
 =head2 Extensions
 
 Perl ships with a number of standard extensions.  These are contained
-in the ext/ subdirectory.
+in the F<ext/> subdirectory.
 
 By default, Configure will offer to build every extension which appears
 to be supported.  For example, Configure will offer to build GDBM_File
@@ -1380,7 +1421,7 @@ including a glossary of all those config.sh variables, is in the Porting
 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
+L<https://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
@@ -1501,35 +1542,14 @@ 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 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.
-
-=item util.c
-
-If you get error messages such as the following (the exact line
-numbers and function name may vary in different versions of perl):
-
-    util.c: In function 'Perl_form':
-    util.c:1107: number of arguments doesn't match prototype
-    proto.h:125: prototype declaration
-
-it might well be a symptom of the gcc "varargs problem".  See the
-previous L<"varargs"> item.
-
 =item LD_LIBRARY_PATH
 
 If you run into dynamic loading problems, check your setting of
-the LD_LIBRARY_PATH environment variable.  If you're creating a static
-Perl library (libperl.a rather than libperl.so) it should build
-fine with LD_LIBRARY_PATH unset, though that may depend on details
-of your local setup.
+the LD_LIBRARY_PATH environment variable (or on some systems the equivalent
+with a different name, see L</Building a shared Perl library>).  If you're
+creating a static Perl library (libperl.a rather than libperl.so) it should
+build fine with LD_LIBRARY_PATH unset, though that may depend on details of
+your local setup.
 
 =item nm extraction
 
@@ -1551,20 +1571,6 @@ Check your config.sh.  You should have d_umask='define'.  If you don't,
 this is probably the L<"nm extraction"> problem discussed above.  Also,
 try reading the hints file for your system for further information.
 
-=item vsprintf
-
-If you run into problems with vsprintf in compiling util.c, the
-problem is probably that Configure failed to detect your system's
-version of vsprintf().  Check whether your system has vprintf().
-(Virtually all modern Unix systems do.)  Then, check the variable
-d_vprintf in config.sh.  If your system has vprintf, it should be:
-
-       d_vprintf='define'
-
-If Configure guessed wrong, it is likely that Configure guessed wrong
-on a number of other common functions too.  This is probably
-the L<"nm extraction"> problem discussed above.
-
 =item do_aspawn
 
 If you run into problems relating to do_aspawn or do_spawn, the
@@ -1660,7 +1666,7 @@ If you still have missing routines or undefined symbols, you probably
 need to add some library or other, make a symbolic link like described
 above, 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
+it has any relevant advice.  You can also look through config.h
 for likely suspects.
 
 =item toke.c
@@ -1684,7 +1690,7 @@ error, as the header file is broken. There are two ways to deal with this
 
  1. Disable the use of ODBM_FILE
 
-    Configure ... -Dnoextensions=ODBM_File
+    sh Configure ... -Dnoextensions=ODBM_File
 
  2. Fix the header file, somewhat like this:
 
@@ -1807,8 +1813,8 @@ to avoid the BIND.
 
 Perl can be cross-compiled.  It is just not trivial, cross-compilation
 rarely is.  Perl is routinely cross-compiled for several platforms: as of
-January 2014, these include Android, Blackberry 10, PocketPC aka
-WinCE, ARM Linux, and Solaris.  Previous versions of
+June 2019, these include Android, Blackberry 10,
+ARM Linux, and Solaris.  Previous versions of
 Perl also provided support for Open Zaurus, Symbian, and
 the IBM OS/400, but it's unknown if those ports are still functional.
 These platforms are known as the B<target> platforms, while the systems
@@ -1827,10 +1833,6 @@ the particular platforms:
 
 =over 4
 
-=item WinCE/PocketPC
-
-L<README.ce or perlce|perlce>
-
 =item Android
 
 L<"Cross-compilation" in README.android or
@@ -1855,11 +1857,11 @@ 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
+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
+C<-Dinstallprefix=...> might be handy, see L</Changing the installation
 directory>.
 
 About the cross-compilation support of Configure: There's two forms.
@@ -1867,7 +1869,7 @@ The more common one requires some way of transferring and running
 executables in the target system, such as an ssh connection; this is the
 C<./Configure -Dusecrosscompile -Dtargethost=...> route.  The second
 method doesn't need access to the target system, but requires you to
-provide a config.sh, and and a canned Makefile; the rest of this section
+provide a config.sh, and a canned Makefile; the rest of this section
 describes the former.
 
 This cross-compilation setup of Configure has successfully been used in
@@ -2033,7 +2035,7 @@ will run all tests.
 If individual tests fail, you can often run them by hand (from the main
 perl directory), e.g.,
 
-       ./perl -MTestInit t/op/groups.t
+       ./perl -I. -MTestInit t/op/groups.t
 
 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
@@ -2100,7 +2102,7 @@ test 85 will fail if run under either t/TEST or t/harness.
 
 Try stopping other jobs on the system and then running the test by itself:
 
-       ./perl -MTestInit t/op/pat.t
+       ./perl -I. -MTestInit t/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
@@ -2389,30 +2391,28 @@ 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.
-Once you've exhausted the documentation, please report bugs to us using
-the 'perlbug' tool.
-
-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
+Please report problems to the GitHub issue tracker at
+https://github.com/Perl/perl5/issues, which will ask for the
+appropriate 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.  Once you've exhausted the documentation,
+please report bugs to us using the GitHub tracker.
+
+The summary configuration information can be printed with C<perl -V>.
+If the install fails, or you want to report problems with C<make test>
+without installing perl, then you can run it by hand from this source
+directory with C<./perl -V>.
+
+If the build fails too early to run perl, then please
+B<run> the C<./myconfig> shell script, and include its output along
+with an accurate description of your problem.
 
 If Configure itself fails, and does not generate a config.sh file
-(needed to run C<./myconfig>), then please mail perlbug@perl.org the
+(needed to run C<./myconfig>), then please open an issue with the
 description of how Configure fails along with details of your system
--- for example the output from running C<uname -a>
+-- 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
@@ -2425,27 +2425,24 @@ 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.
+appropriate context.
 
 If the bug you are reporting has security implications which make it
-inappropriate to send to a publicly archived mailing list, then see
+inappropriate to send to a public issue tracker, then see
 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
 for details of how to report the issue.
 
 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
+L<https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>
 
 =head1 Coexistence with earlier versions of perl 5
 
-Perl 5.25.10 is not binary compatible with earlier versions of Perl.
+Perl 5.33.5 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
+In general, you can usually safely upgrade from one stable version of Perl
+(e.g. 5.30.0) to another similar minor version (e.g. 5.30.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.
@@ -2516,9 +2513,9 @@ 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.25.10
+       sh Configure -Dprefix=/opt/perl5.33.5
 
-and adding /opt/perl5.25.10/bin to the shell PATH variable.  Such users
+and adding /opt/perl5.33.5/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.
 
@@ -2531,13 +2528,13 @@ seriously consider using a separate directory, since development
 subversions may not have all the compatibility wrinkles ironed out
 yet.
 
-=head2 Upgrading from 5.25.2 or earlier
+=head2 Upgrading from 5.33.4 or earlier
 
-B<Perl 5.25.10 may not be binary compatible with Perl 5.25.3 or
+B<Perl 5.33.5 may not be binary compatible with Perl 5.33.4 or
 earlier Perl releases.>  Perl modules having binary parts
 (meaning that a C compiler is used) will have to be recompiled to be
-used with 5.25.10.  If you find you do need to rebuild an extension with
-5.25.10, you may safely do so without disturbing the older
+used with 5.33.5.  If you find you do need to rebuild an extension with
+5.33.5, you may safely do so without disturbing the older
 installations.  (See L<"Coexistence with earlier versions of perl 5">
 above.)
 
@@ -2570,15 +2567,15 @@ Firstly, the bare minimum to run this script
      print("$f\n");
   }
 
-in Linux with perl-5.25.10 is as follows (under $Config{prefix}):
+in Linux with perl-5.33.5 is as follows (under $Config{prefix}):
 
   ./bin/perl
-  ./lib/perl5/5.25.10/strict.pm
-  ./lib/perl5/5.25.10/warnings.pm
-  ./lib/perl5/5.25.10/i686-linux/File/Glob.pm
-  ./lib/perl5/5.25.10/feature.pm
-  ./lib/perl5/5.25.10/XSLoader.pm
-  ./lib/perl5/5.25.10/i686-linux/auto/File/Glob/Glob.so
+  ./lib/perl5/5.33.5/strict.pm
+  ./lib/perl5/5.33.5/warnings.pm
+  ./lib/perl5/5.33.5/i686-linux/File/Glob.pm
+  ./lib/perl5/5.33.5/feature.pm
+  ./lib/perl5/5.33.5/XSLoader.pm
+  ./lib/perl5/5.33.5/i686-linux/auto/File/Glob/Glob.so
 
 Secondly, for perl-5.10.1, the Debian perl-base package contains 591
 files, (of which 510 are for lib/unicore) totaling about 3.5MB in its
@@ -2690,10 +2687,16 @@ 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.
 
+=head2 C<-DNO_PERL_INTERNAL_RAND_SEED>
+X<PERL_INTERNAL_RAND_SEED>
+
+If you configure perl with C<-Accflags=-DNO_PERL_INTERNAL_RAND_SEED>,
+perl will ignore the C<PERL_INTERNAL_RAND_SEED> environment variable.
+
 =head1 DOCUMENTATION
 
 Read the manual entries before running perl.  The main documentation
-is in the pod/ subdirectory and should have been installed during the
+is in the F<pod/> subdirectory and should have been installed during the
 build process.  Type B<man perl> to get started.  Alternatively, you
 can type B<perldoc perl> to use the supplied perldoc script.  This is
 sometimes useful for finding things in the library modules.
@@ -2713,4 +2716,5 @@ This document is part of the Perl package and may be distributed under
 the same terms as perl itself, with the following additional request:
 If you are distributing a modified version of perl (perhaps as part of
 a larger package) please B<do> modify these installation instructions
-and the contact information to match your distribution.
+and the contact information to match your distribution. Additional
+information for packagers is in F<PACKAGING>.