This is ../../gcc-3.4/gcc/doc/gccint.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/gccint.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

File: gccint.info,  Node: Top,  Next: Contributing,  Up: (DIR)

Introduction
************

   This manual documents the internals of the GNU compilers, including
how to port them to new targets and some information about how to write
front ends for new languages.  It corresponds to GCC version 3.4.  The
use of the GNU compilers is documented in a separate manual.  *Note
Introduction: (gcc)Top.

   This manual is mainly a reference manual rather than a tutorial.  It
discusses how to contribute to GCC (*note Contributing::), the
characteristics of the machines supported by GCC as hosts and targets
(*note Portability::), how GCC relates to the ABIs on such systems
(*note Interface::), and the characteristics of the languages for which
GCC front ends are written (*note Languages::).  It then describes the
GCC source tree structure and build system, some of the interfaces to
GCC front ends, and how support for a target system is implemented in
GCC.

   Additional tutorial information is linked to from
`http://gcc.gnu.org/readings.html'.

* Menu:

* Contributing::    How to contribute to testing and developing GCC.
* Portability::     Goals of GCC's portability features.
* Interface::       Function-call interface of GCC output.
* Libgcc::          Low-level runtime library used by GCC.
* Languages::       Languages for which GCC front ends are written.
* Source Tree::     GCC source tree structure and build system.
* Passes::          Order of passes, what they do, and what each file is for.
* Trees::           The source representation used by the C and C++ front ends.
* RTL::             The intermediate representation that most passes work on.
* Machine Desc::    How to write machine description instruction patterns.
* Target Macros::   How to write the machine description C macros and functions.
* Host Config::     Writing the `xm-MACHINE.h' file.
* Fragments::       Writing the `t-TARGET' and `x-HOST' files.
* Collect2::        How `collect2' works; how it finds `ld'.
* Header Dirs::     Understanding the standard header file directories.
* Type Information:: GCC's memory management; generating type information.

* Funding::         How to help assure funding for free software.
* GNU Project::     The GNU Project and GNU/Linux.

* Copying::         GNU General Public License says
                     how you can copy and share GCC.
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors::    People who have contributed to GCC.

* Option Index::    Index to command line options.
* Index::	    Index of concepts and symbol names.


File: gccint.info,  Node: Contributing,  Next: Portability,  Prev: Top,  Up: Top

Contributing to GCC Development
*******************************

   If you would like to help pretest GCC releases to assure they work
