Patch to move more chapters from gcc.texi to separate files

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

This patch moves the remaining chapters in gcc.texi out to separate
files.

Note on linux-and-gnu.texi: this goes in doc/include since it is
something other manuals might want, although no other manuals
currently include it.  It might be appropriate for the FSF to consider
the following (although hopefully this shouldn't hold up this patch):

* Whether that section should be invariant (it hasn't been so far).
* What copyright notice should go on it (the version at
  http://www.gnu.org/gnu/linux-and-gnu.html lists it as copyright
  Richard Stallman).
* Whether it should be updated to the current slightly different
  version at that URL.
* Whether it can in fact be removed from the GCC manual - as some
  people have suggested that this text does not belong there and
  everyone is familiar with it by now anyway.

It passes "make info" and "make dvi".  OK to commit?

2001-11-11  Joseph S. Myers  <jsm28@cam.ac.uk>

	* doc/gcc.texi: Move several chapters out to ...
	* doc/configterms.texi, doc/fragments.texi, doc/hostconfig.texi,
	doc/include/linux-and-gnu.texi, doc/interface.texi,
	doc/makefile.texi, doc/passes.texi, doc/portability.texi:
	... here.  New files.
	* doc/gcc.texi, doc/contrib.texi: Move section headings into
	contrib.texi.
	* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.

diff -rcN gcc.orig/Makefile.in gcc/Makefile.in
*** gcc.orig/Makefile.in	Sun Nov 11 11:28:07 2001
--- gcc/Makefile.in	Sun Nov 11 19:51:55 2001
***************
*** 2318,2324 ****
  	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
  	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
  	 $(docdir)/service.texi $(docdir)/standards.texi \
! 	 $(docdir)/trouble.texi $(docdir)/vms.texi
  	cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
  
  $(docdir)/cppinternals.info: $(docdir)/cppinternals.texi
--- 2318,2328 ----
  	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
  	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
  	 $(docdir)/service.texi $(docdir)/standards.texi \
! 	 $(docdir)/trouble.texi $(docdir)/vms.texi $(docdir)/configterms.texi \
! 	 $(docdir)/fragments.texi $(docdir)/hostconfig.texi \
! 	 $(docdir)/include/linux-and-gnu.texi $(docdir)/interface.texi \
! 	 $(docdir)/makefile.texi $(docdir)/passes.texi \
! 	 $(docdir)/portability.texi
  	cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
  
  $(docdir)/cppinternals.info: $(docdir)/cppinternals.texi
***************
*** 2339,2345 ****
  	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
  	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
  	 $(docdir)/service.texi $(docdir)/standards.texi \
! 	 $(docdir)/trouble.texi $(docdir)/vms.texi
  	$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
  
  cppinternals.dvi: $(docdir)/cppinternals.texi
--- 2343,2353 ----
  	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
  	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
  	 $(docdir)/service.texi $(docdir)/standards.texi \
! 	 $(docdir)/trouble.texi $(docdir)/vms.texi $(docdir)/configterms.texi \
! 	 $(docdir)/fragments.texi $(docdir)/hostconfig.texi \
! 	 $(docdir)/include/linux-and-gnu.texi $(docdir)/interface.texi \
! 	 $(docdir)/makefile.texi $(docdir)/passes.texi \
! 	 $(docdir)/portability.texi
  	$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
  
  cppinternals.dvi: $(docdir)/cppinternals.texi
diff -rcN gcc.orig/doc/configterms.texi gcc/doc/configterms.texi
*** gcc.orig/doc/configterms.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/configterms.texi	Sun Nov 11 19:08:18 2001
***************
*** 0 ****
--- 1,65 ----
+ @c Copyright (C) 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @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.
diff -rcN gcc.orig/doc/contrib.texi gcc/doc/contrib.texi
*** gcc.orig/doc/contrib.texi	Sat Nov  3 22:54:04 2001
--- gcc/doc/contrib.texi	Sun Nov 11 19:20:47 2001
***************
*** 3,8 ****
--- 3,12 ----
  @c This is part of the GCC manual.
  @c For copying conditions, see the file gcc.texi.
  
+ @node Contributors
+ @unnumbered Contributors to GCC
+ @cindex contributors
+ 
  The GCC project would like to thank its many contributors.  Without them the
  project would not have been nearly as successful as it has been.  Any omissions
  in this list are accidental.  Feel free to contact
diff -rcN gcc.orig/doc/fragments.texi gcc/doc/fragments.texi
*** gcc.orig/doc/fragments.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/fragments.texi	Sun Nov 11 19:13:04 2001
***************
*** 0 ****
--- 1,159 ----
+ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+ @c 1999, 2000, 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Fragments
+ @chapter Makefile Fragments
+ @cindex makefile fragment
+ 
+ When you configure GCC using the @file{configure} script
+ (@pxref{Installation}), it will construct the file @file{Makefile} from
+ the template file @file{Makefile.in}.  When it does this, it will
+ incorporate makefile fragment files from the @file{config} directory,
+ named @file{t-@var{target}} and @file{x-@var{host}}.  If these files do
+ not exist, it means nothing needs to be added for a given target or
+ host.
+ 
+ @menu
+ * Target Fragment:: Writing the @file{t-@var{target}} file.
+ * Host Fragment::   Writing the @file{x-@var{host}} file.
+ @end menu
+ 
+ @node Target Fragment
+ @section The Target Makefile Fragment
+ @cindex target makefile fragment
+ @cindex @file{t-@var{target}}
+ 
+ The target makefile fragment, @file{t-@var{target}}, defines special
+ target dependent variables and targets used in the @file{Makefile}:
+ 
+ @table @code
+ @findex LIBGCC2_CFLAGS
+ @item LIBGCC2_CFLAGS
+ Compiler flags to use when compiling @file{libgcc2.c}.
+ 
+ @findex LIB2FUNCS_EXTRA
+ @item LIB2FUNCS_EXTRA
+ A list of source file names to be compiled or assembled and inserted
+ into @file{libgcc.a}.
+ 
+ @findex Floating Point Emulation
+ @item Floating Point Emulation
+ To have GCC include software floating point libraries in @file{libgcc.a}
+ define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
+ @smallexample
+ # We want fine grained libraries, so use the new code
+ # to build the floating point emulation libraries.
+ FPBIT = fp-bit.c
+ DPBIT = dp-bit.c
+ 
+ 
+ fp-bit.c: $(srcdir)/config/fp-bit.c
+         echo '#define FLOAT' > fp-bit.c
+         cat $(srcdir)/config/fp-bit.c >> fp-bit.c
+ 
+ dp-bit.c: $(srcdir)/config/fp-bit.c
+         cat $(srcdir)/config/fp-bit.c > dp-bit.c
+ @end smallexample
+ 
+ You may need to provide additional #defines at the beginning of @file{fp-bit.c}
+ and @file{dp-bit.c} to control target endianness and other options.
+ 
+ 
+ @findex CRTSTUFF_T_CFLAGS
+ @item CRTSTUFF_T_CFLAGS
+ Special flags used when compiling @file{crtstuff.c}.
+ @xref{Initialization}.
+ 
+ @findex CRTSTUFF_T_CFLAGS_S
+ @item CRTSTUFF_T_CFLAGS_S
+ Special flags used when compiling @file{crtstuff.c} for shared
+ linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
+ in @code{EXTRA-PARTS}.
+ @xref{Initialization}.
+ 
+ @findex MULTILIB_OPTIONS
+ @item MULTILIB_OPTIONS
+ For some targets, invoking GCC in different ways produces objects
+ that can not be linked together.  For example, for some targets GCC
+ produces both big and little endian code.  For these targets, you must
+ arrange for multiple versions of @file{libgcc.a} to be compiled, one for
+ each set of incompatible options.  When GCC invokes the linker, it
+ arranges to link in the right version of @file{libgcc.a}, based on
+ the command line options used.
+ 
+ The @code{MULTILIB_OPTIONS} macro lists the set of options for which
+ special versions of @file{libgcc.a} must be built.  Write options that
+ are mutually incompatible side by side, separated by a slash.  Write
+ options that may be used together separated by a space.  The build
+ procedure will build all combinations of compatible options.
+ 
+ For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
+ msoft-float}, @file{Makefile} will build special versions of
+ @file{libgcc.a} using the following sets of options:  @option{-m68000},
+ @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
+ @samp{-m68020 -msoft-float}.
+ 
+ @findex MULTILIB_DIRNAMES
+ @item MULTILIB_DIRNAMES
+ If @code{MULTILIB_OPTIONS} is used, this variable specifies the
+ directory names that should be used to hold the various libraries.
+ Write one element in @code{MULTILIB_DIRNAMES} for each element in
+ @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
+ default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
+ as spaces.
+ 
+ For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
+ msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
+ @samp{m68000 m68020 msoft-float}.  You may specify a different value if
+ you desire a different set of directory names.
+ 
+ @findex MULTILIB_MATCHES
+ @item MULTILIB_MATCHES
+ Sometimes the same option may be written in two different ways.  If an
+ option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
+ any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
+ items of the form @samp{option=option} to describe all relevant
+ synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
+ 
+ @findex MULTILIB_EXCEPTIONS
+ @item MULTILIB_EXCEPTIONS
+ Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
+ specified, there are combinations that should not be built.  In that
+ case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
+ in shell case syntax that should not be built.
+ 
+ For example, in the PowerPC embedded ABI support, it is not desirable
+ to build libraries compiled with the @option{-mcall-aix} option
+ and either of the @option{-fleading-underscore} or @option{-mlittle} options
+ at the same time.  Therefore @code{MULTILIB_EXCEPTIONS} is set to
+ @smallexample
+ *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
+ @end smallexample
+ 
+ @findex MULTILIB_EXTRA_OPTS
+ @item MULTILIB_EXTRA_OPTS
+ Sometimes it is desirable that when building multiple versions of
+ @file{libgcc.a} certain options should always be passed on to the
+ compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
+ of options to be used for all builds.
+ @end table
+ 
+ @node Host Fragment
+ @section The Host Makefile Fragment
+ @cindex host makefile fragment
+ @cindex @file{x-@var{host}}
+ 
+ The host makefile fragment, @file{x-@var{host}}, defines special host
+ dependent variables and targets used in the @file{Makefile}:
+ 
+ @table @code
+ @findex CC
+ @item CC
+ The compiler to use when building the first stage.
+ 
+ @findex INSTALL
+ @item INSTALL
+ The install program to use.
+ @end table
diff -rcN gcc.orig/doc/gcc.texi gcc/doc/gcc.texi
*** gcc.orig/doc/gcc.texi	Sun Nov 11 11:28:07 2001
--- gcc/doc/gcc.texi	Sun Nov 11 19:20:31 2001
***************
*** 302,1769 ****
  
  @include vms.texi
  
! @node Makefile
! @chapter Additional Makefile and configure information.
  
! @section Makefile Targets
! @cindex makefile targets
! @cindex targets, makefile
  
- @table @code
- @item all
- This is the default target.  Depending on what your build/host/target
- configuration is, it coordinates all the things that need to be built.
- 
- @item doc
- Produce info-formatted documentation.  Also, @code{make dvi} is
- available for DVI-formatted documentation, and @code{make
- generated-manpages} to generate man pages.
- 
- @item mostlyclean
- Delete the files made while building the compiler.
- 
- @item clean
- That, and all the other files built by @code{make all}.
- 
- @item distclean
- That, and all the files created by @code{configure}.
- 
- @item extraclean
- That, and any temporary or intermediate files, like emacs backup files.
- 
- @item maintainer-clean
- Distclean plus any file that can be generated from other files.  Note
- that additional tools may be required beyond what is normally needed to
- build gcc.
- 
- @item install
- Installs gcc.
- 
- @item uninstall
- Deletes installed files.
- 
- @item check
- Run the testsuite.  This creates a @file{testsuite} subdirectory that
- has various @file{.sum} and @file{.log} files containing the results of
- the testing.  You can run subsets with, for example, @code{make check-gcc}.
- You can specify specific tests by setting RUNTESTFLAGS to be the name
- of the @file{.exp} file, optionally followed by (for some tests) an equals
- and a file wildcard, like:
- 
- @example
- make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
- @end example
- 
- Note that running the testsuite may require additional tools be
- installed, such as TCL or dejagnu.
- 
- @item bootstrap
- Builds gcc three times---once with the native compiler, once with the
- native-built compiler it just built, and once with the compiler it built
- the second time.  In theory, the last two should produce the same
- results, which @code{make compare} can check.  Each step of this process
- is called a ``stage'', and the results of each stage @var{N}
- (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
- 
- @item bootstrap-lean
- Like @code{bootstrap}, except that the various stages are removed once
- they're no longer needed.  This saves disk space.
- 
- @item bubblestrap
- Once bootstrapped, this incrementally rebuilds each of the three stages,
- one at a time.  It does this by ``bubbling'' the stages up from their
- subdirectories, rebuilding them, and copying them back to their
- subdirectories.  This will allow you to, for example, quickly rebuild a
- bootstrapped compiler after changing the sources, without having to do a
- full bootstrap.
- 
- @item quickstrap
- Rebuilds the most recently built stage.  Since each stage requires
- special invocation, using this target means you don't have to keep track
- of which stage you're on or what invocation that stage needs.
- 
- @item cleanstrap
- Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
- 
- @item stage@var{N} (@var{N} = 1@dots{}4)
- For each stage, moves the appropriate files to the @file{stage@var{N}}
- subdirectory.
- 
- @item unstage@var{N} (@var{N} = 1@dots{}4)
- Undoes the corresponding @code{stage@var{N}}.
- 
- @item restage@var{N} (@var{N} = 1@dots{}4)
- Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
- appropriate flags.
- 
- @item compare
- Compares the results of stages 2 and 3.  This ensures that the compiler
- is running properly, since it should produce the same object files
- 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
- @node Portability
- @chapter GCC and Portability
- @cindex portability
- @cindex GCC and portability
- 
- The main goal of GCC was to make a good, fast compiler for machines in
- the class that the GNU system aims to run on: 32-bit machines that address
- 8-bit bytes and have several general registers.  Elegance, theoretical
- power and simplicity are only secondary.
- 
- GCC gets most of the information about the target machine from a machine
- description which gives an algebraic formula for each of the machine's
- instructions.  This is a very clean way to describe the target.  But when
- the compiler needs information that is difficult to express in this
- fashion, I have not hesitated to define an ad-hoc parameter to the machine
- description.  The purpose of portability is to reduce the total work needed
- on the compiler; it was not of interest for its own sake.
- 
- @cindex endianness
- @cindex autoincrement addressing, availability
- @findex abort
- GCC does not contain machine dependent code, but it does contain code
- that depends on machine parameters such as endianness (whether the most
- significant byte has the highest or lowest address of the bytes in a word)
- and the availability of autoincrement addressing.  In the RTL-generation
- pass, it is often necessary to have multiple strategies for generating code
- for a particular kind of syntax tree, strategies that are usable for different
- combinations of parameters.  Often I have not tried to address all possible
- cases, but only the common ones or only the ones that I have encountered.
- As a result, a new target may require additional strategies.  You will know
- if this happens because the compiler will call @code{abort}.  Fortunately,
- the new strategies can be added in a machine-independent fashion, and will
- affect only the target machines that need them.
- @end ifset
- 
- @ifset INTERNALS
- @node Interface
- @chapter Interfacing to GCC Output
- @cindex interfacing to GCC output
- @cindex run-time conventions
- @cindex function call conventions
- @cindex conventions, run-time
- 
- GCC is normally configured to use the same function calling convention
- normally in use on the target system.  This is done with the
- machine-description macros described (@pxref{Target Macros}).
- 
- @cindex unions, returning
- @cindex structures, returning
- @cindex returning structures and unions
- However, returning of structure and union values is done differently on
- some target machines.  As a result, functions compiled with PCC
- returning such types cannot be called from code compiled with GCC,
- and vice versa.  This does not cause trouble often because few Unix
- library routines return structures or unions.
- 
- GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
- long in the same registers used for @code{int} or @code{double} return
- values.  (GCC typically allocates variables of such types in
- registers also.)  Structures and unions of other sizes are returned by
- storing them into an address passed by the caller (usually in a
- register).  The machine-description macros @code{STRUCT_VALUE} and
- @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
- 
- By contrast, PCC on most target machines returns structures and unions
- of any size by copying the data into an area of static storage, and then
- returning the address of that storage as if it were a pointer value.
- The caller must copy the data from that memory area to the place where
- the value is wanted.  This is slower than the method used by GCC, and
- fails to be reentrant.
- 
- On some target machines, such as RISC machines and the 80386, the
- standard system convention is to pass to the subroutine the address of
- where to return the value.  On these machines, GCC has been
- configured to be compatible with the standard compiler, when this method
- is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
- 
- @cindex argument passing
- @cindex passing arguments
- GCC uses the system's standard convention for passing arguments.  On
- some machines, the first few arguments are passed in registers; in
- others, all are passed on the stack.  It would be possible to use
- registers for argument passing on any machine, and this would probably
- result in a significant speedup.  But the result would be complete
- incompatibility with code that follows the standard convention.  So this
- change is practical only if you are switching to GCC as the sole C
- compiler for the system.  We may implement register argument passing on
- certain machines once we have a complete GNU system so that we can
- compile the libraries with GCC@.
- 
- On some machines (particularly the Sparc), certain types of arguments
- are passed ``by invisible reference''.  This means that the value is
- stored in memory, and the address of the memory location is passed to
- the subroutine.
- 
- @cindex @code{longjmp} and automatic variables
- If you use @code{longjmp}, beware of automatic variables.  ISO C says that
- automatic variables that are not declared @code{volatile} have undefined
- values after a @code{longjmp}.  And this is all GCC promises to do,
- because it is very difficult to restore register variables correctly, and
- one of GCC's features is that it can put variables in registers without
- your asking it to.
- 
- If you want a variable to be unaltered by @code{longjmp}, and you don't
- want to write @code{volatile} because old C compilers don't accept it,
- just take the address of the variable.  If a variable's address is ever
- taken, even if just to compute it and ignore it, then the variable cannot
- go in a register:
- 
- @example
- @{
-   int careful;
-   &careful;
-   @dots{}
- @}
- @end example
- 
- @cindex arithmetic libraries
- @cindex math libraries
- @opindex msoft-float
- Code compiled with GCC may call certain library routines.  Most of
- them handle arithmetic for which there are no instructions.  This
- includes multiply and divide on some machines, and floating point
- operations on any machine for which floating point support is disabled
- with @option{-msoft-float}.  Some standard parts of the C library, such as
- @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
- function call interface is used for calling the library routines.
- 
- Some of these routines can be defined in mostly machine-independent C;
- they appear in @file{libgcc2.c}.  Others must be hand-written in
- assembly language for each processor.  Wherever they are defined, they
- are compiled into the support library, @file{libgcc.a}, which is
- automatically searched when you link programs with GCC@.
- @end ifset
- 
- @ifset INTERNALS
- @node Passes
- @chapter Passes and Files of the Compiler
- @cindex passes and files of the compiler
- @cindex files and passes of the compiler
- @cindex compiler passes and files
- 
- @cindex top level of compiler
- The overall control structure of the compiler is in @file{toplev.c}.  This
- file is responsible for initialization, decoding arguments, opening and
- closing files, and sequencing the passes.
- 
- @cindex parsing pass
- The parsing pass is invoked only once, to parse the entire input.  A
- high level tree representation is then generated from the input,
- one function at a time.  This tree code is then transformed into RTL
- intermediate code, and processed.  The files involved in transforming
- the trees into RTL are @file{expr.c}, @file{expmed.c}, and
- @file{stmt.c}.
- @c Note, the above files aren't strictly the only files involved. It's
- @c all over the place (function.c, final.c,etc).  However, those are
- @c the files that are supposed to be directly involved, and have
- @c their purpose listed as such, so i've only listed them.
- The order of trees that are processed, is not
- necessarily the same order they are generated from
- the input, due to deferred inlining, and other considerations.
- 
- @findex rest_of_compilation
- @findex rest_of_decl_compilation
- Each time the parsing pass reads a complete function definition or
- top-level declaration, it calls either the function
- @code{rest_of_compilation}, or the function
- @code{rest_of_decl_compilation} in @file{toplev.c}, which are
- responsible for all further processing necessary, ending with output of
- the assembler language.  All other compiler passes run, in sequence,
- within @code{rest_of_compilation}.  When that function returns from
- compiling a function definition, the storage used for that function
- definition's compilation is entirely freed, unless it is an inline
- function, or was deferred for some reason (this can occur in
- templates, for example).
- @ifset USING
- (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
- @end ifset
- @ifclear USING
- (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
- @end ifclear
- 
- Here is a list of all the passes of the compiler and their source files.
- Also included is a description of where debugging dumps can be requested
- with @option{-d} options.
- 
- @itemize @bullet
- @item
- Parsing.  This pass reads the entire text of a function definition,
- constructing a high level tree representation.  (Because of the semantic
- analysis that takes place during this pass, it does more than is
- formally considered to be parsing.)
- 
- The tree representation does not entirely follow C syntax, because it is
- intended to support other languages as well.
- 
- Language-specific data type analysis is also done in this pass, and every
- tree node that represents an expression has a data type attached.
- Variables are represented as declaration nodes.
- 
- The language-independent source files for parsing are
- @file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
- There are also header files @file{tree.h} and @file{tree.def}
- which define the format of the tree representation.
- 
- C preprocessing, for language front ends, that want or require it, is
- performed by cpplib, which is covered in separate documentation.  In
- particular, the internals are covered in @xref{Top, ,Cpplib internals,
- cppinternals, Cpplib Internals}.
- 
- @c Avoiding overfull is tricky here.
- The source files to parse C are
- @file{c-convert.c},
- @file{c-decl.c},
- @file{c-errors.c},
- @file{c-lang.c},
- @file{c-parse.in},
- @file{c-aux-info.c},
- and
- @file{c-typeck.c},
- along with a header file
- @file{c-tree.h}
- and some files shared with Objective-C and C++.
- 
- The source files for parsing C++ are in @file{cp/}.
- They are @file{parse.y},
- @file{class.c},
- @file{cvt.c}, @file{decl.c}, @file{decl2.c},
- @file{except.c},
- @file{expr.c}, @file{init.c}, @file{lex.c},
- @file{method.c}, @file{ptree.c},
- @file{search.c}, @file{spew.c},
- @file{semantics.c}, @file{tree.c},
- @file{typeck2.c}, and
- @file{typeck.c}, along with header files @file{cp-tree.def},
- @file{cp-tree.h}, and @file{decl.h}.
- 
- The special source files for parsing Objective-C are in @file{objc/}.
- They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
- Certain C-specific files are used for this as well.
- 
- The files
- @file{c-common.c},
- @file{c-common.def},
- @file{c-dump.c},
- @file{c-format.c},
- @file{c-pragma.c},
- @file{c-semantics.c},
- and
- @file{c-lex.c},
- along with header files
- @file{c-common.h},
- @file{c-dump.h},
- @file{c-lex.h},
- and
- @file{c-pragma.h},
- are also used for all of the above languages.
- 
- 
- @cindex Tree optimization
- @item
- Tree optimization.   This is the optimization of the tree
- representation, before converting into RTL code.
- 
- @cindex inline on trees, automatic
- Currently, the main optimization performed here is tree-based
- inlining.
- This is implemented for C++ in @file{cp/optimize.c}.  Note that
- tree based inlining turns off rtx based inlining (since it's more
- powerful, it would be a waste of time to do rtx based inlining in
- addition).
- The C front end currently does not perform tree based inlining.
- 
- @cindex constant folding
- @cindex arithmetic simplifications
- @cindex simplifications, arithmetic
- Constant folding and some arithmetic simplifications are also done
- during this pass, on the tree representation.
- The routines that perform these tasks are located in @file{fold-const.c}.
- 
- @cindex RTL generation
- @item
- RTL generation.  This is the conversion of syntax tree into RTL code.
- 
- @cindex target-parameter-dependent code
- This is where the bulk of target-parameter-dependent code is found,
- since often it is necessary for strategies to apply only when certain
- standard kinds of instructions are available.  The purpose of named
- instruction patterns is to provide this information to the RTL
- generation pass.
- 
- @cindex tail recursion optimization
- Optimization is done in this pass for @code{if}-conditions that are
- comparisons, boolean operations or conditional expressions.  Tail
- recursion is detected at this time also.  Decisions are made about how
- best to arrange loops and how to output @code{switch} statements.
- 
- @c Avoiding overfull is tricky here.
- The source files for RTL generation include
- @file{stmt.c},
- @file{calls.c},
- @file{expr.c},
- @file{explow.c},
- @file{expmed.c},
- @file{function.c},
- @file{optabs.c}
- and @file{emit-rtl.c}.
- Also, the file
- @file{insn-emit.c}, generated from the machine description by the
- program @code{genemit}, is used in this pass.  The header file
- @file{expr.h} is used for communication within this pass.
- 
- @findex genflags
- @findex gencodes
- The header files @file{insn-flags.h} and @file{insn-codes.h},
- generated from the machine description by the programs @code{genflags}
- and @code{gencodes}, tell this pass which standard names are available
- for use and which patterns correspond to them.
- 
- Aside from debugging information output, none of the following passes
- refers to the tree structure representation of the function (only
- part of which is saved).
- 
- @cindex inline on rtx, automatic
- The decision of whether the function can and should be expanded inline
- in its subsequent callers is made at the end of rtl generation.  The
- function must meet certain criteria, currently related to the size of
- the function and the types and number of parameters it has.  Note that
- this function may contain loops, recursive calls to itself
- (tail-recursive functions can be inlined!), gotos, in short, all
- constructs supported by GCC@.  The file @file{integrate.c} contains
- the code to save a function's rtl for later inlining and to inline that
- rtl when the function is called.  The header file @file{integrate.h}
- is also used for this purpose.
- 
- @opindex dr
- The option @option{-dr} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.rtl} to
- the input file name.
- 
- @c Should the exception handling pass be talked about here?
- 
- @cindex sibling call optimization
- @item
- Sibiling call optimization.   This pass performs tail recursion
- elimination, and tail and sibling call optimizations.  The purpose of
- these optimizations is to reduce the overhead of function calls,
- whenever possible.
- 
- The source file of this pass is @file{sibcall.c}
- 
- @opindex di
- The option @option{-di} causes a debugging dump of the RTL code after
- this pass is run.  This dump file's name is made by appending
- @samp{.sibling} to the input file name.
- 
- @cindex jump optimization
- @cindex unreachable code
- @cindex dead code
- @item
- Jump optimization.  This pass simplifies jumps to the following
- instruction, jumps across jumps, and jumps to jumps.  It deletes
- unreferenced labels and unreachable code, except that unreachable code
- that contains a loop is not recognized as unreachable in this pass.
- (Such loops are deleted later in the basic block analysis.)  It also
- converts some code originally written with jumps into sequences of
- instructions that directly set values from the results of comparisons,
- if the machine has such instructions.
- 
- Jump optimization is performed two or three times.  The first time is
- immediately following RTL generation.  The second time is after CSE,
- but only if CSE says repeated jump optimization is needed.  The
- last time is right before the final pass.  That time, cross-jumping
- and deletion of no-op move instructions are done together with the
- optimizations described above.
- 
- The source file of this pass is @file{jump.c}.
- 
- @opindex dj
- The option @option{-dj} causes a debugging dump of the RTL code after
- this pass is run for the first time.  This dump file's name is made by
- appending @samp{.jump} to the input file name.
- 
- 
- @cindex register use analysis
- @item
- Register scan.  This pass finds the first and last use of each
- register, as a guide for common subexpression elimination.  Its source
- is in @file{regclass.c}.
- 
- @cindex jump threading
- @item
- @opindex fthread-jumps
- Jump threading.  This pass detects a condition jump that branches to an
- identical or inverse test.  Such jumps can be @samp{threaded} through
- the second conditional test.  The source code for this pass is in
- @file{jump.c}.  This optimization is only performed if
- @option{-fthread-jumps} is enabled.
- 
- @cindex SSA optimizations
- @cindex Single Static Assignment optimizations
- @opindex fssa
- @item
- Static Single Assignment (SSA) based optimization passes.  The
- SSA conversion passes (to/from) are turned on by the @option{-fssa}
- option (it is also done automatically if you enable an SSA optimization pass).
- These passes utilize a form called Static Single Assignment.  In SSA form,
- each variable (pseudo register) is only set once, giving you def-use
- and use-def chains for free, and enabling a lot more optimization
- passes to be run in linear time.
- Conversion to and from SSA form is handled by functions in
- @file{ssa.c}.
- 
- @opindex de
- The option @option{-de} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.ssa} to
- the input file name.
- @itemize @bullet
- @cindex SSA Conditional Constant Propagation
- @cindex Conditional Constant Propagation, SSA based
- @cindex conditional constant propagation
- @opindex fssa-ccp
- @item
- SSA Conditional Constant Propagation.  Turned on by the @option{-fssa-ccp}
- SSA Aggressive Dead Code Elimination.  Turned on by the @option{-fssa-dce}
- option.  This pass performs conditional constant propagation to simplify
- instructions including conditional branches.  This pass is more aggressive
- than the constant propgation done by the CSE and GCSE pases, but operates
- in linear time.
- 
- @opindex dW
- The option @option{-dW} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.ssaccp} to
- the input file name.
- 
- @cindex SSA DCE
- @cindex DCE, SSA based
- @cindex dead code elimination
- @opindex fssa-dce
- @item
- SSA Aggressive Dead Code Elimination.  Turned on by the @option{-fssa-dce}
- option.  This pass performs elimination of code considered unnecessary because
- it has no externally visible effects on the program.  It operates in
- linear time.
- 
- @opindex dX
- The option @option{-dX} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.ssadce} to
- the input file name.
- @end itemize
- 
- @cindex common subexpression elimination
- @cindex constant propagation
- @item
- Common subexpression elimination.  This pass also does constant
- propagation.  Its source files are @file{cse.c}, and @file{cselib.c}.
- If constant  propagation causes conditional jumps to become
- unconditional or to become no-ops, jump optimization is run again when
- CSE is finished.
- 
- @opindex ds
- The option @option{-ds} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.cse} to
- the input file name.
- 
- @cindex global common subexpression elimination
- @cindex constant propagation
- @cindex copy propagation
- @item
- Global common subexpression elimination.  This pass performs two
- different types of GCSE  depending on whether you are optimizing for
- size or not (LCM based GCSE tends to increase code size for a gain in
- speed, while Morel-Renvoise based GCSE does not).
- When optimizing for size, GCSE is done using Morel-Renvoise Partial
- Redundancy Elimination, with the exception that it does not try to move
- invariants out of loops---that is left to  the loop optimization pass.
- If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
- well as load motion.
- If you are optimizing for speed, LCM (lazy code motion) based GCSE is
- done.  LCM is based on the work of Knoop, Ruthing, and Steffen.  LCM
- based GCSE also does loop invariant code motion.  We also perform load
- and store motion when optimizing for speed.
- Regardless of which type of GCSE is used, the GCSE pass also performs
- global constant and  copy propagation.
- 
- The source file for this pass is @file{gcse.c}, and the LCM routines
- are in @file{lcm.c}.
- 
- @opindex dG
- The option @option{-dG} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.gcse} to
- the input file name.
- 
- @cindex loop optimization
- @cindex code motion
- @cindex strength-reduction
- @item
- Loop optimization.  This pass moves constant expressions out of loops,
- and optionally does strength-reduction and loop unrolling as well.
- Its source files are @file{loop.c} and @file{unroll.c}, plus the header
- @file{loop.h} used for communication between them.  Loop unrolling uses
- some functions in @file{integrate.c} and the header @file{integrate.h}.
- Loop dependency analysis routines are contained in @file{dependence.c}.
- 
- @opindex dL
- The option @option{-dL} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.loop} to
- the input file name.
- 
- @item
- @opindex frerun-cse-after-loop
- If @option{-frerun-cse-after-loop} was enabled, a second common
- subexpression elimination pass is performed after the loop optimization
- pass.  Jump threading is also done again at this time if it was specified.
- 
- @opindex dt
- The option @option{-dt} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.cse2} to
- the input file name.
- 
- @cindex data flow analysis
- @cindex analysis, data flow
- @cindex basic blocks
- @item
- Data flow analysis (@file{flow.c}).  This pass divides the program
- into basic blocks (and in the process deletes unreachable loops); then
- it computes which pseudo-registers are live at each point in the
- program, and makes the first instruction that uses a value point at
- the instruction that computed the value.
- 
- @cindex autoincrement/decrement analysis
- This pass also deletes computations whose results are never used, and
- combines memory references with add or subtract instructions to make
- autoincrement or autodecrement addressing.
- 
- @opindex df
- The option @option{-df} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.flow} to
- the input file name.  If stupid register allocation is in use, this
- dump file reflects the full results of such allocation.
- 
- @cindex instruction combination
- @item
- Instruction combination (@file{combine.c}).  This pass attempts to
- combine groups of two or three instructions that are related by data
- flow into single instructions.  It combines the RTL expressions for
- the instructions by substitution, simplifies the result using algebra,
- and then attempts to match the result against the machine description.
- 
- @opindex dc
- The option @option{-dc} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.combine}
- to the input file name.
- 
- @cindex if conversion
- @item
- If-conversion is a transformation that transforms control dependencies
- into data dependencies (IE it transforms conditional code into a
- single control stream).
- It is implemented in the file @file{ifcvt.c}.
- 
- @opindex dE
- The option @option{-dE} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.ce} to
- the input file name.
- 
- @cindex register movement
- @item
- Register movement (@file{regmove.c}).  This pass looks for cases where
- matching constraints would force an instruction to need a reload, and
- this reload would be a register to register move.  It then attempts
- to change the registers used by the instruction to avoid the move
- instruction.
- 
- @opindex dN
- The option @option{-dN} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.regmove}
- to the input file name.
- 
- @cindex instruction scheduling
- @cindex scheduling, instruction
- @item
- Instruction scheduling (@file{sched.c}).  This pass looks for
- instructions whose output will not be available by the time that it is
- used in subsequent instructions.  (Memory loads and floating point
- instructions often have this behavior on RISC machines).  It re-orders
- instructions within a basic block to try to separate the definition and
- use of items that otherwise would cause pipeline stalls.
- 
- Instruction scheduling is performed twice.  The first time is immediately
- after instruction combination and the second is immediately after reload.
- 
- @opindex dS
- The option @option{-dS} causes a debugging dump of the RTL code after this
- pass is run for the first time.  The dump file's name is made by
- appending @samp{.sched} to the input file name.
- 
- @cindex register class preference pass
- @item
- Register class preferencing.  The RTL code is scanned to find out
- which register class is best for each pseudo register.  The source
- file is @file{regclass.c}.
- 
- @cindex register allocation
- @cindex local register allocation
- @item
- Local register allocation (@file{local-alloc.c}).  This pass allocates
- hard registers to pseudo registers that are used only within one basic
- block.  Because the basic block is linear, it can use fast and
- powerful techniques to do a very good job.
- 
- @opindex dl
- The option @option{-dl} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.lreg} to
- the input file name.
- 
- @cindex global register allocation
- @item
- Global register allocation (@file{global.c}).  This pass
- allocates hard registers for the remaining pseudo registers (those
- whose life spans are not contained in one basic block).
- 
- @cindex reloading
- @item
- Reloading.  This pass renumbers pseudo registers with the hardware
- registers numbers they were allocated.  Pseudo registers that did not
- get hard registers are replaced with stack slots.  Then it finds
- instructions that are invalid because a value has failed to end up in
- a register, or has ended up in a register of the wrong kind.  It fixes
- up these instructions by reloading the problematical values
- temporarily into registers.  Additional instructions are generated to
- do the copying.
- 
- The reload pass also optionally eliminates the frame pointer and inserts
- instructions to save and restore call-clobbered registers around calls.
- 
- Source files are @file{reload.c} and @file{reload1.c}, plus the header
- @file{reload.h} used for communication between them.
- 
- @opindex dg
- The option @option{-dg} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.greg} to
- the input file name.
- 
- @cindex instruction scheduling
- @cindex scheduling, instruction
- @item
- Instruction scheduling is repeated here to try to avoid pipeline stalls
- due to memory loads generated for spilled pseudo registers.
- 
- @opindex dR
- The option @option{-dR} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.sched2}
- to the input file name.
- 
- @cindex basic block reordering
- @cindex reordering, block
- @item
- Basic block reordering.  This pass implements profile guided code
- positioning.  If profile information is not available, various types of
- static analysis are performed to make the predictions normally coming
- from the profile feedback (IE execution frequency, branch probability,
- etc).  It is implemented in the file @file{bb-reorder.c}, and the
- various prediction routines are in @file{predict.c}.
- 
- @opindex dB
- The option @option{-dB} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.bbro} to
- the input file name.
- 
- @cindex cross-jumping
- @cindex no-op move instructions
- @item
- Jump optimization is repeated, this time including cross-jumping
- and deletion of no-op move instructions.
- 
- @opindex dJ
- The option @option{-dJ} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.jump2}
- to the input file name.
- 
- @cindex delayed branch scheduling
- @cindex scheduling, delayed branch
- @item
- Delayed branch scheduling.  This optional pass attempts to find
- instructions that can go into the delay slots of other instructions,
- usually jumps and calls.  The source file name is @file{reorg.c}.
- 
- @opindex dd
- The option @option{-dd} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.dbr}
- to the input file name.
- 
- @cindex branch shortening
- @item
- Branch shortening.  On many RISC machines, branch instructions have a
- limited range.  Thus, longer sequences of instructions must be used for
- long branches.  In this pass, the compiler figures out what how far each
- instruction will be from each other instruction, and therefore whether
- the usual instructions, or the longer sequences, must be used for each
- branch.
- 
- @cindex register-to-stack conversion
- @item
- Conversion from usage of some hard registers to usage of a register
- stack may be done at this point.  Currently, this is supported only
- for the floating-point registers of the Intel 80387 coprocessor.   The
- source file name is @file{reg-stack.c}.
- 
- @opindex dk
- The options @option{-dk} causes a debugging dump of the RTL code after
- this pass.  This dump file's name is made by appending @samp{.stack}
- to the input file name.
- 
- @cindex final pass
- @cindex peephole optimization
- @item
- Final.  This pass outputs the assembler code for the function.  It is
- also responsible for identifying spurious test and compare
- instructions.  Machine-specific peephole optimizations are performed
- at the same time.  The function entry and exit sequences are generated
- directly as assembler code in this pass; they never exist as RTL@.
- 
- The source files are @file{final.c} plus @file{insn-output.c}; the
- latter is generated automatically from the machine description by the
- tool @file{genoutput}.  The header file @file{conditions.h} is used
- for communication between these files.
- 
- @cindex debugging information generation
- @item
- Debugging information output.  This is run after final because it must
- output the stack slot offsets for pseudo registers that did not get
- hard registers.  Source files are @file{dbxout.c} for DBX symbol table
- format, @file{sdbout.c} for SDB symbol table format,  @file{dwarfout.c}
- for DWARF symbol table format, and the files @file{dwarf2out.c} and
- @file{dwarf2asm.c} for DWARF2 symbol table format.
- @end itemize
- 
- Some additional files are used by all or many passes:
- 
- @itemize @bullet
- @item
- Every pass uses @file{machmode.def} and @file{machmode.h} which define
- the machine modes.
- 
- @item
- Several passes use @file{real.h}, which defines the default
- representation of floating point constants and how to operate on them.
- 
- @item
- All the passes that work with RTL use the header files @file{rtl.h}
- and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
- @code{gen*} also use these files to read and work with the machine
- description RTL@.
- 
- @item
- All the tools that read the machine description use support routines
- found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
- 
- @findex genconfig
- @item
- Several passes refer to the header file @file{insn-config.h} which
- contains a few parameters (C macro definitions) generated
- automatically from the machine description RTL by the tool
- @code{genconfig}.
- 
- @cindex instruction recognizer
- @item
- Several passes use the instruction recognizer, which consists of
- @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
- and @file{insn-extract.c} that are generated automatically from the
- machine description by the tools @file{genrecog} and
- @file{genextract}.
- 
- @item
- Several passes use the header files @file{regs.h} which defines the
- information recorded about pseudo register usage, and @file{basic-block.h}
- which defines the information recorded about basic blocks.
- 
- @item
- @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
- with a bit for each hard register, and some macros to manipulate it.
- This type is just @code{int} if the machine has few enough hard registers;
- otherwise it is an array of @code{int} and some of the macros expand
- into loops.
- 
- @item
- Several passes use instruction attributes.  A definition of the
- attributes defined for a particular machine is in file
- @file{insn-attr.h}, which is generated from the machine description by
- the program @file{genattr}.  The file @file{insn-attrtab.c} contains
- subroutines to obtain the attribute values for insns.  It is generated
- from the machine description by the program @file{genattrtab}.
- @end itemize
  @end ifset
  
  @ifset INTERNALS
  @include c-tree.texi
  @include rtl.texi
  @include md.texi
  @include tm.texi
