better INSTALL notes on Solaris issues (from Dominic Dunlop)

p4raw-id: //depot/perl@5960

1 files changed, 69 insertions, 3 deletions

diff --git a/INSTALL b/INSTALL
index 552c870201..712c04f590 100644
--- a/INSTALL
+++ b/INSTALL
@@ -6,7 +6,7 @@ Install - Build and Installation guide for perl5.
 
 First, make sure you are installing an up-to-date version of Perl.   If
 you didn't get your Perl source from CPAN, check the latest version at
-<URL:http://www.perl.com/CPAN/src/>.
+<URL:http://www.cpan.org/src/>.
 
 The basic steps to build and install perl5 on a Unix system
 with all the defaults are:
@@ -113,8 +113,42 @@ currently installed modules.
 
 =head1 WARNING:  This version requires a compiler that supports ANSI C.
 
-If you find that your C compiler is not ANSI-capable, try obtaining
-GCC, available from GNU mirrors worldwide (e.g. ftp://ftp.gnu.org/pub/gnu).
+Most C compilers are now ANSI-compliant.  However, a few current
+computers are delivered with an older C compiler expressly for
+rebuilding the system kernel, or for some other historical reason.
+Alternatively, you may have an old machine which was shipped before
+ANSI compliance became widespread.  Such compilers are not suitable
+for building Perl.
+
+If you find that your default C compiler is not ANSI-capable, but you
+know that an ANSI-capable compiler is installed on your system, you
+can tell F<Configure> to use the correct compiler by means of the
+C<-Dcc=> command-line option -- see L<"gcc">.
+
+If do not have an ANSI-capable compiler there are several avenues open
+to you:
+
+=over 4
+
+=item *
+
+You may try obtaining GCC, available from GNU mirrors worldwide,
+listed at <URL:http://www.gnu.org/order/ftp.html>.  If, rather than
+building gcc from source code, you locate a binary version configured
+for your platform, be sure that it is compiled for the version of the
+operating system that you are using.
+
+=item *
+
+You may purchase a commercial ANSI C compiler from your system
+supplier or elsewhere.  (Or your organization may already have
+licensed such software -- ask your colleagues to find out how to
+access it.)  If there is a README file for your system in the Perl
+distribution (for example, F<README.hpux>), it may contain advice on
+suitable compilers.
+
+=item *
+
 Another alternative may be to use a tool like ansi2knr to convert the
 sources back to K&R style, but there is no guarantee this route will get
 you anywhere, since the prototypes are not the only ANSI features used
@@ -128,6 +162,8 @@ 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
 followed.  This will enable us to officially support this option.
 
+=back
+
 Although Perl can be compiled using a C++ compiler, the Configure script
 does not work with some C++ compilers.
 
@@ -1518,6 +1554,36 @@ to include the GNU utils before running Configure, or specify the
 vendor-supplied utilities explicitly to Configure, for example by
 Configure -Dar=/bin/ar.
 
+=item THIS PACKAGE SEEMS TO BE INCOMPLETE
+
+The F<Configure> program has not been able to find all the files which
+make up the complete Perl distribution.  You may have a damaged source
+archive file (in which case you may also have seen messages such as
+C<gzip: stdin: unexpected end of file> and C<tar: Unexpected EOF on
+archive file>), or you may have obtained a structurally-sound but
+incomplete archive.  In either case, try downloading again from the
+official site named at the start of this document.  If you do find
+that any site is carrying a corrupted or incomplete source code
+archive, please report it to the site's maintainer.
+
+This message can also be a symptom of using (say) a GNU tar compiled
+for SunOS4 on Solaris.  When you run SunOS4 binaries on Solaris the
+run-time system magically alters pathnames matching m#lib/locale# - so
+when tar tries to create lib/locale.pm a differently-named file gets
+created instead.
+
+You may find the file under its assumed name and be able to rename it
+back.  Or use Sun's tar to do the extract.
+
+=item invalid token: ##
+
+You are using a non-ANSI-compliant C compiler.  See L<WARNING:  This
+version requires a compiler that supports ANSI C>.
+
+=item lib/locale.pm: No such file or directory
+
+See L<THIS PACKAGE SEEMS TO BE INCOMPLETE>.
+
 =item Miscellaneous
 
 Some additional things that have been reported for either perl4 or perl5: