[Patch][doc][PR101843]clarification on building gcc and binutils together

[Patch][doc][PR101843]clarification on building gcc and binutils together

[Qing Zhao]

Hi,

This patch is on behalf of John Henning, who opened PR 101843: 
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101843

He proposed the following doc change, please take a look and let me know whether this is Okay for commit?

Thanks.

Qing
========
From 9bf6f9a5964df26cac32d90f57719f4871874d54 Mon Sep 17 00:00:00 2001
From: qing zhao <qing.zhao@oracle.com>
Date: Thu, 19 Aug 2021 18:20:49 -0400
Subject: [PATCH] doc/install.texi: add a generic advice on building gcc and
 binutils together.

gcc/ChangeLog:

* doc/install.texi: Add a generic advice on building gcc and binutils together.
---
 gcc/doc/install.texi | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 8e974d2..4f1abbd 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -562,11 +562,13 @@ language front end and the language runtime (where appropriate).
 
 If you also intend to build binutils (either to upgrade an existing
 installation or for use in place of the corresponding tools of your
-OS), unpack the binutils distribution either in the same directory or
-a separate one.  In the latter case, add symbolic links to any
-components of the binutils you intend to build alongside the compiler
-(@file{bfd}, @file{binutils}, @file{gas}, @file{gprof}, @file{ld},
-@file{opcodes}, @dots{}) to the directory containing the GCC sources.
+OS), begin by identifying a version of binutils that was created at
+about the same time as your version of GCC.  Then unpack the binutils
+distribution either in the same directory or a separate one. In the
+latter case, add symbolic links to any components of the binutils you
+intend to build alongside the compiler (@file{bfd}, @file{binutils},
+@file{gas}, @file{gprof}, @file{ld}, @file{opcodes}, @dots{}) to the
+directory containing the GCC sources.
 
 Likewise the GMP, MPFR and MPC libraries can be automatically built
 together with GCC.  You may simply run the
-- 
1.8.3.1

Re: [Patch][doc][PR101843]clarification on building gcc and binutils together

[Jeff Law]

On 8/19/2021 4:27 PM, Qing Zhao via Gcc-patches wrote:
> Hi,
>
> This patch is on behalf of John Henning, who opened PR 101843:
> https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101843
>
> He proposed the following doc change, please take a look and let me know whether this is Okay for commit?
I think we need to get away from suggesting single tree builds. Instead 
what we should recommend is to identify the right version of binutils, 
build and install it into the same prefix as GCC will be installed, then 
build and install GCC.

jeff

Re: [Patch][doc][PR101843]clarification on building gcc and binutils together

[Qing Zhao]

Hi, Jeff,

Sorry for the late reply.

The following is the reply from John Henning and the updated patch based on your suggestions, 
Please take a look and let us know any issue there.

Thanks.

Qing

======================================================================
Jeff Law suggested that the documentation should recommend building binutils
separately.  The same suggestion was made in the discussion of bug 101843.  

OK.  Rev.2 of the suggested doc patch DOES make that recommendation.

Rev.2 of the patch DOES NOT remove all documentation of GCC+binutils
combined builds, out of respect for existing user practice (*).

Rev.2 of the patch DOES remove mention of unpacking binutils 
   "in the same directory"
which is clearly dangerous for subdirectories that have the same 
name but different content (such as libiberty/, which is what led 
to bug 101843).

(*) There are many google tracks, and it has been documented >20 years
    https://web.archive.org/web/20001014203336/http://gcc.gnu.org:80/install/download.html
    Therefore I (jhenning) suggest that it is useful to provide the clue on
    how to have the best chance that a combined build will succeed.


From b0034a941ff6a74589369a1f79cfc12295edf5d3 Mon Sep 17 00:00:00 2001
From: Qing Zhao <qing.zhao@oracle.com>
Date: Thu, 9 Sep 2021 15:00:26 +0000
Subject: [PATCH] doc/install.texi: add a generic advice on building gcc and
 binutils together.

---
 gcc/doc/install.texi | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 8e974d2952ef..a5ac462933b9 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -562,8 +562,14 @@ language front end and the language runtime (where appropriate).

 If you also intend to build binutils (either to upgrade an existing
 installation or for use in place of the corresponding tools of your
-OS), unpack the binutils distribution either in the same directory or
-a separate one.  In the latter case, add symbolic links to any
+OS), begin by identifying a version of binutils that was created at
+about the same time as your version of GCC.  It is recommended to build
+and install binutils first, before building GCC. You can set the prefix
+directory to the same as will be used for the GCC installation.
+
+Alternatively, it is often possible to build binutils at the same time
+that you build GCC.  If you wish to try this method, unpack the binutils
+distribution in a separate directory, and add symbolic links to any
 components of the binutils you intend to build alongside the compiler
 (@file{bfd}, @file{binutils}, @file{gas}, @file{gprof}, @file{ld},
 @file{opcodes}, @dots{}) to the directory containing the GCC sources.
-- 
2.27.0


> On Aug 23, 2021, at 12:45 AM, Jeff Law via Gcc-patches <gcc-patches@gcc.gnu.org> wrote:
> 
> 
> 
> On 8/19/2021 4:27 PM, Qing Zhao via Gcc-patches wrote:
>> Hi,
>> 
>> This patch is on behalf of John Henning, who opened PR 101843:
>> https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101843
>> 
>> He proposed the following doc change, please take a look and let me know whether this is Okay for commit?
> I think we need to get away from suggesting single tree builds. Instead what we should recommend is to identify the right version of binutils, build and install it into the same prefix as GCC will be installed, then build and install GCC.
> 
> jeff
> 

Re: [Patch][doc][PR101843]clarification on building gcc and binutils together

[Jeff Law]

On 9/9/2021 9:05 AM, Qing Zhao wrote:
> Hi, Jeff,
>
> Sorry for the late reply.
>
> The following is the reply from John Henning and the updated patch based on your suggestions,
> Please take a look and let us know any issue there.
I would strongly recommend removing all the documentation related to 
single tree builds.  While they were quite useful in the past, setting 
up such a tree these days is error prone and discouraged.

Jeff

Re: [Patch][doc][PR101843]clarification on building gcc and binutils together

[John Henning]

Hello Jeff,

>    I would strongly recommend removing all the documentation related to 
>    single tree builds.  

Two questions:

(1) When you say "all", are you suggesting that in-the-gcc-tree builds of gmp, mpfr, mpc, and isl should no longer be documented?  Or only in-tree builds of binutils?

(2) Is there any truth to the suggestion (found in some google tracks) that when building a cross-compiler, it is easier to build binutils in the same tree?   For example

https://gcc.gnu.org/wiki/Building_Cross_Toolchains_with_gcc
https://www.gnu.org/software/gcc/simtest-howto.html 
https://stackoverflow.com/a/6228588

It is out of respect for existing user habit that I proposed merely demoting it to an "alternative" method (while "recommending" the separate build).  

   -john