Re: INSTALL updates

From c97bcff8c41b297fc408d6935133aa4616724030 Mon Sep 17 00:00:00 2001
From: Bruno Haible <[email protected]>
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

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Untitled Document</title>

<meta name="description" content="Untitled Document">
<meta name="keywords" content="Untitled Document">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="#Basic-Installation" rel="start" title="Basic Installation">
<link href="#Compilers-and-Options" rel="next" title="Compilers and Options">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">


<div class="unnumbered" id="Installation-Instructions">
<div class="header">
<p>
Next: <a href="#Compilers-and-Options" accesskey="n" rel="next">Compilers and Options</a> &nbsp; </p>
</div>
<h2 class="unnumbered">Installation Instructions</h2>

<p>Copyright &copy; 1994&ndash;1996, 1999&ndash;2002, 2004&ndash;2017, 2020&ndash;2023
Free Software Foundation, Inc.
</p>
<p>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.
</p>

<ul class="section-toc">
<li><a href="#Basic-Installation" accesskey="1">Basic Installation</a></li>
<li><a href="#Compilers-and-Options" accesskey="2">Compilers and Options</a></li>
<li><a href="#Multiple-Architectures" accesskey="3">Compiling For Multiple Architectures</a></li>
<li><a href="#Installation-Names" accesskey="4">Installation Names</a></li>
<li><a href="#Optional-Features" accesskey="5">Optional Features</a></li>
<li><a href="#System-Types" accesskey="6">Specifying a System Type</a></li>
<li><a href="#Building-for-a-different-system-type" accesskey="7">Creating binaries for a different system type</a></li>
<li><a href="#Troubleshooting-the-Build-Type" accesskey="8">Fixing a &ldquo;cannot guess build type&rdquo; error</a></li>
<li><a href="#Configuring-a-Compiler" accesskey="9">Configuration options specific to a compiler</a></li>
<li><a href="#Sharing-Defaults">Sharing Defaults</a></li>
<li><a href="#Defining-Variables">Defining Variables</a></li>
<li><a href="#configure-Invocation"><code>configure</code> Invocation</a></li>
</ul>
<div class="section" id="Basic-Installation">
<span id="Basic-Installation-1"></span><h3 class="section">Basic Installation</h3>

<p>Briefly, the following shell commands:
</p>
<div class="example">
<pre class="example">test -f configure || ./bootstrap
./configure
make
make install
</pre></div>

<p>should configure, build, and install this package.
The <code>./bootstrap</code> line is intended for developers;
you can omit it when building from a distribution tarball.
</p>
<p>The following
more-detailed instructions are generic; see the <samp>README</samp> file for
instructions specific to this package.
Some packages provide this <samp>INSTALL</samp> 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
<a data-manual="standards" href="https://www.gnu.org/prep/standards/standards.html#Makefile-Conventions">Makefile Conventions</a> in <cite>GNU Coding Standards</cite>.
</p>
<p>If the <code>bootstrap</code> shell script exists, it attempts to build the
<code>configure</code> shell script and related files, perhaps by
downloading other software components from the network, and by using
developer tools that are less commonly installed.  Because the output of
<code>bootstrap</code> is system-independent, it is normally run by a
package developer so that its output can be put into the distribution
tarball and ordinary builders and users need not run <code>bootstrap</code>.
Some packages have commands like <code>./autopull.sh</code> and
<code>./autogen.sh</code> that you can run instead of <code>./bootstrap</code>,
for more fine-grained control over bootstrapping.
</p>
<p>The <code>configure</code> shell script attempts to guess correct values
for various system-dependent variables used during compilation.  It uses
those values to create a <samp>Makefile</samp> in each directory of the
package.  It may also create one or more <samp>.h</samp> files containing
system-dependent definitions.  Finally, it creates a shell script
<samp>config.status</samp> that you can run in the future to recreate the
current configuration, and a file <samp>config.log</samp> containing compiler
output (useful mainly for debugging <code>configure</code>).
</p>
<p>It can also use an optional file (typically called <samp>config.cache</samp>
and enabled with <samp>--cache-file=config.cache</samp> or simply
<samp>-C</samp>) 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.
</p>
<p>If you need to do unusual things to compile the package, please try to
figure out how <code>configure</code> could check whether to do them, and
mail diffs or instructions to the address given in the <samp>README</samp> so
they can be considered for the next release.  If you are using the
cache, and at some point <samp>config.cache</samp> contains results you don&rsquo;t
want to keep, you may remove or edit it.
</p>
<p>The file <samp>configure.ac</samp> (or <samp>configure.in</samp>) is used to create
<samp>configure</samp> by a program called <code>autoconf</code>.  You need
<samp>configure.ac</samp> if you want to change it or regenerate
<samp>configure</samp> using a newer version of <code>autoconf</code>.
</p>
<p>The simplest way to compile this package is:
</p>
<ol>
<li> <code>cd</code> to the directory containing the package&rsquo;s source code.

