rework INSTALL to reflect new logic for versioning sitelibs

p4raw-id: //depot/perl@4794

1 files changed, 44 insertions, 44 deletions

diff --git a/INSTALL b/INSTALL
index 33176a97a4..7ac14caef2 100644
--- a/INSTALL
+++ b/INSTALL
@@ -335,7 +335,7 @@ The directories set up by Configure fall into three broad categories.
 
 By default, Configure will use the following directories for 5.6.
 $version is the full perl version number, including subversion, e.g.
-5.6 or 5.6.1, and $archname is a string like sun4-sunos,
+5.6.0 or 5.6.1, and $archname is a string like sun4-sunos,
 determined by Configure.  The full definitions of all Configure
 variables are in the file Porting/Glossary.
 
@@ -462,7 +462,7 @@ without resetting MANPATH.
 
 You can continue to use the old default from the command line with
 
-	sh Configure -Dman3dir=/usr/local/lib/perl5/5.6/man/man3
+	sh Configure -Dman3dir=/usr/local/lib/perl5/5.6.0/man/man3
 
 Some users also prefer to use a .3pm suffix.  You can do that with
 
@@ -500,13 +500,13 @@ library directory structure is slightly simplified.  Instead of
 suggesting $prefix/lib/perl5/, Configure will suggest $prefix/lib.
 
 Thus, for example, if you Configure with
--Dprefix=/opt/perl, then the default library directories for 5.6 are
+-Dprefix=/opt/perl, then the default library directories for 5.6.0 are
 
     Configure variable	Default value
-	$privlib	/opt/perl/lib/5.6
-	$archlib	/opt/perl/lib/5.6/$archname
-	$sitelib	/opt/perl/lib/site_perl/5.6
-	$sitearch	/opt/perl/lib/site_perl/5.6/$archname
+	$privlib	/opt/perl/lib/5.6.0
+	$archlib	/opt/perl/lib/5.6.0/$archname
+	$sitelib	/opt/perl/lib/site_perl/5.6.0
+	$sitearch	/opt/perl/lib/site_perl/5.6.0/$archname
 
 =head2 Changing the installation directory
 
@@ -1693,13 +1693,14 @@ searched by 5.005_03 are
 	/usr/local/lib/perl5/site_perl/5.005/$archname
 	/usr/local/lib/perl5/site_perl/5.005
 
-Now, suppose you install version 5.6.  The directories searched by
-version 5.6 will be
+Beginning with 5.6.0 the version number in the site libraries are
+fully versioned.  Now, suppose you install version 5.6.0.  The directories
+searched by version 5.6.0 will be
 
-	/usr/local/lib/perl5/5.6/$archname
-	/usr/local/lib/perl5/5.6
-	/usr/local/lib/perl5/site_perl/5.6/$archname
-	/usr/local/lib/perl5/site_perl/5.6
+	/usr/local/lib/perl5/5.6.0/$archname
+	/usr/local/lib/perl5/5.6.0
+	/usr/local/lib/perl5/site_perl/5.6.0/$archname
+	/usr/local/lib/perl5/site_perl/5.6.0
 
 	/usr/local/lib/perl5/site_perl/5.005/$archname
 	/usr/local/lib/perl5/site_perl/5.005
@@ -1707,56 +1708,55 @@ version 5.6 will be
 Notice the last two entries -- Perl understands the default structure
 of the $sitelib directories and will look back in older, compatible
 directories.  This way, modules installed under 5.005_03 will continue
-to be usable by 5.005_03 but will also accessible to 5.6.  Further,
+to be usable by 5.005_03 but will also accessible to 5.6.0.  Further,
 suppose that you upgrade a module to one which requires features
-present only in 5.6.  That new module will get installed into
-/usr/local/lib/perl5/site_perl/5.6 and will be available to 5.6,
+present only in 5.6.0.  That new module will get installed into
+/usr/local/lib/perl5/site_perl/5.6.0 and will be available to 5.6.0,
 but will not interfere with the 5.005_03 version.
 
-Also, by default, 5.6 will look in
+Also, by default, 5.6.0 will look in
 
 	/usr/local/lib/perl5/site_perl/
 
 for 5.004-era pure perl modules.
 
-Lastly, suppose you now install version 5.6.1.  The directories
-searched by 5.6.1 will be
+Lastly, suppose you now install version 5.6.1, which we'll assume is
+binary compatible with 5.6.0 and 5.005.  The directories searched
+by 5.6.1 (if you don't change the Configure defaults) will be:
 
 	/usr/local/lib/perl5/5.6.1/$archname
 	/usr/local/lib/perl5/5.6.1
-	/usr/local/lib/perl5/site_perl/5.6/$archname
-	/usr/local/lib/perl5/site_perl/5.6
+	/usr/local/lib/perl5/site_perl/5.6.1/$archname
+	/usr/local/lib/perl5/site_perl/5.6.1
+
+	/usr/local/lib/perl5/site_perl/5.6.0/$archname
+	/usr/local/lib/perl5/site_perl/5.6.0
 
 	/usr/local/lib/perl5/site_perl/5.005/$archname
 	/usr/local/lib/perl5/site_perl/5.005
 	/usr/local/lib/perl5/site_perl/
 
-When you install an add-on extension, it gets installed into $sitelib (or
-$sitearch if it is architecture-specific).  This directory deliberately
-does NOT include the sub-version number (01) so that both 5.6 and
-5.6.1 can use the extension.
-
-However, if you do run into problems, and you want to continue to use the
-old version of perl along with your extension, move those extension files
-to the appropriate version directory, such as $privlib (or $archlib).
-(The extension's .packlist file lists the files installed with that
-extension.  For the Tk extension, for example, the list of files installed
-is in $sitearch/auto/Tk/.packlist.)  Then use your newer version of perl
-to rebuild and re-install the extension into $sitelib.  This way, Perl
-5.6 will find your files in the 5.6 directory, and newer versions
-of perl will find your newer extension in the $sitelib directory.
-(This is also why perl searches the site-specific libraries last.)
-
-Alternatively, if you are willing to reinstall all your modules
-every time you upgrade perl, then you can include the subversion
-number in $sitearch and $sitelib when you run Configure.
+Assuming the users in your site are still actively using perl 5.6.0 and
+5.005 after you installed 5.6.1, you can continue to install add-on
+extensions using any of perl 5.6.1, 5.6.0, or 5.005.  The installations
+of these different versions remain distinct, but remember that the newer
+versions of perl are automatically set up to search the site libraries of
+the older ones.  This means that installing a new extension with 5.005
+will make it visible to all three versions.  Later, if you install the
+same extension using, say, perl 5.6.1, it will override the 5.005-installed
+version, but only for perl 5.6.1.
+
+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.  One convenient way to do this
-is by using a separate prefix for each version, such as
+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.004
 
@@ -1773,13 +1773,13 @@ seriously consider using a separate directory, since development
 subversions may not have all the compatibility wrinkles ironed out
 yet.
 
-=head2 Upgrading from 5.005 to 5.6
+=head2 Upgrading from 5.005 to 5.6.0
 
 Extensions built and installed with versions of perl prior to 5.005_50
 will need to be recompiled to be used with 5.005_50 and later.  You will,
 however, be able to continue using 5.005 even after you install 5.6.
 The 5.005 binary will still be able to find the modules built under
-5.005; the 5.6 binary will look in the new $sitearch and $sitelib
+5.005; the 5.6.0 binary will look in the new $sitearch and $sitelib
 directories, and will not find them.  See also 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