[doc] Improve support library requirements documentation (PR bootstrap/48135)

While investigating PR bootstrap/48135, it came up that the submitter
had run into trouble bootstrapping with mpc 0.9.0.  Unfortunately,
install.texi when describing support library requirements always lists
`(or later)' with the individual libraries.

Users who don't have the minimal required library installed (or even
those that do) often tend to build the latest release available instead
of the minimum, which has often led to trouble in the past, e.g. with
GMP 5.0.

I've therefore added a paragraph in front of the support libraries
explaining the situation and suggesting to stick with the exact versions
mentioned.  I've left the `(or later)' for the time being; we should
further improve install.texi by listing ranges of known-good versions
there.

Ok for mainline and the 4.6 branch?

	Rainer


2011-03-19  Rainer Orth  <ro@CeBiTec.Uni-Bielefeld.DE>

	PR bootstrap/48135
	* doc/install.texi (Prerequisites): Move jar etc. up.
	Explain support library version requirements.

On Mon, 21 Mar 2011, Rainer Orth wrote:

> While investigating PR bootstrap/48135, it came up that the submitter
> had run into trouble bootstrapping with mpc 0.9.0.  Unfortunately,
> install.texi when describing support library requirements always lists
> `(or later)' with the individual libraries.
> 
> Users who don't have the minimal required library installed (or even
> those that do) often tend to build the latest release available instead
> of the minimum, which has often led to trouble in the past, e.g. with
> GMP 5.0.
> 
> I've therefore added a paragraph in front of the support libraries
> explaining the situation and suggesting to stick with the exact versions
> mentioned.  I've left the `(or later)' for the time being; we should
> further improve install.texi by listing ranges of known-good versions
> there.
> 
> Ok for mainline and the 4.6 branch?

Ok.

Thanks,
Richard.

> 	Rainer
> 
> 
> 2011-03-19  Rainer Orth  <ro@CeBiTec.Uni-Bielefeld.DE>
> 
> 	PR bootstrap/48135
> 	* doc/install.texi (Prerequisites): Move jar etc. up.
> 	Explain support library version requirements.
> 
> diff -r c1a515add087 gcc/doc/install.texi
> --- a/gcc/doc/install.texi	Sat Mar 19 10:25:56 2011 +0100
> +++ b/gcc/doc/install.texi	Sat Mar 19 10:35:17 2011 +0100
> @@ -319,6 +319,20 @@
>  Used by various scripts to generate some files included in SVN (mainly
>  Unicode-related and rarely changing) from source tables.
>  
> +@item @command{jar}, or InfoZIP (@command{zip} and @command{unzip})
> +
> +Necessary to build libgcj, the GCJ runtime.
> +
> +@end table
> +
> +Several support libraries are necessary to build GCC, some are required,
> +others optional.  While any sufficiently new version of required tools
> +usually work, library requirements are generally stricter.  Newer
> +versions may work in some cases, but it's safer to use the exact
> +versions documented.  We appreciate bug reports about problems with
> +newer versions, though.
> +
> +@table @asis
>  @item GNU Multiple Precision Library (GMP) version 4.3.2 (or later)
>  
>  Necessary to build GCC@.  If you do not have it installed in your
> @@ -374,10 +388,6 @@
>  In both cases @option{--with-cloog} configure option should be used
>  if CLooG is not installed in your default library search path.
>  
> -@item @command{jar}, or InfoZIP (@command{zip} and @command{unzip})
> -
> -Necessary to build libgcj, the GCJ runtime.
> -
>  @end table
>  
>  @heading Tools/packages necessary for modifying GCC
> 
> 
>

On Mon, 21 Mar 2011, Rainer Orth wrote:
> While investigating PR bootstrap/48135, it came up that the submitter 
> had run into trouble bootstrapping with mpc 0.9.0.  Unfortunately, 
> install.texi when describing support library requirements always
> lists `(or later)' with the individual libraries.

I wouldn't say "unfortunately", since those later versions _are_
supposed to work.  Also, think of users of a distribution that has
these libraries in specific, possibly newer version, who ideally
should be able to use those.

> +Several support libraries are necessary to build GCC, some are required,
> +others optional.

Something's odd here. :-)  Some of the necessary libaries are required,
while other necessary libaries are optional?  How about something like

  Several support libraries are necessary to build GCC, plus there
  are a couple of optional ones.

or so?

   While any sufficiently new version of required tools
> +usually work, library requirements are generally stricter.  Newer
> +versions may work in some cases, but it's safer to use the exact
> +versions documented.  We appreciate bug reports about problems with
> +newer versions, though.

This is an important clarification, though at the same time I'm a bit 
concerned about our installation documentation getting ever bigger (and
less likely to be read in consequence).  Perhaps omit the part about
bug reports?


Gerald