Patchwork adjust installation docs to discourage installing GMP, MPFR and MPC separately

login
register
mail settings
Submitter Jonathan Wakely
Date Jan. 6, 2012, 12:17 a.m.
Message ID <CAH6eHdRuxtp53s7JfV1sRW6A06JcKSL_Dqg09QhuxCA17D=Z=Q@mail.gmail.com>
Download mbox | patch
Permalink /patch/134560/
State New
Headers show

Comments

Jonathan Wakely - Jan. 6, 2012, 12:17 a.m.
Ping.

I think this is a useful improvement to the docs and could prevent the
most commonly-encountered bootstrap failure for inexpert users
building GCC.

OK for trunk?


On 30 December 2011 13:29, Jonathan Wakely wrote:
On 22 December 2011 00:23, Jonathan Wakely wrote:
> The most frequently asked question on gcc-help, and a frequently
> reported "bug" in bugzilla, is
> http://gcc.gnu.org/wiki/FAQ#configure_suffix
>
> It is almost always caused by installing libgmp.so etc. in a
> non-standard location and not using ldconfig, DT_RUNPATH,
> $LD_LIBRARY_PATH or some other method to tell the dynamic linker how
> to find them.  The current installation docs mention --with-gmp right
> away, which probably gives the impression that it's the recommended
> method, whereas it actually causes problems for the majority of users
> who don't understand dynamic linker search paths.  I think rewording
> the installation docs to suggest building the support libs as part of
> GCC first, and only using --with-gmp second, might steer people in the
> right direction.
>
> Separately, I also plan to write an "Installing GCC" page on the GCC
> wiki which (among other things) discourages installing the support
> libraries by hand, recommending installing prebuilt packages in
> standard system dirs instead, or if that's not an option then using
> contrib/download_prerequisites to get the sources and build them
> in-tree.
>
>
>        * doc/install.text (Prerequisites): Suggest building GMP, MPFR and
>        MPC as part of GCC before describing configuring with --with-gmp etc.
>
> Tested by running "make doc" and viewing the resulting .info pages, OK
> for trunk?

Here's an updated patch which also adjusts the --with-gmp docs in the
Configuration chapter to mention the option of putting the support lib
sources under the GCC sources

       * doc/install.texi (Prerequisites): Suggest building GMP, MPFR and
       MPC as part of GCC before describing configuring with --with-gmp etc.
       (Installing GCC: Configuration): State that --with-gmp etc. aren't
       needed if sources are present.

OK for trunk?
Quentin Neill - Jan. 20, 2012, 11:08 p.m.
On Thu, Jan 5, 2012 at 6:17 PM, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> Ping.
>
> I think this is a useful improvement to the docs and could prevent the
> most commonly-encountered bootstrap failure for inexpert users
> building GCC.
>
> OK for trunk?
>
>
> On 30 December 2011 13:29, Jonathan Wakely wrote:
> On 22 December 2011 00:23, Jonathan Wakely wrote:
>> The most frequently asked question on gcc-help, and a frequently
>> reported "bug" in bugzilla, is
>> http://gcc.gnu.org/wiki/FAQ#configure_suffix
>>
>> It is almost always caused by installing libgmp.so etc. in a
>> non-standard location and not using ldconfig, DT_RUNPATH,
>> $LD_LIBRARY_PATH or some other method to tell the dynamic linker how
>> to find them.  The current installation docs mention --with-gmp right
>> away, which probably gives the impression that it's the recommended
>> method, whereas it actually causes problems for the majority of users
>> who don't understand dynamic linker search paths.  I think rewording
>> the installation docs to suggest building the support libs as part of
>> GCC first, and only using --with-gmp second, might steer people in the
>> right direction.
>>
>> Separately, I also plan to write an "Installing GCC" page on the GCC
>> wiki which (among other things) discourages installing the support
>> libraries by hand, recommending installing prebuilt packages in
>> standard system dirs instead, or if that's not an option then using
>> contrib/download_prerequisites to get the sources and build them
>> in-tree.
>>
>>
>>        * doc/install.text (Prerequisites): Suggest building GMP, MPFR and
>>        MPC as part of GCC before describing configuring with --with-gmp etc.
>>
>> Tested by running "make doc" and viewing the resulting .info pages, OK
>> for trunk?
>
> Here's an updated patch which also adjusts the --with-gmp docs in the
> Configuration chapter to mention the option of putting the support lib
> sources under the GCC sources
>
>       * doc/install.texi (Prerequisites): Suggest building GMP, MPFR and
>       MPC as part of GCC before describing configuring with --with-gmp etc.
>       (Installing GCC: Configuration): State that --with-gmp etc. aren't
>       needed if sources are present.
>
> OK for trunk?

