Target maintainers: doc/install.texi love and care

Target maintainers: doc/install.texi love and care

[Gerald Pfeifer]

I noticed that the target-specific sections in doc/install.texi
need a little lover and care.  It would be great could you have
a look and streamline/update before the GCC 7 release.

Thanks!


Also, I'm offering help around one particular aspect I noticed:

References to dependencies on really, really old versions of
binutils (talking 10+ years here) which I think we can remove.
Let me follow-up with some of you with concrete suggestions 
around that.

Gerald

Re: Target maintainers: doc/install.texi love and care

[Palmer Dabbelt]

On Sun, 12 Mar 2017 04:27:26 PDT (-0700), gerald@pfeifer.com wrote:
> I noticed that the target-specific sections in doc/install.texi
> need a little lover and care.  It would be great could you have
> a look and streamline/update before the GCC 7 release.

I looked at our stuff (RISC-V) and there's almost nothing in there.  Is there
something I should add?  I looked at the aarch64 stuff in the "host/target
specific issues start here" section and there's some notes about binutils-2.24.
We'll require binutils-2.28 (the first version that we're upstream in), I can
add a note in that section about RISC-V as well if you think it's appropriate.

Re: Target maintainers: doc/install.texi love and care

[Gerald Pfeifer]

Hi Palmer,

On Sun, 12 Mar 2017, Palmer Dabbelt wrote:
> I looked at our stuff (RISC-V) and there's almost nothing in there.  
> Is there something I should add?  I looked at the aarch64 stuff in the 
> "host/target specific issues start here" section and there's some notes 
> about binutils-2.24. We'll require binutils-2.28 (the first version that 
> we're upstream in), I can add a note in that section about RISC-V as 
> well if you think it's appropriate.

I am generally a fan of keeping documentation short (lest it is
skipped or skimmed), but as long as necessary.

In your case I don't think artificially blowing up the section on RISC-V 
to match others would be helpful.  However, given that binutils 2.28 is
so brand new, that I'd definitely mention.

(My proposals/patches yesterday are about removing references to ten
year old versions of binutils from install.texi, quite the other end
of the spectrum.)

Gerald

Re: Target maintainers: doc/install.texi love and care

[Palmer Dabbelt]

On Mon, 13 Mar 2017 01:59:28 PDT (-0700), gerald@pfeifer.com wrote:
> On Sun, 12 Mar 2017, Palmer Dabbelt wrote:
>> I looked at our stuff (RISC-V) and there's almost nothing in there.
>> Is there something I should add?  I looked at the aarch64 stuff in the
>> "host/target specific issues start here" section and there's some notes
>> about binutils-2.24. We'll require binutils-2.28 (the first version that
>> we're upstream in), I can add a note in that section about RISC-V as
>> well if you think it's appropriate.
>
> I am generally a fan of keeping documentation short (lest it is
> skipped or skimmed), but as long as necessary.
>
> In your case I don't think artificially blowing up the section on RISC-V
> to match others would be helpful.  However, given that binutils 2.28 is
> so brand new, that I'd definitely mention.
>
> (My proposals/patches yesterday are about removing references to ten
> year old versions of binutils from install.texi, quite the other end
> of the spectrum.)

Makes sense.  I think I found a few other problems in ours as well.  How does
this look?

[PATCH] RISC-V documentation cleanups

[PATCH] RISC-V documentation cleanups

[Palmer Dabbelt]

A recent mailing list post about install.texi cleanup suggested I take a
look at ours, and there were a few problems:

 * No table of contents entries
 * Not alphabetically ordered
 * Missing a note about requiring binutils-2.28

gcc/ChangeLog:

2017-03-13  Palmer Dabbelt  <palmer@dabbelt.com

        * doc/install.texi (Specific) <riscv32-*-elf>: Add table of contents
        link.
        <riscv32-*-linux>: Likewise.
        <riscv64-*-elf>: Likewise
        <riscv64-*-linux>: Likewise.
        <riscv64-*-elf>: Re-arrange section
        <riscv32-*-elf>: Add a note about requiring binutils-2.28.
        <riscv32-*-linux>: Likewise.
        <riscv64-*-elf>: Likewise
        <riscv64-*-linux>: Likewise.
---
 gcc/ChangeLog        | 13 +++++++++++++
 gcc/doc/install.texi | 30 +++++++++++++++++++++++-------
 2 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index a4cd56f..9493330 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,16 @@
