Paul Eggert wrote: > > There are more and more random users, who are not experts and who try the > > git checkout of a GNU package, rather than the newest release. And then > > wonder, for example, why the INSTALL file suggests to run './configure' > > although no 'configure' file is present. [1] > > [1] https://savannah.gnu.org/bugs/?62196 > > Good point. And this is not the only reason INSTALL is out of date. I > took a shot at fixing this by installing the second attached patch into > Autoconf and propagating it into Gnulib. Comments welcome of course.
Thanks for doing this modernization! Comments:
* I find the mention of 'bootstrap' and autopull.sh + autogen.sh well done:
it goes into enough detail so that people who did a 'git clone ...' are
not stuck, while at the same time keeping the focus on the tarball users.
* The wording regarding --build and --host is misleading and, IMO, backwards.
Reasons:
1) './configure --help' says
--build=BUILD configure for building on BUILD [guessed]
--host=HOST cross-compile to build programs to run on HOST [BUILD]
whereas in the INSTALL file we read:
‘--build=TYPE’
Build for architecture TYPE.
The latter is wrong, IMO. "Build for", in my understanding, is --host=TYPE.
2) I have experience building for many system types, and I only give the
--host option, never the --build option.
* The --build type is always guessed correctly. And if it were not
guessed correctly, it's not enough to specify --build. It should also
be reported upstream.
* The term "cross-compiler" is ambiguous, because is it "cross compiling"
when
- compiling for i386-linux-gnu on a x86_64-linux-gnu machine?
- compiling for aarch64-linux-gnu on a x86_64-linux-gnu machine that
has the binfmt support enabled for executing aarch64 binaries
through qemu?
- compiling for i386-w64-mingw32 on a x86_64-pc-cygwin host?
Different people will given different responses to these questions.
3) Cross-compilation can easily run into trouble when one specifies CC or
--host but not both. The text should recommend to specify both in this
case.
4) The section "System Type" starts with a hint to a use-case:
"Usually, assuming the package is built to be run on the
*same* architectures ..."
but then gets back to this use-case way too late, only after having
explained two other use-cases. A proper doc structure should mention
the three use-cases one by one.
5) It mentions the --target option before mentioning --host. But many more
people use cross-compilation (including the three cases above) than there
are people who build GCC themselves.
Find here a proposed patch. For ease of review, find also the HTML-formatted
chapter: `makeinfo --html --no-split install.texi`.
>From c97bcff8c41b297fc408d6935133aa4616724030 Mon Sep 17 00:00:00 2001
From: Bruno Haible <br...@clisp.org>
Date: Fri, 23 Jun 2023 17:37:35 +0200
Subject: [PATCH] INSTALL: Clarify --build, --host, --target, and the system
types.
* doc/install.texi (Compilers and Options): Add another reference.
(System Types): Renamed from System Type. Explain how to canonicalize and how to
validate a system type. Don't explain --build, --host, --target here.
(Building for a different system type): New section.
(Troubleshooting the Build Type): New section.
(Configuring a Compiler): New section.
(configure Invocation): Mention the --host option, not the --build option, since
--build is so rarely needed.
---
doc/install.texi | 132 ++++++++++++++++++++++++++++++++++++++---------
1 file changed, 108 insertions(+), 24 deletions(-)
diff --git a/doc/install.texi b/doc/install.texi
index 6d9788fa..a3ef1782 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -157,8 +157,16 @@ Here is an example:
./configure CC=gcc CFLAGS=-g LIBS=-lposix
@end example
-@xref{Defining Variables}, for more details.
-
+See
+@ref{Defining Variables} and
+@ifset autoconf
+@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
@@ -263,18 +271,17 @@ output, which can be overridden with @code{make V=1}; while running
@samp{./configure --disable-silent-rules} sets the default to verbose,
which can be overridden with @code{make V=0}.
-@node System Type
-@section Specifying the System Type
+@node System Types
+@section Specifying a System Type
-There may be some features @command{configure} cannot figure out
-automatically, but needs to determine by the type of machine the package
-will run on. Usually, assuming the package is built to be run on the
-@emph{same} architectures, @command{configure} can figure that out, but
-if it prints a message saying it cannot guess the machine type, give it
-the @option{--build=@var{type}} option. @var{type} can either be a
-short name like @samp{mingw64} for the system type, or a canonical name
-like @samp{x86_64-pc-linux-gnu}
-which has the form:
+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}
@@ -291,16 +298,93 @@ where @var{system} can have one of these forms:
@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 the machine type.
+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
+
+@example
+$ sh config.sub x86_64-linux
+x86_64-pc-linux-gnu
+$ sh config.sub arm64-linux
+aarch64-unknown-linux-gnu
+@end example
+
+@noindent
+It also validates the parts. For example, this interaction tells you
+that ``crusoe'' is not a valid cpu architecture name:
-If you are @emph{building} compiler tools for cross-compiling, you
-should use the option @option{--target=@var{type}} to select the type of
-system they will produce code for.
+@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 want to @emph{use} a cross compiler, that generates code for a
-platform different from the build platform, you should specify the
-@dfn{host} platform (i.e., that on which the generated programs will
-eventually be run) with @option{--host=@var{type}}.
+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
+@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.
@node Sharing Defaults
@section Sharing Defaults
@@ -384,9 +468,9 @@ Use @var{dir} as the installation prefix. @ref{Installation Names}
for more details, including other options available for fine-tuning
the installation locations.
-@item --build=@var{type}
-Build for architecture @var{type}. @ref{System Type}.
-for more details, including other system type options.
+@item --host=@var{type}
+Build binaries for architecture @var{type}. @ref{System Types} and
+@ref{Building for a different system type} for more details.
@item --enable-@var{feature}
@itemx --disable-@var{feature}
--
2.34.1
Title: Untitled Document
|
Next: Compilers and Options Installation InstructionsCopyright © 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.
Basic InstallationBriefly, the following shell commands: test -f configure || ./bootstrap ./configure make make install should configure, build, and install this package.
The The following more-detailed instructions are generic; see the README file for instructions specific to this package. Some packages provide this INSTALL file but do not implement all of the features documented below. The lack of an optional feature in a given package is not necessarily a bug. More recommendations for GNU packages can be found in Makefile Conventions in GNU Coding Standards. If the The It can also use an optional file (typically called config.cache and enabled with --cache-file=config.cache or simply -C) that saves the results of its tests to speed up reconfiguring. Caching is disabled by default to prevent problems with accidental use of stale cache files. If you need to do unusual things to compile the package, please try to
figure out how The file configure.ac (or configure.in) is used to create
configure by a program called The simplest way to compile this package is:
Next: Compiling For Multiple Architectures, Previous: Basic Installation Compilers and OptionsSome systems require unusual options for compilation or linking that the
You can give ./configure CC=gcc CFLAGS=-g LIBS=-lposix See Defining Variables and Preset Output Variables in Autoconf for more details. Next: Installation Names, Previous: Compilers and Options Compiling For Multiple ArchitecturesYou 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
own directory. To do this, you can use GNU With a non-GNU Some platforms, notably macOS, support “fat” or “universal” binaries, where a single binary can execute on different architectures. On these platforms you can configure and compile just once, with options specific to that platform. Next: Optional Features, Previous: Compiling For Multiple Architectures Installation NamesBy default, ‘make install’ installs the package’s commands under
/usr/local/bin, include files under /usr/local/include, etc.
You can specify an
installation prefix other than /usr/local by giving
You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you pass the option
--exec-prefix=prefix to In addition, if you use an unusual directory layout you can give options like --bindir=dir to specify different values for particular kinds of files. Run ‘configure --help’ for a list of the directories you can set and what kinds of files go in them. In general, the default for these options is expressed in terms of ‘${prefix}’, so that specifying just --prefix will affect all of the other directory specifications that were not explicitly provided. The most portable way to affect installation locations is to pass the
correct locations to The first method involves providing an override variable for each
affected directory. For example, ‘make install
prefix=/alternate/directory’ will choose an alternate location for all
directory configuration variables that were expressed in terms of
‘${prefix}’. Any directories that were specified during
The second method involves providing the ‘DESTDIR’ variable. For
example, ‘make install DESTDIR=/alternate/directory’ will prepend
‘/alternate/directory’ before all installation names. The approach
of ‘DESTDIR’ overrides is not required by the GNU Coding
Standards, and does not work on platforms that have drive letters. On
the other hand, it does better at avoiding recompilation issues, and
works well even when some directory options were not specified in terms
of ‘${prefix}’ at Next: Specifying a System Type, Previous: Installation Names Optional FeaturesIf the package supports it, you can cause programs to be installed with
an extra prefix or suffix on their names by giving Some packages pay attention to --enable-feature
and --disable-feature options
to Some packages offer the ability to configure how verbose the execution
of Next: Creating binaries for a different system type, Previous: Optional Features Specifying a System TypeThe following sections go into details regarding situations where you may have to specify a system type, either through the option --host=type, or through the option --build=type, or – in the case of compilers – through --target=type. A system type type can either be a short name like ‘mingw64’, or a canonical name like ‘x86_64-pc-linux-gnu’ which has the form: cpu-company-system where system can have one of these forms: os kernel-os See the file config.sub for the possible values of each field. If config.sub isn’t included in this package, then this package doesn’t need to know any machine type. The file config.sub is a program that validates and canonicalizes a system type. It can do canonicalization, as in $ sh config.sub x86_64-linux x86_64-pc-linux-gnu $ sh config.sub arm64-linux aarch64-unknown-linux-gnu It also validates the parts. For example, this interaction tells you that “crusoe” is not a valid cpu architecture name: $ sh config.sub crusoe-linux Invalid configuration `crusoe-linux': machine `crusoe-unknown' not recognized Next: Fixing a “cannot guess build type” error, Previous: Specifying a System Type Creating binaries for a different system typeWhen 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
For example, to create binaries intended to run on a 64-bit ARM processor: ./configure --host=aarch64-linux-gnu \
CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++
If you do this on a machine that can execute such binaries (e.g. by
virtue of the Next: Configuration options specific to a compiler, Previous: Creating binaries for a different system type Fixing a “cannot guess build type” errorIn rare cases, it may happen that 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 config.guess and config.sub. As a workaround, you can use a configure option --build=type, where type comes closest to your system type. Also, you’re welcome to file a report to config-patc...@gnu.org. Next: Sharing Defaults, Previous: Fixing a “cannot guess build type” error Configuration options specific to a compilerIf 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 --target=type to select the type of system for which the compiler should produce code. Next: Defining Variables, Previous: Configuration options specific to a compiler Sharing DefaultsIf you want to set default values for
Next: Defining VariablesVariables not defined in a site shell script can be set in the
environment passed to ./configure CC=/usr/local2/bin/gcc causes the specified Unfortunately, this technique does not work for CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash Previous: Defining Variables
|