! @end ifset
! 
! @ifset INTERNALS
! @node Config
! @chapter The Configuration File
! @cindex configuration file
! @cindex @file{xm-@var{machine}.h}
! 
! The configuration file @file{xm-@var{machine}.h} contains macro
! definitions that describe the machine and system on which the compiler
! is running, unlike the definitions in @file{@var{machine}.h}, which
! describe the machine for which the compiler is producing output.  Most
! of the values in @file{xm-@var{machine}.h} are actually the same on all
! machines that GCC runs on, so large parts of all configuration files
! are identical.  But there are some macros that vary:
! 
! @table @code
! @findex USG
! @item USG
! Define this macro if the host system is System V@.
! 
! @findex VMS
! @item VMS
! Define this macro if the host system is VMS@.
! 
! @findex FATAL_EXIT_CODE
! @item FATAL_EXIT_CODE
! A C expression for the status code to be returned when the compiler
! exits after serious errors.  The default is the system-provided macro
! @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
! macro.  Define this macro only if these defaults are incorrect.
! 
! @findex SUCCESS_EXIT_CODE
! @item SUCCESS_EXIT_CODE
! A C expression for the status code to be returned when the compiler
! exits without serious errors.  (Warnings are not serious errors.)  The
! default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
! the system doesn't define that macro.  Define this macro only if these
! defaults are incorrect.
! 
! @findex HOST_WORDS_BIG_ENDIAN
! @item HOST_WORDS_BIG_ENDIAN
! Defined if the host machine stores words of multi-word values in
! big-endian order.  (GCC does not depend on the host byte ordering
! within a word.)
! 
! @findex HOST_FLOAT_WORDS_BIG_ENDIAN
! @item HOST_FLOAT_WORDS_BIG_ENDIAN
! Define this macro to be 1 if the host machine stores @code{DFmode},
! @code{XFmode} or @code{TFmode} floating point numbers in memory with the
! word containing the sign bit at the lowest address; otherwise, define it
! to be zero.
! 
! This macro need not be defined if the ordering is the same as for
! multi-word integers.
! 
! @findex HOST_FLOAT_FORMAT
! @item HOST_FLOAT_FORMAT
! A numeric code distinguishing the floating point format for the host
! machine.  See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
! alternatives and default.
! 
! @findex HOST_BITS_PER_CHAR
! @item HOST_BITS_PER_CHAR
! A C expression for the number of bits in @code{char} on the host
! machine.
! 
! @findex HOST_BITS_PER_SHORT
! @item HOST_BITS_PER_SHORT
! A C expression for the number of bits in @code{short} on the host
! machine.
! 
! @findex HOST_BITS_PER_INT
! @item HOST_BITS_PER_INT
! A C expression for the number of bits in @code{int} on the host
! machine.
! 
! @findex HOST_BITS_PER_LONG
! @item HOST_BITS_PER_LONG
! A C expression for the number of bits in @code{long} on the host
! machine.
! 
! @findex HOST_BITS_PER_LONGLONG
! @item HOST_BITS_PER_LONGLONG
! A C expression for the number of bits in @code{long long} on the host
! machine.
! 
! @findex ONLY_INT_FIELDS
! @item ONLY_INT_FIELDS
! Define this macro to indicate that the host compiler only supports
! @code{int} bit-fields, rather than other integral types, including
! @code{enum}, as do most C compilers.
! 
! @findex OBSTACK_CHUNK_SIZE
! @item OBSTACK_CHUNK_SIZE
! A C expression for the size of ordinary obstack chunks.
! If you don't define this, a usually-reasonable default is used.
! 
! @findex OBSTACK_CHUNK_ALLOC
! @item OBSTACK_CHUNK_ALLOC
! The function used to allocate obstack chunks.
! If you don't define this, @code{xmalloc} is used.
! 
! @findex OBSTACK_CHUNK_FREE
! @item OBSTACK_CHUNK_FREE
! The function used to free obstack chunks.
! If you don't define this, @code{free} is used.
! 
! @findex USE_C_ALLOCA
! @item USE_C_ALLOCA
! Define this macro to indicate that the compiler is running with the
! @code{alloca} implemented in C@.  This version of @code{alloca} can be
! found in the file @file{alloca.c}; to use it, you must also alter the
! @file{Makefile} variable @code{ALLOCA}.  (This is done automatically
! for the systems on which we know it is needed.)
! 
! If you do define this macro, you should probably do it as follows:
! 
! @example
! #ifndef __GNUC__
! #define USE_C_ALLOCA
! #else
! #define alloca __builtin_alloca
! #endif
! @end example
! 
! @noindent
! so that when the compiler is compiled with GCC it uses the more
! efficient built-in @code{alloca} function.
! 
! @item FUNCTION_CONVERSION_BUG
! @findex FUNCTION_CONVERSION_BUG
! Define this macro to indicate that the host compiler does not properly
! handle converting a function value to a pointer-to-function when it is
! used in an expression.
! 
! @findex MULTIBYTE_CHARS
! @item MULTIBYTE_CHARS
! Define this macro to enable support for multibyte characters in the
! input to GCC@.  This requires that the host system support the ISO C
! library functions for converting multibyte characters to wide
! characters.
! 
! @findex POSIX
! @item POSIX
! Define this if your system is POSIX.1 compliant.
! 
! @findex PATH_SEPARATOR
! @item PATH_SEPARATOR
! Define this macro to be a C character constant representing the
! character used to separate components in paths.  The default value is
! the colon character
! 
! @findex DIR_SEPARATOR
! @item DIR_SEPARATOR
! If your system uses some character other than slash to separate
! directory names within a file specification, define this macro to be a C
! character constant specifying that character.  When GCC displays file
! names, the character you specify will be used.  GCC will test for
! both slash and the character you specify when parsing filenames.
! 
! @findex DIR_SEPARATOR_2
! @item DIR_SEPARATOR_2
! If your system uses an alternative character other than
! @samp{DIR_SEPARATOR} to separate directory names within a file
! specification, define this macro to be a C character constant specifying
! that character.  If you define this macro, GCC will test for slash,
! @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
! 
! @findex TARGET_OBJECT_SUFFIX
! @item TARGET_OBJECT_SUFFIX
! Define this macro to be a C string representing the suffix for object
! files on your target machine.  If you do not define this macro, GCC will
! use @samp{.o} as the suffix for object files.
! 
! @findex TARGET_EXECUTABLE_SUFFIX
! @item TARGET_EXECUTABLE_SUFFIX
! Define this macro to be a C string representing the suffix to be
! automatically added to executable files on your target machine.  If you
! do not define this macro, GCC will use the null string as the suffix for
! executable files.
! 
! @findex HOST_OBJECT_SUFFIX
! @item HOST_OBJECT_SUFFIX
! Define this macro to be a C string representing the suffix for object
! files on your host machine (@samp{xm-*.h}).  If you do not define this
! macro, GCC will use @samp{.o} as the suffix for object files.
! 
! @findex HOST_EXECUTABLE_SUFFIX
! @item HOST_EXECUTABLE_SUFFIX
! Define this macro to be a C string representing the suffix for
! executable files on your host machine (@samp{xm-*.h}).  If you do not
! define this macro, GCC will use the null string as the suffix for
! executable files.
! 
! @findex HOST_BIT_BUCKET
! @item HOST_BIT_BUCKET
! The name of a file or file-like object on the host system which acts as
! a ``bit bucket''.  If you do not define this macro, GCC will use
! @samp{/dev/null} as the bit bucket.  If the target does not support a
! bit bucket, this should be defined to the null string, or some other
! invalid filename.  If the bit bucket is not writable, GCC will use a
! temporary file instead.
! 
! @findex COLLECT_EXPORT_LIST
! @item COLLECT_EXPORT_LIST
! If defined, @code{collect2} will scan the individual object files
! specified on its command line and create an export list for the linker.
! Define this macro for systems like AIX, where the linker discards
! object files that are not referenced from @code{main} and uses export
! lists.
! 
! @findex COLLECT2_HOST_INITIALIZATION
! @item COLLECT2_HOST_INITIALIZATION
! If defined, a C statement (sans semicolon) that performs host-dependent
! initialization when @code{collect2} is being initialized.
! 
! @findex GCC_DRIVER_HOST_INITIALIZATION
! @item GCC_DRIVER_HOST_INITIALIZATION
! If defined, a C statement (sans semicolon) that performs host-dependent
! initialization when a compilation driver is being initialized.
! 
! @findex UPDATE_PATH_HOST_CANONICALIZE
! @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
! If defined, a C statement (sans semicolon) that performs host-dependent
! canonicalization when a path used in a compilation driver or
! preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
! canonicalized.  If the C statement does canonicalize @var{path} into a
! different buffer, the old path should be freed and the new buffer should
! have been allocated with malloc.
! @end table
! 
! @findex bzero
! @findex bcmp
! In addition, configuration files for system V define @code{bcopy},
! @code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
! as a macro when compiled with GCC, in order to take advantage of the
! benefit of GCC's built-in @code{alloca}.
! 
! @node Fragments
! @chapter Makefile Fragments
! @cindex makefile fragment
! 
! When you configure GCC using the @file{configure} script
! (@pxref{Installation}), it will construct the file @file{Makefile} from
! the template file @file{Makefile.in}.  When it does this, it will
! incorporate makefile fragment files from the @file{config} directory,
! named @file{t-@var{target}} and @file{x-@var{host}}.  If these files do
! not exist, it means nothing needs to be added for a given target or
! host.
! 
! @menu
! * Target Fragment:: Writing the @file{t-@var{target}} file.
! * Host Fragment::   Writing the @file{x-@var{host}} file.
! @end menu
! 
! @node Target Fragment
! @section The Target Makefile Fragment
! @cindex target makefile fragment
! @cindex @file{t-@var{target}}
! 
! The target makefile fragment, @file{t-@var{target}}, defines special
! target dependent variables and targets used in the @file{Makefile}:
! 
! @table @code
! @findex LIBGCC2_CFLAGS
! @item LIBGCC2_CFLAGS
! Compiler flags to use when compiling @file{libgcc2.c}.
! 
! @findex LIB2FUNCS_EXTRA
! @item LIB2FUNCS_EXTRA
! A list of source file names to be compiled or assembled and inserted
! into @file{libgcc.a}.
! 
! @findex Floating Point Emulation
! @item Floating Point Emulation
! To have GCC include software floating point libraries in @file{libgcc.a}
! define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
! @smallexample
! # We want fine grained libraries, so use the new code
! # to build the floating point emulation libraries.
! FPBIT = fp-bit.c
! DPBIT = dp-bit.c
! 
! 
! fp-bit.c: $(srcdir)/config/fp-bit.c
!         echo '#define FLOAT' > fp-bit.c
!         cat $(srcdir)/config/fp-bit.c >> fp-bit.c
! 
! dp-bit.c: $(srcdir)/config/fp-bit.c
!         cat $(srcdir)/config/fp-bit.c > dp-bit.c
! @end smallexample
! 
! You may need to provide additional #defines at the beginning of @file{fp-bit.c}
! and @file{dp-bit.c} to control target endianness and other options.
! 
! 
! @findex CRTSTUFF_T_CFLAGS
! @item CRTSTUFF_T_CFLAGS
! Special flags used when compiling @file{crtstuff.c}.
! @xref{Initialization}.
! 
! @findex CRTSTUFF_T_CFLAGS_S
! @item CRTSTUFF_T_CFLAGS_S
! Special flags used when compiling @file{crtstuff.c} for shared
! linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
! in @code{EXTRA-PARTS}.
! @xref{Initialization}.
! 
! @findex MULTILIB_OPTIONS
! @item MULTILIB_OPTIONS
! For some targets, invoking GCC in different ways produces objects
! that can not be linked together.  For example, for some targets GCC
! produces both big and little endian code.  For these targets, you must
! arrange for multiple versions of @file{libgcc.a} to be compiled, one for
! each set of incompatible options.  When GCC invokes the linker, it
! arranges to link in the right version of @file{libgcc.a}, based on
! the command line options used.
! 
! The @code{MULTILIB_OPTIONS} macro lists the set of options for which
! special versions of @file{libgcc.a} must be built.  Write options that
! are mutually incompatible side by side, separated by a slash.  Write
! options that may be used together separated by a space.  The build
! procedure will build all combinations of compatible options.
! 
! For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
! msoft-float}, @file{Makefile} will build special versions of
! @file{libgcc.a} using the following sets of options:  @option{-m68000},
! @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
! @samp{-m68020 -msoft-float}.
! 
! @findex MULTILIB_DIRNAMES
! @item MULTILIB_DIRNAMES
! If @code{MULTILIB_OPTIONS} is used, this variable specifies the
! directory names that should be used to hold the various libraries.
! Write one element in @code{MULTILIB_DIRNAMES} for each element in
! @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
! default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
! as spaces.
! 
! For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
! msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
! @samp{m68000 m68020 msoft-float}.  You may specify a different value if
! you desire a different set of directory names.
! 
! @findex MULTILIB_MATCHES
! @item MULTILIB_MATCHES
! Sometimes the same option may be written in two different ways.  If an
! option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
! any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
! items of the form @samp{option=option} to describe all relevant
! synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
! 
! @findex MULTILIB_EXCEPTIONS
! @item MULTILIB_EXCEPTIONS
! Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
! specified, there are combinations that should not be built.  In that
! case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
! in shell case syntax that should not be built.
! 
! For example, in the PowerPC embedded ABI support, it is not desirable
! to build libraries compiled with the @option{-mcall-aix} option
! and either of the @option{-fleading-underscore} or @option{-mlittle} options
! at the same time.  Therefore @code{MULTILIB_EXCEPTIONS} is set to
! @smallexample
! *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
! @end smallexample
! 
! @findex MULTILIB_EXTRA_OPTS
! @item MULTILIB_EXTRA_OPTS
! Sometimes it is desirable that when building multiple versions of
! @file{libgcc.a} certain options should always be passed on to the
! compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
! of options to be used for all builds.
! @end table
! 
! @node Host Fragment
! @section The Host Makefile Fragment
! @cindex host makefile fragment
! @cindex @file{x-@var{host}}
! 
! The host makefile fragment, @file{x-@var{host}}, defines special host
! dependent variables and targets used in the @file{Makefile}:
! 
! @table @code
! @findex CC
! @item CC
! The compiler to use when building the first stage.
! 
! @findex INSTALL
! @item INSTALL
! The install program to use.
! @end table
  @end ifset
  
  @include funding.texi
  