well, our current development sources are available by CVS (see
`http://gcc.gnu.org/cvs.html').  Source and binary snapshots are also
available for FTP; see `http://gcc.gnu.org/snapshots.html'.

   If you would like to work on improvements to GCC, please read the
advice at these URLs:

     `http://gcc.gnu.org/contribute.html'
     `http://gcc.gnu.org/contributewhy.html'

for information on how to make useful contributions and avoid
duplication of effort.  Suggested projects are listed at
`http://gcc.gnu.org/projects/'.


File: gccint.info,  Node: Portability,  Next: Interface,  Prev: Contributing,  Up: Top

GCC and Portability
*******************

   GCC itself aims to be portable to any machine where `int' is at least
a 32-bit type.  It aims to target machines with a flat (non-segmented)
byte addressed data address space (the code address space can be
separate).  Target ABIs may have 8, 16, 32 or 64-bit `int' type. `char'
can be wider than 8 bits.

   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.

   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 `abort'.  Fortunately, the new strategies can be
added in a machine-independent fashion, and will affect only the target
machines that need them.


File: gccint.info,  Node: Interface,  Next: Libgcc,  Prev: Portability,  Up: Top

Interfacing to GCC Output
*************************

   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 (*note Target Macros::).

   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 `int' or `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 `STRUCT_VALUE' and `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.

   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.

   If you use `longjmp', beware of automatic variables.  ISO C says that
automatic variables that are not declared `volatile' have undefined
values after a `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 `longjmp', and you don't
want to write `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:

     {
       int careful;
       &careful;
       ...
     }


File: gccint.info,  Node: Libgcc,  Next: Languages,  Prev: Interface,  Up: Top

The GCC low-level runtime library
*********************************

   GCC provides a low-level runtime library, `libgcc.a' or
`libgcc_s.so.1' on some platforms.  GCC generates calls to routines in
this library automatically, whenever it needs to perform some operation
that is too complicated to emit inline code for.

   Most of the routines in `libgcc' handle arithmetic operations that
the target processor cannot perform directly.  This includes integer
multiply and divide on some machines, and all floating-point operations
on other machines.  `libgcc' also includes routines for exception
handling, and a handful of miscellaneous operations.

   Some of these routines can be defined in mostly machine-independent
C.  Others must be hand-written in assembly language for each processor
that needs them.

   GCC will also generate calls to C library routines, such as `memcpy'
and `memset', in some cases.  The set of routines that GCC may possibly
use is documented in *Note Other Builtins: (gcc)Other Builtins.

* Menu:

* Integer library routines::
* Soft float library routines::
* Exception handling routines::
* Miscellaneous routines::


File: gccint.info,  Node: Integer library routines,  Next: Soft float library routines,  Up: Libgcc

Routines for integer arithmetic
===============================

   document me!

       __absvsi2
       __addvsi3
       __ashlsi3
       __ashrsi3
       __divsi3
       __lshrsi3
       __modsi3
       __mulsi3
       __mulvsi3
       __negvsi2
       __subvsi3
       __udivsi3
       __umodsi3
     
       __absvdi2
       __addvdi3
       __ashldi3
       __ashrdi3
       __cmpdi2
       __divdi3
       __ffsdi2
       __fixdfdi
       __fixsfdi
       __fixtfdi
       __fixxfdi
       __fixunsdfdi
       __fixunsdfsi
       __fixunssfsi
       __fixunssfdi
       __fixunstfdi
       __fixunstfsi
       __fixunsxfdi
       __fixunsxfsi
       __floatdidf
       __floatdisf
       __floatdixf
       __floatditf
       __lshrdi3
       __moddi3
       __muldi3
       __mulvdi3
       __negdi2
       __negvdi2
       __subvdi3
       __ucmpdi2
       __udivdi3
       __udivmoddi4
       __umoddi3
     
       __ashlti3
       __ashrti3
       __cmpti2
       __divti3
       __ffsti2
       __fixdfti
       __fixsfti
       __fixtfti
       __fixxfti
       __lshrti3
       __modti3
       __multi3
       __negti2
       __ucmpti2
       __udivmodti4
       __udivti3
       __umodti3
       __fixunsdfti
       __fixunssfti
       __fixunstfti
       __fixunsxfti
       __floattidf
       __floattisf
       __floattixf
       __floattitf
     
       __clzsi2
       __clzdi2
       __clzti2
       __ctzsi2
       __ctzdi2
       __ctzti2
       __popcountsi2
       __popcountdi2
       __popcountti2
       __paritysi2
       __paritydi2
       __parityti2


File: gccint.info,  Node: Soft float library routines,  Next: Exception handling routines,  Prev: Integer library routines,  Up: Libgcc

Routines for floating point emulation
=====================================

   The software floating point library is used on machines which do not
have hardware support for floating point.  It is also used whenever
`-msoft-float' is used to disable generation of floating point
instructions.  (Not all targets support this switch.)

   For compatibility with other compilers, the floating point emulation
routines can be renamed with the `DECLARE_LIBRARY_RENAMES' macro (*note
Library Calls::).  In this section, the default names are used.

   These routines take arguments and return values of a specific machine
mode, not a specific C type.  *Note Machine Modes::, for an explanation
of this concept.  For illustrative purposes, in this section `float' is
assumed to correspond to `SFmode'; `double' to `DFmode'; `long double'
to `TFmode'; and `int' to `SImode'.  This is a common mapping, but not
the only possibility.

   Presently the library does not support `XFmode', which is used for
`long double' on some architectures.

Arithmetic functions
--------------------

 - Runtime Function: float __addsf3 (float A, float B)
 - Runtime Function: double __adddf3 (double A, double B)
 - Runtime Function: long double __addtf3 (long double A, long double B)
     These functions return the sum of A and B.

 - Runtime Function: float __subsf3 (float A, float B)
 - Runtime Function: double __subdf3 (double A, double B)
 - Runtime Function: long double __subtf3 (long double A, long double B)
     These functions return the difference between B and A; that is,
     A - B.

 - Runtime Function: float __mulsf3 (float A, float B)
 - Runtime Function: double __muldf3 (double A, double B)
 - Runtime Function: long double __multf3 (long double A, long double B)
     These functions return the product of A and B.

 - Runtime Function: float __divsf3 (float A, float B)
 - Runtime Function: double __divdf3 (double A, double B)
 - Runtime Function: long double __divtf3 (long double A, long double B)
     These functions return the quotient of A and B; that is, A / B.

 - Runtime Function: double __negdf2 (double A)
 - Runtime Function: long double __negtf2 (long double A)
 - Runtime Function: float __negsf2 (float A)
     These functions return the negation of A.  They simply flip the
     sign bit, so they can produce negative zero and negative NaN.

