Patch: Documenting tools necessary for GCC [take 2]

["Kaveh R. Ghazi" <ghazi at caip dot rutgers dot edu>]

Thanks everyone for all your feedback.  If I omitted someone's input I
apologize, below is the latest text.  (I've left out anything about
which "make" tool we support since that turned out to be radioactive.)

This time I've put it in the form of a patch against install.texi.  I
added a new section called "Prerequisites" before "Downloading", and
this passes "make info".  My markup is weak so be kind, I simply cut
and pasted and poked until "make info" stopped complaining. :-)

Regarding remaining content tweeks, if possible I'd prefer to get
something installed and then continue having individuals iterate over
specific tool details in the form of patches against the actual file.
That way I won't serve as a bottleneck.  So I'd like to concentrate on
meta-issues precluding installation, like my sectioning attempt was
looney or it'll break the website, something of that nature.

Ok to install?

		Thanks,
		--Kaveh


2003-06-06  Kaveh R. Ghazi  <ghazi@caip.rutgers.edu>

	* install.texi (Prerequisites): New section documenting tools and
	packages necessary prior to building and/or modifying GCC.
	
diff -rup orig/egcc-CVS20030605/gcc/doc/install.texi egcc-CVS20030605/gcc/doc/install.texi
--- orig/egcc-CVS20030605/gcc/doc/install.texi	2003-06-05 20:01:51.000000000 -0400
+++ egcc-CVS20030605/gcc/doc/install.texi	2003-06-06 00:31:04.409635000 -0400
@@ -14,6 +14,9 @@
 @ifset specifichtml
 @settitle Host/Target specific installation notes for GCC
 @end ifset
+@ifset prerequisiteshtml
+@settitle Prerequisites for GCC
+@end ifset
 @ifset downloadhtml
 @settitle Downloading GCC
 @end ifset
@@ -47,6 +50,7 @@
 @ifnothtml
 @set indexhtml
 @set specifichtml
+@set prerequisiteshtml
 @set downloadhtml
 @set configurehtml
 @set buildhtml
@@ -155,6 +159,7 @@ The installation procedure itself is bro
 
 @ifinfo
 @menu
+* Prerequisites::
 * Downloading the source::
 * Configuration::
 * Building::
@@ -165,6 +170,8 @@ The installation procedure itself is bro
 @ifhtml
 @enumerate
 @item
+@uref{prerequisites.html,,Prerequisites}
+@item
 @uref{download.html,,Downloading the source}
 @item
 @uref{configure.html,,Configuration}
@@ -201,10 +208,175 @@ not yet been merged into the main part o
 @end ifhtml
 @end ifset
 
