First cut at INSTALL edit

1 files changed, 127 insertions, 127 deletions

diff --git a/INSTALL b/INSTALL
index 90163b4a75..30862d5324 100644
--- a/INSTALL
+++ b/INSTALL
@@ -4,6 +4,10 @@ Install - Build and Installation guide for perl5.
 
 =head1 SYNOPSIS
 
+ ****************************
+ *** NEEDS WORK FOR 5.004 ***
+ ****************************
+
 The basic steps to build and install perl5 on a Unix system are:
 
 	rm -f config.sh
@@ -120,6 +124,44 @@ your system supports it.  If you want to force perl to be compiled
 statically, you can either choose this when Configure prompts you or
 you can use the Configure command line option -Uusedl.
 
+=head2 GNU-style configure
+
+If you prefer the GNU-style B<configure> command line interface, you can
+use the supplied B<configure> command, e.g.
+
+	CC=gcc ./configure
+
+The B<configure> script emulates several of the more common configure
+options.  Try
+
+	./configure --help
+
+for a listing.
+
+Cross compiling is currently not supported.
+
+For systems that do not distinguish the files "Configure" and
+"configure", Perl includes a copy of B<configure> named
+B<configure.gnu>.
+
+=head2 Binary Compatibility With Earlier Versions of Perl 5
+
+Starting with Perl 5.003, all functions in the Perl C source code have
+been protected by default by the prefix Perl_ (or perl_) so that you
+may link with third-party libraries without fear of namespace
+collisons.  This change broke compatability with version 5.002, so
+installing 5.003 or 5.004 over 5.002 or earlier will force you to
+re-build and install all of your dynamically loadable extensions.
+(The standard extensions supplied with Perl are handled
+automatically).  You can turn off this namespace protection by adding
+-DNO_EMBED to your ccflags variable in config.sh.
+
+Perl 5.003's namespace protection was incomplete, which has been
+rectified in Perl 5.004.  However, some sites may need to maintain
+complete binary compatibility with Perl 5.003.  If you are building
+Perl for such a site, then when B<Configure> asks if you want binary
+compatibility, answer "y".
+
 =head2 Extensions
 
 By default, Configure will offer to build every extension which appears
@@ -167,22 +209,6 @@ 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 GNU-style configure
-
-If you prefer the GNU-style B<configure> command line interface, you can
-use the supplied B<configure> command, e.g.
-
-	CC=gcc ./configure
-
-The B<configure> script emulates several of the more common configure
-options.  Try
-
-	./configure --help
-
-for a listing.
-
-Cross compiling is currently not supported.
-
 =head2 Including locally-installed libraries
 
 Perl5 comes with interfaces to number of database extensions, including
@@ -274,7 +300,7 @@ By default, Configure uses the following directories for
 library files  (archname is a string like sun4-sunos, determined
 by Configure)
 
-	/usr/local/lib/perl5/archname/5.002
+	/usr/local/lib/perl5/archname/5.004
 	/usr/local/lib/perl5/
 	/usr/local/lib/perl5/site_perl/archname
 	/usr/local/lib/perl5/site_perl
@@ -296,7 +322,7 @@ 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 are
 
-	/opt/perl/lib/archname/5.002
+	/opt/perl/lib/archname/5.004
 	/opt/perl/lib
 	/opt/perl/lib/site_perl/archname
 	/opt/perl/lib/site_perl
@@ -312,10 +338,10 @@ intended to be used for installing local or site-wide extensions.  Perl
 will automatically look in these directories.  Previously, most sites
 just put their local extensions in with the standard distribution.
 
-In order to support using things like #!/usr/local/bin/perl5.002 after
+In order to support using things like #!/usr/local/bin/perl5.004 after
 a later version is released, architecture-dependent libraries are
 stored in a version-specific directory, such as
-/usr/local/lib/perl5/archname/5.002/.  In Perl 5.000 and 5.001, these
+/usr/local/lib/perl5/archname/5.004/.  In Perl 5.000 and 5.001, these
 files were just stored in /usr/local/lib/perl5/archname/.  If you will
 not be using 5.001 binaries, you can delete the standard extensions from
 the /usr/local/lib/perl5/archname/ directory.  Locally-added extensions
@@ -324,6 +350,66 @@ can be moved to the site_perl and site_perl/archname directories.
 Again, these are just the defaults, and can be changed as you run
 Configure.
 