Conversion functions
--------------------

 - Runtime Function: double __extendsfdf2 (float A)
 - Runtime Function: long double __extendsftf2 (float A)
 - Runtime Function: long double __extenddftf2 (double A)
     These functions extend A to the wider mode of their return type.

 - Runtime Function: double __trunctfdf2 (long double A)
 - Runtime Function: float __trunctfsf2 (long double A)
 - Runtime Function: float __truncdfsf2 (double A)
     These functions truncate A to the narrower mode of their return
     type, rounding toward zero.

 - Runtime Function: int __fixsfsi (float A)
 - Runtime Function: int __fixdfsi (double A)
 - Runtime Function: int __fixtfsi (long double A)
     These functions convert A to a signed integer, rounding toward
     zero.

 - Runtime Function: unsigned int __fixunssfsi (float A)
 - Runtime Function: unsigned int __fixunsdfsi (double A)
 - Runtime Function: unsigned int __fixunstfsi (long double A)
     These functions convert A to an unsigned integer, rounding toward
     zero.  Negative values all become zero.

 - Runtime Function: float __floatsisf (int I)
 - Runtime Function: double __floatsidf (int I)
 - Runtime Function: long double __floatsitf (int I)
     These functions convert I, a signed integer, to floating point.

 - Runtime Function: float __floatunsisf (unsigned int N)
 - Runtime Function: double __floatunsidf (unsigned int N)
 - Runtime Function: long double __floatunsitf (unsigned int N)
     These functions convert N, an unsigned integer, to floating point.

   There are no functions to convert `DImode' integers to or from
floating point; this reflects the fact that such conversions are rare,
and processors with native 64-bit arithmetic tend to have hardware
floating point support.  If such routines ever get added, they will be
named `__fixsfdi', `__floatdisf', and so on.

Comparison functions
--------------------

   There are two sets of basic comparison functions.

 - Runtime Function: int __cmpsf2 (float A, float B)
 - Runtime Function: int __cmpdf2 (double A, double B)
 - Runtime Function: int __cmptf2 (long double A, long double B)
     These functions calculate a <=> b.  That is, if A is less than B,
     they return -1; if A is greater than B, they return 1; and if A
     and B are equal they return 0.  If either argument is NaN they
     return 1, but you should not rely on this; if NaN is a
     possibility, use one of the higher-level comparison functions.

 - Runtime Function: int __unordsf2 (float A, float B)
 - Runtime Function: int __unorddf2 (double A, double B)
 - Runtime Function: int __unordtf2 (long double A, long double B)
     These functions return 1 if either argument is NaN, otherwise 0.

   There is also a complete group of higher level functions which
correspond directly to comparison operators.  They implement the ISO C
semantics for floating-point comparisons, taking NaN into account.  Pay
careful attention to the return values defined for each set.  Under the
hood, all of these routines are implemented as

       if (__unordXf2 (a, b))
         return E;
       return __cmpXf2 (a, b);

where E is a constant chosen to give the proper behavior for NaN.
Thus, the meaning of the return value is different for each set.  Do
not rely on this implementation; only the semantics documented below
are guaranteed.

 - Runtime Function: int __eqsf2 (float A, float B)
 - Runtime Function: int __eqdf2 (double A, double B)
 - Runtime Function: int __eqtf2 (long double A, long double B)
     These functions return zero if neither argument is NaN, and A and
     B are equal.

 - Runtime Function: int __nesf2 (float A, float B)
 - Runtime Function: int __nedf2 (double A, double B)
 - Runtime Function: int __netf2 (long double A, long double B)
     These functions return a nonzero value if either argument is NaN,
     or if A and B are unequal.

 - Runtime Function: int __gesf2 (float A, float B)
 - Runtime Function: int __gedf2 (double A, double B)
 - Runtime Function: int __getf2 (long double A, long double B)
     These functions return a value greater than or equal to zero if
     neither argument is NaN, and A is greater than or equal to B.

 - Runtime Function: int __ltsf2 (float A, float B)
 - Runtime Function: int __ltdf2 (double A, double B)
 - Runtime Function: int __lttf2 (long double A, long double B)
     These functions return a value less than zero if neither argument
     is NaN, and A is strictly less than B.

 - Runtime Function: int __lesf2 (float A, float B)
 - Runtime Function: int __ledf2 (double A, double B)
 - Runtime Function: int __letf2 (long double A, long double B)
     These functions return a value less than or equal to zero if
     neither argument is NaN, and A is less than or equal to B.

 - Runtime Function: int __gtsf2 (float A, float B)
 - Runtime Function: int __gtdf2 (double A, double B)
 - Runtime Function: int __gttf2 (long double A, long double B)
     These functions return a value greater than zero if neither
     argument is NaN, and A is strictly greater than B.


File: gccint.info,  Node: Exception handling routines,  Next: Miscellaneous routines,  Prev: Soft float library routines,  Up: Libgcc