+@c ***Prerequisites**************************************************
+@ifnothtml
+@comment node-name,     next,          previous, up
+@node    Prerequisites, Downloading the source, , Installing GCC
+@end ifnothtml
+@ifset prerequisiteshtml
+@ifnothtml
+@chapter Prerequisites
+@end ifnothtml
+@cindex Prerequisites
+
+GCC requires that various tools and packages be available for use in the
+build procedure.  Modifying GCC sources requires additional tools
+described below.
+
+@heading Tools/packages necessary for building GCC
+@table @code
+@item ISO C90 compiler
+Necessary to bootstrap the GCC package, although versions of GCC prior
+to 3.4 also allow bootstrapping with a traditional (K&R) C compiler.
+
+To make all languages in a cross-compiler or other configuration where
+3-stage bootstrap is not performed, you need to start with an existing
+GCC binary (version 2.95 or later) because source code for language
+frontends other than C might use GCC extensions.
+
+@item GNAT
+
+In order to build the Ada compiler (GNAT) you must already have GNAT
+installed because portions of the Ada frontend are written in Ada
+(with GNAT extensions.)  Refer to the Ada installation instructions
+for more specific information.
+
+@item A "working" POSIX compatible shell, or GNU bash
+
+Necessary when running configure because some /bin/sh shells have bugs
+and may crash when configuring the target libraries.  In other cases,
+/bin/sh or even some ksh have disastrous corner-case performance
+problems.  This can cause target configure runs to literally take days
+to complete in some cases.
+
+So on some platforms /bin/ksh is sufficient, on others it isn't.  See
+the host/target specific instructions for your platform, or use bash
+to be sure.  Then set CONFIG_SHELL in your environment to your "good"
+shell prior to running configure/make.
+
+@item GNU binutils
+
+Necessary in some circumstances, optional in others.  See the
+host/target specific instructions for your platform for the exact
+requirements.
+
+@item gzip version 1.2.4 (or later) or
+@item bzip2 version 1.0.2 (or later)
+
+Necessary to uncompress GCC tar files when source code is obtained via
+FTP mirror sites.
+
+@item GNU tar version 1.12 (or later)
+
+Necessary (only on some platforms) to untar the source code.  Many
+system tar's will also work, only try GNU tar if you have problems.
+
+@end table
+
+
+@heading Tools/packages necessary for modifying GCC
+@table @code
+
+@item autoconf version 2.13 (NO earlier or later versions) and
+@item GNU m4 version 1.4 (or later)
+
+Necessary when modifying configure.in, aclocal.m4, etc to regenerate
+configure and config.in files
+
+@item automake version ???
+
+Necessary when modifying a Makefile.am to regenerate its associated
+Makefile.in
+
+@item gperf version 2.7.2 (or later)
+
+Necessary when modifying gperf input files, e.g. gcc/cp/cfns.gperf to
+regenerate its associated header file, e.g. gcc/cp/cfns.h.
+
+@item expect version ???
+@item tcl version ???
+@item dejagnu version ???
+
+Necessary to run the GCC testsuite.
+
+@item autogen version 5.5.4 (or later) and
+@item guile version 1.4.1 (or later)
+
+Necessary to regenerate fixinc/fixincl.x from fixinc/inclhack.def and
+fixinc/*.tpl.
+
+Necessary to run the fixinc/ directory "make check".
+
+Necessary to regenerate the top level Makefile.am's from Makefile.tpl
+and Makefile.def.
+
+@item GNU Bison version 1.28 (or later)
+Berkeley yacc (byacc) is also reported to work other than for java.
+
+Necessary when modifying *.y files.
+
+Necessary to build GCC during development because the generated output
+files are not included in the cvs repository.  They are included in
+releases.
+
+@item Flex version 2.5.4 (or later)
+
+Necessary when modifying *.l files.
+
+Necessary to build GCC during development because the generated output
+files are not included in the cvs repository.  They are included in
+releases.
+
+@item texinfo version 4.2 (or later)
+
+Necessary for running makeinfo when modifying *.texi files to test
+your changes.
+
+Necessary to build GCC documentation during development because the
+generated output files are not included in the cvs repository.  They
+are included in releases.
+
+@item TeX (any working version)
+
+Necessary for running texi2dvi, used when running "make dvi" to create
+DVI files.
+
+@item cvs version 1.10 (or later)
+@item ssh (any version)
+
+Necessary to access the cvs repository.  Public releases and weekly
+snapshots of the development sources are also available via FTP.
+
+@item perl version 5.6.1 (or later)
+
+Necessary when regenerating Makefile dependencies in libiberty.
+Necessary when regenerating something with intl??? (pod2man???)
+Other stuff???
+
+@item GNU diffutils version 2.7 (or later)
+
+Necessary when creating changes to GCC source code to submit for review.
+
+@item patch version 2.5.4 (or later)
+
+Necessary when applying patches, created with "diff", to one's own
+sources.
+
+@end table
+
+@html
+<hr />
+<p>
+@end html
+@ifhtml
+@uref{./index.html,,Return to the GCC Installation page}
+@end ifhtml
+@end ifset
+
 @c ***Downloading the source**************************************************
 @ifnothtml
 @comment node-name,     next,          previous, up
-@node    Downloading the source, Configuration, , Installing GCC
+@node    Downloading the source, Configuration, Prerequisites, Installing GCC
 @end ifnothtml
 @ifset downloadhtml
 @ifnothtml