Installation Instructions
*************************
- 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.
-
Basic Installation
==================
- Briefly, the following shell commands:
+ The following shell commands:
test -f configure || ./bootstrap
./configure
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 *note Makefile Conventions: (standards)Makefile Conventions.
+found in the GNU Coding Standards.
If the ‘bootstrap’ shell script exists, it attempts to build the
‘configure’ shell script and related files, perhaps by downloading other
It may also create one or more ‘.h’ files containing system-dependent
definitions. Finally, it creates a shell script ‘config.status’ that
you can run in the future to recreate the current configuration, and a
-file ‘config.log’ containing compiler output (useful mainly for
-debugging ‘configure’).
+file ‘config.log’ containing output useful for debugging ‘configure’.
It can also use an optional file (typically called ‘config.cache’ and
enabled with ‘--cache-file=config.cache’ or simply ‘-C’) that saves the
some point ‘config.cache’ contains results you don’t want to keep, you
may remove or edit it.
- The file ‘configure.ac’ (or ‘configure.in’) is used to create
-‘configure’ by a program called ‘autoconf’. You need ‘configure.ac’ if
-you want to change it or regenerate ‘configure’ using a newer version of
-‘autoconf’.
+ The ‘autoconf’ program generates ‘configure’ from the file
+‘configure.ac’. Normally you should edit ‘configure.ac’ instead of
+editing ‘configure’ directly.
The simplest way to compile this package is:
exist, type ‘./bootstrap’ to create it. You may need special
developer tools and network access to bootstrap.
- 3. Type ‘./configure’ to configure the package for your system.
-
- Running ‘configure’ might take a while. While running, it prints
- some messages telling which features it is checking for.
+ 3. Type ‘./configure’ to configure the package for your system. This
+ might take a while. While running, ‘configure’ prints messages
+ telling which features it is checking for.
4. Type ‘make’ to compile the package.
files that ‘configure’ created (so you can compile the package for
a different kind of computer), type ‘make distclean’. There is
also a ‘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.
+ for the package’s developers. If you use it, you may have to
+ bootstrap again.
- 9. Often, you can also type ‘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.
-
- 10. Some packages, particularly those that use Automake, provide ‘make
- distcheck’, which can by used by developers to test that all other
- targets like ‘make install’ and ‘make uninstall’ work correctly.
- This target is generally not run by end users.
+ 9. If the package follows the GNU Coding Standards, you can type ‘make
+ uninstall’ to remove the installed files.
Compilers and Options
=====================
./configure CC=gcc CFLAGS=-g LIBS=-lposix
- *Note Defining Variables::, for more details.
+ See *note Defining Variables:: for more details.
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
-own directory. To do this, you can use GNU ‘make’. ‘cd’ to the
-directory where you want the object files and executables to go and run
-the ‘configure’ script. ‘configure’ automatically checks for the source
+same time, by placing the object files for each system in their own
+directory. To do this, you can use GNU ‘make’. ‘cd’ to the directory
+where you want the object files and executables to go and run the
+‘configure’ script. ‘configure’ automatically checks for the source
code in the directory that ‘configure’ is in and in ‘..’. This is known
as a “VPATH” build.
With a non-GNU ‘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 ‘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 ‘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. On these
--disable-silent-rules’ sets the default to verbose, which can be
overridden with ‘make V=0’.
-Specifying the System Type
-==========================
-
- There may be some features ‘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
-_same_ architectures, ‘configure’ can figure that out, but if it prints
-a message saying it cannot guess the machine type, give it the
-‘--build=TYPE’ option. TYPE can either be a short name like ‘mingw64’
-for the system type, 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 the machine type.
-
- If you are _building_ compiler tools for cross-compiling, you should
-use the option ‘--target=TYPE’ to select the type of system they will
-produce code for.
-
- If you want to _use_ a cross compiler, that generates code for a
-platform different from the build platform, you should specify the
-“host” platform (i.e., that on which the generated programs will
-eventually be run) with ‘--host=TYPE’.
+Specifying a System Type
+========================
+
+ By default ‘configure’ builds for the current system. To create
+binaries that can run on a different system type, specify a
+‘--host=TYPE’ option along with compiler variables that specify how to
+generate object code for TYPE. 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 done on a machine that can execute these binaries (e.g., via
+‘qemu-aarch64’, ‘$QEMU_LD_PREFIX’, and Linux’s ‘binfmt_misc’
+capability), the build behaves like a native build. Otherwise it is a
+cross-build: ‘configure’ will make cross-compilation guesses instead of
+running test programs, and ‘make check’ will not work.
+
+ A system type can either be a short name like ‘mingw64’, or a
+canonical name like ‘x86_64-pc-linux-gnu’. Canonical names have the
+form CPU-COMPANY-SYSTEM where SYSTEM is either OS or KERNEL-OS. To
+canonicalize and validate a system type, you can run the command
+‘config.sub’, which is often squirreled away in a subdirectory like
+‘build-aux’. For example:
+
+ $ build-aux/config.sub arm64-linux
+ aarch64-unknown-linux-gnu
+ $ build-aux/config.sub riscv-lnx
+ Invalid configuration 'riscv-lnx': OS 'lnx' not recognized
+
+You can look at the ‘config.sub’ file to see which types are recognized.
+If the file is absent, this package does not need the system type.
+
+ If ‘configure’ fails with the diagnostic “cannot guess build type”.
+‘config.sub’ did not recognize your system’s type. In this case, first
+fetch the newest versions of these files from the GNU config package
+(https://savannah.gnu.org/projects/config). If that fixes things,
+please report it to the maintainers of the package containing
+‘configure’. Otherwise, you can try the configure option ‘--build=TYPE’
+where TYPE comes close to your system type; also, please report the
+problem to <config-patches@gnu.org>.
+
+ For more details about configuring system types, see the Autoconf
+documentation.
Sharing Defaults
================
more details, including other options available for fine-tuning the
installation locations.
-‘--build=TYPE’
- Build for architecture TYPE. *note System Type::. for more
- details, including other system type options.
+‘--host=TYPE’
+ Build binaries for system TYPE. *Note System Types::.
‘--enable-FEATURE’
‘--disable-FEATURE’
‘configure’ also recognizes several environment variables, and accepts
some other, less widely useful, options. Run ‘configure --help’ for
more details.
+
+Copyright notice
+================
+
+ 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.
@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.
-
-@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.
+the package's developers. If you use it, you may have to bootstrap again.
@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
./configure CC=gcc CFLAGS=-g LIBS=-lposix
@end example
-@xref{Defining Variables}, for more details.
-
+See
+@ref{Defining Variables}
+@ifset autoconf
+and @ref{Preset Output Variables}
+@end ifset
+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.
@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:
+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{cpu}-@var{company}-@var{system}
+./configure --host=aarch64-linux-gnu \
+ CC=aarch64-linux-gnu-gcc \
+ CXX=aarch64-linux-gnu-g++
@end example
@noindent
-where @var{system} can have one of these forms:
+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
-@var{os}
-@var{kernel}-@var{os}
+$ 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
-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.
-
-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.
-
-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}}.
+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}.
+
+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
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 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"