Language-independent routines for exception handling
====================================================

   document me!

       _Unwind_DeleteException
       _Unwind_Find_FDE
       _Unwind_ForcedUnwind
       _Unwind_GetGR
       _Unwind_GetIP
       _Unwind_GetLanguageSpecificData
       _Unwind_GetRegionStart
       _Unwind_GetTextRelBase
       _Unwind_GetDataRelBase
       _Unwind_RaiseException
       _Unwind_Resume
       _Unwind_SetGR
       _Unwind_SetIP
       _Unwind_FindEnclosingFunction
       _Unwind_SjLj_Register
       _Unwind_SjLj_Unregister
       _Unwind_SjLj_RaiseException
       _Unwind_SjLj_ForcedUnwind
       _Unwind_SjLj_Resume
       __deregister_frame
       __deregister_frame_info
       __deregister_frame_info_bases
       __register_frame
       __register_frame_info
       __register_frame_info_bases
       __register_frame_info_table
       __register_frame_info_table_bases
       __register_frame_table


File: gccint.info,  Node: Miscellaneous routines,  Prev: Exception handling routines,  Up: Libgcc

Miscellaneous runtime library routines
======================================

   document me!

       __clear_cache

   any others?


File: gccint.info,  Node: Languages,  Next: Source Tree,  Prev: Libgcc,  Up: Top

Language Front Ends in GCC
**************************

   The interface to front ends for languages in GCC, and in particular
the `tree' structure (*note Trees::), was initially designed for C, and
many aspects of it are still somewhat biased towards C and C-like
languages.  It is, however, reasonably well suited to other procedural
languages, and front ends for many such languages have been written for
GCC.

   Writing a compiler as a front end for GCC, rather than compiling
directly to assembler or generating C code which is then compiled by
GCC, has several advantages:

   * GCC front ends benefit from the support for many different target
     machines already present in GCC.

   * GCC front ends benefit from all the optimizations in GCC.  Some of
     these, such as alias analysis, may work better when GCC is
     compiling directly from source code then when it is compiling from
     generated C code.

   * Better debugging information is generated when compiling directly
     from source code than when going via intermediate generated C code.

   Because of the advantages of writing a compiler as a GCC front end,
GCC front ends have also been created for languages very different from
those for which GCC was designed, such as the declarative
logic/functional language Mercury.  For these reasons, it may also be
useful to implement compilers created for specialized purposes (for
example, as part of a research project) as GCC front ends.


File: gccint.info,  Node: Source Tree,  Next: Passes,  Prev: Languages,  Up: Top

Source Tree Structure and Build System
**************************************

   This chapter describes the structure of the GCC source tree, and how
GCC is built.  The user documentation for building and installing GCC
is in a separate manual (`http://gcc.gnu.org/install/'), with which it
is presumed that you are familiar.

* Menu:

* Configure Terms:: Configuration terminology and history.
* Top Level::       The top level source directory.
* gcc Directory::   The `gcc' subdirectory.
* Test Suites::     The GCC test suites.


File: gccint.info,  Node: Configure Terms,  Next: Top Level,  Up: Source Tree

Configure Terms and History
===========================

   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 ("build"), the machine that you are building for
("host"), and the machine that GCC will produce code for ("target").
When you configure GCC, you specify these with `--build=', `--host=',
and `--target='.

   Specifying the host without specifying the build should be avoided,
as `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
"native".  If build and host are the same but target is different, this
is called a "cross".  If build, host, and target are all different this
is called a "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 "host-x-host", "crossed
native", or "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 way of describing it (although I propose
calling it a "crossback").

   If build and host are the same, the GCC you are building will also be
