PATCH: wrt with_cross_host vs cross-hosted

[DJ Delorie <dj at redhat dot com>]

Here's the results of all the comments I got...

2001-07-06  DJ Delorie  <dj@redhat.com>

	* doc/gcc.texi (Makefile): Rename to be a more general purpose
	chapter about various build hints and history.  Add section
	talking about the various types of native and cross builds.

Index: gcc.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/gcc.texi,v
retrieving revision 1.28
diff -p -3 -r1.28 gcc.texi
*** gcc.texi	2001/07/05 06:53:56	1.28
--- gcc.texi	2001/07/06 18:13:25
*************** bugs.  It corresponds to GCC version 3.1
*** 263,269 ****
  * Service::         How to find suppliers of support for GCC.
  * Contributing::    How to contribute to testing and developing GCC.
  * VMS::             Using GCC on VMS.
! * Makefile::        List of Makefile targets.
  @end ifset
  @ifset INTERNALS
  * Portability::     Goals of GCC's portability features.
--- 263,269 ----
  * Service::         How to find suppliers of support for GCC.
  * Contributing::    How to contribute to testing and developing GCC.
  * VMS::             Using GCC on VMS.
! * Makefile::        Additional Makefile and configure information.
  @end ifset
  @ifset INTERNALS
  * Portability::     Goals of GCC's portability features.
*************** These macro definitions can be placed in
*** 2862,2868 ****
  number of changes to your source code.
  
  @node Makefile
! @chapter Makefile Targets
  @cindex makefile targets
  @cindex targets, makefile
  
--- 2862,2870 ----
  number of changes to your source code.
  
  @node Makefile
! @chapter Additional Makefile and configure information.
! 
! @section Makefile Targets
  @cindex makefile targets
  @cindex targets, makefile
  
*************** is running properly, since it should pro
*** 2959,2964 ****
--- 2961,3028 ----
  regardless of how it itself was compiled.
  
  @end table
+ 
+ @section Configure Terms and History
+ @cindex configure terms
+ @cindex canadian
+ 
+ This section is not instructions for building GCC.  If you are trying to
+ do a build, you should first read @uref{http://gcc.gnu.org/install/} or
+ whatever installation instructions came with your source package.
+ 
+ The configure and build process has a long and colorful history, and can
+ be confusing to anyone who doesn't know why things are the way they are.
+ While there are other documents which describe the configuration process
+ in detail, here are a few things that everyone working on GCC should
+ know.
+ 
+ There are three system names that the build knows about: the machine you
+ are building on (@dfn{build}), the machine that you are building for
+ (@dfn{host}), and the machine that GCC will produce code for
+ (@dfn{target}).  When you configure GCC, you specify these with
+ @option{--build=}, @option{--host=}, and @option{--target=}.
+ 
+ Specifying the host without specifying the build should be avoided, as
+ @command{configure} may (and once did) assume that the host you specify
+ is also the build, which may not be true.
+ 
+ If build, host, and target are all the same, this is called a
+ @dfn{native}.  If build and host are the same but target is different,
+ this is called a @dfn{cross}.  If build, host, and target are all
+ different this is called a @dfn{canadian} (for obscure reasons dealing
+ with Canada's political party and the background of the person working
+ on the build at that time).  If host and target are the same, but build
+ is different, you are using a cross-compiler to build a native for a
+ different system.  Some people call this a @dfn{host-x-host},
+ @dfn{crossed native}, or @dfn{cross-built native}.  If build and target
+ are the same, but host is different, you are using a cross compiler to
+ build a cross compiler that produces code for the machine you're
+ building on.  This is rare, so there is no common say of describing it
+ (although I propose calling it a @dfn{crossback}).
+ 
+ If build and host are the same, the GCC you are building will also be
+ used to build the target libraries (like @code{libstdc++}).  If build and host
+ are different, you must have already build and installed a cross
+ compiler that will be used to build the target libraries (if you
+ configured with @option{--target=foo-bar}, this compiler will be called
+ @command{foo-bar-gcc}).
+ 
+ In the case of target libraries, the machine you're building for is the
+ machine you specified with @option{--target}.  So, build is the machine
+ you're building on (no change there), host is the machine you're
+ building for (the target libraries are built for the target, so host is
+ the target you specified), and target doesn't apply (because you're not
+ building a compiler, you're building libraries).  The configure/make
+ process will adjust these variables as needed.  It also sets
+ @code{$with_cross_host} to the original @option{--host} value in case you
+ need it.
+ 
+ Libiberty, for example, is built twice.  The first time, host comes from
+ @option{--host} and the second time host comes from @option{--target}.
+ Historically, libiberty has not been built for the build machine,
+ though, which causes some interesting issues with programs used to
+ generate sources for the build.  Fixing this, so that libiberty is built
+ three times, has long been on the to-do list.
  
  @end ifset