* 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.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@43819 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 66 insertions, 2 deletions

diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi
index 10a963f7630..7e0cd1a155d 100644
--- a/gcc/doc/gcc.texi
+++ b/gcc/doc/gcc.texi
@@ -263,7 +263,7 @@ bugs.  It corresponds to GCC version 3.1.
 * 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.
+* Makefile::        Additional Makefile and configure information.
 @end ifset
 @ifset INTERNALS
 * Portability::     Goals of GCC's portability features.
@@ -2862,7 +2862,9 @@ These macro definitions can be placed in a header file to minimize the
 number of changes to your source code.
 
 @node Makefile
-@chapter Makefile Targets
+@chapter Additional Makefile and configure information.
+
+@section Makefile Targets
 @cindex makefile targets
 @cindex targets, makefile
 
@@ -2960,6 +2962,68 @@ 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
 
 @ifset INTERNALS