</li><li> If this is a developer checkout and file &lsquo;<samp>configure</samp>&rsquo; does not yet exist,
type &lsquo;<samp>./bootstrap</samp>&rsquo; to create it.
You may need special developer tools and network access to bootstrap.

</li><li> Type &lsquo;<samp>./configure</samp>&rsquo; to configure the package for your system.

<p>Running <code>configure</code> might take a while.  While running, it prints some
messages telling which features it is checking for.
</p>
</li><li> Type &lsquo;<samp>make</samp>&rsquo; to compile the package.

</li><li> Optionally, type &lsquo;<samp>make check</samp>&rsquo; to run any self-tests that come with
the package, generally using the just-built uninstalled binaries.

</li><li> Type &lsquo;<samp>make install</samp>&rsquo; to install the programs and any data files and
documentation.  When installing into a prefix owned by root, it is
recommended that the package be configured and built as a regular user,
and only the &lsquo;<samp>make install</samp>&rsquo; phase executed with root privileges.

</li><li> Optionally, type &lsquo;<samp>make installcheck</samp>&rsquo; to repeat any self-tests, but
this time using the binaries in their final installed location.  This
target does not install anything.  Running this target as a regular
user, particularly if the prior &lsquo;<samp>make install</samp>&rsquo; required root
privileges, verifies that the installation completed correctly.

</li><li> You can remove the program binaries and object files from the source
code directory by typing &lsquo;<samp>make clean</samp>&rsquo;.  To also remove the files
that <code>configure</code> created (so you can compile the package for a
different kind of computer), type &lsquo;<samp>make distclean</samp>&rsquo;.  There is also
a &lsquo;<samp>make maintainer-clean</samp>&rsquo; target, but that is intended mainly for
the package&rsquo;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.

</li><li> Often, you can also type &lsquo;<samp>make uninstall</samp>&rsquo; 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.

</li><li> Some packages, particularly those that use Automake, provide &lsquo;<samp>make
distcheck</samp>&rsquo;, which can by used by developers to test that all other
targets like &lsquo;<samp>make install</samp>&rsquo; and &lsquo;<samp>make uninstall</samp>&rsquo; work
correctly.  This target is generally not run by end users.
</li></ol>

<hr>
</div>
<div class="section" id="Compilers-and-Options">
<div class="header">
<p>
Next: <a href="#Multiple-Architectures" accesskey="n" rel="next">Compiling For Multiple Architectures</a>, Previous: <a href="#Basic-Installation" accesskey="p" rel="prev">Basic Installation</a> &nbsp; </p>
</div>
<span id="Compilers-and-Options-1"></span><h3 class="section">Compilers and Options</h3>

<p>Some systems require unusual options for compilation or linking that the
<code>configure</code> script does not know about.  Run &lsquo;<samp>./configure
--help</samp>&rsquo; for details on some of the pertinent environment variables.
</p>
<p>You can give <code>configure</code> initial values for configuration
parameters by setting variables in the command line or in the environment.
Here is an example:
</p>
<div class="example">
<pre class="example">./configure CC=gcc CFLAGS=-g LIBS=-lposix
</pre></div>

<p>See
<a href="#Defining-Variables">Defining Variables</a> and
<a data-manual="autoconf" href="https://www.gnu.org/software/autoconf/manual/autoconf.html#Preset-Output-Variables">Preset Output Variables</a> in <cite>Autoconf</cite>
for more details.
</p>
<hr>
</div>
<div class="section" id="Multiple-Architectures">
<div class="header">
<p>
Next: <a href="#Installation-Names" accesskey="n" rel="next">Installation Names</a>, Previous: <a href="#Compilers-and-Options" accesskey="p" rel="prev">Compilers and Options</a> &nbsp; </p>
</div>
<span id="Compiling-For-Multiple-Architectures"></span><h3 class="section">Compiling For Multiple Architectures</h3>

