From d8ca8b323873e5cd9d969a062f70b31db450ba53 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 24 Jun 2023 14:39:34 -0700
Subject: [PATCH 29/29] Shorten and improve INSTALL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrite install.texi so that INSTALL is shorter and hopefully
more useful for new installers.
* doc/install.texi: When not building the Autoconf manual, put
copyright notice at the end, and omit external references as they
do not work in INSTALL.
Avoid long URLs as they do not work well in INSTALL or
in info files.  Be more consistent (though not entirely
consistent) about “system” vs “architecture”.
(System Types, Building for a different system type)
(Troubleshooting the Build Type): Coalesce into a single section
and rewrite for clarity and brevity.  Mention build-aux.  Do not
mention --target here as it’s too rare to make the cut.

Upstream-Status: Backport
Signed-off-by: Khem Raj <raj.khem@gmail.com>
---
 doc/install.texi | 224 +++++++++++++++++------------------------------
 1 file changed, 82 insertions(+), 142 deletions(-)

diff --git a/doc/install.texi b/doc/install.texi
index a3ef17828..6c3a9c21c 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -2,23 +2,13 @@
 @c the INSTALL file.
 
 @ifclear autoconf
-
 @unnumbered Installation Instructions
-
-Copyright @copyright{} 1994--1996, 1999--2002, 2004--2017, 2020--2023
-Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification, are
-permitted in any medium without royalty provided the copyright notice
-and this notice are preserved.  This file is offered as-is, without
-warranty of any kind.
-
 @end ifclear
 
 @node Basic Installation
 @section Basic Installation
 
-Briefly, the following shell commands:
+The following shell commands:
 
 @example
 test -f configure || ./bootstrap
@@ -41,8 +31,13 @@ of the features documented below.  The lack of an optional feature in a
 given package is not necessarily a bug.
 @end ifclear
 More recommendations for GNU packages can be found in
+@ifset autoconf
 @ref{Makefile Conventions, , Makefile Conventions, standards,
 GNU Coding Standards}.
+@end ifset
+@ifclear autoconf
+the GNU Coding Standards.
+@end ifclear
 
 If the @command{bootstrap} shell script exists, it attempts to build the
 @command{configure} shell script and related files, perhaps by
@@ -61,8 +56,8 @@ those values to create a @file{Makefile} in each directory of the
 package.  It may also create one or more @file{.h} files containing
 system-dependent definitions.  Finally, it creates a shell script
 @file{config.status} that you can run in the future to recreate the