My 2c - I heartily recommend this patch.

May I suggest updating
/cvs/gcc/wwwdocs/htdocs/install/prerequisites.html (or wherever it
lives) with the same wording, since it is a frequent landing page for
people hunting for GCC building/installing information?

And perhaps add a page to the twiki
http://gcc.gnu.org/wiki/BuildingGCC to catch google searches for
"building gcc"?
Jonathan Wakely - Jan. 21, 2012, 12:10 a.m.
On 20 January 2012 23:08, Quentin Neill  wrote:
>
> My 2c - I heartily recommend this patch.

Thanks. I'm a bit surprised noone else has commented - I hoped this
would be a no-brainer, or at least get some constructive feedback for
further improvement.

> May I suggest updating
> /cvs/gcc/wwwdocs/htdocs/install/prerequisites.html (or wherever it
> lives) with the same wording, since it is a frequent landing page for
> people hunting for GCC building/installing information?

That's exactly the page I'm trying to change, it's generated from the
texi file my patch changes.

> And perhaps add a page to the twiki
> http://gcc.gnu.org/wiki/BuildingGCC to catch google searches for
> "building gcc"?

I recently added http://gcc.gnu.org/wiki/InstallingGCC
I chose "installing" not "building" because I believe that of the
people who fail to build GCC and look for support, most of them
probably should have installed a pre-built package supplied by their
OS or another third-party packager. Maybe it could be changed to
attract more search hits.
Quentin Neill - Jan. 27, 2012, 8:51 p.m.
On Fri, Jan 20, 2012 at 6:10 PM, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> On 20 January 2012 23:08, Quentin Neill  wrote:
>>
>> My 2c - I heartily recommend this patch.
>
> Thanks. I'm a bit surprised noone else has commented - I hoped this
> would be a no-brainer, or at least get some constructive feedback for
> further improvement.

Another +1 for this patch.  Who can approve?

Seems like this would be okay for stage4 too.

>> May I suggest updating
>> /cvs/gcc/wwwdocs/htdocs/install/prerequisites.html
> That's exactly the page I'm trying to change, it's generated from the
> texi file my patch changes.

Didn't know that, makes sense.

>> And perhaps add a page to the twiki
>> http://gcc.gnu.org/wiki/BuildingGCC to catch google searches for
>> "building gcc"?
>
> I recently added http://gcc.gnu.org/wiki/InstallingGCC
> I chose "installing" not "building" because I believe that of the
> people who fail to build GCC and look for support, most of them
> probably should have installed a pre-built package supplied by their
> OS or another third-party packager. Maybe it could be changed to
> attract more search hits.

Yes I saw your InstallingGCC and I like it.  I was thinking a
BuildingGCC would catch searches and could direct to InstallingGCC.
Does MoinMoin have a way to attach keyword data to a page?  Consider
where InstallingGCC appears in these different results from google:

? https://www.google.com/search?q=installing+gcc <-surprised me
? http://www.google.com/search?q=building+gcc
? http://www.google.com/search?q=building+gcc+wiki
#2 http://www.google.com/search?q=installing+gcc+wiki
#4 http://www.google.com/search?q=building+installing+gcc

Another suggestion would be to link from one or both of these:
http://gcc.gnu.org/install/index.html
http://gcc.gnu.org/install/build.html
Richard Guenther - Jan. 30, 2012, 9:52 a.m.
On Fri, Jan 27, 2012 at 9:51 PM, Quentin Neill
<quentin.neill.gnu@gmail.com> wrote:
> On Fri, Jan 20, 2012 at 6:10 PM, Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>> On 20 January 2012 23:08, Quentin Neill  wrote:
>>>
>>> My 2c - I heartily recommend this patch.
>>
>> Thanks. I'm a bit surprised noone else has commented - I hoped this
>> would be a no-brainer, or at least get some constructive feedback for
>> further improvement.
>
> Another +1 for this patch.  Who can approve?

