Revamp the section on local() in perlsub.

[perl5.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 4b20540..1ea3e7b 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -82,7 +82,7 @@ also read the README file specific to that system.
 
 If there is a hint file for your system (in the hints/ directory) you
 should also read that hint file for specific information for your
-system.  (Unixware users should use the svr4.sh hint file.)
+system.  (Unixware users should use the svr4.sh or the svr5.sh hint file.)
 Additional information is in the Porting/ directory.
 
 =head1 WARNING:  This version requires an extra step to build old extensions.
@@ -319,14 +319,24 @@ It may seem obvious, but Perl is useful only when users can easily
 find it.  It's often a good idea to have both /usr/bin/perl and
 /usr/local/bin/perl be symlinks to the actual binary.  Be especially
 careful, however, not to overwrite a version of perl supplied by your
-vendor unless you are sure you know what you are doing.
+vendor unless you are sure you know what you are doing.  If you insist
+on replacing your vendor's perl, useful information on how it was
+configured may be found with
 
-By default, Configure will arrange for /usr/bin/perl to be linked to
-the current version of perl.  You can turn off that behavior by running
+       perl -V:config_args
 
-       Configure -Uinstallusrbinperl
+(Check the output carefully, however, since this doesn't preserve
+spaces in arguments to Configure.  For that, you have to look
+carefully at config_arg1, config_arg2, etc.)
 
-or by answering 'no' to the appropriate Configure prompt.
+By default, Configure will not try to link /usr/bin/perl to
+the current version of perl.  You can turn on that behavior by running
+
+       Configure -Dinstallusrbinperl
+
+or by answering 'yes' to the appropriate Configure prompt.
+(Note that before perl 5.8.1, the default behavior was to create
+or overwrite /usr/bin/perl even if it already existed.)
 
 In any case, system administrators are strongly encouraged to
 put (symlinks to) perl and its accompanying utilities, such as perldoc,
@@ -438,10 +448,10 @@ be used for installing those add-on modules and scripts.
     $sitescript                $siteprefix/bin
     $sitelib           $siteprefix/lib/perl5/site_perl/$version
     $sitearch          $siteprefix/lib/perl5/site_perl/$version/$archname
-    $siteman1          $siteprefix/man/man1
-    $siteman3          $siteprefix/man/man3
-    $sitehtml1         (none)
-    $sitehtml3         (none)
+    $siteman1dir       $siteprefix/man/man1
+    $siteman3dir       $siteprefix/man/man3
+    $sitehtml1dir      (none)
+    $sitehtml3dir      (none)
 
 By default, ExtUtils::MakeMaker will install architecture-independent
 modules into $sitelib and architecture-dependent modules into $sitearch.
@@ -459,10 +469,10 @@ for you to use to distribute add-on modules.
     $vendorscript      $vendorprefix/bin
     $vendorlib         $vendorprefix/lib/perl5/vendor_perl/$version
     $vendorarch                $vendorprefix/lib/perl5/vendor_perl/$version/$archname
-    $vendorman1                $vendorprefix/man/man1
-    $vendorman3                $vendorprefix/man/man3
-    $vendorhtml1       (none)
-    $vendorhtml3       (none)
+    $vendorman1dir     $vendorprefix/man/man1
+    $vendorman3dir     $vendorprefix/man/man3
+    $vendorhtml1dir    (none)
+    $vendorhtml3dir    (none)
 
 These are normally empty, but may be set as needed.  For example,
 a vendor might choose the following settings:
@@ -484,15 +494,15 @@ This would have the effect of setting the following:
        $sitescript     /usr/local/bin
        $sitelib        /usr/local/lib/perl5/site_perl/$version
        $sitearch       /usr/local/lib/perl5/site_perl/$version/$archname
-       $siteman1       /usr/local/man/man1
-       $siteman3       /usr/local/man/man3
+       $siteman1dir    /usr/local/man/man1
+       $siteman3dir    /usr/local/man/man3
 
        $vendorbin      /usr/bin
        $vendorscript   /usr/bin
        $vendorlib      /usr/lib/perl5/vendor_perl/$version
        $vendorarch     /usr/lib/perl5/vendor_perl/$version/$archname
-       $vendorman1     /usr/man/man1
-       $vendorman3     /usr/man/man3
+       $vendorman1dir  /usr/man/man1
+       $vendorman3dir  /usr/man/man3
 
 Note how in this example, the vendor-supplied directories are in the
 /usr hierarchy, while the directories reserved for the end-user are in
@@ -650,6 +660,18 @@ Here's one way to do that:
     cd /opt/perl # Or wherever you specified as $prefix
     tar xvf perl5-archive.tar
 
+Alternatively, the DESTDIR variable is honored during C<make install>.
+The DESTDIR is automatically prepended to all the installation paths
+(and there is no need to edit anything).  With DESTDIR, the above
+example can we written as:
+
+    sh Configure -Dprefix=/opt/perl -des
+    make
+    make test
+    make install DESTDIR=/tmp/perl5
+    cd /tmp/perl5/opt/perl
+    tar cvf /tmp/perl5-archive.tar .
+
 =head2 Site-wide Policy settings
 
 After Configure runs, it stores a number of common site-wide "policy"
@@ -1498,6 +1520,15 @@ explicitly above.
 
 This will attempt to make perl in the current directory.
 
+=head2 Expected errors
+
+These errors are normal, and can be ignored:
+
+  ...
+  make: [extra.pods] Error 1 (ignored)
+  ...
+  make: [extras.make] Error 1 (ignored)
+
 =head2 What if it doesn't work?
 
 If you can't compile successfully, try some of the following ideas.