+2017-03-13  Palmer Dabbelt  <palmer@dabbelt.com
+
+	* doc/install.texi (Specific) <riscv32-*-elf>: Add table of contents
+	link.
+	<riscv32-*-linux>: Likewise.
+	<riscv64-*-elf>: Likewise
+	<riscv64-*-linux>: Likewise.
+	<riscv64-*-elf>: Re-arrange section
+	<riscv32-*-elf>: Add a note about requiring binutils-2.28.
+	<riscv32-*-linux>: Likewise.
+	<riscv64-*-elf>: Likewise
+	<riscv64-*-linux>: Likewise.
+
 2017-03-13  Martin Liska  <mliska@suse.cz>
 
 	PR middle-end/78339
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index dced17d..e7cb30c 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -3211,6 +3211,14 @@ information have to.
 @item
 @uref{#powerpcle-x-eabi,,powerpcle-*-eabi}
 @item
+@uref{#riscv32-x-elf,,riscv32-*-elf}
+@item
+@uref{#riscv32-x-linux,,riscv32-*-linux}
+@item
+@uref{#riscv64-x-elf,,riscv64-*-elf}
+@item
+@uref{#riscv64-x-linux,,riscv64-*-linux}
+@item
 @uref{#s390-x-linux,,s390-*-linux*}
 @item
 @uref{#s390x-x-linux,,s390x-*-linux*}
@@ -4288,21 +4296,27 @@ This configuration is intended for embedded systems.
 @heading riscv32-*-elf
 The RISC-V RV32 instruction set.
 This configuration is intended for embedded systems.
+This (and all other RISC-V) targets are supported upstream as of the
+binutils-2.28 release.
 
 @html
 <hr />
 @end html
-@anchor{riscv64-x-elf}
-@heading riscv64-*-elf
-The RISC-V RV64 instruction set.
-This configuration is intended for embedded systems.
+@anchor{riscv32-x-linux}
+@heading riscv32-*-linux
+The RISC-V RV32 instruction set running GNU/Linux.
+This (and all other RISC-V) targets are supported upstream as of the
+binutils-2.28 release.
 
 @html
 <hr />
 @end html
-@anchor{riscv32-x-linux}
-@heading riscv32-*-linux
-The RISC-V RV32 instruction set running GNU/Linux.
+@anchor{riscv64-x-elf}
+@heading riscv64-*-elf
+The RISC-V RV64 instruction set.
+This configuration is intended for embedded systems.
+This (and all other RISC-V) targets are supported upstream as of the
+binutils-2.28 release.
 
 @html
 <hr />
@@ -4310,6 +4324,8 @@ The RISC-V RV32 instruction set running GNU/Linux.
 @anchor{riscv64-x-linux}
 @heading riscv64-*-linux
 The RISC-V RV64 instruction set running GNU/Linux.
+This (and all other RISC-V) targets are supported upstream as of the
+binutils-2.28 release.
 
 @html
 <hr />
-- 
2.10.2

Re: Target maintainers: doc/install.texi love and care

[Joseph Myers]

On Sun, 12 Mar 2017, Gerald Pfeifer wrote:

> References to dependencies on really, really old versions of
> binutils (talking 10+ years here) which I think we can remove.
> Let me follow-up with some of you with concrete suggestions 
> around that.

I think we should set a global minimum binutils version (for all targets 
using GNU binutils) and give an error at configure time for too-old 
binutils.  But not at the present development stage.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH] RISC-V documentation cleanups

[Gerald Pfeifer]

On Mon, 13 Mar 2017, Palmer Dabbelt wrote:
> A recent mailing list post about install.texi cleanup suggested I 
> take a look at ours, and there were a few problems:
> 
>  * No table of contents entries
>  * Not alphabetically ordered
>  * Missing a note about requiring binutils-2.28

This looks fine with a few changes, thank you.

Perhaps a bit repetitive?  I'm wondering, would it make sense to 
have general riscv64-*-* entries that cover the general items?

> 2017-03-13  Palmer Dabbelt  <palmer@dabbelt.com
> 
>         * doc/install.texi (Specific) <riscv32-*-elf>: Add table of contents
>         link.
>         <riscv32-*-linux>: Likewise.
>         <riscv64-*-elf>: Likewise
>         <riscv64-*-linux>: Likewise.

Here I'd just say

	* doc/install.texi (Specific): Add foo, bar, didl, doo to the
	table of contents.

>         <riscv32-*-elf>: Add a note about requiring binutils-2.28.

Here and in the text, binutils 2.28 (without the dash).

Approved.

Gerald

PS: We usually send patches to the gcc-patches@ list.