If we discourage from separately installing these libraries, who will do
the required in-tree-bootstrap testing before a release on the Hosts
we care for?

Can we at least recommend using the OS vendors versions of the
libraries in case they match our minimum (not recommended) version
requirements?  Is our in-tree build support robust enough against
newer/older OS vendor installed copies?

Richard.

> Seems like this would be okay for stage4 too.
>
>>> May I suggest updating
>>> /cvs/gcc/wwwdocs/htdocs/install/prerequisites.html
>> That's exactly the page I'm trying to change, it's generated from the
>> texi file my patch changes.
>
> Didn't know that, makes sense.
>
>>> And perhaps add a page to the twiki
>>> http://gcc.gnu.org/wiki/BuildingGCC to catch google searches for
>>> "building gcc"?
>>
>> I recently added http://gcc.gnu.org/wiki/InstallingGCC
>> I chose "installing" not "building" because I believe that of the
>> people who fail to build GCC and look for support, most of them
>> probably should have installed a pre-built package supplied by their
>> OS or another third-party packager. Maybe it could be changed to
>> attract more search hits.
>
> Yes I saw your InstallingGCC and I like it.  I was thinking a
> BuildingGCC would catch searches and could direct to InstallingGCC.
> Does MoinMoin have a way to attach keyword data to a page?  Consider
> where InstallingGCC appears in these different results from google:
>
> ? https://www.google.com/search?q=installing+gcc <-surprised me
> ? http://www.google.com/search?q=building+gcc
> ? http://www.google.com/search?q=building+gcc+wiki
> #2 http://www.google.com/search?q=installing+gcc+wiki
> #4 http://www.google.com/search?q=building+installing+gcc
>
> Another suggestion would be to link from one or both of these:
> http://gcc.gnu.org/install/index.html
> http://gcc.gnu.org/install/build.html
> --
> Quentin
Jonathan Wakely - Jan. 31, 2012, 3:13 p.m.
On 30 January 2012 09:52, Richard Guenther wrote:
> If we discourage from separately installing these libraries, who will do
> the required in-tree-bootstrap testing before a release on the Hosts
> we care for?

My patch doesn't actually discourage it (although my new wiki page
does, as it's meant for the less experienced who are installing or
building gcc for the first time.) My patch just reorders the options
so that the method that is almost guaranteed to work comes before the
suggestion that requires reading and understanding complete sentences.
People who don't read the paragraph to the end will find what they
need and will stop reporting bugs and asking for help on the gcc-help
list because they can't RTFM.

I don't think the people who fail to bootstrap because they don't
understand the runtime linker are the same people who provide useful
feedback about build issues and incompatibilities with new versions of
the support libs.

> Can we at least recommend using the OS vendors versions of the
> libraries in case they match our minimum (not recommended) version
> requirements?  Is our in-tree build support robust enough against
> newer/older OS vendor installed copies?

Arguably the minimum versions are recommended by "Newer versions may
work in some cases, but it's safer to use the exact versions
documented."

I will revise the patch to suggest vendor-supplied versions first,
then in-tree, then finally using --with-gmp (which is the method that
causes the most frequently asked questions)
Gerald Pfeifer - Feb. 12, 2012, 11:43 p.m.
On Sat, 21 Jan 2012, Jonathan Wakely wrote:
>> My 2c - I heartily recommend this patch.
> Thanks. I'm a bit surprised noone else has commented - I hoped this
> would be a no-brainer, or at least get some constructive feedback for
> further improvement.

One reason surely is that the diffs for changes like this look
a lot more frightening than the actual changes are. :-)

> I recently added http://gcc.gnu.org/wiki/InstallingGCC

That does indicate a problem, if our primary documentation is
not suitable for beginners as well.  Do you see any chance to
merge the two and account for the use case you are addressing
with the new document as part of doc/install.texi and its
associated web pages?

Gerald
Jonathan Wakely - Feb. 12, 2012, 11:57 p.m.
On 12 February 2012 23:43, Gerald Pfeifer wrote:
> On Sat, 21 Jan 2012, Jonathan Wakely wrote:
>>> My 2c - I heartily recommend this patch.
>> Thanks. I'm a bit surprised noone else has commented - I hoped this
>> would be a no-brainer, or at least get some constructive feedback for
>> further improvement.
>
> One reason surely is that the diffs for changes like this look
> a lot more frightening than the actual changes are. :-)
>
>> I recently added http://gcc.gnu.org/wiki/InstallingGCC
>
> That does indicate a problem, if our primary documentation is
> not suitable for beginners as well.  Do you see any chance to
> merge the two and account for the use case you are addressing
> with the new document as part of doc/install.texi and its
> associated web pages?