-current configuration, and a file @file{config.log} containing compiler
-output (useful mainly for debugging @command{configure}).
+current configuration, and a file @file{config.log} containing
+output useful for debugging @command{configure}.
 
 It can also use an optional file (typically called @file{config.cache}
 and enabled with @option{--cache-file=config.cache} or simply
@@ -77,10 +72,9 @@ they can be considered for the next release.  If you are using the
 cache, and at some point @file{config.cache} contains results you don't
 want to keep, you may remove or edit it.
 
-The file @file{configure.ac} (or @file{configure.in}) is used to create
-@file{configure} by a program called @command{autoconf}.  You need
-@file{configure.ac} if you want to change it or regenerate
-@file{configure} using a newer version of @command{autoconf}.
+The @command{autoconf} program generates @file{configure} from the file
+@file{configure.ac}.  Normally you should edit @file{configure.ac}
+instead of editing @file{configure} directly.
 
 The simplest way to compile this package is:
 
@@ -95,8 +89,7 @@ You may need special developer tools and network access to bootstrap.
 
 @item
 Type @samp{./configure} to configure the package for your system.
-
-Running @command{configure} might take a while.  While running, it prints some
+This might take a while.  While running, @command{configure} prints
 messages telling which features it is checking for.
 
 @item
@@ -125,21 +118,11 @@ code directory by typing @samp{make clean}.  To also remove the files
 that @command{configure} created (so you can compile the package for a
 different kind of computer), type @samp{make distclean}.  There is also
 a @samp{make maintainer-clean} target, but that is intended mainly for
-the package's developers.  If you use it, you may have to get all sorts
-of other programs in order to regenerate files that came with the
-distribution.
+the package's developers.  If you use it, you may have to bootstrap again.
 
 @item
-Often, you can also type @samp{make uninstall} to remove the installed
-files again.  In practice, not all packages have tested that
-uninstallation works correctly, even though it is required by the
-GNU Coding Standards.
-
-@item
-Some packages, particularly those that use Automake, provide @samp{make
-distcheck}, which can by used by developers to test that all other
-targets like @samp{make install} and @samp{make uninstall} work
-correctly.  This target is generally not run by end users.
+If the package follows the GNU Coding Standards,
+you can type @samp{make uninstall} to remove the installed files.
 @end enumerate
 
 @node Compilers and Options
@@ -158,21 +141,17 @@ Here is an example:
 @end example
 
 See
-@ref{Defining Variables} and
+@ref{Defining Variables}
 @ifset autoconf
-@ref{Preset Output Variables}
+and @ref{Preset Output Variables}
 @end ifset
-@ifclear autoconf
-@ref{Preset Output Variables,,, autoconf, Autoconf}
-@c (@url{https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.71/html_node/Preset-Output-Variables.html})
-@end ifclear
 for more details.
 
 @node Multiple Architectures
 @section Compiling For Multiple Architectures
 
 You can compile the package for more than one kind of computer at the
-same time, by placing the object files for each architecture in their
+same time, by placing the object files for each system in their
 own directory.  To do this, you can use GNU @command{make}.
 @command{cd} to the directory where you want the object files and
 executables to go and run the @command{configure} script.
@@ -182,9 +161,9 @@ known as a @dfn{VPATH} build.
 
 With a non-GNU @command{make},
 it is safer to compile the package for one
-architecture at a time in the source code directory.  After you have
-installed the package for one architecture, use @samp{make distclean}
-before reconfiguring for another architecture.
+system at a time in the source code directory.  After you have
+installed the package for one system, use @samp{make distclean}
+before reconfiguring for another system.
 
 Some platforms, notably macOS, support ``fat'' or ``universal'' binaries,
 where a single binary can execute on different architectures.
@@ -274,117 +253,65 @@ which can be overridden with @code{make V=0}.
 @node System Types
 @section Specifying a System Type
 
-The following sections go into details regarding situations where you
-may have to specify a system type, either through the option
-@option{--host=@var{type}}, or through the option
-@option{--build=@var{type}}, or -- in the case of compilers -- through
-@option{--target=@var{type}}.
-
-A system type @var{type} can either be a short name like @samp{mingw64},
-or a canonical name like @samp{x86_64-pc-linux-gnu} which has the form:
-
-@example
-@var{cpu}-@var{company}-@var{system}
-@end example
-
-@noindent
-where @var{system} can have one of these forms:
+By default @command{configure} builds for the current system.
+To create binaries that can run on a different system type,
+specify a @option{--host=@var{type}} option along with compiler
+variables that specify how to generate object code for @var{type}.
+For example, to create binaries intended to run on a 64-bit ARM
+processor:
 
 @example
-@var{os}
-@var{kernel}-@var{os}
+./configure --host=aarch64-linux-gnu \
+   CC=aarch64-linux-gnu-gcc \
+   CXX=aarch64-linux-gnu-g++
 @end example
 
 @noindent
-See the file @file{config.sub} for the possible values of each field.
-If @file{config.sub} isn't included in this package, then this package
-doesn't need to know any machine type.
-
-The file @file{config.sub} is a program that validates and canonicalizes
-a system type.
-It can do canonicalization, as in
+If done on a machine that can execute these binaries
+(e.g., via @command{qemu-aarch64}, @env{$QEMU_LD_PREFIX}, and Linux's
+@code{binfmt_misc} capability), the build behaves like a native build.
+Otherwise it is a cross-build: @code{configure}
+will make cross-compilation guesses instead of running test programs,
+and @code{make check} will not work.
+
+A system type can either be a short name like @samp{mingw64},
+or a canonical name like @samp{x86_64-pc-linux-gnu}.
+Canonical names have the form @var{cpu}-@var{company}-@var{system}
+where @var{system} is either @var{os} or @var{kernel}-@var{os}.
+To canonicalize and validate a system type,
+you can run the command @file{config.sub},
+which is often squirreled away in a subdirectory like @file{build-aux}.
+For example:
 
 @example
-$ sh config.sub x86_64-linux
-x86_64-pc-linux-gnu
-$ sh config.sub arm64-linux
+$ build-aux/config.sub arm64-linux
 aarch64-unknown-linux-gnu
+$ build-aux/config.sub riscv-lnx
+Invalid configuration 'riscv-lnx': OS 'lnx' not recognized
 @end example
 
 @noindent
-It also validates the parts.  For example, this interaction tells you
-that ``crusoe'' is not a valid cpu architecture name:
-
-@example
-$ sh config.sub crusoe-linux
-Invalid configuration `crusoe-linux': machine `crusoe-unknown' not recognized
-@end example
-
-@node Building for a different system type
-@section Creating binaries for a different system type
-
-When you want to create binaries that will run on a different machine
-type than the one you are building on, you need to specify both
-@itemize @bullet
-@item
-a @option{--host=@var{type}} option, specifying the machine type on
-which the binaries shall run,
-@item
-compiler variables (@code{CC} for the C compiler, @code{CXX} for the C++
-compiler, and so on), pointing to compilers that generate object code
-for that machine type.
-@end itemize
-
-For example, to create binaries intended to run on a 64-bit ARM
-processor:
-@example
-./configure --host=aarch64-linux-gnu \
-            CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++
-@end example
-
-If you do this on a machine that can execute such binaries (e.g.@: by
-virtue of the @code{qemu-aarch64} program, system libraries for that
-architecture under @code{$QEMU_LD_PREFIX}, and a Linux
-@code{binfmt_misc} configuration), the build behaves like a native
-build.
-If not, the build is a cross-build, in the sense that @code{configure}
-will make cross-compilation guesses instead of running test programs,
-and ``make check'' will not work.
-
-@node Troubleshooting the Build Type
-@section Fixing a ``cannot guess build type'' error
-
-In rare cases, it may happen that @code{configure} fails with the error
-message ``cannot guess build type''.
-This error means that the files @file{config.guess} and
-@file{config.sub} don't recognize the type of the system on which you
-are building.
-In this case, first fetch the newest versions of these files, from
-@url{https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess}
-and
-@url{https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub},
-respectively, and use these as drop-in replacement for the files
-@file{config.guess} and @file{config.sub} that were shipped with this
-package.
-
-If this resolves the problem, feel free to report the solution to the
-maintainers of this package.
-
-Otherwise, it means that your system is not yet supported by
-@file{config.guess} and @file{config.sub}.
-As a workaround, you can use a configure option
-@option{--build=@var{type}}, where @var{type} comes closest to your
-system type.
-Also, you're welcome to file a report to
+You can look at the @file{config.sub} file to see which types are recognized.
+If the file is absent, this package does not need the system type.
+
+If @command{configure} fails with the diagnostic ``cannot guess build type''.
+@file{config.sub} did not recognize your system's type.
+In this case, first fetch the newest versions of these files
+from the @url{https://savannah.gnu.org/projects/config, GNU config package}.
+If that fixes things, please report it to the
+maintainers of the package containing @command{configure}.
+Otherwise, you can try the configure option
+@option{--build=@var{type}} where @var{type} comes close to your
+system type; also, please report the problem to
 @email{config-patches@@gnu.org}.
 
-@node Configuring a Compiler
-@section Configuration options specific to a compiler
-
-If you are building a compiler, and this compiler should generate code
-for a system type that is different from the one on which the compiler
-binaries shall run on, use the option @option{--target=@var{type}} to
-select the type of system for which the compiler should produce code.
+For more details about configuring system types, see
+@ifset autoconf
+@ref{Manual Configuration}.
+@end ifset
+@ifclear autoconf
+the Autoconf documentation.
+@end ifclear
 
 @node Sharing Defaults
 @section Sharing Defaults
@@ -469,8 +396,8 @@ for more details, including other options available for fine-tuning
 the installation locations.
 
 @item --host=@var{type}
-Build binaries for architecture @var{type}.  @ref{System Types} and
-@ref{Building for a different system type} for more details.
+Build binaries for system @var{type}.
+@xref{System Types}.
 
 @item --enable-@var{feature}
 @itemx --disable-@var{feature}
@@ -497,6 +424,19 @@ Run the configure checks, but stop before creating any output files.
 and accepts some other, less widely useful, options.
 Run @samp{configure --help} for more details.
 
+@ifclear autoconf
+@node Copyright notice
+@section Copyright notice
+
+Copyright @copyright{} 1994--1996, 1999--2002, 2004--2017, 2020--2023
+Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice
+and this notice are preserved.  This file is offered as-is, without
+warranty of any kind.
+@end ifclear
+
 @c Local Variables:
 @c fill-column: 72
 @c ispell-local-dictionary: "american"
-- 
2.41.0

