mirror/autoconf
2
0
Fork 0
mirror of git://git.sv.gnu.org/autoconf synced 2025-02-17 14:01:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Shorten and improve INSTALL

Browse Source 
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.
This commit is contained in:
Paul Eggert 2023-06-24 14:39:34 -07:00
parent 328f9b88ef
commit d8ca8b3238
1 changed files with 82 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
doc/install.texi
View File

@ -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:
@example
@var{os}
@var{kernel}-@var{os}
@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
@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:
@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
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
./configure --host=aarch64-linux-gnu \
CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++
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}
@noindent
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 ``make check'' will not work.
and @code{make check} will not work.
@node Troubleshooting the Build Type
@section Fixing a ``cannot guess build type'' error
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:
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.
@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
@end example
If this resolves the problem, feel free to report the solution to the
maintainers of this package.
@noindent
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.
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
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"