@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
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
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
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:
@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
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
@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.
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.
@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
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}
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"
projects / thirdparty / autoconf.git / commitdiff