! @node GNU/Linux
! @unnumbered Linux and the GNU Project
! 
! Many computer users run a modified version of the GNU system every
! day, without realizing it.  Through a peculiar turn of events, the
! version of GNU which is widely used today is more often known as
! ``Linux'', and many users are not aware of the extent of its
! connection with the GNU Project.
! 
! There really is a Linux; it is a kernel, and these people are using
! it.  But you can't use a kernel by itself; a kernel is useful only as
! part of a whole system.  The system in which Linux is typically used
! is a modified variant of the GNU system---in other words, a Linux-based
! GNU system.
! 
! Many users are not fully aware of the distinction between the kernel,
! which is Linux, and the whole system, which they also call ``Linux''.
! The ambiguous use of the name doesn't promote understanding.
! 
! Programmers generally know that Linux is a kernel.  But since they
! have generally heard the whole system called ``Linux'' as well, they
! often envisage a history which fits that name.  For example, many
! believe that once Linus Torvalds finished writing the kernel, his
! friends looked around for other free software, and for no particular
! reason most everything necessary to make a Unix-like system was
! already available.
! 
! What they found was no accident---it was the GNU system.  The available
! free software added up to a complete system because the GNU Project
! had been working since 1984 to make one.  The GNU Manifesto
! had set forth the goal of developing a free Unix-like system, called
! GNU@.  By the time Linux was written, the system was almost finished.
! 
! Most free software projects have the goal of developing a particular
! program for a particular job.  For example, Linus Torvalds set out to
! write a Unix-like kernel (Linux); Donald Knuth set out to write a text
! formatter (TeX); Bob Scheifler set out to develop a window system (X
! Windows).  It's natural to measure the contribution of this kind of
! project by specific programs that came from the project.
! 
! If we tried to measure the GNU Project's contribution in this way,
! what would we conclude?  One CD-ROM vendor found that in their ``Linux
! distribution'', GNU software was the largest single contingent, around
! 28% of the total source code, and this included some of the essential
! major components without which there could be no system.  Linux itself
! was about 3%.  So if you were going to pick a name for the system
! based on who wrote the programs in the system, the most appropriate
! single choice would be ``GNU''@.
! 
! But we don't think that is the right way to consider the question.
! The GNU Project was not, is not, a project to develop specific
! software packages.  It was not a project to develop a C compiler,
! although we did.  It was not a project to develop a text editor,
! although we developed one.  The GNU Project's aim was to develop
! @emph{a complete free Unix-like system}.
! 
! Many people have made major contributions to the free software in the
! system, and they all deserve credit.  But the reason it is @emph{a
! system}---and not just a collection of useful programs---is because the
! GNU Project set out to make it one.  We wrote the programs that were
! needed to make a @emph{complete} free system.  We wrote essential but
! unexciting major components, such as the assembler and linker, because
! you can't have a system without them.  A complete system needs more
! than just programming tools, so we wrote other components as well,
! such as the Bourne Again SHell, the PostScript interpreter
! Ghostscript, and the GNU C library.
! 
! By the early 90s we had put together the whole system aside from the
! kernel (and we were also working on a kernel, the GNU Hurd, which runs
! on top of Mach).  Developing this kernel has been a lot harder than we
! expected, and we are still working on finishing it.
! 
! Fortunately, you don't have to wait for it, because Linux is working
! now.  When Linus Torvalds wrote Linux, he filled the last major gap.
! People could then put Linux together with the GNU system to make a
! complete free system: a Linux-based GNU system (or GNU/Linux system,
! for short).
! 
! Putting them together sounds simple, but it was not a trivial job.
! The GNU C library (called glibc for short) needed substantial changes.
! Integrating a complete system as a distribution that would work ``out
! of the box'' was a big job, too.  It required addressing the issue of
! how to install and boot the system---a problem we had not tackled,
! because we hadn't yet reached that point.  The people who developed
! the various system distributions made a substantial contribution.
! 
! The GNU Project supports GNU/Linux systems as well as @emph{the}
! GNU system---even with funds.  We funded the rewriting of the
! Linux-related extensions to the GNU C library, so that now they are
! well integrated, and the newest GNU/Linux systems use the current
! library release with no changes.  We also funded an early stage of the
! development of Debian GNU/Linux.
! 
! We use Linux-based GNU systems today for most of our work, and we hope
! you use them too.  But please don't confuse the public by using the
! name ``Linux'' ambiguously.  Linux is the kernel, one of the essential
! major components of the system.  The system as a whole is more or less
! the GNU system.
  
  @include gpl.texi
  
