-Copyright 1994, 1995, 1996, 1999, 2000, 2001 Free Software Foundation,
-Inc.
+Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
+Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
==========================
There may be some features `configure' cannot figure out
-automatically, but needs to determine by the type of host the package
-will run on. Usually `configure' can figure that out, but if it prints
-a message saying it cannot guess the host type, give it the
+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 for the system
type, such as `sun4', or a canonical name which has the form:
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 host type.
+need to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should
use the `--target=TYPE' option 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'. In this case, you should also specify the
-build platform with `--build=TYPE', because, in this case, it may not
-be possible to guess the build platform (it sometimes involves
-compiling and running simple test programs, and this can't be done if
-the compiler is a cross compiler).
+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'.
Sharing Defaults
================
* Changed Quotation:: Broken code which used to work
* New Macros:: Interaction with foreign macros
+* Hosts and Cross-Compilation:: Bugward compatibility kludges
Generating Test Suites with Autotest
@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
@acindex CHECK_TOOLS
-Like @code{AC_CHECK_TOOL}, each of the tools in the list @var{progs-to-check-for} are
-checked with a prefix of the host type as determined by @code{AC_CANONICAL_HOST},
-followed by a dash (@pxref{Canonicalizing}). If none of the tools can be found with a
-prefix, then the first one without a prefix is used. If a tool is found, set
-@var{variable} to the name of that program. If none of the tools in the
-list are found, set @var{variable} to @var{value-if-not-found}; if
+Like @code{AC_CHECK_TOOL}, each of the tools in the list
+@var{progs-to-check-for} are checked with a prefix of the host type as
+determined by @code{AC_CANONICAL_HOST}, followed by a dash
+(@pxref{Canonicalizing}). If none of the tools can be found with a
+prefix, then the first one without a prefix is used. If a tool is found,
+set @var{variable} to the name of that program. If none of the tools in
+the list are found, set @var{variable} to @var{value-if-not-found}; if
@var{value-if-not-found} is not specified, the value of @var{variable}
is not changed. Calls @code{AC_SUBST} for @var{variable}.
@end defmac
Alternately, the user can specify the system type with command line
arguments to @command{configure}. Doing so is necessary when
cross-compiling. In the most complex case of cross-compiling, three
-system types are involved. The options to specify them are@footnote{For
-backward compatibility, @command{configure} will accept a system type as an
-option by itself. Such an option will override the defaults for build,
-host and target system types. The following configure statement will
-configure a cross toolchain that will run on NetBSD/alpha but generate
-code for GNU Hurd/sparc, which is also the build platform.
-
-@example
-./configure --host=alpha-netbsd sparc-gnu
-@end example
-}:
+system types are involved. The options to specify them are:
@table @option
@item --build=@var{build-type}
the type of system on which the package is being configured and
-compiled.
+compiled. It defaults to the result of running @command{config.guess}.
@item --host=@var{host-type}
@ovindex cross_compiling
-the type of system on which the package will run.
+the type of system on which the package will run. By default it is the
+same as the build machine. Specifying it enables the cross-compilation
+mode.
@item --target=@var{target-type}
the type of system for which any compiler tools in the package will
produce code (rarely needed). By default, it is the same as host.
@end table
-They all default to the result of running @command{config.guess}, unless
-you specify either @option{--build} or @option{--host}. In this case, the
-default becomes the system type you specified. If you specify both, and
-they're different, @command{configure} will enter cross compilation mode,
-so it won't run any tests that require execution.
-
-Hint: if you mean to override the result of @command{config.guess}, prefer
-@option{--build} over @option{--host}. In the future, @option{--host} will
-not override the name of the build system type. Also, if you specify
-@option{--host}, but not @option{--build}, when @command{configure} performs
-the first compiler test it will try to run an executable produced by the
-compiler. If the execution fails, it will enter cross-compilation mode.
-Note, however, that it won't guess the build-system type, since this may
-require running test programs. Moreover, by the time the compiler test
-is performed, it may be too late to modify the build-system type: other
-tests may have already been performed. Therefore, whenever you specify
-@code{--host}, be sure to specify @code{--build} too.
+If you mean to override the result of @command{config.guess}, use
+@option{--build}, not @option{--host}, which enables cross-compilation.
+For historical reasons, passing @option{--host} also changes the build
+type. Therefore, whenever you specify @code{--host}, be sure to specify
+@code{--build} too. This will be fixed in the future.
@example
./configure --build=i686-pc-linux-gnu --host=m68k-coff
./configure CC=m68k-coff-gcc
@end example
+@cindex @command{config.sub}
@command{configure} recognizes short aliases for many system types; for
example, @samp{decstation} can be used instead of
@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
@command{config.sub} to canonicalize system type aliases.
+This section deliberately omits the description of the obsolete
+interface, see @ref{Hosts and Cross-Compilation}.
@node Canonicalizing
If @option{--host} was specified, then @code{host} is the
canonicalization of @code{host_alias} by @command{config.sub},
otherwise it defaults to @code{build}.
-
-For temporary backward-compatibility, when @option{--host} is specified
-by @option{--build} isn't, the build system will be assumed to be the
-same as @option{--host}, and @samp{build_alias} will be set to that
-value. Eventually, this historically incorrect behavior will go away.
-
@end defmac
@defmac AC_CANONICAL_TARGET
otherwise it defaults to @code{host}.
@end defmac
+Note that there can be artifacts due to the backward compatibility
+code. @xref{Hosts and Cross-Compilation}, for more.
@node Using System Type
@section Using the System Type
If any of the options described below are given to @command{configure},
program names are transformed accordingly. Otherwise, if
@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
-is given that differs from the host type (specified with @option{--host}),
-the target type followed by a dash is used as a prefix. Otherwise, no
-program name transformation is done.
+is given, the target type followed by a dash is used as a prefix.
+Otherwise, no program name transformation is done.
@end defmac
@menu
@menu
* Changed Quotation:: Broken code which used to work
* New Macros:: Interaction with foreign macros
+* Hosts and Cross-Compilation:: Bugward compatibility kludges
@end menu
@node Changed Quotation
@end example
+@node Hosts and Cross-Compilation
+@subsection Hosts and Cross-Compilation
+
+Based on the experience of compiler writers, and after long public
+debates, many aspects of the cross-compilation chain have changed:
+
+@itemize @minus
+@item
+the relationship between the build, host, and target architecture types,
+
+@item
+the command line interface for specifying them to @command{configure},
+
+@item
+the variables defined in @command{configure},
+
+@item
+the enabling of cross-compilation mode.
+@end itemize
+
+@sp 1
+
+The relationship between build, host, and target have been cleaned up:
+the chain of default is now simply: target defaults to host, host to
+build, and build to the result of @command{config.guess}. Nevertheless,
+in order to ease the transition from 2.13 to 2.50, the following
+transition scheme is implemented. @emph{Do not rely on it}, as it will
+be completely disabled in a couple of releases (we cannot keep it, as it
+proves to cause more problems than to cure).
+
+They all default to the result of running @command{config.guess}, unless
+you specify either @option{--build} or @option{--host}. In this case,
+the default becomes the system type you specified. If you specify both,
+and they're different, @command{configure} will enter cross compilation
+mode, so it won't run any tests that require execution.
+
+Hint: if you mean to override the result of @command{config.guess},
+prefer @option{--build} over @option{--host}. In the future,
+@option{--host} will not override the name of the build system type.
+Whenever you specify @code{--host}, be sure to specify @code{--build}
+too.
+
+@sp 1
+
+For backward compatibility, @command{configure} will accept a system
+type as an option by itself. Such an option will override the defaults
+for build, host and target system types. The following configure
+statement will configure a cross toolchain that will run on NetBSD/alpha
+but generate code for GNU Hurd/sparc, which is also the build platform.
+
+@example
+./configure --host=alpha-netbsd sparc-gnu
+@end example
+
+@sp 1
+
+In Autoconf, the variables @code{build}, @code{host}, and @code{target}
+had a different semantics before and after the invocation of
+@code{AC_CANONICAL_BUILD} etc. Now, the argument of @option{--build} is
+strictly copied into @code{build_alias}, and is left empty otherwise.
+After the @code{AC_CANONICAL_BUILD}, @code{build} is set to the
+canonicalized build type. To ease the transition, before, its contents
+is the same as that of @code{build_alias}. Do @emph{not} rely on this
+broken feature.
+
+For consistency with the backward compatibility scheme exposed above,
+when @option{--host} is specified by @option{--build} isn't, the build
+system will be assumed to be the same as @option{--host}, and
+@samp{build_alias} will be set to that value. Eventually, this
+historically incorrect behavior will go away.
+
+@sp 1
+
+The former scheme to enable cross-compilation proved to cause more harm
+than good, in particular, it used to be triggered too easily, leaving
+regular end users puzzled in front of cryptic error messages.
+@command{configure} could even enter cross-compilation mode, only
+because the compiler was not functional. This is mainly because
+@command{configure} used to try to detect cross-compilation, instead of
+waiting for an explicit flag from the user.
+
+Now, @command{configure} enters cross-compilation mode iff
+@option{--host} is passed.
+
+That's the short documentation. To ease the transition between 2.13 and
+its successors, a more complicated scheme is implemented. @emph{Do not
+rely on the following}, as it will be removed in a near future.
+
+If you specify @option{--host}, but not @option{--build}, when
+@command{configure} performs the first compiler test it will try to run
+an executable produced by the compiler. If the execution fails, it will
+enter cross-compilation mode. This is fragile. Moreover, by the time
+the compiler test is performed, it may be too late to modify the
+build-system type: other tests may have already been performed.
+Therefore, whenever you specify @code{--host}, be sure to specify
+@code{--build} too.
+
+@example
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
+@end example
+
+@noindent
+will enter cross-compilation mode. The former interface, which
+consisted in setting the compiler to a cross-compiler without informing
+@command{configure} is obsolete. For instance, @command{configure} will
+fail if it can't run the code generated by the specified compiler if you
+configure as follows:
+
+@example
+./configure CC=m68k-coff-gcc
+@end example
+
+
@c ============================= Generating Test Suites with Autotest
@node Using Autotest
@ifclear autoconf
-Copyright 1994, 1995, 1996, 1999, 2000, 2001 Free Software Foundation,
-Inc.
+Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
+Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
@section Specifying the System Type
There may be some features @command{configure} cannot figure out
-automatically, but needs to determine by the type of host the package
-will run on. Usually @command{configure} can figure that out, but if it
-prints a message saying it cannot guess the host type, give it the
-@option{--build=@var{type}} option. @var{type} can either be a short
-name for the system type, such as @samp{sun4}, or a canonical name which
-has the form:
+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 for the system type, such as @samp{sun4}, or a canonical name
+which has the form:
@example
@var{cpu}-@var{company}-@var{system}
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 host type.
+doesn't need to know the machine type.
If you are @emph{building} compiler tools for cross-compiling, you
should use the @option{--target=@var{type}} option 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 host
-platform (i.e., that on which the generated programs will eventually be
-run) with @option{--host=@var{type}}. In this case, you should also
-specify the build platform with @option{--build=@var{type}}, because, in
-this case, it may not be possible to guess the build platform (it
-sometimes involves compiling and running simple test programs, and this
-can't be done if the compiler is a cross compiler).
+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}}.
@node Sharing Defaults
@section Sharing Defaults
projects / thirdparty / autoconf.git / commitdiff