used to build the target libraries (like `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 `--target=foo-bar', this compiler will be called
`foo-bar-gcc').

   In the case of target libraries, the machine you're building for is
the machine you specified with `--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
`$with_cross_host' to the original `--host' value in case you need it.

   The `libiberty' support library is built up to three times: once for
the host, once for the target (even if they are the same), and once for
the build if build and host are different.  This allows it to be used
by all programs which are generated in the course of the build process.


File: gccint.info,  Node: Top Level,  Next: gcc Directory,  Prev: Configure Terms,  Up: Source Tree

Top Level Source Directory
==========================

   The top level source directory in a GCC distribution contains several
files and directories that are shared with other software distributions
such as that of GNU Binutils.  It also contains several subdirectories
that contain parts of GCC and its runtime libraries:

`boehm-gc'
     The Boehm conservative garbage collector, used as part of the Java
     runtime library.

`contrib'
     Contributed scripts that may be found useful in conjunction with
     GCC.  One of these, `contrib/texi2pod.pl', is used to generate man
     pages from Texinfo manuals as part of the GCC build process.

`fastjar'
     An implementation of the `jar' command, used with the Java front
     end.

`gcc'
     The main sources of GCC itself (except for runtime libraries),
     including optimizers, support for different target architectures,
     language front ends, and test suites.  *Note The `gcc'
     Subdirectory: gcc Directory, for details.

`include'
     Headers for the `libiberty' library.

`libf2c'
     The Fortran runtime library.

`libffi'
     The `libffi' library, used as part of the Java runtime library.

`libiberty'
     The `libiberty' library, used for portability and for some
     generally useful data structures and algorithms.  *Note
     Introduction: (libiberty)Top, for more information about this
     library.

`libjava'
     The Java runtime library.

`libobjc'
     The Objective-C runtime library.

`libstdc++-v3'
     The C++ runtime library.

`maintainer-scripts'
     Scripts used by the `gccadmin' account on `gcc.gnu.org'.

`zlib'
     The `zlib' compression library, used by the Java front end and as
     part of the Java runtime library.

   The build system in the top level directory, including how recursion
into subdirectories works and how building runtime libraries for
multilibs is handled, is documented in a separate manual, included with
GNU Binutils.  *Note GNU configure and build system: (configure)Top,
for details.


File: gccint.info,  Node: gcc Directory,  Next: Test Suites,  Prev: Top Level,  Up: Source Tree

The `gcc' Subdirectory
======================

   The `gcc' directory contains many files that are part of the C
sources of GCC, other files used as part of the configuration and build
process, and subdirectories including documentation and a test suite.
The files that are sources of GCC are documented in a separate chapter.
*Note Passes and Files of the Compiler: Passes.

* Menu:

* Subdirectories:: Subdirectories of `gcc'.
* Configuration::  The configuration process, and the files it uses.
* Build::          The build system in the `gcc' directory.
* Makefile::       Targets in `gcc/Makefile'.
* Library Files::  Library source files and headers under `gcc/'.
* Headers::        Headers installed by GCC.
* Documentation::  Building documentation in GCC.
* Front End::      Anatomy of a language front end.
* Back End::       Anatomy of a target back end.


File: gccint.info,  Node: Subdirectories,  Next: Configuration,  Up: gcc Directory

Subdirectories of `gcc'
-----------------------

   The `gcc' directory contains the following subdirectories:

`LANGUAGE'
     Subdirectories for various languages.  Directories containing a
     file `config-lang.in' are language subdirectories.  The contents of
     the subdirectories `cp' (for C++) and `objc' (for Objective-C) are
     documented in this manual (*note Passes and Files of the Compiler:
     Passes.); those for other languages are not.  *Note Anatomy of a
     Language Front End: Front End, for details of the files in these
     directories.

`config'
     Configuration files for supported architectures and operating
     systems.  *Note Anatomy of a Target Back End: Back End, for
     details of the files in this directory.

`doc'
     Texinfo documentation for GCC, together with automatically
     generated man pages and support for converting the installation
     manual to HTML.  *Note Documentation::.

`fixinc'
     The support for fixing system headers to work with GCC.  See
     `fixinc/README' for more information.  The headers fixed by this
     mechanism are installed in `LIBSUBDIR/include'.  Along with those
     headers, `README-fixinc' is also installed, as
     `LIBSUBDIR/include/README'.

`ginclude'
     System headers installed by GCC, mainly those required by the C
     standard of freestanding implementations.  *Note Headers Installed
     by GCC: Headers, for details of when these and other headers are
     installed.

`intl'
     GNU `libintl', from GNU `gettext', for systems which do not
     include it in libc.  Properly, this directory should be at top
     level, parallel to the `gcc' directory.

`po'
     Message catalogs with translations of messages produced by GCC into
     various languages, `LANGUAGE.po'.  This directory also contains
     `gcc.pot', the template for these message catalogues, `exgettext',
     a wrapper around `gettext' to extract the messages from the GCC
     sources and create `gcc.pot', which is run by `make gcc.pot', and
     `EXCLUDES', a list of files from which messages should not be
     extracted.

`testsuite'
     The GCC test suites (except for those for runtime libraries).
     *Note Test Suites::.


File: gccint.info,  Node: Configuration,  Next: Build,  Prev: Subdirectories,  Up: gcc Directory

Configuration in the `gcc' Directory
------------------------------------

   The `gcc' directory is configured with an Autoconf-generated script
`configure'.  The `configure' script is generated from `configure.in'
and `aclocal.m4'.  From the files `configure.in' and `acconfig.h',
Autoheader generates the file `config.in'.  The file `cstamp-h.in' is
used as a timestamp.

* Menu:

* Config Fragments::     Scripts used by `configure'.
* System Config::        The `config.gcc' file.
* Configuration Files::  Files created by running `configure'.


File: gccint.info,  Node: Config Fragments,  Next: System Config,  Up: Configuration

Scripts Used by `configure'
...........................

   `configure' uses some other scripts to help in its work:

   * The standard GNU `config.sub' and `config.guess' files, kept in
     the top level directory, are used.  FIXME: when is the
     `config.guess' file in the `gcc' directory (that just calls the
     top level one) used?

   * The file `config.gcc' is used to handle configuration specific to
     the particular build, host or target machine.  (In general, this
     should only be used for features that cannot reasonably be tested
     in Autoconf feature tests.)  *Note The `config.gcc' File: System
     Config, for details of the contents of this file.

   * Each language subdirectory has a file `LANGUAGE/config-lang.in'
     that is used for front-end-specific configuration.  *Note The
     Front End `config-lang.in' File: Front End Config, for details of
     this file.

   * A helper script `configure.frag' is used as part of creating the
     output of `configure'.