The wiki has several advantages, including that it's MUCH easier to
make small improvements to without waiting weeks for review, and the
less-official wiki docs can more easily refer to e.g. "For
Debian-based systems, including Ubuntu" where the main docs seem to
avoid referring to specific systems or vendors (though maybe that's
just my perception.)

That wiki page is far less formal in style than the main docs, which
has both pros and cons.

Patch

Index: doc/install.texi
===================================================================
--- doc/install.texi	(revision 182629)
+++ doc/install.texi	(working copy)
@@ -333,32 +333,35 @@  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
+Necessary to build GCC@.  If a GMP source distribution is found in a
+subdirectory of your GCC sources named @file{gmp}, it will be built
+together with GCC, this avoids the need to build GMP separately.
+Alternatively, if GMP is already installed but it is not in your
 library search path, you will have to configure with the
 @option{--with-gmp} configure option.  See also @option{--with-gmp-lib}
-and @option{--with-gmp-include}.  Alternatively, if a GMP source
-distribution is found in a subdirectory of your GCC sources named
-@file{gmp}, it will be built together with GCC@.
+and @option{--with-gmp-include}.
 
 @item MPFR Library version 2.4.2 (or later)
 
 Necessary to build GCC@.  It can be downloaded from
-@uref{http://www.mpfr.org/}.  The @option{--with-mpfr} configure
-option should be used if your MPFR Library is not installed in your
-default library search path.  See also @option{--with-mpfr-lib} and
-@option{--with-mpfr-include}.  Alternatively, if a MPFR source
-distribution is found in a subdirectory of your GCC sources named
-@file{mpfr}, it will be built together with GCC@.
+@uref{http://www.mpfr.org/}.  If an MPFR source distribution is found
+in a subdirectory of your GCC sources named @file{mpfr}, it will be
+built together with GCC, this avoids the need to build MPFR separately.
+Alternatively, if MPFR is already installed but it is not in your
+default library search path, the @option{--with-mpfr} configure
+option should be used.  See also @option{--with-mpfr-lib} and
+@option{--with-mpfr-include}.
 
 @item MPC Library version 0.8.1 (or later)
 
 Necessary to build GCC@.  It can be downloaded from
-@uref{http://www.multiprecision.org/}.  The @option{--with-mpc}
-configure option should be used if your MPC Library is not installed
-in your default library search path.  See also @option{--with-mpc-lib}
-and @option{--with-mpc-include}.  Alternatively, if an MPC source
-distribution is found in a subdirectory of your GCC sources named
-@file{mpc}, it will be built together with GCC@.
+@uref{http://www.multiprecision.org/}.  If an MPC source distribution
+is found in a subdirectory of your GCC sources named @file{mpc}, it
+will be built together with GCC, this avoids the need to build MPC
+separately.  Alternatively, if MPC is already installed but it is
+not in your default library search path, the @option{--with-mpc}
+configure option should be used.  See also @option{--with-mpc-lib}
+and @option{--with-mpc-include}.
 
 @item Parma Polyhedra Library (PPL) version 0.11
 
@@ -1608,9 +1611,10 @@  When neither of these configure options 
 @itemx --with-mpc=@var{pathname}
 @itemx --with-mpc-include=@var{pathname}
 @itemx --with-mpc-lib=@var{pathname}
-If you do not have GMP (the GNU Multiple Precision library), the MPFR
-library and/or the MPC library installed in a standard location and
-you want to build GCC, you can explicitly specify the directory where
+If you want to build GCC but do not have GMP (the GNU Multiple Precision
+library), the MPFR library and/or the MPC library installed in a
+standard location and don't have their sources present in the GCC
+source tree then you can explicitly specify the directory where
 they are installed (@samp{--with-gmp=@var{gmpinstalldir}},
 @samp{--with-mpfr=@/@var{mpfrinstalldir}},
 @samp{--with-mpc=@/@var{mpcinstalldir}}).  The