From 0a08c020238096f33826419fc8f499789a1b40a2 Mon Sep 17 00:00:00 2001 From: Gurusamy Sarathy Date: Tue, 11 Jan 2000 19:18:50 +0000 Subject: [PATCH] rework INSTALL to reflect new logic for versioning sitelibs p4raw-id: //depot/perl@4794 --- INSTALL | 88 ++++++++++++++++++++++++++++++++--------------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/INSTALL b/INSTALL index 33176a9..7ac14ca 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 -- 2.7.4