generalize AIX ccversion hack for re extension
[p5sagit/p5-mst-13.2.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 1b258d0..50e7773 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -85,7 +85,7 @@ extensions that have not been updated for the new naming convention
 with:
 
        perl Makefile.PL POLLUTE=1
-       
+
 Alternatively, you can enable CPP symbol pollution wholesale by
 building perl itself with:
 
@@ -168,7 +168,7 @@ run, you may have to run it on a platform where GCC is available, and move
 the sources back to the platform without GCC.
 
 If you succeed in automatically converting the sources to a K&R compatible
-form, be sure to email perlbug@perl.com to let us know the steps you
+form, be sure to email perlbug@perl.org to let us know the steps you
 followed.  This will enable us to officially support this option.
 
 =back
@@ -1748,6 +1748,51 @@ test, it does not necessarily mean you have a broken perl.  This test
 tries to exercise the regular expression subsystem quite thoroughly,
 and may well be far more demanding than your normal usage.
 
+=item Test failures from lib/ftmp-security saying "system possibly insecure"
+
+Firstly, test failures from the ftmp-security are not necessarily
+serious or indicative of a real security threat.  That being said,
+they bear investigating.
+
+The tests may fail for the following reasons.   Note that each of the
+tests is run both in the building directory and the temporary
+directory, as returned by File::Spec->tmpdir().
+
+(1) If the directory the tests are being run is owned by somebody else
+than the user running the tests, or root (uid 0).  This failure can
+happen if the Perl source code distribution is unpacked in a way that
+the user ids in the distribution package are used as-is.  Some tar
+programs do this.
+
+(2) If the directory the test are being run in is writable by group
+or by other (remember: with UNIX/POSIX semantics, write access to
+a directory means the right to add/remove files in that directory),
+and there is no sticky bit set in the directory.  'Sticky bit' is
+a feature used in some UNIXes to give extra protection to files: if
+the bit is on a directory, no one but the owner (or the root) can remove
+that file even if the permissions of the directory would allow file
+removal by others.  This failure can happen if the permissions in the
+directory simply are a bit too liberal for the tests' liking.  This
+may or may not be a real problem: it depends on the permissions policy
+used on this particular directory/project/system/site.  This failure
+can also happen if the system either doesn't support the sticky bit
+(this is the case with many non-UNIX platforms: in principle the
+File::Temp should know about these platforms and skip the tests), or
+if the system supports the sticky bit but for some reason or reasons
+it is not being used.  This is for example the case with HP-UX: as of
+HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
+doesn't use it on its /tmp directory as shipped.  Also as with the
+permissions, some local policy might dictate that the stickiness is
+not used.
+
+(3) If the system supports the POSIX 'chown giveaway' feature and if
+any of the parent directories of the temporary file back to the root
+directory are 'unsafe', using the definitions given above in (1) and
+(2).
+
+See the documentation for the File::Temp module for more information
+about the various security aspects.
+
 =back
 
 =head1 make install
@@ -1786,12 +1831,17 @@ anything, you can run
 
 make install will install the following:
 
+    binaries
+
        perl,
            perl5.nnn   where nnn is the current release number.  This
                        will be a link to perl.
        suidperl,
            sperl5.nnn  If you requested setuid emulation.
        a2p             awk-to-perl translator
+
+    scripts
+
        cppstdin        This is used by perl -P, if your cc -E can't
                        read from stdin.
        c2ph, pstruct   Scripts for handling C structures in header files.
@@ -1804,13 +1854,21 @@ make install will install the following:
        pl2pm           Convert Perl 4 .pl files to Perl 5 .pm modules
        pod2html,       Converters from perl's pod documentation format
        pod2latex,      to other useful formats.
-       pod2man, and
-       pod2text
+       pod2man,
+       pod2text,
+       pod2checker,
+       pod2select,
+       pod2usage
        splain          Describe Perl warnings and errors
        dprofpp         Perl code profile post-processor
 
-       library files   in $privlib and $archlib specified to
+    library files
+
+                       in $privlib and $archlib specified to
                        Configure, usually under /usr/local/lib/perl5/.
+
+    documentation
+
        man pages       in $man1dir, usually /usr/local/man/man1.
        module man
        pages           in $man3dir, usually /usr/local/man/man3.
@@ -1819,11 +1877,28 @@ make install will install the following:
 Installperl will also create the directories listed above
 in L<"Installation Directories">.
 
-Perl's *.h header files and the libperl.a library are also installed
+Perl's *.h header files and the libperl library are also installed
 under $archlib so that any user may later build new modules, run the
 optional Perl compiler, or embed the perl interpreter into another
 program even if the Perl source is no longer available.
 
+Sometimes you only want to install the version-specific parts of the perl
+installation.  For example, you may wish to install a newer version of
+perl alongside an already installed production version of perl without
+disabling installation of new modules for the production version.
+To only install the version-specific parts of the perl installation, run
+
+       Configure -Dversiononly
+
+or answer 'y' to the appropriate Configure prompt.  Alternatively,
+you can just manually run
+
+       ./perl installperl -v
+
+and skip installman altogether.
+See also L<"Maintaining completely separate versions"> for another
+approach.
+
 =head1 Coexistence with earlier versions of perl5
 
 In general, you can usually safely upgrade from one version of Perl (e.g.
@@ -2010,7 +2085,7 @@ available in TeX format.  Type
 If you have difficulty building perl, and none of the advice in this file
 helps, and careful reading of the error message and the relevant manual
 pages on your system doesn't help either, then you should send a message
-to either the comp.lang.perl.misc newsgroup or to perlbug@perl.com with
+to either the comp.lang.perl.misc newsgroup or to perlbug@perl.org with
 an accurate description of your problem.
 
 Please include the output of the ./myconfig shell script that comes with