--- 302,328 ----
  
  @include vms.texi
  
! @include makefile.texi
  
! @include configterms.texi
  
  @end ifset
  
  @ifset INTERNALS
+ @include portability.texi
+ @include interface.texi
+ @include passes.texi
  @include c-tree.texi
  @include rtl.texi
  @include md.texi
  @include tm.texi
! @include hostconfig.texi
! @include fragments.texi
  @end ifset
  
  @include funding.texi
  
! @include linux-and-gnu.texi
  
  @include gpl.texi
  
***************
*** 1773,1781 ****
  
  @include fdl.texi
  
- @node Contributors
- @unnumbered Contributors to GCC
- @cindex contributors
  @include contrib.texi
  
  @c ---------------------------------------------------------------------
--- 332,337 ----
diff -rcN gcc.orig/doc/hostconfig.texi gcc/doc/hostconfig.texi
*** gcc.orig/doc/hostconfig.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/hostconfig.texi	Sun Nov 11 19:12:00 2001
***************
*** 0 ****
--- 1,240 ----
+ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+ @c 1999, 2000, 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Config
+ @chapter The Configuration File
+ @cindex configuration file
+ @cindex @file{xm-@var{machine}.h}
+ 
+ The configuration file @file{xm-@var{machine}.h} contains macro
+ definitions that describe the machine and system on which the compiler
+ is running, unlike the definitions in @file{@var{machine}.h}, which
+ describe the machine for which the compiler is producing output.  Most
+ of the values in @file{xm-@var{machine}.h} are actually the same on all
+ machines that GCC runs on, so large parts of all configuration files
+ are identical.  But there are some macros that vary:
+ 
+ @table @code
+ @findex USG
+ @item USG
+ Define this macro if the host system is System V@.
+ 
+ @findex VMS
+ @item VMS
+ Define this macro if the host system is VMS@.
+ 
+ @findex FATAL_EXIT_CODE
+ @item FATAL_EXIT_CODE
+ A C expression for the status code to be returned when the compiler
+ exits after serious errors.  The default is the system-provided macro
+ @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
+ macro.  Define this macro only if these defaults are incorrect.
+ 
+ @findex SUCCESS_EXIT_CODE
+ @item SUCCESS_EXIT_CODE
+ A C expression for the status code to be returned when the compiler
+ exits without serious errors.  (Warnings are not serious errors.)  The
+ default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
+ the system doesn't define that macro.  Define this macro only if these
+ defaults are incorrect.
+ 
+ @findex HOST_WORDS_BIG_ENDIAN
+ @item HOST_WORDS_BIG_ENDIAN
+ Defined if the host machine stores words of multi-word values in
+ big-endian order.  (GCC does not depend on the host byte ordering
+ within a word.)
+ 
+ @findex HOST_FLOAT_WORDS_BIG_ENDIAN
+ @item HOST_FLOAT_WORDS_BIG_ENDIAN
+ Define this macro to be 1 if the host machine stores @code{DFmode},
+ @code{XFmode} or @code{TFmode} floating point numbers in memory with the
+ word containing the sign bit at the lowest address; otherwise, define it
+ to be zero.
+ 
+ This macro need not be defined if the ordering is the same as for
+ multi-word integers.
+ 
+ @findex HOST_FLOAT_FORMAT
+ @item HOST_FLOAT_FORMAT
+ A numeric code distinguishing the floating point format for the host
+ machine.  See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
+ alternatives and default.
+ 
+ @findex HOST_BITS_PER_CHAR
+ @item HOST_BITS_PER_CHAR
+ A C expression for the number of bits in @code{char} on the host
+ machine.
+ 
+ @findex HOST_BITS_PER_SHORT
+ @item HOST_BITS_PER_SHORT
+ A C expression for the number of bits in @code{short} on the host
+ machine.
+ 
+ @findex HOST_BITS_PER_INT
+ @item HOST_BITS_PER_INT
+ A C expression for the number of bits in @code{int} on the host
+ machine.
+ 
+ @findex HOST_BITS_PER_LONG
+ @item HOST_BITS_PER_LONG
+ A C expression for the number of bits in @code{long} on the host
+ machine.
+ 
+ @findex HOST_BITS_PER_LONGLONG
+ @item HOST_BITS_PER_LONGLONG
+ A C expression for the number of bits in @code{long long} on the host
+ machine.
+ 
+ @findex ONLY_INT_FIELDS
+ @item ONLY_INT_FIELDS
+ Define this macro to indicate that the host compiler only supports
+ @code{int} bit-fields, rather than other integral types, including
+ @code{enum}, as do most C compilers.
+ 
+ @findex OBSTACK_CHUNK_SIZE
+ @item OBSTACK_CHUNK_SIZE
+ A C expression for the size of ordinary obstack chunks.
+ If you don't define this, a usually-reasonable default is used.
+ 
+ @findex OBSTACK_CHUNK_ALLOC
+ @item OBSTACK_CHUNK_ALLOC
+ The function used to allocate obstack chunks.
+ If you don't define this, @code{xmalloc} is used.
+ 
+ @findex OBSTACK_CHUNK_FREE
+ @item OBSTACK_CHUNK_FREE
+ The function used to free obstack chunks.
+ If you don't define this, @code{free} is used.
+ 
+ @findex USE_C_ALLOCA
+ @item USE_C_ALLOCA
+ Define this macro to indicate that the compiler is running with the
+ @code{alloca} implemented in C@.  This version of @code{alloca} can be
+ found in the file @file{alloca.c}; to use it, you must also alter the
+ @file{Makefile} variable @code{ALLOCA}.  (This is done automatically
+ for the systems on which we know it is needed.)
+ 
+ If you do define this macro, you should probably do it as follows:
+ 
+ @example
+ #ifndef __GNUC__
+ #define USE_C_ALLOCA
+ #else
+ #define alloca __builtin_alloca
+ #endif
+ @end example
+ 
+ @noindent
+ so that when the compiler is compiled with GCC it uses the more
+ efficient built-in @code{alloca} function.
+ 
+ @item FUNCTION_CONVERSION_BUG
+ @findex FUNCTION_CONVERSION_BUG
+ Define this macro to indicate that the host compiler does not properly
+ handle converting a function value to a pointer-to-function when it is
+ used in an expression.
+ 
+ @findex MULTIBYTE_CHARS
+ @item MULTIBYTE_CHARS
+ Define this macro to enable support for multibyte characters in the
+ input to GCC@.  This requires that the host system support the ISO C
+ library functions for converting multibyte characters to wide
+ characters.
+ 
+ @findex POSIX
+ @item POSIX
+ Define this if your system is POSIX.1 compliant.
+ 
+ @findex PATH_SEPARATOR
+ @item PATH_SEPARATOR
+ Define this macro to be a C character constant representing the
+ character used to separate components in paths.  The default value is
+ the colon character
+ 
+ @findex DIR_SEPARATOR
+ @item DIR_SEPARATOR
+ If your system uses some character other than slash to separate
+ directory names within a file specification, define this macro to be a C
+ character constant specifying that character.  When GCC displays file
+ names, the character you specify will be used.  GCC will test for
+ both slash and the character you specify when parsing filenames.
+ 
+ @findex DIR_SEPARATOR_2
+ @item DIR_SEPARATOR_2
+ If your system uses an alternative character other than
+ @samp{DIR_SEPARATOR} to separate directory names within a file
+ specification, define this macro to be a C character constant specifying
+ that character.  If you define this macro, GCC will test for slash,
+ @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
+ 
+ @findex TARGET_OBJECT_SUFFIX
+ @item TARGET_OBJECT_SUFFIX
+ Define this macro to be a C string representing the suffix for object
+ files on your target machine.  If you do not define this macro, GCC will
+ use @samp{.o} as the suffix for object files.
+ 
+ @findex TARGET_EXECUTABLE_SUFFIX
+ @item TARGET_EXECUTABLE_SUFFIX
+ Define this macro to be a C string representing the suffix to be
+ automatically added to executable files on your target machine.  If you
+ do not define this macro, GCC will use the null string as the suffix for
+ executable files.
+ 
+ @findex HOST_OBJECT_SUFFIX
+ @item HOST_OBJECT_SUFFIX
+ Define this macro to be a C string representing the suffix for object
+ files on your host machine (@samp{xm-*.h}).  If you do not define this
+ macro, GCC will use @samp{.o} as the suffix for object files.
+ 
+ @findex HOST_EXECUTABLE_SUFFIX
+ @item HOST_EXECUTABLE_SUFFIX
+ Define this macro to be a C string representing the suffix for
+ executable files on your host machine (@samp{xm-*.h}).  If you do not
+ define this macro, GCC will use the null string as the suffix for
+ executable files.
+ 
+ @findex HOST_BIT_BUCKET
+ @item HOST_BIT_BUCKET
+ The name of a file or file-like object on the host system which acts as
+ a ``bit bucket''.  If you do not define this macro, GCC will use
+ @samp{/dev/null} as the bit bucket.  If the target does not support a
+ bit bucket, this should be defined to the null string, or some other
+ invalid filename.  If the bit bucket is not writable, GCC will use a
+ temporary file instead.
+ 
+ @findex COLLECT_EXPORT_LIST
+ @item COLLECT_EXPORT_LIST
+ If defined, @code{collect2} will scan the individual object files
+ specified on its command line and create an export list for the linker.
+ Define this macro for systems like AIX, where the linker discards
+ object files that are not referenced from @code{main} and uses export
+ lists.
+ 
+ @findex COLLECT2_HOST_INITIALIZATION
+ @item COLLECT2_HOST_INITIALIZATION
+ If defined, a C statement (sans semicolon) that performs host-dependent
+ initialization when @code{collect2} is being initialized.
+ 
+ @findex GCC_DRIVER_HOST_INITIALIZATION
+ @item GCC_DRIVER_HOST_INITIALIZATION
+ If defined, a C statement (sans semicolon) that performs host-dependent
+ initialization when a compilation driver is being initialized.
+ 
+ @findex UPDATE_PATH_HOST_CANONICALIZE
+ @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
+ If defined, a C statement (sans semicolon) that performs host-dependent
+ canonicalization when a path used in a compilation driver or
+ preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
+ canonicalized.  If the C statement does canonicalize @var{path} into a
+ different buffer, the old path should be freed and the new buffer should
+ have been allocated with malloc.
+ @end table
+ 
+ @findex bzero
+ @findex bcmp
+ In addition, configuration files for system V define @code{bcopy},
+ @code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
+ as a macro when compiled with GCC, in order to take advantage of the
+ benefit of GCC's built-in @code{alloca}.
diff -rcN gcc.orig/doc/include/linux-and-gnu.texi gcc/doc/include/linux-and-gnu.texi
*** gcc.orig/doc/include/linux-and-gnu.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/include/linux-and-gnu.texi	Sun Nov 11 19:20:17 2001
***************
*** 0 ****
--- 1,102 ----
+ @c Copyright (C) 1997, 1998 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node GNU/Linux
+ @unnumbered Linux and the GNU Project
+ 
+ Many computer users run a modified version of the GNU system every
+ day, without realizing it.  Through a peculiar turn of events, the
+ version of GNU which is widely used today is more often known as
+ ``Linux'', and many users are not aware of the extent of its
+ connection with the GNU Project.
+ 
+ There really is a Linux; it is a kernel, and these people are using
+ it.  But you can't use a kernel by itself; a kernel is useful only as
+ part of a whole system.  The system in which Linux is typically used
+ is a modified variant of the GNU system---in other words, a Linux-based
+ GNU system.
+ 
+ Many users are not fully aware of the distinction between the kernel,
+ which is Linux, and the whole system, which they also call ``Linux''.
+ The ambiguous use of the name doesn't promote understanding.
+ 
+ Programmers generally know that Linux is a kernel.  But since they
+ have generally heard the whole system called ``Linux'' as well, they
+ often envisage a history which fits that name.  For example, many
+ believe that once Linus Torvalds finished writing the kernel, his
+ friends looked around for other free software, and for no particular
+ reason most everything necessary to make a Unix-like system was
+ already available.
+ 
+ What they found was no accident---it was the GNU system.  The available
+ free software added up to a complete system because the GNU Project
+ had been working since 1984 to make one.  The GNU Manifesto
+ had set forth the goal of developing a free Unix-like system, called
+ GNU@.  By the time Linux was written, the system was almost finished.
+ 
+ Most free software projects have the goal of developing a particular
+ program for a particular job.  For example, Linus Torvalds set out to
+ write a Unix-like kernel (Linux); Donald Knuth set out to write a text
+ formatter (TeX); Bob Scheifler set out to develop a window system (X
+ Windows).  It's natural to measure the contribution of this kind of
+ project by specific programs that came from the project.
+ 
+ If we tried to measure the GNU Project's contribution in this way,
+ what would we conclude?  One CD-ROM vendor found that in their ``Linux
+ distribution'', GNU software was the largest single contingent, around
+ 28% of the total source code, and this included some of the essential
+ major components without which there could be no system.  Linux itself
+ was about 3%.  So if you were going to pick a name for the system
+ based on who wrote the programs in the system, the most appropriate
+ single choice would be ``GNU''@.
+ 
+ But we don't think that is the right way to consider the question.
+ The GNU Project was not, is not, a project to develop specific
+ software packages.  It was not a project to develop a C compiler,
+ although we did.  It was not a project to develop a text editor,
+ although we developed one.  The GNU Project's aim was to develop
+ @emph{a complete free Unix-like system}.
+ 
+ Many people have made major contributions to the free software in the
+ system, and they all deserve credit.  But the reason it is @emph{a
+ system}---and not just a collection of useful programs---is because the
+ GNU Project set out to make it one.  We wrote the programs that were
+ needed to make a @emph{complete} free system.  We wrote essential but
+ unexciting major components, such as the assembler and linker, because
+ you can't have a system without them.  A complete system needs more
+ than just programming tools, so we wrote other components as well,
+ such as the Bourne Again SHell, the PostScript interpreter
+ Ghostscript, and the GNU C library.
+ 
+ By the early 90s we had put together the whole system aside from the
+ kernel (and we were also working on a kernel, the GNU Hurd, which runs
+ on top of Mach).  Developing this kernel has been a lot harder than we
+ expected, and we are still working on finishing it.
+ 
+ Fortunately, you don't have to wait for it, because Linux is working
+ now.  When Linus Torvalds wrote Linux, he filled the last major gap.
+ People could then put Linux together with the GNU system to make a
+ complete free system: a Linux-based GNU system (or GNU/Linux system,
+ for short).
+ 
+ Putting them together sounds simple, but it was not a trivial job.
+ The GNU C library (called glibc for short) needed substantial changes.
+ Integrating a complete system as a distribution that would work ``out
+ of the box'' was a big job, too.  It required addressing the issue of
+ how to install and boot the system---a problem we had not tackled,
+ because we hadn't yet reached that point.  The people who developed
+ the various system distributions made a substantial contribution.
+ 
+ The GNU Project supports GNU/Linux systems as well as @emph{the}
+ GNU system---even with funds.  We funded the rewriting of the
+ Linux-related extensions to the GNU C library, so that now they are
+ well integrated, and the newest GNU/Linux systems use the current
+ library release with no changes.  We also funded an early stage of the
+ development of Debian GNU/Linux.
+ 
+ We use Linux-based GNU systems today for most of our work, and we hope
+ you use them too.  But please don't confuse the public by using the
+ name ``Linux'' ambiguously.  Linux is the kernel, one of the essential
+ major components of the system.  The system as a whole is more or less
+ the GNU system.
diff -rcN gcc.orig/doc/interface.texi gcc/doc/interface.texi
*** gcc.orig/doc/interface.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/interface.texi	Sun Nov 11 19:09:59 2001
***************
*** 0 ****
--- 1,102 ----
+ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+ @c 1999, 2000, 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Interface
+ @chapter Interfacing to GCC Output
+ @cindex interfacing to GCC output
+ @cindex run-time conventions
+ @cindex function call conventions
+ @cindex conventions, run-time
+ 
+ GCC is normally configured to use the same function calling convention
+ normally in use on the target system.  This is done with the
+ machine-description macros described (@pxref{Target Macros}).
+ 
+ @cindex unions, returning
+ @cindex structures, returning
+ @cindex returning structures and unions
+ However, returning of structure and union values is done differently on
+ some target machines.  As a result, functions compiled with PCC
+ returning such types cannot be called from code compiled with GCC,
+ and vice versa.  This does not cause trouble often because few Unix
+ library routines return structures or unions.
+ 
+ GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
+ long in the same registers used for @code{int} or @code{double} return
+ values.  (GCC typically allocates variables of such types in
+ registers also.)  Structures and unions of other sizes are returned by
+ storing them into an address passed by the caller (usually in a
+ register).  The machine-description macros @code{STRUCT_VALUE} and
+ @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
+ 
+ By contrast, PCC on most target machines returns structures and unions
+ of any size by copying the data into an area of static storage, and then
+ returning the address of that storage as if it were a pointer value.
+ The caller must copy the data from that memory area to the place where
+ the value is wanted.  This is slower than the method used by GCC, and
+ fails to be reentrant.
+ 
+ On some target machines, such as RISC machines and the 80386, the
+ standard system convention is to pass to the subroutine the address of
+ where to return the value.  On these machines, GCC has been
+ configured to be compatible with the standard compiler, when this method
+ is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
+ 
+ @cindex argument passing
+ @cindex passing arguments
+ GCC uses the system's standard convention for passing arguments.  On
+ some machines, the first few arguments are passed in registers; in
+ others, all are passed on the stack.  It would be possible to use
+ registers for argument passing on any machine, and this would probably
+ result in a significant speedup.  But the result would be complete
+ incompatibility with code that follows the standard convention.  So this
+ change is practical only if you are switching to GCC as the sole C
+ compiler for the system.  We may implement register argument passing on
+ certain machines once we have a complete GNU system so that we can
+ compile the libraries with GCC@.
+ 
+ On some machines (particularly the Sparc), certain types of arguments
+ are passed ``by invisible reference''.  This means that the value is
+ stored in memory, and the address of the memory location is passed to
+ the subroutine.
+ 
+ @cindex @code{longjmp} and automatic variables
+ If you use @code{longjmp}, beware of automatic variables.  ISO C says that
+ automatic variables that are not declared @code{volatile} have undefined
+ values after a @code{longjmp}.  And this is all GCC promises to do,
+ because it is very difficult to restore register variables correctly, and
+ one of GCC's features is that it can put variables in registers without
+ your asking it to.
+ 
+ If you want a variable to be unaltered by @code{longjmp}, and you don't
+ want to write @code{volatile} because old C compilers don't accept it,
+ just take the address of the variable.  If a variable's address is ever
+ taken, even if just to compute it and ignore it, then the variable cannot
+ go in a register:
+ 
+ @example
+ @{
+   int careful;
+   &careful;
+   @dots{}
+ @}
+ @end example
+ 
+ @cindex arithmetic libraries
+ @cindex math libraries
+ @opindex msoft-float
+ Code compiled with GCC may call certain library routines.  Most of
+ them handle arithmetic for which there are no instructions.  This
+ includes multiply and divide on some machines, and floating point
+ operations on any machine for which floating point support is disabled
+ with @option{-msoft-float}.  Some standard parts of the C library, such as
+ @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
+ function call interface is used for calling the library routines.
+ 
+ Some of these routines can be defined in mostly machine-independent C;
+ they appear in @file{libgcc2.c}.  Others must be hand-written in
+ assembly language for each processor.  Wherever they are defined, they
+ are compiled into the support library, @file{libgcc.a}, which is
+ automatically searched when you link programs with GCC@.
diff -rcN gcc.orig/doc/makefile.texi gcc/doc/makefile.texi
*** gcc.orig/doc/makefile.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/makefile.texi	Sun Nov 11 19:03:24 2001
***************
*** 0 ****
--- 1,104 ----
+ @c Copyright (C) 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Makefile
+ @chapter Additional Makefile and configure information.
+ 
+ @section Makefile Targets
+ @cindex makefile targets
+ @cindex targets, makefile
+ 
+ @table @code
+ @item all
+ This is the default target.  Depending on what your build/host/target
+ configuration is, it coordinates all the things that need to be built.
+ 
+ @item doc
+ Produce info-formatted documentation.  Also, @code{make dvi} is
+ available for DVI-formatted documentation, and @code{make
+ generated-manpages} to generate man pages.
+ 
+ @item mostlyclean
+ Delete the files made while building the compiler.
+ 
+ @item clean
+ That, and all the other files built by @code{make all}.
+ 
+ @item distclean
+ That, and all the files created by @code{configure}.
+ 
+ @item extraclean
+ That, and any temporary or intermediate files, like emacs backup files.
+ 
+ @item maintainer-clean
+ Distclean plus any file that can be generated from other files.  Note
+ that additional tools may be required beyond what is normally needed to
+ build gcc.
+ 
+ @item install
+ Installs gcc.
+ 
+ @item uninstall
+ Deletes installed files.
+ 
+ @item check
+ Run the testsuite.  This creates a @file{testsuite} subdirectory that
+ has various @file{.sum} and @file{.log} files containing the results of
+ the testing.  You can run subsets with, for example, @code{make check-gcc}.
+ You can specify specific tests by setting RUNTESTFLAGS to be the name
+ of the @file{.exp} file, optionally followed by (for some tests) an equals
+ and a file wildcard, like:
+ 
+ @example
+ make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
+ @end example
+ 
+ Note that running the testsuite may require additional tools be
+ installed, such as TCL or dejagnu.
+ 
+ @item bootstrap
+ Builds gcc three times---once with the native compiler, once with the
+ native-built compiler it just built, and once with the compiler it built
+ the second time.  In theory, the last two should produce the same
+ results, which @code{make compare} can check.  Each step of this process
+ is called a ``stage'', and the results of each stage @var{N}
+ (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
+ 
+ @item bootstrap-lean
+ Like @code{bootstrap}, except that the various stages are removed once
+ they're no longer needed.  This saves disk space.
+ 
+ @item bubblestrap
+ Once bootstrapped, this incrementally rebuilds each of the three stages,
+ one at a time.  It does this by ``bubbling'' the stages up from their
+ subdirectories, rebuilding them, and copying them back to their
+ subdirectories.  This will allow you to, for example, quickly rebuild a
+ bootstrapped compiler after changing the sources, without having to do a
+ full bootstrap.
+ 
+ @item quickstrap
+ Rebuilds the most recently built stage.  Since each stage requires
+ special invocation, using this target means you don't have to keep track
+ of which stage you're on or what invocation that stage needs.
+ 
+ @item cleanstrap
+ Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
+ 
+ @item stage@var{N} (@var{N} = 1@dots{}4)
+ For each stage, moves the appropriate files to the @file{stage@var{N}}
+ subdirectory.
+ 
+ @item unstage@var{N} (@var{N} = 1@dots{}4)
+ Undoes the corresponding @code{stage@var{N}}.
+ 
+ @item restage@var{N} (@var{N} = 1@dots{}4)
+ Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
+ appropriate flags.
+ 
+ @item compare
+ Compares the results of stages 2 and 3.  This ensures that the compiler
+ is running properly, since it should produce the same object files
+ regardless of how it itself was compiled.
+ 
+ @end table
diff -rcN gcc.orig/doc/passes.texi gcc/doc/passes.texi
*** gcc.orig/doc/passes.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/passes.texi	Sun Nov 11 19:10:47 2001
***************
*** 0 ****
--- 1,663 ----
+ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+ @c 1999, 2000, 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Passes
+ @chapter Passes and Files of the Compiler
+ @cindex passes and files of the compiler
+ @cindex files and passes of the compiler
+ @cindex compiler passes and files
+ 
+ @cindex top level of compiler
+ The overall control structure of the compiler is in @file{toplev.c}.  This
+ file is responsible for initialization, decoding arguments, opening and
+ closing files, and sequencing the passes.
+ 
+ @cindex parsing pass
+ The parsing pass is invoked only once, to parse the entire input.  A
+ high level tree representation is then generated from the input,
+ one function at a time.  This tree code is then transformed into RTL
+ intermediate code, and processed.  The files involved in transforming
+ the trees into RTL are @file{expr.c}, @file{expmed.c}, and
+ @file{stmt.c}.
+ @c Note, the above files aren't strictly the only files involved. It's
+ @c all over the place (function.c, final.c,etc).  However, those are
+ @c the files that are supposed to be directly involved, and have
+ @c their purpose listed as such, so i've only listed them.
+ The order of trees that are processed, is not
+ necessarily the same order they are generated from
+ the input, due to deferred inlining, and other considerations.
+ 
+ @findex rest_of_compilation
+ @findex rest_of_decl_compilation
+ Each time the parsing pass reads a complete function definition or
+ top-level declaration, it calls either the function
+ @code{rest_of_compilation}, or the function
+ @code{rest_of_decl_compilation} in @file{toplev.c}, which are
+ responsible for all further processing necessary, ending with output of
+ the assembler language.  All other compiler passes run, in sequence,
+ within @code{rest_of_compilation}.  When that function returns from
+ compiling a function definition, the storage used for that function
+ definition's compilation is entirely freed, unless it is an inline
+ function, or was deferred for some reason (this can occur in
+ templates, for example).
+ @ifset USING
+ (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
+ @end ifset
+ @ifclear USING
+ (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
+ @end ifclear
+ 
+ Here is a list of all the passes of the compiler and their source files.
+ Also included is a description of where debugging dumps can be requested
+ with @option{-d} options.
+ 
+ @itemize @bullet
+ @item
+ Parsing.  This pass reads the entire text of a function definition,
+ constructing a high level tree representation.  (Because of the semantic
+ analysis that takes place during this pass, it does more than is
+ formally considered to be parsing.)
+ 
+ The tree representation does not entirely follow C syntax, because it is
+ intended to support other languages as well.
+ 
+ Language-specific data type analysis is also done in this pass, and every
+ tree node that represents an expression has a data type attached.
+ Variables are represented as declaration nodes.
+ 
+ The language-independent source files for parsing are
+ @file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
+ There are also header files @file{tree.h} and @file{tree.def}
+ which define the format of the tree representation.
+ 
+ C preprocessing, for language front ends, that want or require it, is
+ performed by cpplib, which is covered in separate documentation.  In
+ particular, the internals are covered in @xref{Top, ,Cpplib internals,
+ cppinternals, Cpplib Internals}.
+ 
+ @c Avoiding overfull is tricky here.
+ The source files to parse C are
+ @file{c-convert.c},
+ @file{c-decl.c},
+ @file{c-errors.c},
+ @file{c-lang.c},
+ @file{c-parse.in},
+ @file{c-aux-info.c},
+ and
+ @file{c-typeck.c},
+ along with a header file
+ @file{c-tree.h}
+ and some files shared with Objective-C and C++.
+ 
+ The source files for parsing C++ are in @file{cp/}.
+ They are @file{parse.y},
+ @file{class.c},
+ @file{cvt.c}, @file{decl.c}, @file{decl2.c},
+ @file{except.c},
+ @file{expr.c}, @file{init.c}, @file{lex.c},
+ @file{method.c}, @file{ptree.c},
+ @file{search.c}, @file{spew.c},
+ @file{semantics.c}, @file{tree.c},
+ @file{typeck2.c}, and
+ @file{typeck.c}, along with header files @file{cp-tree.def},
+ @file{cp-tree.h}, and @file{decl.h}.
+ 
+ The special source files for parsing Objective-C are in @file{objc/}.
+ They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
+ Certain C-specific files are used for this as well.
+ 
+ The files
+ @file{c-common.c},
+ @file{c-common.def},
+ @file{c-dump.c},
+ @file{c-format.c},
+ @file{c-pragma.c},
+ @file{c-semantics.c},
+ and
+ @file{c-lex.c},
+ along with header files
+ @file{c-common.h},
+ @file{c-dump.h},
+ @file{c-lex.h},
+ and
+ @file{c-pragma.h},
+ are also used for all of the above languages.
+ 
+ 
+ @cindex Tree optimization
+ @item
+ Tree optimization.   This is the optimization of the tree
+ representation, before converting into RTL code.
+ 
+ @cindex inline on trees, automatic
+ Currently, the main optimization performed here is tree-based
+ inlining.
+ This is implemented for C++ in @file{cp/optimize.c}.  Note that
+ tree based inlining turns off rtx based inlining (since it's more
+ powerful, it would be a waste of time to do rtx based inlining in
+ addition).
+ The C front end currently does not perform tree based inlining.
+ 
+ @cindex constant folding
+ @cindex arithmetic simplifications
+ @cindex simplifications, arithmetic
+ Constant folding and some arithmetic simplifications are also done
+ during this pass, on the tree representation.
+ The routines that perform these tasks are located in @file{fold-const.c}.
+ 
+ @cindex RTL generation
+ @item
+ RTL generation.  This is the conversion of syntax tree into RTL code.
+ 
+ @cindex target-parameter-dependent code
+ This is where the bulk of target-parameter-dependent code is found,
+ since often it is necessary for strategies to apply only when certain
+ standard kinds of instructions are available.  The purpose of named
+ instruction patterns is to provide this information to the RTL
+ generation pass.
+ 
+ @cindex tail recursion optimization
+ Optimization is done in this pass for @code{if}-conditions that are
+ comparisons, boolean operations or conditional expressions.  Tail
+ recursion is detected at this time also.  Decisions are made about how
+ best to arrange loops and how to output @code{switch} statements.
+ 
+ @c Avoiding overfull is tricky here.
+ The source files for RTL generation include
+ @file{stmt.c},
+ @file{calls.c},
+ @file{expr.c},
+ @file{explow.c},
+ @file{expmed.c},
+ @file{function.c},
+ @file{optabs.c}
+ and @file{emit-rtl.c}.
+ Also, the file
+ @file{insn-emit.c}, generated from the machine description by the
+ program @code{genemit}, is used in this pass.  The header file
+ @file{expr.h} is used for communication within this pass.
+ 
+ @findex genflags
+ @findex gencodes
+ The header files @file{insn-flags.h} and @file{insn-codes.h},
+ generated from the machine description by the programs @code{genflags}
+ and @code{gencodes}, tell this pass which standard names are available
+ for use and which patterns correspond to them.
+ 
+ Aside from debugging information output, none of the following passes
+ refers to the tree structure representation of the function (only
+ part of which is saved).
+ 
+ @cindex inline on rtx, automatic
+ The decision of whether the function can and should be expanded inline
+ in its subsequent callers is made at the end of rtl generation.  The
+ function must meet certain criteria, currently related to the size of
+ the function and the types and number of parameters it has.  Note that
+ this function may contain loops, recursive calls to itself
+ (tail-recursive functions can be inlined!), gotos, in short, all
+ constructs supported by GCC@.  The file @file{integrate.c} contains
+ the code to save a function's rtl for later inlining and to inline that
+ rtl when the function is called.  The header file @file{integrate.h}
+ is also used for this purpose.
+ 
+ @opindex dr
+ The option @option{-dr} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.rtl} to
+ the input file name.
+ 
+ @c Should the exception handling pass be talked about here?
+ 
+ @cindex sibling call optimization
+ @item
+ Sibiling call optimization.   This pass performs tail recursion
+ elimination, and tail and sibling call optimizations.  The purpose of
+ these optimizations is to reduce the overhead of function calls,
+ whenever possible.
+ 
+ The source file of this pass is @file{sibcall.c}
+ 
+ @opindex di
+ The option @option{-di} causes a debugging dump of the RTL code after
+ this pass is run.  This dump file's name is made by appending
+ @samp{.sibling} to the input file name.
+ 
+ @cindex jump optimization
+ @cindex unreachable code
+ @cindex dead code
+ @item
+ Jump optimization.  This pass simplifies jumps to the following
+ instruction, jumps across jumps, and jumps to jumps.  It deletes
+ unreferenced labels and unreachable code, except that unreachable code
+ that contains a loop is not recognized as unreachable in this pass.
+ (Such loops are deleted later in the basic block analysis.)  It also
+ converts some code originally written with jumps into sequences of
+ instructions that directly set values from the results of comparisons,
+ if the machine has such instructions.
+ 
+ Jump optimization is performed two or three times.  The first time is
+ immediately following RTL generation.  The second time is after CSE,
+ but only if CSE says repeated jump optimization is needed.  The
+ last time is right before the final pass.  That time, cross-jumping
+ and deletion of no-op move instructions are done together with the
+ optimizations described above.
+ 
+ The source file of this pass is @file{jump.c}.
+ 
+ @opindex dj
+ The option @option{-dj} causes a debugging dump of the RTL code after
+ this pass is run for the first time.  This dump file's name is made by
+ appending @samp{.jump} to the input file name.
+ 
+ 
+ @cindex register use analysis
+ @item
+ Register scan.  This pass finds the first and last use of each
+ register, as a guide for common subexpression elimination.  Its source
+ is in @file{regclass.c}.
+ 
+ @cindex jump threading
+ @item
+ @opindex fthread-jumps
+ Jump threading.  This pass detects a condition jump that branches to an
+ identical or inverse test.  Such jumps can be @samp{threaded} through
+ the second conditional test.  The source code for this pass is in
+ @file{jump.c}.  This optimization is only performed if
+ @option{-fthread-jumps} is enabled.
+ 
+ @cindex SSA optimizations
+ @cindex Single Static Assignment optimizations
+ @opindex fssa
+ @item
+ Static Single Assignment (SSA) based optimization passes.  The
+ SSA conversion passes (to/from) are turned on by the @option{-fssa}
+ option (it is also done automatically if you enable an SSA optimization pass).
+ These passes utilize a form called Static Single Assignment.  In SSA form,
+ each variable (pseudo register) is only set once, giving you def-use
+ and use-def chains for free, and enabling a lot more optimization
+ passes to be run in linear time.
+ Conversion to and from SSA form is handled by functions in
+ @file{ssa.c}.
+ 
+ @opindex de
+ The option @option{-de} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.ssa} to
+ the input file name.
+ @itemize @bullet
+ @cindex SSA Conditional Constant Propagation
+ @cindex Conditional Constant Propagation, SSA based
+ @cindex conditional constant propagation
+ @opindex fssa-ccp
+ @item
+ SSA Conditional Constant Propagation.  Turned on by the @option{-fssa-ccp}
+ SSA Aggressive Dead Code Elimination.  Turned on by the @option{-fssa-dce}
+ option.  This pass performs conditional constant propagation to simplify
+ instructions including conditional branches.  This pass is more aggressive
+ than the constant propgation done by the CSE and GCSE pases, but operates
+ in linear time.
+ 
+ @opindex dW
+ The option @option{-dW} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.ssaccp} to
+ the input file name.
+ 
+ @cindex SSA DCE
+ @cindex DCE, SSA based
+ @cindex dead code elimination
+ @opindex fssa-dce
+ @item
+ SSA Aggressive Dead Code Elimination.  Turned on by the @option{-fssa-dce}
+ option.  This pass performs elimination of code considered unnecessary because
+ it has no externally visible effects on the program.  It operates in
+ linear time.
+ 
+ @opindex dX
+ The option @option{-dX} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.ssadce} to
+ the input file name.
+ @end itemize
+ 
+ @cindex common subexpression elimination
+ @cindex constant propagation
+ @item
+ Common subexpression elimination.  This pass also does constant
+ propagation.  Its source files are @file{cse.c}, and @file{cselib.c}.
+ If constant  propagation causes conditional jumps to become
+ unconditional or to become no-ops, jump optimization is run again when
+ CSE is finished.
+ 
+ @opindex ds
+ The option @option{-ds} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.cse} to
+ the input file name.
+ 
+ @cindex global common subexpression elimination
+ @cindex constant propagation
+ @cindex copy propagation
+ @item
+ Global common subexpression elimination.  This pass performs two
+ different types of GCSE  depending on whether you are optimizing for
+ size or not (LCM based GCSE tends to increase code size for a gain in
+ speed, while Morel-Renvoise based GCSE does not).
+ When optimizing for size, GCSE is done using Morel-Renvoise Partial
+ Redundancy Elimination, with the exception that it does not try to move
+ invariants out of loops---that is left to  the loop optimization pass.
+ If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
+ well as load motion.
+ If you are optimizing for speed, LCM (lazy code motion) based GCSE is
+ done.  LCM is based on the work of Knoop, Ruthing, and Steffen.  LCM
+ based GCSE also does loop invariant code motion.  We also perform load
+ and store motion when optimizing for speed.
+ Regardless of which type of GCSE is used, the GCSE pass also performs
+ global constant and  copy propagation.
+ 
+ The source file for this pass is @file{gcse.c}, and the LCM routines
+ are in @file{lcm.c}.
+ 
+ @opindex dG
+ The option @option{-dG} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.gcse} to
+ the input file name.
+ 
+ @cindex loop optimization
+ @cindex code motion
+ @cindex strength-reduction
+ @item
+ Loop optimization.  This pass moves constant expressions out of loops,
+ and optionally does strength-reduction and loop unrolling as well.
+ Its source files are @file{loop.c} and @file{unroll.c}, plus the header
+ @file{loop.h} used for communication between them.  Loop unrolling uses
+ some functions in @file{integrate.c} and the header @file{integrate.h}.
+ Loop dependency analysis routines are contained in @file{dependence.c}.
+ 
+ @opindex dL
+ The option @option{-dL} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.loop} to
+ the input file name.
+ 
+ @item
+ @opindex frerun-cse-after-loop
+ If @option{-frerun-cse-after-loop} was enabled, a second common
+ subexpression elimination pass is performed after the loop optimization
+ pass.  Jump threading is also done again at this time if it was specified.
+ 
+ @opindex dt
+ The option @option{-dt} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.cse2} to
+ the input file name.
+ 
+ @cindex data flow analysis
+ @cindex analysis, data flow
+ @cindex basic blocks
+ @item
+ Data flow analysis (@file{flow.c}).  This pass divides the program
+ into basic blocks (and in the process deletes unreachable loops); then
+ it computes which pseudo-registers are live at each point in the
+ program, and makes the first instruction that uses a value point at
+ the instruction that computed the value.
+ 
+ @cindex autoincrement/decrement analysis
+ This pass also deletes computations whose results are never used, and
+ combines memory references with add or subtract instructions to make
+ autoincrement or autodecrement addressing.
+ 
+ @opindex df
+ The option @option{-df} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.flow} to
+ the input file name.  If stupid register allocation is in use, this
+ dump file reflects the full results of such allocation.
+ 
+ @cindex instruction combination
+ @item
+ Instruction combination (@file{combine.c}).  This pass attempts to
+ combine groups of two or three instructions that are related by data
+ flow into single instructions.  It combines the RTL expressions for
+ the instructions by substitution, simplifies the result using algebra,
+ and then attempts to match the result against the machine description.
+ 
+ @opindex dc
+ The option @option{-dc} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.combine}
+ to the input file name.
+ 
+ @cindex if conversion
+ @item
+ If-conversion is a transformation that transforms control dependencies
+ into data dependencies (IE it transforms conditional code into a
+ single control stream).
+ It is implemented in the file @file{ifcvt.c}.
+ 
+ @opindex dE
+ The option @option{-dE} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.ce} to
+ the input file name.
+ 
+ @cindex register movement
+ @item
+ Register movement (@file{regmove.c}).  This pass looks for cases where
+ matching constraints would force an instruction to need a reload, and
+ this reload would be a register to register move.  It then attempts
+ to change the registers used by the instruction to avoid the move
+ instruction.
+ 
+ @opindex dN
+ The option @option{-dN} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.regmove}
+ to the input file name.
+ 
+ @cindex instruction scheduling
+ @cindex scheduling, instruction
+ @item
+ Instruction scheduling (@file{sched.c}).  This pass looks for
+ instructions whose output will not be available by the time that it is
+ used in subsequent instructions.  (Memory loads and floating point
+ instructions often have this behavior on RISC machines).  It re-orders
+ instructions within a basic block to try to separate the definition and
+ use of items that otherwise would cause pipeline stalls.
+ 
+ Instruction scheduling is performed twice.  The first time is immediately
+ after instruction combination and the second is immediately after reload.
+ 
+ @opindex dS
+ The option @option{-dS} causes a debugging dump of the RTL code after this
+ pass is run for the first time.  The dump file's name is made by
+ appending @samp{.sched} to the input file name.
+ 
+ @cindex register class preference pass
+ @item
+ Register class preferencing.  The RTL code is scanned to find out
+ which register class is best for each pseudo register.  The source
+ file is @file{regclass.c}.
+ 
+ @cindex register allocation
+ @cindex local register allocation
+ @item
+ Local register allocation (@file{local-alloc.c}).  This pass allocates
+ hard registers to pseudo registers that are used only within one basic
+ block.  Because the basic block is linear, it can use fast and
+ powerful techniques to do a very good job.
+ 
+ @opindex dl
+ The option @option{-dl} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.lreg} to
+ the input file name.
+ 
+ @cindex global register allocation
+ @item
+ Global register allocation (@file{global.c}).  This pass
+ allocates hard registers for the remaining pseudo registers (those
+ whose life spans are not contained in one basic block).
+ 
+ @cindex reloading
+ @item
+ Reloading.  This pass renumbers pseudo registers with the hardware
+ registers numbers they were allocated.  Pseudo registers that did not
+ get hard registers are replaced with stack slots.  Then it finds
+ instructions that are invalid because a value has failed to end up in
+ a register, or has ended up in a register of the wrong kind.  It fixes
+ up these instructions by reloading the problematical values
+ temporarily into registers.  Additional instructions are generated to
+ do the copying.
+ 
+ The reload pass also optionally eliminates the frame pointer and inserts
+ instructions to save and restore call-clobbered registers around calls.
+ 
+ Source files are @file{reload.c} and @file{reload1.c}, plus the header
+ @file{reload.h} used for communication between them.
+ 
+ @opindex dg
+ The option @option{-dg} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.greg} to
+ the input file name.
+ 
+ @cindex instruction scheduling
+ @cindex scheduling, instruction
+ @item
+ Instruction scheduling is repeated here to try to avoid pipeline stalls
+ due to memory loads generated for spilled pseudo registers.
+ 
+ @opindex dR
+ The option @option{-dR} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.sched2}
+ to the input file name.
+ 
+ @cindex basic block reordering
+ @cindex reordering, block
+ @item
+ Basic block reordering.  This pass implements profile guided code
+ positioning.  If profile information is not available, various types of
+ static analysis are performed to make the predictions normally coming
+ from the profile feedback (IE execution frequency, branch probability,
+ etc).  It is implemented in the file @file{bb-reorder.c}, and the
+ various prediction routines are in @file{predict.c}.
+ 
+ @opindex dB
+ The option @option{-dB} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.bbro} to
+ the input file name.
+ 
+ @cindex cross-jumping
+ @cindex no-op move instructions
+ @item
+ Jump optimization is repeated, this time including cross-jumping
+ and deletion of no-op move instructions.
+ 
+ @opindex dJ
+ The option @option{-dJ} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.jump2}
+ to the input file name.
+ 
+ @cindex delayed branch scheduling
+ @cindex scheduling, delayed branch
+ @item
+ Delayed branch scheduling.  This optional pass attempts to find
+ instructions that can go into the delay slots of other instructions,
+ usually jumps and calls.  The source file name is @file{reorg.c}.
+ 
+ @opindex dd
+ The option @option{-dd} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.dbr}
+ to the input file name.
+ 
+ @cindex branch shortening
+ @item
+ Branch shortening.  On many RISC machines, branch instructions have a
+ limited range.  Thus, longer sequences of instructions must be used for
+ long branches.  In this pass, the compiler figures out what how far each
+ instruction will be from each other instruction, and therefore whether
+ the usual instructions, or the longer sequences, must be used for each
+ branch.
+ 
+ @cindex register-to-stack conversion
+ @item
+ Conversion from usage of some hard registers to usage of a register
+ stack may be done at this point.  Currently, this is supported only
+ for the floating-point registers of the Intel 80387 coprocessor.   The
+ source file name is @file{reg-stack.c}.
+ 
+ @opindex dk
+ The options @option{-dk} causes a debugging dump of the RTL code after
+ this pass.  This dump file's name is made by appending @samp{.stack}
+ to the input file name.
+ 
+ @cindex final pass
+ @cindex peephole optimization
+ @item
+ Final.  This pass outputs the assembler code for the function.  It is
+ also responsible for identifying spurious test and compare
+ instructions.  Machine-specific peephole optimizations are performed
+ at the same time.  The function entry and exit sequences are generated
+ directly as assembler code in this pass; they never exist as RTL@.
+ 
+ The source files are @file{final.c} plus @file{insn-output.c}; the
+ latter is generated automatically from the machine description by the
+ tool @file{genoutput}.  The header file @file{conditions.h} is used
+ for communication between these files.
+ 
+ @cindex debugging information generation
+ @item
+ Debugging information output.  This is run after final because it must
+ output the stack slot offsets for pseudo registers that did not get
+ hard registers.  Source files are @file{dbxout.c} for DBX symbol table
+ format, @file{sdbout.c} for SDB symbol table format,  @file{dwarfout.c}
+ for DWARF symbol table format, and the files @file{dwarf2out.c} and
+ @file{dwarf2asm.c} for DWARF2 symbol table format.
+ @end itemize
+ 
+ Some additional files are used by all or many passes:
+ 
+ @itemize @bullet
+ @item
+ Every pass uses @file{machmode.def} and @file{machmode.h} which define
+ the machine modes.
+ 
+ @item
+ Several passes use @file{real.h}, which defines the default
+ representation of floating point constants and how to operate on them.
+ 
+ @item
+ All the passes that work with RTL use the header files @file{rtl.h}
+ and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
+ @code{gen*} also use these files to read and work with the machine
+ description RTL@.
+ 
+ @item
+ All the tools that read the machine description use support routines
+ found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
+ 
+ @findex genconfig
+ @item
+ Several passes refer to the header file @file{insn-config.h} which
+ contains a few parameters (C macro definitions) generated
+ automatically from the machine description RTL by the tool
+ @code{genconfig}.
+ 
+ @cindex instruction recognizer
+ @item
+ Several passes use the instruction recognizer, which consists of
+ @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
+ and @file{insn-extract.c} that are generated automatically from the
+ machine description by the tools @file{genrecog} and
+ @file{genextract}.
+ 
+ @item
+ Several passes use the header files @file{regs.h} which defines the
+ information recorded about pseudo register usage, and @file{basic-block.h}
+ which defines the information recorded about basic blocks.
+ 
+ @item
+ @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
+ with a bit for each hard register, and some macros to manipulate it.
+ This type is just @code{int} if the machine has few enough hard registers;
+ otherwise it is an array of @code{int} and some of the macros expand
+ into loops.
+ 
+ @item
+ Several passes use instruction attributes.  A definition of the
+ attributes defined for a particular machine is in file
+ @file{insn-attr.h}, which is generated from the machine description by
+ the program @file{genattr}.  The file @file{insn-attrtab.c} contains
+ subroutines to obtain the attribute values for insns.  It is generated
+ from the machine description by the program @file{genattrtab}.
+ @end itemize
diff -rcN gcc.orig/doc/portability.texi gcc/doc/portability.texi
*** gcc.orig/doc/portability.texi	Thu Jan  1 00:00:00 1970
--- gcc/doc/portability.texi	Sun Nov 11 19:09:04 2001
***************
*** 0 ****
--- 1,38 ----
+ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+ @c 1999, 2000, 2001 Free Software Foundation, Inc.
+ @c This is part of the GCC manual.
+ @c For copying conditions, see the file gcc.texi.
+ 
+ @node Portability
+ @chapter GCC and Portability
+ @cindex portability
+ @cindex GCC and portability
+ 
+ The main goal of GCC was to make a good, fast compiler for machines in
+ the class that the GNU system aims to run on: 32-bit machines that address
+ 8-bit bytes and have several general registers.  Elegance, theoretical
+ power and simplicity are only secondary.
+ 
+ GCC gets most of the information about the target machine from a machine
+ description which gives an algebraic formula for each of the machine's
+ instructions.  This is a very clean way to describe the target.  But when
+ the compiler needs information that is difficult to express in this
+ fashion, I have not hesitated to define an ad-hoc parameter to the machine
+ description.  The purpose of portability is to reduce the total work needed
+ on the compiler; it was not of interest for its own sake.
+ 
+ @cindex endianness
+ @cindex autoincrement addressing, availability
+ @findex abort
+ GCC does not contain machine dependent code, but it does contain code
+ that depends on machine parameters such as endianness (whether the most
+ significant byte has the highest or lowest address of the bytes in a word)
+ and the availability of autoincrement addressing.  In the RTL-generation
+ pass, it is often necessary to have multiple strategies for generating code
+ for a particular kind of syntax tree, strategies that are usable for different
+ combinations of parameters.  Often I have not tried to address all possible
+ cases, but only the common ones or only the ones that I have encountered.
+ As a result, a new target may require additional strategies.  You will know
+ if this happens because the compiler will call @code{abort}.  Fortunately,
+ the new strategies can be added in a machine-independent fashion, and will
+ affect only the target machines that need them.

-- 
Joseph S. Myers
jsm28@cam.ac.uk