This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[DOC PATCH] perlthrtut proofreading
[perl5.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index dbb757a..f087b77 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -24,7 +24,7 @@ with all the defaults are:
 
 Each of these is explained in further detail below.
 
-B<NOTE>: starting from the release 5.6.0 Perl will use a version
+B<NOTE>: starting from the release 5.6.0, Perl will use a version
 scheme where even-numbered subreleases (like 5.6) are stable
 maintenance releases and odd-numbered subreleases (like 5.7) are
 unstable development releases.  Development releases should not be
@@ -88,8 +88,8 @@ that too.  Additional information is in the Porting/ directory.
 =head1 WARNING:  This version requires an extra step to build old extensions.
 
 5.005_53 and later releases do not export unadorned
-global symbols anymore.  This means you may need to build older
-extensions that have not been updated for the new naming convention
+global symbols anymore.  This means you may need to build rather old
+extensions that have not been updated for the current naming convention
 with:
 
        perl Makefile.PL POLLUTE=1
@@ -101,17 +101,12 @@ building perl itself with:
 
 pod/perldelta.pod contains more details about this.
 
-=head1 WARNING:  This version may not be binary compatible with Perl 5.005.
+=head1 WARNING:  This version is not binary compatible with releases of
+Perl prior to 5.8.0.
 
-Using the default Configure options for building perl should get you
-a perl that will be binary compatible with the 5.005 release.
-
-However, if you run Configure with any custom options, such as
--Dusethreads, -Dusemultiplicity, -Dusemymalloc, -Ubincompat5005 etc.,
-the resulting perl will not be binary compatible.  Under these
-circumstances, if you have dynamically loaded extensions that were
-built under perl 5.005, you will need to rebuild and reinstall all
-those extensions to use them with 5.6.
+If you have built extensions (ie modules that include C code)
+using an earlier version of Perl, you will need to rebuild and reinstall
+those extensions.
 
 Pure perl modules without XS or C code should continue to work fine
 without reinstallation.  See the discussions below on
@@ -186,10 +181,10 @@ does not work with some C++ compilers.
 
 =head1 Space Requirements
 
-The complete perl5 source tree takes up about 40 MB of disk space.
-After completing make, it takes up roughly 60 MB, though the actual
+The complete perl5 source tree takes up about 50 MB of disk space.
+After completing make, it takes up roughly 100 MB, though the actual
 total is likely to be quite system-dependent.  The installation
-directories need something on the order of 35 MB, though again that
+directories need something on the order of 45 MB, though again that
 value is system-dependent.
 
 =head1 Start with a Fresh Distribution
@@ -328,7 +323,8 @@ 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.
+for more details.  Do not include a trailing slash, (i.e. /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
@@ -403,7 +399,8 @@ appropriate questions in Configure.  For convenience, all the
 installation questions are near the beginning of Configure.
 Further, there are a number of additions to the installation
 directories since 5.005, so reusing your old config.sh may not
-be sufficient to put everything where you want it.
+be sufficient to put everything where you want it.  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
@@ -804,18 +801,23 @@ and the long double support.
 
 =head2 Selecting File IO mechanisms
 
-Previous versions of perl used the standard IO mechanisms as defined in
-stdio.h.  Versions 5.003_02 and later of perl allowed alternate IO
-mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
-the default and is the only supported mechanism.
+Executive summary: in Perl 5.8, you should use the default "PerlIO"
+as the IO mechanism unless you have a good reason not to.
+
+In more detail: previous versions of perl used the standard IO
+mechanisms as defined in stdio.h.  Versions 5.003_02 and later of perl
+introduced alternate IO mechanisms via a "PerlIO" abstraction, but up
+until and including Perl 5.6, the stdio mechanism was still the default
+and the only supported mechanism.
 
-Starting from Perl 5.8 the default mechanism is to use the PerlIO
+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 disabled either on the Configure
-command line with
+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
 
@@ -984,15 +986,8 @@ or you can answer 'n' at the appropriate interactive Configure prompt.
 
 =item -DPERL_POLLUTE_MALLOC
 
-NOTE: This flag is enabled automatically on some platforms if you
-asked for binary compatibility with version 5.005, or if you just
-run Configure to accept all the defaults on those platforms.  You
-can refuse the automatic binary compatibility flags wholesale by
-running:
-
-       sh Configure -Ubincompat5005
-
-or by answering 'n' at the appropriate prompt.
+NOTE: This flag is enabled automatically on some platforms if you just
+run Configure to accept all the defaults on those platforms.
 
 Perl's malloc family of functions are called Perl_malloc(),
 Perl_realloc(), Perl_calloc() and Perl_mfree().  When this flag is
@@ -1612,16 +1607,6 @@ to
 then propagate your changes with B<sh Configure -S> and rebuild
 with B<make depend; make>.
 
-=item CRIPPLED_CC
-
-If you still can't compile successfully, try:
-
-       sh Configure -Accflags=-DCRIPPLED_CC
-
-This flag simplifies some complicated expressions for compilers that get
-indigestion easily.  (Just because you get no errors doesn't mean it
-compiled right!)
-
 =item Missing functions
 
 If you have missing routines, you probably need to add some library or
@@ -1735,14 +1720,12 @@ Genix may need to use libc rather than libc_s, or #undef VARARGS.
 
 NCR Tower 32 (OS 2.01.01) may need -W2,-Sl,2000 and #undef MKDIR.
 
-UTS may need one or more of -DCRIPPLED_CC, -K or -g, and undef LSTAT.
+UTS may need one or more of -K or -g, and undef LSTAT.
 
 FreeBSD can fail the lib/ipc_sysv.t test if SysV IPC has not been
 configured to the kernel.  Perl tries to detect this, though, and
 you will get a message telling what to do.
 
-If you get syntax errors on '(', try -DCRIPPLED_CC.
-
 Machines with half-implemented dbm routines will need to #undef I_ODBM
 
 HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
@@ -1930,10 +1913,12 @@ external program.
 
 Several tests in the test suite check timing functions, such as
 sleep(), and see if they return in a reasonable amount of time.
-If your system is quite busy and doesn't return quickly enough,
-these tests might fail.  If possible, try running the tests again with
-the system under a lighter load.  These tests include F<t/op/alarm.t>,
-F<ext/Time/HiRes/HiRes.t>, and F<lib/Benchmark.t>.
+If your system is quite busy and doesn't respond quickly enough,
+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<lib/Memoize/t/expmod_t.t>, and F<lib/Memoize/t/speed.t>.
 
 =item Out of memory
 
@@ -2104,6 +2089,9 @@ approach.
 
 =head1 Coexistence with earlier versions of perl5
 
+Perl 5.8 is not binary compatible with earlier versions of Perl.
+In other words, you have to recompile your XS modules.
+
 In general, you can usually safely upgrade from one version of Perl (e.g.
 5.004_04) to another similar version (e.g. 5.004_05) without re-compiling
 all of your add-on extensions.  You can also safely leave the old version
@@ -2289,6 +2277,13 @@ 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:
+especially the Encode with its big conversion tables consumes a lot of
+space.  On the other hand, you cannot throw away everything, especially
+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.