INSTALL patches

	Message-Id: <Pine.GSU.4.05.9903191208250.8899-100000@newton.phys>

p4raw-id: //depot/perl@3303

1 files changed, 208 insertions, 186 deletions

diff --git a/INSTALL b/INSTALL
index fccc4f141a..8e6f81ce86 100644
--- a/INSTALL
+++ b/INSTALL
@@ -22,6 +22,9 @@ Each of these is explained in further detail below.
 For information on non-Unix systems, see the section on
 L<"Porting information"> below.
 
+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 detailed information about specific
 changes, see the Changes file.
@@ -91,10 +94,10 @@ followed.  This will enable us to officially support this option.
 
 =head1 Space Requirements
 
-The complete perl5 source tree takes up about 10 MB of disk space.  The
+The complete perl5 source tree takes up about 15 MB of disk space.  The
 complete tree after completing make takes roughly 20 MB, though the
 actual total is likely to be quite system-dependent.  The installation
-directories need something on the order of 10 MB, though again that
+directories need something on the order of 15 MB, though again that
 value is system-dependent.
 
 =head1 Start with a Fresh Distribution
@@ -167,10 +170,13 @@ If you want to use your old config.sh but override some of the items
 with command line options, you need to use B<Configure -O>.
 
 By default, for most systems, perl will be installed in