File: gccint.info,  Node: System Config,  Next: Configuration Files,  Prev: Config Fragments,  Up: Configuration

The `config.gcc' File
.....................

   FIXME: document the contents of this file, and what variables should
be set to control build, host and target configuration.


File: gccint.info,  Node: Configuration Files,  Prev: System Config,  Up: Configuration

Files Created by `configure'
............................

   Here we spell out what files will be set up by `configure' in the
`gcc' directory.  Some other files are created as temporary files in
the configuration process, and are not used in the subsequent build;
these are not documented.

   * `Makefile' is constructed from `Makefile.in', together with the
     host and target fragments (*note Makefile Fragments: Fragments.)
     `t-TARGET' and `x-HOST' from `config', if any, and language
     Makefile fragments `LANGUAGE/Make-lang.in'.

   * `auto-host.h' contains information about the host machine
     determined by `configure'.  If the host machine is different from
     the build machine, then `auto-build.h' is also created, containing
     such information about the build machine.

   * `config.status' is a script that may be run to recreate the
     current configuration.

   * `configargs.h' is a header containing details of the arguments
     passed to `configure' to configure GCC, and of the thread model
     used.

   * `cstamp-h' is used as a timestamp.

   * `fixinc/Makefile' is constructed from `fixinc/Makefile.in'.

   * `gccbug', a script for reporting bugs in GCC, is constructed from
     `gccbug.in'.

   * `intl/Makefile' is constructed from `intl/Makefile.in'.

   * `mklibgcc', a shell script to create a Makefile to build libgcc,
     is constructed from `mklibgcc.in'.

   * If a language `config-lang.in' file (*note The Front End
     `config-lang.in' File: Front End Config.) sets `outputs', then the
     files listed in `outputs' there are also generated.

   The following configuration headers are created from the Makefile,
using `mkconfig.sh', rather than directly by `configure'.  `config.h',
`bconfig.h' and `tconfig.h' all contain the `xm-MACHINE.h' header, if
any, appropriate to the host, build and target machines respectively,
the configuration headers for the target, and some definitions; for the
host and build machines, these include the autoconfigured headers
generated by `configure'.  The other configuration headers are
determined by `config.gcc'.  They also contain the typedefs for `rtx',
`rtvec' and `tree'.

   * `config.h', for use in programs that run on the host machine.

   * `bconfig.h', for use in programs that run on the build machine.

   * `tconfig.h', for use in programs and libraries for the target
     machine.

   * `tm_p.h', which includes the header `MACHINE-protos.h' that
     contains prototypes for functions in the target `.c' file.  FIXME:
     why is such a separate header necessary?


File: gccint.info,  Node: Build,  Next: Makefile,  Prev: Configuration,  Up: gcc Directory

Build System in the `gcc' Directory
-----------------------------------

   FIXME: describe the build system, including what is built in what
stages.  Also list the various source files that are used in the build
process but aren't source files of GCC itself and so aren't documented
below (*note Passes::).


File: gccint.info,  Node: Makefile,  Next: Library Files,  Prev: Build,  Up: gcc Directory

Makefile Targets
----------------

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

`doc'
     Produce info-formatted documentation.  Also, `make dvi' is
     available for DVI-formatted documentation, and `make
     generated-manpages' to generate man pages.

`mostlyclean'
     Delete the files made while building the compiler.

`clean'
     That, and all the other files built by `make all'.

`distclean'
     That, and all the files created by `configure'.

`extraclean'
     That, and any temporary or intermediate files, like emacs backup
     files.

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

`install'
     Installs gcc.

`uninstall'
     Deletes installed files.

`check'
     Run the testsuite.  This creates a `testsuite' subdirectory that
     has various `.sum' and `.log' files containing the results of the
     testing.  You can run subsets with, for example, `make check-gcc'.
     You can specify specific tests by setting RUNTESTFLAGS to be the
     name of the `.exp' file, optionally followed by (for some tests)
     an equals and a file wildcard, like:

          make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"

     Note that running the testsuite may require additional tools be
     installed, such as TCL or dejagnu.

