04-host-and-cross-compilation.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>
        
        * doc/autoconf.texi (Transforming Names): Equality between target
        and host is irrelevant.
        (Specifying Names, Canonicalizing): Remove all references to the
        backward compatibility hooks.  Rather, collect them all into...
        (Hosts and Cross-Compilation): this new section.
        * doc/install.texi (System Type): Ditto.
        * lib/autoconf/general.m4 (AC_CANONICAL_HOST): Explicitly state
        that `--host' implies cross-compilation.
        
Index: NEWS
--- NEWS Tue, 05 Feb 2002 22:43:38 +0100 akim
+++ NEWS Sat, 02 Mar 2002 20:13:51 +0100 akim
@@ -16,6 +16,12 @@
   AC_TRY_CPP, AC_TRY_COMPILE, AC_TRY_LINK and AC_TRY_RUN.
 - Licensing
   The Autoconf manual is now distributed under the terms of the GNU FDL.
+- Section `Hosts and Cross-Compilation'
+  Explains the rationale for the 2.5x changes in the cross-compilation
+  chain, and in the relationships between build, host, and target
+  types.
+  Emphasizes that `cross-compilation' == `--host is given'.
+  If you are working on compilers etc., be sure to read this section.
 
 ** configure
 
Index: doc/autoconf.texi
--- doc/autoconf.texi Fri, 01 Mar 2002 13:41:32 +0100 akim
+++ doc/autoconf.texi Sat, 02 Mar 2002 20:10:38 +0100 akim
@@ -411,6 +411,7 @@ @node Top
 
 * 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
 
@@ -3203,12 +3204,13 @@ @node Generic Programs
 
 @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
address@hidden 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
address@hidden 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
@@ -9523,49 +9525,29 @@ @node Specifying Names
 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 address@hidden
-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.
-
address@hidden
-./configure --host=alpha-netbsd sparc-gnu
address@hidden example
-}:
+system types are involved.  The options to specify them are:
 
 @table @option
 @item address@hidden
 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 address@hidden
 @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 address@hidden
 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
address@hidden over @option{--host}.  In the future, @option{--host} will
-not override the name of the build system type.  Also, if you specify
address@hidden, 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
address@hidden, be sure to specify @code{--build} too.
+If you mean to override the result of @command{config.guess}, use
address@hidden, 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
address@hidden too.  This will be fixed in the future.
 
 @example
 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
@@ -9580,11 +9562,14 @@ Hint: if you mean to override the result
 ./configure CC=m68k-coff-gcc
 @end example
 
address@hidden @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
@@ -9643,12 +9628,6 @@ @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
@@ -9666,6 +9645,8 @@ @node Canonicalizing
 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
@@ -9979,9 +9960,8 @@ @node Transforming Names
 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
@@ -11469,6 +11449,7 @@ @node Autoconf 2.13
 @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
@@ -11595,6 +11576,119 @@ autoupdate: `configure.in' is updated
 $ @kbd{aclocal-1.4}
 $ @kbd{autoconf}
 $
address@hidden example
+
+
address@hidden Hosts and Cross-Compilation
address@hidden 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:
+
address@hidden @minus
address@hidden
+the relationship between the build, host, and target architecture types,
+
address@hidden
+the command line interface for specifying them to @command{configure},
+
address@hidden
+the variables defined in @command{configure},
+
address@hidden
+the enabling of cross-compilation mode.
address@hidden itemize
+
address@hidden 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,
address@hidden will not override the name of the build system type.
+Whenever you specify @code{--host}, be sure to specify @code{--build}
+too.
+
address@hidden 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.
+
address@hidden
+./configure --host=alpha-netbsd sparc-gnu
address@hidden example
+
address@hidden 1
+
+In Autoconf, the variables @code{build}, @code{host}, and @code{target}
+had a different semantics before and after the invocation of
address@hidden 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
address@hidden will be set to that value.  Eventually, this
+historically incorrect behavior will go away.
+
address@hidden 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.
address@hidden could even enter cross-compilation mode, only
+because the compiler was not functional.  This is mainly because
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden too.
+
address@hidden
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
address@hidden example
+
address@hidden
+will enter cross-compilation mode.  The former interface, which
+consisted in setting the compiler to a cross-compiler without informing
address@hidden 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:
+
address@hidden
+./configure CC=m68k-coff-gcc
 @end example
 
 
Index: doc/install.texi
--- doc/install.texi Tue, 21 Aug 2001 07:55:37 +0200 akim
+++ doc/install.texi Sat, 02 Mar 2002 19:59:03 +0100 akim
@@ -3,8 +3,8 @@
 
 @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.
@@ -160,12 +160,13 @@ @node System Type
 @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
address@hidden@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
address@hidden architectures, @command{configure} can figure that out, but
+if it prints a message saying it cannot guess the machine type, give it
+the @address@hidden 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
 @address@hidden@var{system}
@@ -180,20 +181,16 @@ @node System Type
 
 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 @address@hidden 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 @address@hidden  In this case, you should also
-specify the build platform with @address@hidden, 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
address@hidden platform (i.e., that on which the generated programs will
+eventually be run) with @address@hidden
 
 @node Sharing Defaults
 @section Sharing Defaults
Index: lib/autoconf/general.m4
--- lib/autoconf/general.m4 Tue, 26 Feb 2002 22:32:15 +0100 akim
+++ lib/autoconf/general.m4 Sat, 02 Mar 2002 20:07:54 +0100 akim
@@ -909,11 +909,12 @@ m4_define([_AC_INIT_PARSE_ARGS],
 
 # There might be people who depend on the old broken behavior: `$host'
 # used to hold the argument of --host etc.
+# FIXME: To remove some day.
 build=$build_alias
 host=$host_alias
 target=$target_alias
 
-# FIXME: should be removed in autoconf 3.0.
+# FIXME: To remove some day.
 if test "x$host_alias" != x; then
   if test "x$build_alias" = x; then
     cross_compiling=maybe
@@ -1586,7 +1587,7 @@ AC_DEFUN_ONCE([AC_CANONICAL_BUILD],
 AC_DEFUN_ONCE([AC_CANONICAL_HOST],
 [AC_REQUIRE([AC_CANONICAL_BUILD])dnl
 m4_divert_text([HELP_CANON],
-[[  --host=HOST       build programs to run on HOST [BUILD]]])dnl
+[[  --host=HOST       cross-compile to build programs to run on HOST 
[BUILD]]])dnl
 AC_CACHE_CHECK([host system type], [ac_cv_host],
 [ac_cv_host_alias=$host_alias
 test -z "$ac_cv_host_alias" &&