<p>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
own directory.  To do this, you can use GNU <code>make</code>.
<code>cd</code> to the directory where you want the object files and
executables to go and run the <code>configure</code> script.
<code>configure</code> automatically checks for the source code in the
directory that <code>configure</code> is in and in <samp>..</samp>.  This is
known as a <em>VPATH</em> build.
</p>
<p>With a non-GNU <code>make</code>,
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 &lsquo;<samp>make distclean</samp>&rsquo;
before reconfiguring for another architecture.
</p>
<p>Some platforms, notably macOS, support &ldquo;fat&rdquo; or &ldquo;universal&rdquo; 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.
</p>
<hr>
</div>
<div class="section" id="Installation-Names">
<div class="header">
<p>
Next: <a href="#Optional-Features" accesskey="n" rel="next">Optional Features</a>, Previous: <a href="#Multiple-Architectures" accesskey="p" rel="prev">Compiling For Multiple Architectures</a> &nbsp; </p>
</div>
<span id="Installation-Names-1"></span><h3 class="section">Installation Names</h3>

<p>By default, &lsquo;<samp>make install</samp>&rsquo; installs the package&rsquo;s commands under
<samp>/usr/local/bin</samp>, include files under <samp>/usr/local/include</samp>, etc.
You can specify an
installation prefix other than <samp>/usr/local</samp> by giving
<code>configure</code> the option <samp>--prefix=<var>prefix</var></samp>, where
<var>prefix</var> must be an absolute file name.
</p>
<p>You can specify separate installation prefixes for architecture-specific
files and architecture-independent files.  If you pass the option
<samp>--exec-prefix=<var>prefix</var></samp> to <code>configure</code>, the
package uses <var>prefix</var> as the prefix for installing programs and
libraries.  Documentation and other data files still use the
regular prefix.
</p>
<p>In addition, if you use an unusual directory layout you can give options
like <samp>--bindir=<var>dir</var></samp> to specify different values for
particular kinds of files.  Run &lsquo;<samp>configure --help</samp>&rsquo; 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
&lsquo;<samp>${prefix}</samp>&rsquo;, so that specifying just <samp>--prefix</samp> will
affect all of the other directory specifications that were not
explicitly provided.
</p>
<p>The most portable way to affect installation locations is to pass the
correct locations to <code>configure</code>; however, many packages provide
one or both of the following shortcuts of passing variable assignments
to the &lsquo;<samp>make install</samp>&rsquo; command line to change installation locations
without having to reconfigure or recompile.
</p>
<p>The first method involves providing an override variable for each
affected directory.  For example, &lsquo;<samp>make install
prefix=/alternate/directory</samp>&rsquo; will choose an alternate location for all
directory configuration variables that were expressed in terms of
&lsquo;<samp>${prefix}</samp>&rsquo;.  Any directories that were specified during
<code>configure</code>, but not in terms of &lsquo;<samp>${prefix}</samp>&rsquo;, must each be
overridden at install time for the entire
installation to be relocated.  The approach of makefile variable
overrides for each directory variable is required by the GNU
Coding Standards, and ideally causes no recompilation.  However, some
platforms have known limitations with the semantics of shared libraries
that end up requiring recompilation when using this method, particularly
noticeable in packages that use GNU Libtool.
</p>
<p>The second method involves providing the &lsquo;<samp>DESTDIR</samp>&rsquo; variable.  For
example, &lsquo;<samp>make install DESTDIR=/alternate/directory</samp>&rsquo; will prepend
&lsquo;<samp>/alternate/directory</samp>&rsquo; before all installation names.  The approach
of &lsquo;<samp>DESTDIR</samp>&rsquo; 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 &lsquo;<samp>${prefix}</samp>&rsquo; at <code>configure</code> time.
</p>
<hr>
</div>
<div class="section" id="Optional-Features">
<div class="header">
<p>
Next: <a href="#System-Types" accesskey="n" rel="next">Specifying a System Type</a>, Previous: <a href="#Installation-Names" accesskey="p" rel="prev">Installation Names</a> &nbsp; </p>
</div>
<span id="Optional-Features-1"></span><h3 class="section">Optional Features</h3>