-/usr/local/{bin, lib, man}.  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.
+/usr/local/{bin, lib, man}.  (See L<"Installation Directories">
+and L<"Coexistence with earlier versions of perl5"> 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.
 
 	sh Configure -Dprefix=/opt/perl
 
@@ -179,9 +185,9 @@ are simplified.  For example, if you use prefix=/opt/perl,
 then Configure will suggest /opt/perl/lib instead of
 /opt/perl/lib/perl5/.
 
-NOTE:  You must not specify an installation directory that is below
-your perl source directory.  If you do, installperl will attempt
-infinite recursion.
+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.
 
 It may seem obvious to say, but Perl is useful only when users can
 easily find it.  It's often a good idea to have both /usr/bin/perl and
@@ -228,150 +234,6 @@ Cross compiling is not supported.
 (The file is called configure.gnu to avoid problems on systems
 that would not distinguish the files "Configure" and "configure".)
 
-=head2 Extensions
-
-By default, Configure will offer to build every extension which appears
-to be supported.  For example, Configure will offer to build GDBM_File
-only if it is able to find the gdbm library.  (See examples below.)
-B, DynaLoader, Fcntl, IO, and attrs are always built by default.
-Configure does not contain code to test for POSIX compliance, so POSIX
-is always built by default as well.  If you wish to skip POSIX, you can
-set the Configure variable useposix=false either in a hint file or from
-the Configure command line.  Similarly, the Opcode extension is always
-built by default, but you can skip it by setting the Configure variable
-useopcode=false either in a hint file for from the command line.
-
-You can learn more about each of these extensions by consulting the
-documentation in the individual .pm modules, located under the
-ext/ subdirectory.
-
-Even if you do not have dynamic loading, you must still build the
-DynaLoader extension; you should just build the stub dl_none.xs
-version.  (Configure will suggest this as the default.)
-
-In summary, here are the Configure command-line variables you can set
-to turn off each extension:
-
-    B			(Always included by default)
-    DB_File		i_db
-    DynaLoader		(Must always be included as a static extension)
-    Fcntl		(Always included by default)
-    GDBM_File		i_gdbm
-    IO			(Always included by default)
-    NDBM_File		i_ndbm
-    ODBM_File		i_dbm
-    POSIX		useposix
-    SDBM_File		(Always included by default)
-    Opcode		useopcode
-    Socket		d_socket
-    Threads		usethreads
-    attrs		(Always included by default)
-
-Thus to skip the NDBM_File extension, you can use
-
-	sh Configure -Ui_ndbm
-
-Again, this is taken care of automatically if you don't have the ndbm
-library.
-
-Of course, you may always run Configure interactively and select only
-the extensions you want.
-
-Note:  The DB_File module will only work with version 1.x of Berkeley
-DB or newer releases of version 2.  Configure will automatically detect
-this for you and refuse to try to build DB_File with version 2.
-
-If you re-use your old config.sh but change your system (e.g. by
-adding libgdbm) Configure will still offer your old choices of extensions
-for the default answer, but it will also point out the discrepancy to
-you.
-
-Finally, if you have dynamic loading (most modern Unix systems do)
-remember that these extensions do not increase the size of your perl
-executable, nor do they impact start-up time, so you probably might as
-well build all the ones that will work on your system.
-
-=head2 Including locally-installed libraries
-
-Perl5 comes with interfaces to number of database extensions, including
-dbm, ndbm, gdbm, and Berkeley db.  For each extension, if
-Configure can find the appropriate header files and libraries, it will
-automatically include that extension.  The gdbm and db libraries
-are not included with perl.  See the library documentation for
-how to obtain the libraries.
-
-Note:  If your database header (.h) files are not in a
-directory normally searched by your C compiler, then you will need to
-include the appropriate -I/your/directory option when prompted by
-Configure.  If your database library (.a) files are not in a directory
-normally searched by your C compiler and linker, then you will need to
-include the appropriate -L/your/directory option when prompted by
-Configure.  See the examples below.
-
-=head2 Examples
-
-=over 4
-
-=item gdbm in /usr/local
-
-Suppose you have gdbm and want Configure to find it and build the
-GDBM_File extension.  This examples assumes you have gdbm.h
-installed in /usr/local/include/gdbm.h and libgdbm.a installed in
-/usr/local/lib/libgdbm.a.  Configure should figure all the
-necessary steps out automatically.
-
-Specifically, when Configure prompts you for flags for
-your C compiler, you should include  -I/usr/local/include.
-
-When Configure prompts you for linker flags, you should include
--L/usr/local/lib.
-
-If you are using dynamic loading, then when Configure prompts you for
-linker flags for dynamic loading, you should again include
--L/usr/local/lib.
-
-Again, this should all happen automatically.  If you want to accept the
-defaults for all the questions and have Configure print out only terse
-messages, then you can just run
-
-	sh Configure -des
-
-and Configure should include the GDBM_File extension automatically.
-
-This should actually work if 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
-
-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.
-
-It is possible to specify this from the command line too (all on one
-line):
-
-	sh Configure -des \
-		-Dlocincpth="/usr/you/include" \
-		-Dloclibpth="/usr/you/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
-
-	sh Configure -des \
-		-Dlocincpth="/usr/you/include /usr/local/include" \
-		-Dloclibpth="/usr/you/lib /usr/local/lib"
-
-=back
-
 =head2 Installation Directories
 
 The installation directories can all be changed by answering the
@@ -392,10 +254,45 @@ for 5.005 (archname is a string like sun4-sunos, determined by Configure).
 	$sitearch	/usr/local/lib/perl5/site_perl/5.005/archname
 	$sitelib	/usr/local/lib/perl5/site_perl/5.005
 
+	$man1dir	/usr/local/man/man1
+	$man3dir	/usr/local/lib/perl5/man/man3
+
+The perl executable will search the libraries in the order given
+above.
+
+The directories under site_perl are empty, but are intended to be used
+for installing local or site-wide extensions.  Perl will automatically
+look in these directories.
+
 Some users prefer to append a "/share" to $privlib and $sitelib
 to emphasize that those directories can be shared among different
 architectures.
 
+Note that these are just the defaults.  You can actually structure the
+directories any way you like.  They don't even have to be on the same
+filesystem.
+
+Further details about the installation directories, maintenance and
+development subversions, and about supporting multiple versions are
+discussed in L<"Coexistence with earlier versions of perl5"> below.
+
+If you specify a prefix that contains the string "perl", then the
+directory structure is simplified.  For example, if you Configure with
+-Dprefix=/opt/perl, then the defaults for 5.005 are
+
+    Configure variable		Default value
+	$archlib	/opt/perl/lib/5.005/archname
+	$privlib	/opt/perl/lib/5.005
+	$sitearch	/opt/perl/lib/site_perl/5.005/archname
+	$sitelib	/opt/perl/lib/site_perl/5.005
+
+	$man1dir	/opt/perl/man/man1
+	$man3dir	/opt/perl/man/man3
+
+=over 4
+
+=item Man Pages
+
 By default, Configure will use the following directories for manual pages:
 
     Configure variable		Default value
@@ -422,34 +319,7 @@ Some users also prefer to use a .3pm suffix.  You can do that with
 
 	sh Configure -Dman3ext=3pm
 
-If you specify a prefix that contains the string "perl", then the
-directory structure is simplified.  For example, if you Configure with
--Dprefix=/opt/perl, then the defaults for 5.005 are
-
-    Configure variable		Default value
-	$archlib	/opt/perl/lib/5.005/archname
-	$privlib	/opt/perl/lib/5.005
-	$sitearch	/opt/perl/lib/site_perl/5.005/archname
-	$sitelib	/opt/perl/lib/site_perl/5.005
-
-	$man1dir	/opt/perl/man/man1
-	$man3dir	/opt/perl/man/man3
-
-The perl executable will search the libraries in the order given
-above.
-
-The directories under site_perl are empty, but are intended to be used
-for installing local or site-wide extensions.  Perl will automatically
-look in these directories.
-
-In order to support using things like #!/usr/local/bin/perl5.005 after
-a later version is released, architecture-dependent libraries are
-stored in a version-specific directory, such as
-/usr/local/lib/perl5/archname/5.005/.
-
-Further details about the installation directories, maintenance and
-development subversions, and about supporting multiple versions are
-discussed in L<"Coexistence with earlier versions of perl5"> below.
+=back
 
 Again, these are just the defaults, and can be changed as you run
 Configure.
@@ -540,6 +410,10 @@ to ensure that Configure doesn't re-use them.
 
 Further information is in the Policy_sh.SH file itself.
 
+If the generated Policy.sh file is unsuitable, you may freely edit it
+to contain any valid shell commands.  It will be run just after the
+platform-specific hints files.
+
 =head2 Configure-time Options
 
 There are several different ways to Configure and build perl for your
@@ -848,8 +722,156 @@ You should also run Configure interactively to verify that a hint file
 doesn't inadvertently override your ccflags setting.  (Hints files
 shouldn't do that, but some might.)
 
+=head2 Extensions
+
+By default, Configure will offer to build every extension which appears
+to be supported.  For example, Configure will offer to build GDBM_File
+only if it is able to find the gdbm library.  (See examples below.)
+B, DynaLoader, Fcntl, IO, and attrs are always built by default.
+Configure does not contain code to test for POSIX compliance, so POSIX
+is always built by default as well.  If you wish to skip POSIX, you can
+set the Configure variable useposix=false either in a hint file or from
+the Configure command line.  Similarly, the Opcode extension is always
+built by default, but you can skip it by setting the Configure variable
+useopcode=false either in a hint file for from the command line.
+
+You can learn more about each of these extensions by consulting the
+documentation in the individual .pm modules, located under the
+ext/ subdirectory.
+
+Even if you do not have dynamic loading, you must still build the
+DynaLoader extension; you should just build the stub dl_none.xs
+version.  (Configure will suggest this as the default.)
+
+In summary, here are the Configure command-line variables you can set
+to turn off each extension:
+
+    B			(Always included by default)
+    DB_File		i_db
+    DynaLoader		(Must always be included as a static extension)
+    Fcntl		(Always included by default)
+    GDBM_File		i_gdbm
+    IO			(Always included by default)
+    NDBM_File		i_ndbm
+    ODBM_File		i_dbm
+    POSIX		useposix
+    SDBM_File		(Always included by default)
+    Opcode		useopcode
+    Socket		d_socket
+    Threads		usethreads
+    attrs		(Always included by default)
+
+Thus to skip the NDBM_File extension, you can use
+
+	sh Configure -Ui_ndbm
+
+Again, this is taken care of automatically if you don't have the ndbm
+library.
+
+Of course, you may always run Configure interactively and select only
+the extensions you want.
+
+Note:  The DB_File module will only work with version 1.x of Berkeley
+DB or newer releases of version 2.  Configure will automatically detect
+this for you and refuse to try to build DB_File with earlier
+releases of version 2.
+
+If you re-use your old config.sh but change your system (e.g. by
+adding libgdbm) Configure will still offer your old choices of extensions
+for the default answer, but it will also point out the discrepancy to
+you.
+
+Finally, if you have dynamic loading (most modern Unix systems do)
+remember that these extensions do not increase the size of your perl
+executable, nor do they impact start-up time, so you probably might as
+well build all the ones that will work on your system.
+
+=head2 Including locally-installed libraries
+
+Perl5 comes with interfaces to number of database extensions, including
+dbm, ndbm, gdbm, and Berkeley db.  For each extension, if
+Configure can find the appropriate header files and libraries, it will
+automatically include that extension.  The gdbm and db libraries
+are not included with perl.  See the library documentation for
+how to obtain the libraries.
+
+Note:  If your database header (.h) files are not in a
+directory normally searched by your C compiler, then you will need to
+include the appropriate -I/your/directory option when prompted by
+Configure.  If your database library (.a) files are not in a directory
+normally searched by your C compiler and linker, then you will need to
+include the appropriate -L/your/directory option when prompted by
+Configure.  See the examples below.
+
+=head2 Examples
+
+=over 4
+
+=item gdbm in /usr/local
+
+Suppose you have gdbm and want Configure to find it and build the
+GDBM_File extension.  This examples assumes you have gdbm.h
+installed in /usr/local/include/gdbm.h and libgdbm.a installed in
+/usr/local/lib/libgdbm.a.  Configure should figure all the
+necessary steps out automatically.
+
+Specifically, when Configure prompts you for flags for
+your C compiler, you should include  -I/usr/local/include.
+
+When Configure prompts you for linker flags, you should include
+-L/usr/local/lib.
+
+If you are using dynamic loading, then when Configure prompts you for
+linker flags for dynamic loading, you should again include
+-L/usr/local/lib.
+
+Again, this should all happen automatically.  If you want to accept the
+defaults for all the questions and have Configure print out only terse
+messages, then you can just run
+
+	sh Configure -des
+
+and Configure should include the GDBM_File extension automatically.
+
+This should actually work if 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
+
+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.
+
+It is possible to specify this from the command line too (all on one
+line):
+
+	sh Configure -des \
+		-Dlocincpth="/usr/you/include" \
+		-Dloclibpth="/usr/you/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
+
+	sh Configure -des \
+		-Dlocincpth="/usr/you/include /usr/local/include" \
+		-Dloclibpth="/usr/you/lib /usr/local/lib"
+
+=back
+
 =head2 What if it doesn't work?
 
+If you run into problems, try some of the following ideas.
+If none of them help, then see L<"Reporting Problems"> below.
+
 =over 4
 
 =item Environment variable clashes
@@ -1014,12 +1036,12 @@ explicitly above.
 
 This will attempt to make perl in the current directory.
 
+=head2 What if it doesn't work?
+
 If you can't compile successfully, try some of the following ideas.
 If none of them help, and careful reading of the error message and
-the relevant manual pages on your system doesn't help, you can
-send a message to either the comp.lang.perl.misc newsgroup or to
-perlbug@perl.com with an accurate description of your problem.
-See L<"Reporting Problems"> below.
+the relevant manual pages on your system doesn't help,
+then see L<"Reporting Problems"> below.
 
 =over 4
 
@@ -1656,4 +1678,4 @@ the contact information to match your distribution.
 
 =head1 LAST MODIFIED
 
-$Id: INSTALL,v 1.42 1998/07/15 18:04:44 doughera Released $
+$Id: INSTALL,v 1.48 1999/03/19 17:00:49 doughera Exp $