`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 `make compare' can check.  Each
     step of this process is called a "stage", and the results of each
     stage N (N = 1...3) are copied to a subdirectory `stageN/'.

`bootstrap-lean'
     Like `bootstrap', except that the various stages are removed once
     they're no longer needed.  This saves disk space.

`bubblestrap'
     This incrementally rebuilds each of the three stages, one at a
     time.  It does this by "bubbling" the stages up from their
     subdirectories (if they had been built previously), rebuilding
     them, and copying them back to their subdirectories.  This will
     allow you to, for example, continue a bootstrap after fixing a bug
     which causes the stage2 build to crash.

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

`cleanstrap'
     Removed everything (`make clean') and rebuilds (`make bootstrap').

`restrap'
     Like `cleanstrap', except that the process starts from the first
     stage build, not from scratch.

`stageN (N = 1...4)'
     For each stage, moves the appropriate files to the `stageN'
     subdirectory.

`unstageN (N = 1...4)'
     Undoes the corresponding `stageN'.

`restageN (N = 1...4)'
     Undoes the corresponding `stageN' and rebuilds it with the
     appropriate flags.

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

`profiledbootstrap'
     Builds a compiler with profiling feedback information.  For more
     information, see *Note Building with profile feedback:
     (gccinstall)Building.  This is actually a target in the top-level
     directory, which then recurses into the `gcc' subdirectory
     multiple times.


File: gccint.info,  Node: Library Files,  Next: Headers,  Prev: Makefile,  Up: gcc Directory

Library Source Files and Headers under the `gcc' Directory
----------------------------------------------------------

   FIXME: list here, with explanation, all the C source files and
headers under the `gcc' directory that aren't built into the GCC
executable but rather are part of runtime libraries and object files,
such as `crtstuff.c' and `unwind-dw2.c'.  *Note Headers Installed by
GCC: Headers, for more information about the `ginclude' directory.


File: gccint.info,  Node: Headers,  Next: Documentation,  Prev: Library Files,  Up: gcc Directory

Headers Installed by GCC
------------------------

   In general, GCC expects the system C library to provide most of the
headers to be used with it.  However, GCC will fix those headers if
necessary to make them work with GCC, and will install some headers
required of freestanding implementations.  These headers are installed
in `LIBSUBDIR/include'.  Headers for non-C runtime libraries are also
installed by GCC; these are not documented here.  (FIXME: document them
somewhere.)

   Several of the headers GCC installs are in the `ginclude' directory.
These headers, `iso646.h', `stdarg.h', `stdbool.h', and `stddef.h',
are installed in `LIBSUBDIR/include', unless the target Makefile
fragment (*note Target Fragment::) overrides this by setting `USER_H'.

   In addition to these headers and those generated by fixing system
headers to work with GCC, some other headers may also be installed in
`LIBSUBDIR/include'.  `config.gcc' may set `extra_headers'; this
specifies additional headers under `config' to be installed on some
systems.

   GCC installs its own version of `<float.h>', from `ginclude/float.h'.