<p>If the package supports it, you can cause programs to be installed with
an extra prefix or suffix on their names by giving <code>configure</code>
the option <samp>--program-prefix=<var>PREFIX</var></samp> or
<samp>--program-suffix=<var>SUFFIX</var></samp>.
</p>
<p>Some packages pay attention to <samp>--enable-<var>feature</var></samp>
and <samp>--disable-<var>feature</var></samp> options
to <code>configure</code>, where <var>feature</var> indicates an optional part
of the package.  They may also pay attention to
<samp>--with-<var>package</var></samp> and <samp>--without-<var>package</var></samp> options,
where <var>package</var> is something like &lsquo;<samp>gnu-ld</samp>&rsquo;.
&lsquo;<samp>./configure --help</samp>&rsquo; should mention the
<samp>--enable-...</samp> and <samp>--with-...</samp>
options that the package recognizes.
</p>
<p>Some packages offer the ability to configure how verbose the execution
of <code>make</code> will be.  For these packages, running
&lsquo;<samp>./configure --enable-silent-rules</samp>&rsquo; sets the default to minimal
output, which can be overridden with <code>make V=1</code>; while running
&lsquo;<samp>./configure --disable-silent-rules</samp>&rsquo; sets the default to verbose,
which can be overridden with <code>make V=0</code>.
</p>
<hr>
</div>
<div class="section" id="System-Types">
<div class="header">
<p>
Next: <a href="#Building-for-a-different-system-type" accesskey="n" rel="next">Creating binaries for a different system type</a>, Previous: <a href="#Optional-Features" accesskey="p" rel="prev">Optional Features</a> &nbsp; </p>
</div>
<span id="Specifying-a-System-Type"></span><h3 class="section">Specifying a System Type</h3>

<p>The following sections go into details regarding situations where you
may have to specify a system type, either through the option
<samp>--host=<var>type</var></samp>, or through the option
<samp>--build=<var>type</var></samp>, or &ndash; in the case of compilers &ndash; through
<samp>--target=<var>type</var></samp>.
</p>
<p>A system type <var>type</var> can either be a short name like &lsquo;<samp>mingw64</samp>&rsquo;,
or a canonical name like &lsquo;<samp>x86_64-pc-linux-gnu</samp>&rsquo; which has the form:
</p>
<div class="example">
<pre class="example"><var>cpu</var>-<var>company</var>-<var>system</var>
</pre></div>

<p>where <var>system</var> can have one of these forms:
</p>
<div class="example">
<pre class="example"><var>os</var>
<var>kernel</var>-<var>os</var>
</pre></div>

<p>See the file <samp>config.sub</samp> for the possible values of each field.
If <samp>config.sub</samp> isn&rsquo;t included in this package, then this package
doesn&rsquo;t need to know any machine type.
</p>
<p>The file <samp>config.sub</samp> is a program that validates and canonicalizes
a system type.
It can do canonicalization, as in
</p>
<div class="example">
<pre class="example">$ sh config.sub x86_64-linux
x86_64-pc-linux-gnu
$ sh config.sub arm64-linux
aarch64-unknown-linux-gnu
</pre></div>

<p>It also validates the parts.  For example, this interaction tells you
that &ldquo;crusoe&rdquo; is not a valid cpu architecture name:
</p>
<div class="example">
<pre class="example">$ sh config.sub crusoe-linux
Invalid configuration `crusoe-linux': machine `crusoe-unknown' not recognized
</pre></div>

<hr>
</div>
<div class="section" id="Building-for-a-different-system-type">
<div class="header">
<p>
Next: <a href="#Troubleshooting-the-Build-Type" accesskey="n" rel="next">Fixing a &ldquo;cannot guess build type&rdquo; error</a>, Previous: <a href="#System-Types" accesskey="p" rel="prev">Specifying a System Type</a> &nbsp; </p>
</div>
<span id="Creating-binaries-for-a-different-system-type"></span><h3 class="section">Creating binaries for a different system type</h3>

<p>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
</p><ul>
<li> a <samp>--host=<var>type</var></samp> option, specifying the machine type on
which the binaries shall run,
</li><li> compiler variables (<code>CC</code> for the C compiler, <code>CXX</code> for the C++
compiler, and so on), pointing to compilers that generate object code
for that machine type.
</li></ul>

<p>For example, to create binaries intended to run on a 64-bit ARM
processor:
</p><div class="example">
<pre class="example">./configure --host=aarch64-linux-gnu \
            CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++
</pre></div>

