[gcc r12-1062] docs: port old-intall.texi part to install.texi

[gcc r12-1062] docs: port old-intall.texi part to install.texi

[Martin Liska]

https://gcc.gnu.org/g:0eac9c60ac1f28eeb7bb0a56e533865d984015f6

commit r12-1062-g0eac9c60ac1f28eeb7bb0a56e533865d984015f6
Author: Martin Liska <mliska@suse.cz>
Date:   Tue May 18 11:57:47 2021 +0200

    docs: port old-intall.texi part to install.texi
    
    gcc/ChangeLog:
    
            * doc/install.texi: Port relevant part from install-old.texi
            and re-generate list of CPUs and systems.

Diff:
---
 gcc/doc/install.texi | 72 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index f0591e06b3e..591ccaacbc1 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -697,23 +697,67 @@ The default value is @uref{https://gcc.gnu.org/,,https://gcc.gnu.org/}.
 
 @end table
 
-@heading Target specification
-@itemize @bullet
-@item
-GCC has code to correctly determine the correct value for @var{target}
-for nearly all native systems.  Therefore, we highly recommend you do
-not provide a configure target when configuring a native compiler.
+@heading Host, Build and Target specification
 
-@item
-@var{target} must be specified as @option{--target=@var{target}}
-when configuring a cross compiler; examples of valid targets would be
-m68k-elf, sh-elf, etc.
+Specify the host, build and target machine configurations.  You do this
+when you run the @file{configure} script.
 
-@item
-Specifying just @var{target} instead of @option{--target=@var{target}}
-implies that the host defaults to @var{target}.
-@end itemize
+The @dfn{build} machine is the system which you are using, the
+@dfn{host} machine is the system where you want to run the resulting
+compiler (normally the build machine), and the @dfn{target} machine is
+the system for which you want the compiler to generate code.
+
+If you are building a compiler to produce code for the machine it runs
+on (a native compiler), you normally do not need to specify any operands
+to @file{configure}; it will try to guess the type of machine you are on
+and use that as the build, host and target machines.  So you don't need
+to specify a configuration when building a native compiler unless
+@file{configure} cannot figure out what your configuration is or guesses
+wrong.
+
+In those cases, specify the build machine's @dfn{configuration name}
+with the @option{--host} option; the host and target will default to be
+the same as the host machine.
+
+Here is an example:
+
+@smallexample
+./configure --host=x86_64-pc-linux-gnu
+@end smallexample
 
+A configuration name may be canonical or it may be more or less
+abbreviated (@file{config.sub} script produces canonical versions).
+
+A canonical configuration name has three parts, separated by dashes.
+It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.
+
+Here are the possible CPU types:
+
+@quotation
+aarch64, aarch64_be, alpha, alpha64, amdgcn, arc, arceb, arm, armeb, avr, bfin,
+bpf, cr16, cris, csky, epiphany, fido, fr30, frv, ft32, h8300, hppa, hppa2.0,
+hppa64, i486, i686, ia64, iq2000, lm32, m32c, m32r, m32rle, m68k, mcore,
+microblaze, microblazeel, mips, mips64, mips64el, mips64octeon, mips64orion,
+mips64vr, mipsel, mipsisa32, mipsisa32r2, mipsisa64, mipsisa64r2,
+mipsisa64r2el, mipsisa64sb1, mipsisa64sr71k, mipstx39, mmix, mn10300, moxie,
+msp430, nds32be, nds32le, nios2, nvptx, or1k, pdp11, powerpc, powerpc64,
+powerpc64le, powerpcle, pru, riscv32, riscv32be, riscv64, riscv64be, rl78, rx,
+s390, s390x, sh, shle, sparc, sparc64, tic6x, tilegx, tilegxbe, tilepro, v850,
+v850e, v850e1, vax, visium, x86_64, xstormy16, xtensa
+@end quotation
+
+Here is a list of system types:
+
+@quotation
+aix@var{version}, amdhsa, aout, cygwin, darwin@var{version},
+eabi, eabialtivec, eabisim, eabisimaltivec, elf, elf32,
+elfbare, elfoabi, freebsd@var{version}, gnu, hpux, hpux@var{version},
+kfreebsd-gnu, kopensolaris-gnu, linux-androideabi, linux-gnu,
+linux-gnu_altivec, linux-musl, linux-uclibc, lynxos, mingw32, mingw32crt,
+mmixware, msdosdjgpp, netbsd, netbsdelf@var{version}, nto-qnx, openbsd,
+rtems, solaris@var{version}, symbianelf, tpf, uclinux, uclinux_eabi, vms,
+vxworks, vxworksae, vxworksmils
+@end quotation
 
 @heading Options specification