This is done to cope with command-line options that change the
representation of floating point numbers.

   GCC also installs its own version of `<limits.h>'; this is generated
from `glimits.h', together with `limitx.h' and `limity.h' if the system
also has its own version of `<limits.h>'.  (GCC provides its own header
because it is required of ISO C freestanding implementations, but needs
to include the system header from its own header as well because other
standards such as POSIX specify additional values to be defined in
`<limits.h>'.)  The system's `<limits.h>' header is used via
`LIBSUBDIR/include/syslimits.h', which is copied from `gsyslimits.h' if
it does not need fixing to work with GCC; if it needs fixing,
`syslimits.h' is the fixed copy.


File: gccint.info,  Node: Documentation,  Next: Front End,  Prev: Headers,  Up: gcc Directory

Building Documentation
----------------------

   The main GCC documentation is in the form of manuals in Texinfo
format.  These are installed in Info format, and DVI versions may be
generated by `make dvi'.  In addition, some man pages are generated
from the Texinfo manuals, there are some other text files with
miscellaneous documentation, and runtime libraries have their own
documentation outside the `gcc' directory.  FIXME: document the
documentation for runtime libraries somewhere.

* Menu:

* Texinfo Manuals::      GCC manuals in Texinfo format.
* Man Page Generation::  Generating man pages from Texinfo manuals.
* Miscellaneous Docs::   Miscellaneous text files with documentation.


File: gccint.info,  Node: Texinfo Manuals,  Next: Man Page Generation,  Up: Documentation

Texinfo Manuals
...............

   The manuals for GCC as a whole, and the C and C++ front ends, are in
files `doc/*.texi'.  Other front ends have their own manuals in files
`LANGUAGE/*.texi'.  Common files `doc/include/*.texi' are provided
which may be included in multiple manuals; the following files are in
`doc/include':

`fdl.texi'
     The GNU Free Documentation License.

`funding.texi'
     The section "Funding Free Software".

`gcc-common.texi'
     Common definitions for manuals.

`gpl.texi'
     The GNU General Public License.

`texinfo.tex'
     A copy of `texinfo.tex' known to work with the GCC manuals.

   DVI formatted manuals are generated by `make dvi', which uses
`texi2dvi' (via the Makefile macro `$(TEXI2DVI)').  Info manuals are
generated by `make info' (which is run as part of a bootstrap); this
generates the manuals in the source directory, using `makeinfo' via the
Makefile macro `$(MAKEINFO)', and they are included in release
distributions.

   Manuals are also provided on the GCC web site, in both HTML and
PostScript forms.  This is done via the script
`maintainer-scripts/update_web_docs'.  Each manual to be provided
online must be listed in the definition of `MANUALS' in that file; a
file `NAME.texi' must only appear once in the source tree, and the
output manual must have the same name as the source file.  (However,
other Texinfo files, included in manuals but not themselves the root
files of manuals, may have names that appear more than once in the
source tree.)  The manual file `NAME.texi' should only include other
files in its own directory or in `doc/include'.  HTML manuals will be
generated by `makeinfo --html' and PostScript manuals by `texi2dvi' and
`dvips'.  All Texinfo files that are parts of manuals must be checked
into CVS, even if they are generated files, for the generation of
online manuals to work.

   The installation manual, `doc/install.texi', is also provided on the
GCC web site.  The HTML version is generated by the script
`doc/install.texi2html'.


File: gccint.info,  Node: Man Page Generation,  Next: Miscellaneous Docs,  Prev: Texinfo Manuals,  Up: Documentation

Man Page Generation
...................

   Because of user demand, in addition to full Texinfo manuals, man
pages are provided which contain extracts from those manuals.  These man
pages are generated from the Texinfo manuals using
`contrib/texi2pod.pl' and `pod2man'.  (The man page for `g++',
`cp/g++.1', just contains a `.so' reference to `gcc.1', but all the
other man pages are generated from Texinfo manuals.)

   Because many systems may not have the necessary tools installed to
generate the man pages, they are only generated if the `configure'
script detects that recent enough tools are installed, and the
Makefiles allow generating man pages to fail without aborting the
build.  Man pages are also included in release distributions.  They are
generated in the source directory.

   Magic comments in Texinfo files starting `@c man' control what parts
of a Texinfo file go into a man page.  Only a subset of Texinfo is
supported by `texi2pod.pl', and it may be necessary to add support for
more Texinfo features to this script when generating new man pages.  To
improve the man page output, some special Texinfo macros are provided
in `doc/include/gcc-common.texi' which `texi2pod.pl' understands:

`@gcctabopt'
     Use in the form `@table @gcctabopt' for tables of options, where
     for printed output the effect of `@code' is better than that of
     `@option' but for man page output a different effect is wanted.

`@gccoptlist'
     Use for summary lists of options in manuals.

`@gol'
     Use at the end of each line inside `@gccoptlist'.  This is
     necessary to avoid problems with differences in how the
     `@gccoptlist' macro is handled by different Texinfo formatters.

   FIXME: describe the `texi2pod.pl' input language and magic comments
in more detail.


File: gccint.info,  Node: Miscellaneous Docs,  Prev: Man Page Generation,  Up: Documentation

Miscellaneous Documentation
...........................

   In addition to the formal documentation that is installed by GCC,
there are several other text files with miscellaneous documentation:

`ABOUT-GCC-NLS'
     Notes on GCC's Native Language Support.  FIXME: this should be
     part of this manual rather than a separate file.

`ABOUT-NLS'
     Notes on the Free Translation Project.

`COPYING'
     The GNU General Public License.

`COPYING.LIB'
     The GNU Lesser General Public License.

`*ChangeLog*'
`*/ChangeLog*'
     Change log files for various parts of GCC.

`LANGUAGES'
     Details of a few changes to the GCC front-end interface.  FIXME:
     the information in this file should be part of general
     documentation of the front-end interface in this manual.

`ONEWS'
     Information about new features in old versions of GCC.  (For recent
     versions, the information is on the GCC web site.)

`README.Portability'
     Information about portability issues when writing code in GCC.
     FIXME: why isn't this part of this manual or of the GCC Coding
     Conventions?

`SERVICE'
     A pointer to the GNU Service Directory.

   FIXME: document such files in subdirectories, at least `config',
`cp', `objc', `testsuite'.