+=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 allow alternate IO
+mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
+the default and is the only supported mechanism.
+
+This PerlIO abstraction can be enabled either on the Configure command
+line with
+
+	sh Configure -Duseperlio
+
+or interactively at the appropriate Configure prompt.
+
+If you choose to use the PerlIO abstraction layer, there are two
+(experimental) possibilities for the underlying IO calls.  These have been
+tested to some extent on some platforms, but are not guaranteed to work
+everywhere.
+
+=over 4
+
+=item 1.
+
+AT&T's "sfio".  This has superior performance to <stdio.h> in many
+cases, and is extensible by the use of "disipline" modules.  Sfio
+currently only builds on a subset of the UNIX platforms perl supports.
+Because the data structures are completely different from stdio, perl
+extension modules or external libraries may not work.  This
+configuration exists to allow these issues to be worked on.
+
+This option requires the 'sfio' package to have been built and installed.
+A (fairly old) version of sfio is in CPAN, and work is in progress to make
+it more easily buildable by adding Configure support.
+
+You select this option by
+
+	sh Configure -Duseperlio -Dusesfio
+
+If you have already selected -Duseperlio, and if Configure detects
+that you have sfio, then sfio will be the default suggested by
+Configure.
+
+=item 2.
+
+Normal stdio IO, but with all IO going through calls to the PerlIO
+abstraction layer.  This configuration can be used to check that perl and
+extension modules have been correctly converted to use the PerlIO
+abstraction.
+
+This configuration should work on all platforms (but might not).
+
+You select this option via :
+
+	sh Configure -Duseperlio -Uusesfio
+
+If you have already selected -Duseperlio, and if Configure does not
+detect sfio, then this will be the default suggested by Configure.
+
+=back
+
 =head2 Changing the installation directory
 
 Configure distinguishes between the directory in which perl (and its
@@ -363,24 +449,6 @@ Then, you can Configure and install in the usual way:
     make test
     make install
 
-=head2 Creating an installable tar archive
-
-If you need to install perl on many identical systems, it is
-convenient to compile it once and create an archive that can be
-installed on multiple systems.  Here's one way to do that:
-
-    # Set up config.over to install perl into a different directory,
-    # e.g. /tmp/perl5 (see previous part).
-    sh Configure -des
-    make
-    make test
-    make install
-    cd /tmp/perl5
-    tar cvf ../perl5-archive.tar .
-    # Then, on each machine where you want to install perl,
-    cd /usr/local  # Or wherever you specified as $prefix
-    tar xvf perl5-archive.tar
-
 =head2 Building a shared libperl.so Perl library.
 
 Currently, for most systems, the main perl executable is built by
@@ -452,65 +520,23 @@ version of perl.  You can do this with by changing all the *archlib*
 variables in config.sh, namely archlib, archlib_exp, and
 installarchlib, to point to your new architecture-dependent library.
 
-=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 allow alternate IO
-mechanisms via a "PerlIO" abstraction, but the stdio mechanism is still
-the default and is the only supported mechanism.
-
-This PerlIO abstraction can be enabled either on the Configure command
-line with
-
-	sh Configure -Duseperlio
-
-or interactively at the appropriate Configure prompt.
-
-If you choose to use the PerlIO abstraction layer, there are two
-(experimental) possibilities for the underlying IO calls.  These have been
-tested to some extent on some platforms, but are not guaranteed to work
-everywhere.
-
-=over 4
-
-=item 1.
-
-AT&T's "sfio".  This has superior performance to <stdio.h> in many
-cases, and is extensible by the use of "disipline" modules.  Sfio
-currently only builds on a subset of the UNIX platforms perl supports.
-Because the data structures are completely different from stdio, perl
-extension modules or external libraries may not work.  This
-configuration exists to allow these issues to be worked on.
-
-This option requires the 'sfio' package to have been built and installed.
-A (fairly old) version of sfio is in CPAN, and work is in progress to make
-it more easily buildable by adding Configure support.
-
-You select this option by
-
-	sh Configure -Duseperlio -Dusesfio
-
-If you have already selected -Duseperlio, and if Configure detects
-that you have sfio, then sfio will be the default suggested by
-Configure.
-
-=item 2.
-
-Normal stdio IO, but with all IO going through calls to the PerlIO
-abstraction layer.  This configuration can be used to check that perl and
-extension modules have been correctly converted to use the PerlIO
-abstraction.
-
-This configuration should work on all platforms (but might not).
-
-You select this option via :
-
-	sh Configure -Duseperlio -Uusesfio
+=head2 Creating an installable tar archive
 
-If you have already selected -Duseperlio, and if Configure does not
-detect sfio, then this will be the default suggested by Configure.
+If you need to install perl on many identical systems, it is
+convenient to compile it once and create an archive that can be
+installed on multiple systems.  Here's one way to do that:
 
-=back
+    # Set up config.over to install perl into a different directory,
+    # e.g. /tmp/perl5 (see previous part).
+    sh Configure -des
+    make
+    make test
+    make install
+    cd /tmp/perl5
+    tar cvf ../perl5-archive.tar .
+    # Then, on each machine where you want to install perl,
+    cd /usr/local  # Or wherever you specified as $prefix
+    tar xvf perl5-archive.tar
 
 =head2 What if it doesn't work?
 
@@ -645,17 +671,6 @@ various other operating systems.
 
 =back
 
-=head1 Binary Compatibility With Perl 5.003
-
-Perl 5.003 turned on the EMBED feature by default, which tries to
-avoid possible symbol name conflict by prefixing all global symbols
-with "Perl_".  However, its list of global symbols was incomplete.
-This error has been rectified in Perl 5.004.
-
-However, some sites may need to maintain complete binary compatibility
-with Perl 5.003.  If you are building Perl for such a site, then when
-B<Configure> asks if you want binary compatibility, answer "y".
-
 =head1 make depend
 
 This will look for all the includes.
@@ -918,8 +933,6 @@ things like: C<exec, `backquoted command`, system, open("|...")> or
 C<open("...|")>.  All these mean that Perl is trying to run some
 external program.
 
-=head1 INSTALLING PERL5
-
 =head1 make install
 
 This will put perl into the public directory you specified to
@@ -1018,7 +1031,7 @@ since some of the architecture-independent library files have changed
 in incompatible ways.
 
 The architecture-dependent files are stored in a version-specific
-directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
+directory (such as F</usr/local/lib/perl5/sun4-sunos/5.004>) so that
 they are still accessible.  I<Note:> Perl 5.000 and 5.001 did not
 put their architecture-dependent libraries in a version-specific
 directory.  They are simply in F</usr/local/lib/perl5/$archname>.  If
@@ -1032,33 +1045,20 @@ Most extensions will probably not need to be recompiled to use with a newer
 version of perl.  If you do run into problems, and you want to continue
 to use the old version of perl along with your extension, simply move
 those extension files to the appropriate version directory, such as
-F</usr/local/lib/perl/archname/5.002>.  Then Perl 5.002 will find your
-files in the 5.002 directory, and newer versions of perl will find your
+F</usr/local/lib/perl/archname/5.004>.  Then Perl 5.004 will find your
+files in the 5.004 directory, and newer versions of perl will find your
 newer extension in the site_perl directory.
 
 Some users may prefer to keep all versions of perl in completely
 separate directories.  One convenient way to do this is by
 using a separate prefix for each version, such as
 
-	sh Configure -Dprefix=/opt/perl5.002
+	sh Configure -Dprefix=/opt/perl5.004
 
-and adding /opt/perl5.002/bin to the shell PATH variable.  Such users
+and adding /opt/perl5.004/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.
 
-B<NOTE>: Starting with Perl 5.002_01, all functions in the perl C source
-code are protected by default by the prefix Perl_ (or perl_) so that
-you may link with third-party libraries without fear of namespace
-collisons.  This breaks compatability with
-version 5.002, so once you install 5.002_01 (or higher) you will
-need to re-build and install all of your dynamically loadable
-extensions.  (The standard extensions supplied with Perl are handled
-automatically).  You can turn off this namespace protection by adding
--DNO_EMBED to your ccflags variable in config.sh.
-
-In the future, we certainly hope that most extensions won't need to be
-recompiled for use with a newer version of perl.
-
 =head1 Coexistence with perl4
 
 You can safely install perl5 even if you want to keep perl4 around.
@@ -1102,4 +1102,4 @@ from the original README by Larry Wall.
 
 =head1 LAST MODIFIED
 
-16 January 1997
+22 January 1997