<p>If you do this on a machine that can execute such binaries (e.g. by
virtue of the <code>qemu-aarch64</code> program, system libraries for that
architecture under <code>$QEMU_LD_PREFIX</code>, and a Linux
<code>binfmt_misc</code> configuration), the build behaves like a native
build.
If not, the build is a cross-build, in the sense that <code>configure</code>
will make cross-compilation guesses instead of running test programs,
and &ldquo;make check&rdquo; will not work.
</p>
<hr>
</div>
<div class="section" id="Troubleshooting-the-Build-Type">
<div class="header">
<p>
Next: <a href="#Configuring-a-Compiler" accesskey="n" rel="next">Configuration options specific to a compiler</a>, Previous: <a href="#Building-for-a-different-system-type" accesskey="p" rel="prev">Creating binaries for a different system type</a> &nbsp; </p>
</div>
<span id="Fixing-a-_0060_0060cannot-guess-build-type_0027_0027-error"></span><h3 class="section">Fixing a &ldquo;cannot guess build type&rdquo; error</h3>

<p>In rare cases, it may happen that <code>configure</code> fails with the error
message &ldquo;cannot guess build type&rdquo;.
This error means that the files <samp>config.guess</samp> and
<samp>config.sub</samp> don&rsquo;t recognize the type of the system on which you
are building.
In this case, first fetch the newest versions of these files, from
<a href="https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess">https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess</a>
and
<a href="https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub">https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub</a>,
respectively, and use these as drop-in replacement for the files
<samp>config.guess</samp> and <samp>config.sub</samp> that were shipped with this
package.
</p>
<p>If this resolves the problem, feel free to report the solution to the
maintainers of this package.
</p>
<p>Otherwise, it means that your system is not yet supported by
<samp>config.guess</samp> and <samp>config.sub</samp>.
As a workaround, you can use a configure option
<samp>--build=<var>type</var></samp>, where <var>type</var> comes closest to your
system type.
Also, you&rsquo;re welcome to file a report to
<a href="mailto:[email protected]">[email protected]</a>.
</p>
<hr>
</div>
<div class="section" id="Configuring-a-Compiler">
<div class="header">
<p>
Next: <a href="#Sharing-Defaults" accesskey="n" rel="next">Sharing Defaults</a>, Previous: <a href="#Troubleshooting-the-Build-Type" accesskey="p" rel="prev">Fixing a &ldquo;cannot guess build type&rdquo; error</a> &nbsp; </p>
</div>
<span id="Configuration-options-specific-to-a-compiler"></span><h3 class="section">Configuration options specific to a compiler</h3>

<p>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 <samp>--target=<var>type</var></samp> to
select the type of system for which the compiler should produce code.
</p>
<hr>
</div>
<div class="section" id="Sharing-Defaults">
<div class="header">
<p>
Next: <a href="#Defining-Variables" accesskey="n" rel="next">Defining Variables</a>, Previous: <a href="#Configuring-a-Compiler" accesskey="p" rel="prev">Configuration options specific to a compiler</a> &nbsp; </p>
</div>
<span id="Sharing-Defaults-1"></span><h3 class="section">Sharing Defaults</h3>

<p>If you want to set default values for <code>configure</code> scripts to
share, you can create a site shell script called <samp>config.site</samp> that
gives default values for variables like <code>CC</code>, <code>cache_file</code>,
and <code>prefix</code>.  <code>configure</code> looks for
<samp><var>prefix</var>/share/config.site</samp> if it exists, then
<samp><var>prefix</var>/etc/config.site</samp> if it exists.  Or, you can set the
<code>CONFIG_SITE</code> environment variable to the location of the site
script.  A warning: not all <code>configure</code> scripts look for a site
script.
</p>
<hr>
</div>
<div class="section" id="Defining-Variables">
<div class="header">
<p>
Next: <a href="#configure-Invocation" accesskey="n" rel="next"><code>configure</code> Invocation</a>, Previous: <a href="#Sharing-Defaults" accesskey="p" rel="prev">Sharing Defaults</a> &nbsp; </p>
</div>
<span id="Defining-Variables-1"></span><h3 class="section">Defining Variables</h3>

<p>Variables not defined in a site shell script can be set in the
environment passed to <code>configure</code>.  However, some packages may
run configure again during the build, and the customized values of these
variables may be lost.  In order to avoid this problem, you should set
them in the <code>configure</code> command line, using &lsquo;<samp>VAR=value</samp>&rsquo;.
For example:
</p>
<div class="example">
<pre class="example">./configure CC=/usr/local2/bin/gcc
</pre></div>

