5.002 beta 1

If you're adventurous, have a look at

    ftp://ftp.sems.com/pub/outgoing/perl5.0/perl5.002beta1.tar.gz

Many thanks to Andy for doing the integration.

Obviously, if you consult the bugs database, you'll note there are
still plenty of buglets that need fixing, and several enhancements that
I've intended to put in still haven't made it in (Hi, Tim and Ilya).
But I think it'll be pretty stable.  And you can start to fiddle around
with prototypes (which are, of course, still totally undocumented).

Packrats, don't worry too much about readvertising this widely.
Nowadays we're on a T1 here, so our bandwidth is okay.

Have the appropriate amount of jollity.

Larry

1 files changed, 112 insertions, 8 deletions

diff --git a/INSTALL b/INSTALL
index b72e43ce34..de7ca20841 100644
--- a/INSTALL
+++ b/INSTALL
@@ -25,7 +25,7 @@ experiencing difficulties building perl, you should probably I<not>
 re-use your old config.sh.  Simply remove it or rename it, e.g.
 
 	mv config.sh config.sh.old
-	
+
 Then run Configure.
 
 =head1 Run Configure.
@@ -46,6 +46,9 @@ to get a listing.  To compile with gcc, for example, you can run
 This is the preferred way to specify gcc (or another alternative
 compiler) so that the hints files can set appropriate defaults.
 
+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>.
+
 If you are willing to accept all the defaults, and you want terse
 output, you can run
 
@@ -57,7 +60,12 @@ the default installation directory, when Configure prompts you or by
 using the Configure command line option -Dprefix='/some/directory',
 e.g.
 
-	Configure -Dprefix=/opt/local
+	Configure -Dprefix=/opt/perl
+
+If your prefix contains the string "perl", then the directories
+are simplified.  For example, if you use prefix=/opt/perl,
+then Configure will suggest /opt/perl/lib instead of
+/usr/local/lib/perl5/.
 
 By default, Configure will compile perl to use dynamic loading, if
 your system supports it.  If you want to force perl to be compiled
@@ -82,10 +90,12 @@ Cross compiling is currently not supported.
 
 =head2 Including locally-installed libraries
 
-Perl5 comes with a number of database extensions, including interfaces
-to 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.
+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 B<not> included with perl.  See the library documentation for
+how to obtain the libraries.
 
 I<Note:>  If your database header (.h) files are not in a
 directory normally searched by your C compiler, then you will need to
@@ -159,6 +169,66 @@ F</usr/you>, then you have to include both, namely
 
 =back
 
+=head2 Installation Directories.
+
+The installation directories can all be changed by answering the
+appropriate questions in Configure.  For convenience, all the
+installation questions are near the beginning of Configure.
+
+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/
+	/usr/local/lib/site_perl/archname
+	/usr/local/lib/site_perl
+
+and the following directories for manual pages:
+
+	/usr/local/man/man1
+	/usr/local/lib/perl5/man/man3
+
+(Actually, Configure recognizes the SVR3-style
+/usr/local/man/l_man/man1 directories, if present, and uses those
+instead.) The module man pages are stuck in that strange spot so that
+they don't collide with other man pages stored in /usr/local/man/man3,
+and so that Perl's man pages don't hide system man pages.  On some
+systems, B<man less> would end up calling up Perl's less.pm module man
+page, rather than the B<less> program.
+
+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
+	/opt/perl/lib/site_perl/archname
+	/opt/perl/lib/site_perl
+
+	/opt/perl/man/man1
+	/opt/perl/man/man3
+
+The perl executable will search the libraries in the order given
+above.
+
+The  directories site_perl and site_perl/archname are empty, but are
+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
+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 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 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 Changing the installation directory
 
 Configure distinguishes between the directory in which perl (and its
@@ -189,6 +259,7 @@ directory of your choice):
     installprivlib=`echo $installprivlib | sed "s!$prefix!$installprefix!"`
     installscript=`echo $installscript | sed "s!$prefix!$installprefix!"`
     installsitelib=`echo $installsitelib | sed "s!$prefix!$installprefix!"`
+    installsitearch=`echo $installsitearch | sed "s!$prefix!$installprefix!"`
 
 Then, you can Configure and install in the usual way:
 
@@ -291,7 +362,7 @@ The output is stored in F<makefile>.  The only difference between
 F<Makefile> and F<makefile> is the dependencies at the bottom of
 F<makefile>.  If you have to make any changes, you should edit
 F<makefile>, not F<Makefile> since the Unix B<make> command reads
-F<makefile>.
+F<makefile> first.
 
 Configure will offer to do this step for you, so it isn't listed
 explicitly above.
@@ -401,7 +472,7 @@ ignore any messages about chown not working.
 
 If you want to see exactly what will happen without installing
 anything, you can run
-	
+
 	./perl installperl -n
 	./perl installman -n
 
@@ -432,6 +503,13 @@ B<make install> will install the following:
 	man pages	under /usr/local/lib/perl5/man/man3.
 	pod/*.pod	in $privlib/pod/.
 
+Installperl will also create the library directories $siteperl and
+$sitearch listed in config.sh.  Usually, these are something like
+	/usr/local/lib/site_perl/
+	/usr/local/lib/site_perl/$archname
+where $archname is something like sun4-sunos.  These directories
+will be used for installing extensions.
+
 Perl's *.h header files and the libperl.a library are also
 installed under $archlib so that any user may later build new
 extensions even if the Perl source is no longer available.
@@ -454,6 +532,32 @@ to generate the html versions, and
 
 to generate the LaTeX versions.
 
+=head1 Coexistence with earlier versions of perl5.
+
+You can safely install the current version of perl5 and still run
+scripts under the old binaries.  Instead of starting your script with
+#!/usr/local/bin/perl, just start it with #!/usr/local/bin/perl5.001
+(or whatever version you want to run.)
+
+The architecture-dependent files are stored in a version-specific
+directory (such as F</usr/local/lib/perl5/sun4-sunos/5.002>) so that
+they are still accessible.  I<Note:> perl5.000 and perl5.001 did not
+put their architecture-dependent libraries in a version-specific
+directory.  They are simply in F</usr/local/lib/perl5/$archname>.  If
+you will not be using 5.000 or 5.001, you may safely remove those
+files.
+
+The standard library files in F</usr/local/lib/perl5>
+should be useable by all versions of perl5.
+
+Most extensions will 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 perl5.002 will find your
+files in the 5.002 directory, and newer versions of perl will find your
+newer extension in the site_perl directory.
+
 =head1 Coexistence with perl4
 
 You can safely install perl5 even if you want to keep perl4 around.