<p>causes the specified <code>gcc</code> to be used as the C compiler (unless it is
overridden in the site shell script).
</p>
<p>Unfortunately, this technique does not work for <code>CONFIG_SHELL</code> due
to an Autoconf limitation.  Until the limitation is lifted, you can use
this workaround:
</p>
<div class="example">
<pre class="example">CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
</pre></div>

<hr>
</div>
<div class="section" id="configure-Invocation">
<div class="header">
<p>
Previous: <a href="#Defining-Variables" accesskey="p" rel="prev">Defining Variables</a> &nbsp; </p>
</div>
<span id="configure-Invocation-1"></span><h3 class="section"><code>configure</code> Invocation</h3>

<p><code>configure</code> recognizes the following options to control how it
operates.
</p>
<dl compact="compact">
<dt><span><samp>--help</samp></span></dt>
<dt><span><samp>-h</samp></span></dt>
<dd><p>Print a summary of all of the options to <code>configure</code>, and exit.
</p>
</dd>
<dt><span><samp>--help=short</samp></span></dt>
<dt><span><samp>--help=recursive</samp></span></dt>
<dd><p>Print a summary of the options unique to this package&rsquo;s
<code>configure</code>, and exit.  The <code>short</code> variant lists options
used only in the top level, while the <code>recursive</code> variant lists
options also present in any nested packages.
</p>
</dd>
<dt><span><samp>--version</samp></span></dt>
<dt><span><samp>-V</samp></span></dt>
<dd><p>Print the version of Autoconf used to generate the <code>configure</code>
script, and exit.
</p>
</dd>
<dt id='index-Cache_002c-enabling'><span><samp>--cache-file=<var>file</var></samp><a href='#index-Cache_002c-enabling' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Enable the cache: use and save the results of the tests in <var>file</var>,
traditionally <samp>config.cache</samp>.  <var>file</var> defaults to
<samp>/dev/null</samp> to disable caching.
</p>
</dd>
<dt><span><samp>--config-cache</samp></span></dt>
<dt><span><samp>-C</samp></span></dt>
<dd><p>Alias for <samp>--cache-file=config.cache</samp>.
</p>
</dd>
<dt><span><samp>--srcdir=<var>dir</var></samp></span></dt>
<dd><p>Look for the package&rsquo;s source code in directory <var>dir</var>.  Usually
<code>configure</code> can determine that directory automatically.
</p>
</dd>
<dt><span><samp>--prefix=<var>dir</var></samp></span></dt>
<dd><p>Use <var>dir</var> as the installation prefix.  <a href="#Installation-Names">Installation Names</a>
for more details, including other options available for fine-tuning
the installation locations.
</p>
</dd>
<dt><span><samp>--host=<var>type</var></samp></span></dt>
<dd><p>Build binaries for architecture <var>type</var>.  <a href="#System-Types">Specifying a System Type</a> and
<a href="#Building-for-a-different-system-type">Creating binaries for a different system type</a> for more details.
</p>
</dd>
<dt><span><samp>--enable-<var>feature</var></samp></span></dt>
<dt><span><samp>--disable-<var>feature</var></samp></span></dt>
<dd><p>Enable or disable the optional <var>feature</var>.  See <a href="#Optional-Features">Optional Features</a>.
</p>
</dd>
<dt><span><samp>--with-<var>package</var></samp></span></dt>
<dt><span><samp>--without-<var>package</var></samp></span></dt>
<dd><p>Use or omit <var>package</var> when building.  See <a href="#Optional-Features">Optional Features</a>.
</p>
</dd>
<dt><span><samp>--quiet</samp></span></dt>
<dt><span><samp>--silent</samp></span></dt>
<dt><span><samp>-q</samp></span></dt>
<dd><p>Do not print messages saying which checks are being made.  To suppress
all normal output, redirect it to <samp>/dev/null</samp> (any error messages
will still be shown).
</p>
</dd>
<dt><span><samp>--no-create</samp></span></dt>
<dt><span><samp>-n</samp></span></dt>
<dd><p>Run the configure checks, but stop before creating any output files.
</p></dd>
</dl>

<p><code>configure</code> also recognizes several environment variables,
and accepts some other, less widely useful, options.
Run &lsquo;<samp>configure --help</samp>&rsquo; for more details.
</p>
</div>
</div>



</body>
</html>