This is doc/gccint.info, produced by makeinfo version 4.8 from
../../gcc-3.4.3/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.
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.3.
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
1 Contributing to GCC Development
*********************************
If you would like to help pretest GCC releases to assure they work well,
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
2 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, ad-hoc parameters have been defined for
machine descriptions. 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, not
all possible cases have been addressed, but only the common ones or
only the ones that have been 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
3 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 target
hook `TARGET_STRUCT_VALUE_RTX' tells 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
4 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.
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 chapter the
floating point type `float' is assumed to correspond to `SFmode';
`double' to `DFmode'; and `long double' to both `TFmode' and `XFmode'.
Similarly, the integer types `int' and `unsigned int' correspond to
`SImode'; `long' and `unsigned long' to `DImode'; and `long long' and
`unsigned long long' to `TImode'.
* 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
4.1 Routines for integer arithmetic
===================================
The integer arithmetic routines are used on platforms that don't provide
hardware support for arithmetic operations on some modes.
4.1.1 Arithmetic functions
--------------------------
-- Runtime Function: int __ashlsi3 (int A, int B)
-- Runtime Function: long __ashldi3 (long A, int B)
-- Runtime Function: long long __ashlti3 (long long A, int B)
These functions return the result of shifting A left by B bits.
-- Runtime Function: int __ashrsi3 (int A, int B)
-- Runtime Function: long __ashrdi3 (long A, int B)
-- Runtime Function: long long __ashrti3 (long long A, int B)
These functions return the result of arithmetically shifting A
right by B bits.
-- Runtime Function: int __divsi3 (int A, int B)
-- Runtime Function: long __divdi3 (long A, long B)
-- Runtime Function: long long __divti3 (long long A, long long B)
These functions return the quotient of the signed division of A and
B.
-- Runtime Function: int __lshrsi3 (int A, int B)
-- Runtime Function: long __lshrdi3 (long A, int B)
-- Runtime Function: long long __lshrti3 (long long A, int B)
These functions return the result of logically shifting A right by
B bits.
-- Runtime Function: int __modsi3 (int A, int B)
-- Runtime Function: long __moddi3 (long A, long B)
-- Runtime Function: long long __modti3 (long long A, long long B)
These functions return the remainder of the signed division of A
and B.
-- Runtime Function: int __mulsi3 (int A, int B)
-- Runtime Function: long __muldi3 (long A, long B)
-- Runtime Function: long long __multi3 (long long A, long long B)
These functions return the product of A and B.
-- Runtime Function: long __negdi2 (long A)
-- Runtime Function: long long __negti2 (long long A)
These functions return the negation of A.
-- Runtime Function: unsigned int __udivsi3 (unsigned int A, unsigned
int B)
-- Runtime Function: unsigned long __udivdi3 (unsigned long A,
unsigned long B)
-- Runtime Function: unsigned long long __udivti3 (unsigned long long
A, unsigned long long B)
These functions return the quotient of the unsigned division of A
and B.
-- Runtime Function: unsigned long __udivmoddi3 (unsigned long A,
unsigned long B, unsigned long *C)
-- Runtime Function: unsigned long long __udivti3 (unsigned long long
A, unsigned long long B, unsigned long long *C)
These functions calculate both the quotient and remainder of the
unsigned division of A and B. The return value is the quotient,
and the remainder is placed in variable pointed to by C.
-- Runtime Function: unsigned int __umodsi3 (unsigned int A, unsigned
int B)
-- Runtime Function: unsigned long __umoddi3 (unsigned long A,
unsigned long B)
-- Runtime Function: unsigned long long __umodti3 (unsigned long long
A, unsigned long long B)
These functions return the remainder of the unsigned division of A
and B.
4.1.2 Comparison functions
--------------------------
The following functions implement integral comparisons. These functions
implement a low-level compare, upon which the higher level comparison
operators (such as less than and greater than or equal to) can be
constructed. The returned values lie in the range zero to two, to allow
the high-level operators to be implemented by testing the returned
result using either signed or unsigned comparison.
-- Runtime Function: int __cmpdi2 (long A, long B)
-- Runtime Function: int __cmpti2 (long long A, long long B)
These functions perform a signed comparison of A and B. If A is
less than B, they return 0; if A is greater than B, they return 2;
and if A and B are equal they return 1.
-- Runtime Function: int __ucmpdi2 (unsigned long A, unsigned long B)
-- Runtime Function: int __ucmpti2 (unsigned long long A, unsigned
long long B)
These functions perform an unsigned comparison of A and B. If A
is less than B, they return 0; if A is greater than B, they return
2; and if A and B are equal they return 1.
4.1.3 Trapping arithmetic functions
-----------------------------------
The following functions implement trapping arithmetic. These functions
call the libc function `abort' upon signed arithmetic overflow.
-- Runtime Function: int __absvsi2 (int A)
-- Runtime Function: long __absvdi2 (long A)
These functions return the absolute value of A.
-- Runtime Function: int __addvsi3 (int A, int B)
-- Runtime Function: long __addvdi3 (long A, long B)
These functions return the sum of A and B; that is `A + B'.
-- Runtime Function: int __mulvsi3 (int A, int B)
-- Runtime Function: long __mulvdi3 (long A, long B)
The functions return the product of A and B; that is `A * B'.
-- Runtime Function: int __negvsi2 (int A)
-- Runtime Function: long __negvdi2 (long A)
These functions return the negation of A; that is `-A'.
-- Runtime Function: int __subvsi3 (int A, int B)
-- Runtime Function: long __subvdi3 (long A, long B)
These functions return the difference between B and A; that is `A
- B'.
4.1.4 Bit operations
--------------------
-- Runtime Function: int __clzsi2 (int A)
-- Runtime Function: int __clzdi2 (long A)
-- Runtime Function: int __clzti2 (long long A)
These functions return the number of leading 0-bits in A, starting
at the most significant bit position. If A is zero, the result is
undefined.
-- Runtime Function: int __ctzsi2 (int A)
-- Runtime Function: int __ctzdi2 (long A)
-- Runtime Function: int __ctzti2 (long long A)
These functions return the number of trailing 0-bits in A, starting
at the least significant bit position. If A is zero, the result is
undefined.
-- Runtime Function: int __ffsdi2 (long A)
-- Runtime Function: int __ffsti2 (long long A)
These functions return the index of the least significant 1-bit in
A, or the value zero if A is zero. The least significant bit is
index one.
-- Runtime Function: int __paritysi2 (int A)
-- Runtime Function: int __paritydi2 (long A)
-- Runtime Function: int __parityti2 (long long A)
These functions return the value zero if the number of bits set in
A is even, and the value one otherwise.
-- Runtime Function: int __popcountsi2 (int A)
-- Runtime Function: int __popcountdi2 (long A)
-- Runtime Function: int __popcountti2 (long long A)
These functions return the number of bits set in A.
File: gccint.info, Node: Soft float library routines, Next: Exception handling routines, Prev: Integer library routines, Up: Libgcc
4.2 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.
Presently the library does not support `XFmode', which is used for
`long double' on some architectures.
4.2.1 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)
-- Runtime Function: long double __addxf3 (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)
-- Runtime Function: long double __subxf3 (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)
-- Runtime Function: long double __mulxf3 (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)
-- Runtime Function: long double __divxf3 (long double A, long double
B)
These functions return the quotient of A and B; that is, A / B.
-- Runtime Function: float __negsf2 (float A)
-- Runtime Function: double __negdf2 (double A)
-- Runtime Function: long double __negtf2 (long double A)
-- Runtime Function: long double __negxf2 (long double A)
These functions return the negation of A. They simply flip the
sign bit, so they can produce negative zero and negative NaN.
4.2.2 Conversion functions
--------------------------
-- Runtime Function: double __extendsfdf2 (float A)
-- Runtime Function: long double __extendsftf2 (float A)
-- Runtime Function: long double __extendsfxf2 (float A)
-- Runtime Function: long double __extenddftf2 (double A)
-- Runtime Function: long double __extenddfxf2 (double A)
These functions extend A to the wider mode of their return type.
-- Runtime Function: double __truncxfdf2 (long double A)
-- Runtime Function: double __trunctfdf2 (long double A)
-- Runtime Function: float __truncxfsf2 (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)
-- Runtime Function: int __fixxfsi (long double A)
These functions convert A to a signed integer, rounding toward
zero.
-- Runtime Function: long __fixsfdi (float A)
-- Runtime Function: long __fixdfdi (double A)
-- Runtime Function: long __fixtfdi (long double A)
-- Runtime Function: long __fixxfdi (long double A)
These functions convert A to a signed long, rounding toward zero.
-- Runtime Function: long long __fixsfti (float A)
-- Runtime Function: long long __fixdfti (double A)
-- Runtime Function: long long __fixtfti (long double A)
-- Runtime Function: long long __fixxfti (long double A)
These functions convert A to a signed long long, 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)
-- Runtime Function: unsigned int __fixunsxfsi (long double A)
These functions convert A to an unsigned integer, rounding toward
zero. Negative values all become zero.
-- Runtime Function: unsigned long __fixunssfdi (float A)
-- Runtime Function: unsigned long __fixunsdfdi (double A)
-- Runtime Function: unsigned long __fixunstfdi (long double A)
-- Runtime Function: unsigned long __fixunsxfdi (long double A)
These functions convert A to an unsigned long, rounding toward
zero. Negative values all become zero.
-- Runtime Function: unsigned long long __fixunssfti (float A)
-- Runtime Function: unsigned long long __fixunsdfti (double A)
-- Runtime Function: unsigned long long __fixunstfti (long double A)
-- Runtime Function: unsigned long long __fixunsxfti (long double A)
These functions convert A to an unsigned long long, 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)
-- Runtime Function: long double __floatsixf (int I)
These functions convert I, a signed integer, to floating point.
-- Runtime Function: float __floatdisf (long I)
-- Runtime Function: double __floatdidf (long I)
-- Runtime Function: long double __floatditf (long I)
-- Runtime Function: long double __floatdixf (long I)
These functions convert I, a signed long, to floating point.
-- Runtime Function: float __floattisf (long long I)
-- Runtime Function: double __floattidf (long long I)
-- Runtime Function: long double __floattitf (long long I)
-- Runtime Function: long double __floattixf (long long I)
These functions convert I, a signed long long, to floating point.
4.2.3 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 a nonzero value 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
4.3 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
4.4 Miscellaneous runtime library routines
==========================================
4.4.1 Cache control functions
-----------------------------
-- Runtime Function: void __clear_cache (char *BEG, char *END)
This function clears the instruction cache between BEG and END.
File: gccint.info, Node: Languages, Next: Source Tree, Prev: Libgcc, Up: Top
5 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
6 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.
* Testsuites:: The GCC testsuites.
File: gccint.info, Node: Configure Terms, Next: Top Level, Up: Source Tree
6.1 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. There is a
proposal to call this 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
6.2 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 testsuites. *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: Testsuites, Prev: Top Level, Up: Source Tree
6.3 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 testsuite.
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
6.3.1 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 testsuites (except for those for runtime libraries).
*Note Testsuites::.
File: gccint.info, Node: Configuration, Next: Build, Prev: Subdirectories, Up: gcc Directory
6.3.2 Configuration in the `gcc' Directory
------------------------------------------
The `gcc' directory is configured with an Autoconf-generated script
`configure'. The `configure' script is generated from `configure.ac'
and `aclocal.m4'. From the files `configure.ac' 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.build', `config.host', and
`config.gcc' files.
* Configuration Files:: Files created by running `configure'.
File: gccint.info, Node: Config Fragments, Next: System Config, Up: Configuration
6.3.2.1 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 target machine. The file `config.build' is used to
handle configuration specific to the particular build machine.
The file `config.host' is used to handle configuration specific to
the particular host machine. (In general, these should only be
used for features that cannot reasonably be tested in Autoconf
feature tests.) *Note The `config.build'; `config.host'; and
`config.gcc' Files: System Config, for details of the contents of
these files.
* 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
6.3.2.2 The `config.build'; `config.host'; and `config.gcc' Files
.................................................................
The `config.build' file contains specific rules for particular systems
which GCC is built on. This should be used as rarely as possible, as
the behavior of the build system can always be detected by autoconf.
The `config.host' file contains specific rules for particular systems
which GCC will run on. This is rarely needed.
The `config.gcc' file contains specific rules for particular systems
which GCC will generate code for. This is usually needed.
Each file has a list of the shell variables it sets, with
descriptions, at the top of the file.
FIXME: document the contents of these files, and what variables
should be set to control build, host and target configuration.
File: gccint.info, Node: Configuration Files, Prev: System Config, Up: Configuration
6.3.2.3 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
6.3.3 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
6.3.4 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 and man pages. Essentially it
calls `make man' and `make info'.
`dvi'
Produce DVI-formatted documentation.
`man'
Generate man pages.
`info'
Generate info-formatted 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'.
`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.
`srcextra'
Generates files in the source directory that do not exist in CVS
but should go into a release tarball. One example is
`gcc/c-parse.c' which is generated from the CVS source file
`gcc/c-parse.in'.
`srcinfo'
`srcman'
Copies the info-formatted and manpage documentation into the source
directory usually for the purpose of generating a release tarball.
`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
6.3.5 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
6.3.6 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
6.3.7 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
6.3.7.1 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
6.3.7.2 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
6.3.7.3 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'.
File: gccint.info, Node: Front End, Next: Back End, Prev: Documentation, Up: gcc Directory
6.3.8 Anatomy of a Language Front End
-------------------------------------
A front end for a language in GCC has the following parts:
* A directory `LANGUAGE' under `gcc' containing source files for
that front end. *Note The Front End `LANGUAGE' Directory: Front
End Directory, for details.
* A mention of the language in the list of supported languages in
`gcc/doc/install.texi'.
* A mention of the name under which the language's runtime library is
recognized by `--enable-shared=PACKAGE' in the documentation of
that option in `gcc/doc/install.texi'.
* A mention of any special prerequisites for building the front end
in the documentation of prerequisites in `gcc/doc/install.texi'.
* Details of contributors to that front end in
`gcc/doc/contrib.texi'. If the details are in that front end's
own manual then there should be a link to that manual's list in
`contrib.texi'.
* Information about support for that language in
`gcc/doc/frontends.texi'.
* Information about standards for that language, and the front end's
support for them, in `gcc/doc/standards.texi'. This may be a link
to such information in the front end's own manual.
* Details of source file suffixes for that language and `-x LANG'
options supported, in `gcc/doc/invoke.texi'.
* Entries in `default_compilers' in `gcc.c' for source file suffixes
for that language.
* Preferably testsuites, which may be under `gcc/testsuite' or
runtime library directories. FIXME: document somewhere how to
write testsuite harnesses.
* Probably a runtime library for the language, outside the `gcc'
directory. FIXME: document this further.
* Details of the directories of any runtime libraries in
`gcc/doc/sourcebuild.texi'.
If the front end is added to the official GCC CVS repository, the
following are also necessary:
* At least one Bugzilla component for bugs in that front end and
runtime libraries. This category needs to be mentioned in
`gcc/gccbug.in', as well as being added to the Bugzilla database.
* Normally, one or more maintainers of that front end listed in
`MAINTAINERS'.
* Mentions on the GCC web site in `index.html' and `frontends.html',
with any relevant links on `readings.html'. (Front ends that are
not an official part of GCC may also be listed on
`frontends.html', with relevant links.)
* A news item on `index.html', and possibly an announcement on the
<gcc-announce@gcc.gnu.org> mailing list.
* The front end's manuals should be mentioned in
`maintainer-scripts/update_web_docs' (*note Texinfo Manuals::) and
the online manuals should be linked to from
`onlinedocs/index.html'.
* Any old releases or CVS repositories of the front end, before its
inclusion in GCC, should be made available on the GCC FTP site
`ftp://gcc.gnu.org/pub/gcc/old-releases/'.
* The release and snapshot script `maintainer-scripts/gcc_release'
should be updated to generate appropriate tarballs for this front
end. The associated `maintainer-scripts/snapshot-README' and
`maintainer-scripts/snapshot-index.html' files should be updated
to list the tarballs and diffs for this front end.
* If this front end includes its own version files that include the
current date, `maintainer-scripts/update_version' should be
updated accordingly.
* `CVSROOT/modules' in the GCC CVS repository should be updated.
* Menu:
* Front End Directory:: The front end `LANGUAGE' directory.
* Front End Config:: The front end `config-lang.in' file.
File: gccint.info, Node: Front End Directory, Next: Front End Config, Up: Front End
6.3.8.1 The Front End `LANGUAGE' Directory
..........................................
A front end `LANGUAGE' directory contains the source files of that
front end (but not of any runtime libraries, which should be outside
the `gcc' directory). This includes documentation, and possibly some
subsidiary programs build alongside the front end. Certain files are
special and other parts of the compiler depend on their names:
`config-lang.in'
This file is required in all language subdirectories. *Note The
Front End `config-lang.in' File: Front End Config, for details of
its contents
`Make-lang.in'
This file is required in all language subdirectories. It contains
targets `LANG.HOOK' (where `LANG' is the setting of `language' in
`config-lang.in') for the following values of `HOOK', and any
other Makefile rules required to build those targets (which may if
necessary use other Makefiles specified in `outputs' in
`config-lang.in', although this is deprecated). Some hooks are
defined by using a double-colon rule for `HOOK', rather than by
using a target of form `LANG.HOOK'. These hooks are called
"double-colon hooks" below. It also adds any testsuite targets
that can use the standard rule in `gcc/Makefile.in' to the variable
`lang_checks'.
`all.build'
`all.cross'
`start.encap'
`rest.encap'
FIXME: exactly what goes in each of these targets?
`tags'
Build an `etags' `TAGS' file in the language subdirectory in
the source tree.
`info'
Build info documentation for the front end, in the build
directory. This target is only called by `make bootstrap' if
a suitable version of `makeinfo' is available, so does not
need to check for this, and should fail if an error occurs.
`dvi'
Build DVI documentation for the front end, in the build
directory. This should be done using `$(TEXI2DVI)', with
appropriate `-I' arguments pointing to directories of
included files. This hook is a double-colon hook.
`man'
Build generated man pages for the front end from Texinfo
manuals (*note Man Page Generation::), in the build
directory. This target is only called if the necessary tools
are available, but should ignore errors so as not to stop the
build if errors occur; man pages are optional and the tools
involved may be installed in a broken way.
`install-normal'
FIXME: what is this target for?
`install-common'
Install everything that is part of the front end, apart from
the compiler executables listed in `compilers' in
`config-lang.in'.
`install-info'
Install info documentation for the front end, if it is
present in the source directory. This target should have
dependencies on info files that should be installed. This
hook is a double-colon hook.
`install-man'
Install man pages for the front end. This target should
ignore errors.
`srcextra'
Copies its dependencies into the source directory. This
generally should be used for generated files such as
`gcc/c-parse.c' which are not present in CVS, but should be
included in any release tarballs. This target will be
executed during a bootstrap if
`--enable-generated-files-in-srcdir' was specified as a
`configure' option.
`srcinfo'
`srcman'
Copies its dependencies into the source directory. These
targets will be executed during a bootstrap if
`--enable-generated-files-in-srcdir' was specified as a
`configure' option.
`uninstall'
Uninstall files installed by installing the compiler. This is
currently documented not to be supported, so the hook need
not do anything.
`mostlyclean'
`clean'
`distclean'
`maintainer-clean'
The language parts of the standard GNU `*clean' targets.
*Note Standard Targets for Users: (standards)Standard
Targets, for details of the standard targets. For GCC,
`maintainer-clean' should delete all generated files in the
source directory that are not checked into CVS, but should
not delete anything checked into CVS.
`stage1'
`stage2'
`stage3'
`stage4'
`stageprofile'
`stagefeedback'
Move to the stage directory files not included in
`stagestuff' in `config-lang.in' or otherwise moved by the
main `Makefile'.
`lang.opt'
This file registers the set of switches that the front end accepts
on the command line, and their -help text. The file format is
documented in the file `c.opt'. These files are processed by the
script `opts.sh'.
`lang-specs.h'
This file provides entries for `default_compilers' in `gcc.c'
which override the default of giving an error that a compiler for
that language is not installed.
`LANGUAGE-tree.def'
This file, which need not exist, defines any language-specific tree
codes.
File: gccint.info, Node: Front End Config, Prev: Front End Directory, Up: Front End
6.3.8.2 The Front End `config-lang.in' File
...........................................
Each language subdirectory contains a `config-lang.in' file. In
addition the main directory contains `c-config-lang.in', which contains
limited information for the C language. This file is a shell script
that may define some variables describing the language:
`language'
This definition must be present, and gives the name of the language
for some purposes such as arguments to `--enable-languages'.
`lang_requires'
If defined, this variable lists (space-separated) language front
ends other than C that this front end requires to be enabled (with
the names given being their `language' settings). For example, the
Java front end depends on the C++ front end, so sets
`lang_requires=c++'.
`target_libs'
If defined, this variable lists (space-separated) targets in the
top level `Makefile' to build the runtime libraries for this
language, such as `target-libobjc'.
`lang_dirs'
If defined, this variable lists (space-separated) top level
directories (parallel to `gcc'), apart from the runtime libraries,
that should not be configured if this front end is not built.
`build_by_default'
If defined to `no', this language front end is not built unless
enabled in a `--enable-languages' argument. Otherwise, front ends
are built by default, subject to any special logic in
`configure.ac' (as is present to disable the Ada front end if the
Ada compiler is not already installed).
`boot_language'
If defined to `yes', this front end is built in stage 1 of the
bootstrap. This is only relevant to front ends written in their
own languages.
`compilers'
If defined, a space-separated list of compiler executables that
will be run by the driver. The names here will each end with
`\$(exeext)'.
`stagestuff'
If defined, a space-separated list of files that should be moved to
the `stageN' directories in each stage of bootstrap.
`outputs'
If defined, a space-separated list of files that should be
generated by `configure' substituting values in them. This
mechanism can be used to create a file `LANGUAGE/Makefile' from
`LANGUAGE/Makefile.in', but this is deprecated, building
everything from the single `gcc/Makefile' is preferred.
`gtfiles'
If defined, a space-separated list of files that should be scanned
by gengtype.c to generate the garbage collection tables and
routines for this language. This excludes the files that are
common to all front ends. *Note Type Information::.
File: gccint.info, Node: Back End, Prev: Front End, Up: gcc Directory
6.3.9 Anatomy of a Target Back End
----------------------------------
A back end for a target architecture in GCC has the following parts:
* A directory `MACHINE' under `gcc/config', containing a machine
description `MACHINE.md' file (*note Machine Descriptions: Machine
Desc.), header files `MACHINE.h' and `MACHINE-protos.h' and a
source file `MACHINE.c' (*note Target Description Macros and
Functions: Target Macros.), possibly a target Makefile fragment
`t-MACHINE' (*note The Target Makefile Fragment: Target
Fragment.), and maybe some other files. The names of these files
may be changed from the defaults given by explicit specifications
in `config.gcc'.
* If necessary, a file `MACHINE-modes.def' in the `MACHINE'
directory, containing additional machine modes to represent
condition codes. *Note Condition Code::, for further details.
* Entries in `config.gcc' (*note The `config.gcc' File: System
Config.) for the systems with this target architecture.
* Documentation in `gcc/doc/invoke.texi' for any command-line
options supported by this target (*note Run-time Target
Specification: Run-time Target.). This means both entries in the
summary table of options and details of the individual options.
* Documentation in `gcc/doc/extend.texi' for any target-specific
attributes supported (*note Defining target-specific uses of
`__attribute__': Target Attributes.), including where the same
attribute is already supported on some targets, which are
enumerated in the manual.
* Documentation in `gcc/doc/extend.texi' for any target-specific
pragmas supported.
* Documentation in `gcc/doc/extend.texi' of any target-specific
built-in functions supported.
* Documentation in `gcc/doc/md.texi' of any target-specific
constraint letters (*note Constraints for Particular Machines:
Machine Constraints.).
* A note in `gcc/doc/contrib.texi' under the person or people who
contributed the target support.
* Entries in `gcc/doc/install.texi' for all target triplets
supported with this target architecture, giving details of any
special notes about installation for this target, or saying that
there are no special notes if there are none.
* Possibly other support outside the `gcc' directory for runtime
libraries. FIXME: reference docs for this. The libstdc++ porting
manual needs to be installed as info for this to work, or to be a
chapter of this manual.
If the back end is added to the official GCC CVS repository, the
following are also necessary:
* An entry for the target architecture in `readings.html' on the GCC
web site, with any relevant links.
* Details of the properties of the back end and target architecture
in `backends.html' on the GCC web site.
* A news item about the contribution of support for that target
architecture, in `index.html' on the GCC web site.
* Normally, one or more maintainers of that target listed in
`MAINTAINERS'. Some existing architectures may be unmaintained,
but it would be unusual to add support for a target that does not
have a maintainer when support is added.
File: gccint.info, Node: Testsuites, Prev: gcc Directory, Up: Source Tree
6.4 Testsuites
==============
GCC contains several testsuites to help maintain compiler quality.
Most of the runtime libraries and language front ends in GCC have
testsuites. Currently only the C language testsuites are documented
here; FIXME: document the others.
* Menu:
* Test Idioms:: Idioms used in testsuite code.
* Ada Tests:: The Ada language testsuites.
* C Tests:: The C language testsuites.
* libgcj Tests:: The Java library testsuites.
* gcov Testing:: Support for testing gcov.
* profopt Testing:: Support for testing profile-directed optimizations.
* compat Testing:: Support for testing binary compatibility.
File: gccint.info, Node: Test Idioms, Next: Ada Tests, Up: Testsuites
6.4.1 Idioms Used in Testsuite Code
-----------------------------------
In general C testcases have a trailing `-N.c', starting with `-1.c', in
case other testcases with similar names are added later. If the test
is a test of some well-defined feature, it should have a name referring
to that feature such as `FEATURE-1.c'. If it does not test a
well-defined feature but just happens to exercise a bug somewhere in
the compiler, and a bug report has been filed for this bug in the GCC
bug database, `prBUG-NUMBER-1.c' is the appropriate form of name.
Otherwise (for miscellaneous bugs not filed in the GCC bug database),
and previously more generally, test cases are named after the date on
which they were added. This allows people to tell at a glance whether
a test failure is because of a recently found bug that has not yet been
fixed, or whether it may be a regression, but does not give any other
information about the bug or where discussion of it may be found. Some
other language testsuites follow similar conventions.
Test cases should use `abort ()' to indicate failure and `exit (0)'
for success; on some targets these may be redefined to indicate failure
and success in other ways.
In the `gcc.dg' testsuite, it is often necessary to test that an
error is indeed a hard error and not just a warning--for example, where
it is a constraint violation in the C standard, which must become an
error with `-pedantic-errors'. The following idiom, where the first
line shown is line LINE of the file and the line that generates the
error, is used for this:
/* { dg-bogus "warning" "warning in place of error" } */
/* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */
It may be necessary to check that an expression is an integer
constant expression and has a certain value. To check that `E' has
value `V', an idiom similar to the following is used:
char x[((E) == (V) ? 1 : -1)];
In `gcc.dg' tests, `__typeof__' is sometimes used to make assertions
about the types of expressions. See, for example,
`gcc.dg/c99-condexpr-1.c'. The more subtle uses depend on the exact
rules for the types of conditional expressions in the C standard; see,
for example, `gcc.dg/c99-intconst-1.c'.
It is useful to be able to test that optimizations are being made
properly. This cannot be done in all cases, but it can be done where
the optimization will lead to code being optimized away (for example,
where flow analysis or alias analysis should show that certain code
cannot be called) or to functions not being called because they have
been expanded as built-in functions. Such tests go in
`gcc.c-torture/execute'. Where code should be optimized away, a call
to a nonexistent function such as `link_failure ()' may be inserted; a
definition
#ifndef __OPTIMIZE__
void
link_failure (void)
{
abort ();
}
#endif
will also be needed so that linking still succeeds when the test is run
without optimization. When all calls to a built-in function should
have been optimized and no calls to the non-built-in version of the
function should remain, that function may be defined as `static' to
call `abort ()' (although redeclaring a function as static may not work
on all targets).
All testcases must be portable. Target-specific testcases must have
appropriate code to avoid causing failures on unsupported systems;
unfortunately, the mechanisms for this differ by directory.
FIXME: discuss non-C testsuites here.
File: gccint.info, Node: Ada Tests, Next: C Tests, Prev: Test Idioms, Up: Testsuites
6.4.2 Ada Language Testsuites
-----------------------------
The Ada testsuite includes executable tests from the ACATS 2.5
testsuite, publicly available at
`http://www.adaic.org/compilers/acats/2.5'
These tests are integrated in the GCC testsuite in the
`gcc/testsuite/ada/acats' directory, and enabled automatically when
running `make check', assuming the Ada language has been enabled when
configuring GCC.
You can also run the Ada testsuite independently, using `make
check-ada', or run a subset of the tests by specifying which chapter to
run, e.g:
$ make check-ada CHAPTERS="c3 c9"
The tests are organized by directory, each directory corresponding to
a chapter of the Ada Reference Manual. So for example, c9 corresponds
to chapter 9, which deals with tasking features of the language.
There is also an extra chapter called `gcc' containing a template for
creating new executable tests.
The tests are run using two 'sh' scripts: run_acats and run_all.sh
To run the tests using a simulator or a cross target, see the small
customization section at the top of run_all.sh
These tests are run using the build tree: they can be run without
doing a `make install'.
File: gccint.info, Node: C Tests, Next: libgcj Tests, Prev: Ada Tests, Up: Testsuites
6.4.3 C Language Testsuites
---------------------------
GCC contains the following C language testsuites, in the
`gcc/testsuite' directory:
`gcc.dg'
This contains tests of particular features of the C compiler,
using the more modern `dg' harness. Correctness tests for various
compiler features should go here if possible.
Magic comments determine whether the file is preprocessed,
compiled, linked or run. In these tests, error and warning
message texts are compared against expected texts or regular
expressions given in comments. These tests are run with the
options `-ansi -pedantic' unless other options are given in the
test. Except as noted below they are not run with multiple
optimization options.
`gcc.dg/compat'
This subdirectory contains tests for binary compatibility using
`compat.exp', which in turn uses the language-independent support
(*note Support for testing binary compatibility: compat Testing.).
`gcc.dg/cpp'
This subdirectory contains tests of the preprocessor.
`gcc.dg/debug'
This subdirectory contains tests for debug formats. Tests in this
subdirectory are run for each debug format that the compiler
supports.
`gcc.dg/format'
This subdirectory contains tests of the `-Wformat' format
checking. Tests in this directory are run with and without
`-DWIDE'.
`gcc.dg/noncompile'
This subdirectory contains tests of code that should not compile
and does not need any special compilation options. They are run
with multiple optimization options, since sometimes invalid code
crashes the compiler with optimization.
`gcc.dg/special'
FIXME: describe this.
`gcc.c-torture'
This contains particular code fragments which have historically
broken easily. These tests are run with multiple optimization
options, so tests for features which only break at some
optimization levels belong here. This also contains tests to
check that certain optimizations occur. It might be worthwhile to
separate the correctness tests cleanly from the code quality
tests, but it hasn't been done yet.
`gcc.c-torture/compat'
FIXME: describe this.
This directory should probably not be used for new tests.
`gcc.c-torture/compile'
This testsuite contains test cases that should compile, but do not
need to link or run. These test cases are compiled with several
different combinations of optimization options. All warnings are
disabled for these test cases, so this directory is not suitable if
you wish to test for the presence or absence of compiler warnings.
While special options can be set, and tests disabled on specific
platforms, by the use of `.x' files, mostly these test cases
should not contain platform dependencies. FIXME: discuss how
defines such as `NO_LABEL_VALUES' and `STACK_SIZE' are used.
`gcc.c-torture/execute'
This testsuite contains test cases that should compile, link and
run; otherwise the same comments as for `gcc.c-torture/compile'
apply.
`gcc.c-torture/execute/ieee'
This contains tests which are specific to IEEE floating point.
`gcc.c-torture/unsorted'
FIXME: describe this.
This directory should probably not be used for new tests.
`gcc.c-torture/misc-tests'
This directory contains C tests that require special handling.
Some of these tests have individual expect files, and others share
special-purpose expect files:
``bprob*.c''
Test `-fbranch-probabilities' using `bprob.exp', which in
turn uses the generic, language-independent framework (*note
Support for testing profile-directed optimizations: profopt
Testing.).
``dg-*.c''
Test the testsuite itself using `dg-test.exp'.
``gcov*.c''
Test `gcov' output using `gcov.exp', which in turn uses the
language-independent support (*note Support for testing gcov:
gcov Testing.).
``i386-pf-*.c''
Test i386-specific support for data prefetch using
`i386-prefetch.exp'.
FIXME: merge in `testsuite/README.gcc' and discuss the format of
test cases and magic comments more.
File: gccint.info, Node: libgcj Tests, Next: gcov Testing, Prev: C Tests, Up: Testsuites
6.4.4 The Java library testsuites.
----------------------------------
Runtime tests are executed via `make check' in the
`TARGET/libjava/testsuite' directory in the build tree. Additional
runtime tests can be checked into this testsuite.
Regression testing of the core packages in libgcj is also covered by
the Mauve testsuite. The Mauve Project develops tests for the Java
Class Libraries. These tests are run as part of libgcj testing by
placing the Mauve tree within the libjava testsuite sources at
`libjava/testsuite/libjava.mauve/mauve', or by specifying the location
of that tree when invoking `make', as in `make MAUVEDIR=~/mauve check'.
To detect regressions, a mechanism in `mauve.exp' compares the
failures for a test run against the list of expected failures in
`libjava/testsuite/libjava.mauve/xfails' from the source hierarchy.
Update this file when adding new failing tests to Mauve, or when fixing
bugs in libgcj that had caused Mauve test failures.
The Jacks project provides a testsuite for Java compilers that can
be used to test changes that affect the GCJ front end. This testsuite
is run as part of Java testing by placing the Jacks tree within the the
libjava testsuite sources at `libjava/testsuite/libjava.jacks/jacks'.
We encourage developers to contribute test cases to Mauve and Jacks.
File: gccint.info, Node: gcov Testing, Next: profopt Testing, Prev: libgcj Tests, Up: Testsuites
6.4.5 Support for testing `gcov'
--------------------------------
Language-independent support for testing `gcov', and for checking that
branch profiling produces expected values, is provided by the expect
file `gcov.exp'. `gcov' tests also rely on procedures in `gcc.dg.exp'
to compile and run the test program. A typical `gcov' test contains
the following DejaGNU commands within comments:
{ dg-options "-fprofile-arcs -ftest-coverage" }
{ dg-do run { target native } }
{ dg-final { run-gcov sourcefile } }
Checks of `gcov' output can include line counts, branch percentages,
and call return percentages. All of these checks are requested via
commands that appear in comments in the test's source file. Commands
to check line counts are processed by default. Commands to check
branch percentages and call return percentages are processed if the
`run-gcov' command has arguments `branches' or `calls', respectively.
For example, the following specifies checking both, as well as passing
`-b' to `gcov':
{ dg-final { run-gcov branches calls { -b sourcefile } } }
A line count command appears within a comment on the source line
that is expected to get the specified count and has the form
`count(CNT)'. A test should only check line counts for lines that will
get the same count for any architecture.
Commands to check branch percentages (`branch') and call return
percentages (`returns') are very similar to each other. A beginning
command appears on or before the first of a range of lines that will
report the percentage, and the ending command follows that range of
lines. The beginning command can include a list of percentages, all of
which are expected to be found within the range. A range is terminated
by the next command of the same kind. A command `branch(end)' or
`returns(end)' marks the end of a range without starting a new one.
For example:
if (i > 10 && j > i && j < 20) /* branch(27 50 75) */
/* branch(end) */
foo (i, j);
For a call return percentage, the value specified is the percentage
of calls reported to return. For a branch percentage, the value is
either the expected percentage or 100 minus that value, since the
direction of a branch can differ depending on the target or the
optimization level.
Not all branches and calls need to be checked. A test should not
check for branches that might be optimized away or replaced with
predicated instructions. Don't check for calls inserted by the
compiler or ones that might be inlined or optimized away.
A single test can check for combinations of line counts, branch
percentages, and call return percentages. The command to check a line
count must appear on the line that will report that count, but commands
to check branch percentages and call return percentages can bracket the
lines that report them.
File: gccint.info, Node: profopt Testing, Next: compat Testing, Prev: gcov Testing, Up: Testsuites
6.4.6 Support for testing profile-directed optimizations
--------------------------------------------------------
The file `profopt.exp' provides language-independent support for
checking correct execution of a test built with profile-directed
optimization. This testing requires that a test program be built and
executed twice. The first time it is compiled to generate profile
data, and the second time it is compiled to use the data that was
generated during the first execution. The second execution is to
verify that the test produces the expected results.
To check that the optimization actually generated better code, a
test can be built and run a third time with normal optimizations to
verify that the performance is better with the profile-directed
optimizations. `profopt.exp' has the beginnings of this kind of
support.
`profopt.exp' provides generic support for profile-directed
optimizations. Each set of tests that uses it provides information
about a specific optimization:
`tool'
tool being tested, e.g., `gcc'
`profile_option'
options used to generate profile data
`feedback_option'
options used to optimize using that profile data
`prof_ext'
suffix of profile data files
`PROFOPT_OPTIONS'
list of options with which to run each test, similar to the lists
for torture tests
File: gccint.info, Node: compat Testing, Prev: profopt Testing, Up: Testsuites
6.4.7 Support for testing binary compatibility
----------------------------------------------
The file `compat.exp' provides language-independent support for binary
compatibility testing. It supports testing interoperability of two
compilers that follow the same ABI, or of multiple sets of compiler
options that should not affect binary compatibility. It is intended to
be used for testsuites that complement ABI testsuites.
A test supported by this framework has three parts, each in a
separate source file: a main program and two pieces that interact with
each other to split up the functionality being tested.
`TESTNAME_main.SUFFIX'
Contains the main program, which calls a function in file
`TESTNAME_x.SUFFIX'.
`TESTNAME_x.SUFFIX'
Contains at least one call to a function in `TESTNAME_y.SUFFIX'.
`TESTNAME_y.SUFFIX'
Shares data with, or gets arguments from, `TESTNAME_x.SUFFIX'.
Within each test, the main program and one functional piece are
compiled by the GCC under test. The other piece can be compiled by an
alternate compiler. If no alternate compiler is specified, then all
three source files are all compiled by the GCC under test. It's also
possible to specify a pair of lists of compiler options, one list for
each compiler, so that each test will be compiled with each pair of
options.
`compat.exp' defines default pairs of compiler options. These can
be overridden by defining the environment variable `COMPAT_OPTIONS' as:
COMPAT_OPTIONS="[list [list {TST1} {ALT1}]
...[list {TSTN} {ALTN}]]"
where TSTI and ALTI are lists of options, with TSTI used by the
compiler under test and ALTI used by the alternate compiler. For
example, with `[list [list {-g -O0} {-O3}] [list {-fpic} {-fPIC -O2}]]',
the test is first built with `-g -O0' by the compiler under test and
with `-O3' by the alternate compiler. The test is built a second time
using `-fpic' by the compiler under test and `-fPIC -O2' by the
alternate compiler.
An alternate compiler is specified by defining an environment
variable; for C++ define `ALT_CXX_UNDER_TEST' to be the full pathname
of an installed compiler. That will be written to the `site.exp' file
used by DejaGNU. The default is to build each test with the compiler
under test using the first of each pair of compiler options from
`COMPAT_OPTIONS'. When `ALT_CXX_UNDER_TEST' is `same', each test is
built using the compiler under test but with combinations of the
options from `COMPAT_OPTIONS'.
To run only the C++ compatibility suite using the compiler under test
and another version of GCC using specific compiler options, do the
following from `OBJDIR/gcc':
rm site.exp
make -k \
ALT_CXX_UNDER_TEST=${alt_prefix}/bin/g++ \
COMPAT_OPTIONS="lists as shown above" \
check-c++ \
RUNTESTFLAGS="compat.exp"
A test that fails when the source files are compiled with different
compilers, but passes when the files are compiled with the same
compiler, demonstrates incompatibility of the generated code or runtime
support. A test that fails for the alternate compiler but passes for
the compiler under test probably tests for a bug that was fixed in the
compiler under test but is present in the alternate compiler.
File: gccint.info, Node: Passes, Next: Trees, Prev: Source Tree, Up: Top
7 Passes and Files of the Compiler
**********************************
The overall control structure of the compiler is in `toplev.c'. This
file is responsible for initialization, decoding arguments, opening and
closing files, and sequencing the passes. Routines for emitting
diagnostic messages are defined in `diagnostic.c'. The files
`pretty-print.h' and `pretty-print.c' provide basic support for
language-independent pretty-printing.
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 `expr.c', `expmed.c', and `stmt.c'. 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.
Each time the parsing pass reads a complete function definition or
top-level declaration, it calls either the function
`rest_of_compilation', or the function `rest_of_decl_compilation' in
`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 `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). (*note An Inline Function is As Fast As a
Macro: (gcc)Inline.).
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 `-d' options.
* 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 `tree.c',
`fold-const.c', and `stor-layout.c'. There are also header files
`tree.h' and `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 *Note
Cpplib internals: (cppinternals)Top.
The source files to parse C are found in the toplevel directory,
and by convention are named `c-*'. Some of these are also used by
the other C-like languages: `c-common.c', `c-common.def',
`c-format.c', `c-opts.c', `c-pragma.c', `c-semantics.c', `c-lex.c',
`c-incpath.c', `c-ppoutput.c', `c-cppbuiltin.c', `c-common.h',
`c-dump.h', `c.opt', `c-incpath.h' and `c-pragma.h',
Files specific to each language are in subdirectories named after
the language in question, like `ada', `objc', `cp' (for C++).
* Tree optimization. This is the optimization of the tree
representation, before converting into RTL code.
Currently, the main optimization performed here is tree-based
inlining. This is implemented in `tree-inline.c' and used by both
C and 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).
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 `fold-const.c'.
* RTL generation. This is the conversion of syntax tree into RTL
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.
Optimization is done in this pass for `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 `switch' statements.
The source files for RTL generation include `stmt.c', `calls.c',
`expr.c', `explow.c', `expmed.c', `function.c', `optabs.c' and
`emit-rtl.c'. Also, the file `insn-emit.c', generated from the
machine description by the program `genemit', is used in this
pass. The header file `expr.h' is used for communication within
this pass.
The header files `insn-flags.h' and `insn-codes.h', generated from
the machine description by the programs `genflags' and `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).
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 `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 `integrate.h' is also used for this purpose.
The option `-dr' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.rtl' to
the input file name.
* Sibling 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 `sibcall.c'
The option `-di' causes a debugging dump of the RTL code after
this pass is run. This dump file's name is made by appending
`.sibling' to the input file name.
* 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 `jump.c'.
The 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 `.jump' to the input file name.
* Register scan. This pass finds the first and last use of each
register, as a guide for common subexpression elimination. Its
source is in `regclass.c'.
* Jump threading. This pass detects a condition jump that branches
to an identical or inverse test. Such jumps can be `threaded'
through the second conditional test. The source code for this
pass is in `jump.c'. This optimization is only performed if
`-fthread-jumps' is enabled.
* Common subexpression elimination. This pass also does constant
propagation. Its source files are `cse.c', and `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.
The option `-ds' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.cse' to
the input file name.
* 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 `gcse.c', and the LCM routines
are in `lcm.c'.
The option `-dG' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.gcse' to
the input file name.
* Loop optimization. This pass moves constant expressions out of
loops, and optionally does strength-reduction and loop unrolling
as well. Its source files are `loop.c' and `unroll.c', plus the
header `loop.h' used for communication between them. Loop
unrolling uses some functions in `integrate.c' and the header
`integrate.h'. Loop dependency analysis routines are contained in
`dependence.c'.
Second loop optimization pass takes care of basic block level
optimizations - unrolling, peeling and unswitching loops. The
source files are `cfgloopanal.c' and `cfgloopmanip.c' containing
generic loop analysis and manipulation code, `loop-init.c' with
initialization and finalization code, `loop-unswitch.c' for loop
unswitching and `loop-unroll.c' for loop unrolling and peeling.
The option `-dL' causes a debugging dump of the RTL code after
these passes. The dump file names are made by appending `.loop'
and `.loop2' to the input file name.
* Jump bypassing. This pass is an aggressive form of GCSE that
transforms the control flow graph of a function by propagating
constants into conditional branch instructions.
The source file for this pass is `gcse.c'.
The option `-dG' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.bypass'
to the input file name.
* Simple optimization pass that splits independent uses of each
pseudo increasing effect of other optimizations. This can improve
effect of the other transformation, such as CSE or register
allocation. Its source files are `web.c'.
The option `-dZ' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.web' to
the input file name.
* If `-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.
The option `-dt' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.cse2' to
the input file name.
* Data flow analysis (`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.
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.
The option `-df' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.flow' to
the input file name. If stupid register allocation is in use, this
dump file reflects the full results of such allocation.
* Instruction combination (`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.
The option `-dc' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.combine'
to the input file name.
* 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
`ifcvt.c'.
The option `-dE' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.ce' to
the input file name.
* Register movement (`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.
The option `-dN' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.regmove'
to the input file name.
* Instruction scheduling (`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.
The 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 `.sched' to the input file name.
* Register allocation. These passes make sure that all occurrences
of pseudo registers are eliminated, either by allocating them to a
hard register, replacing them by an equivalent expression (e.g. a
constant) or by placing them on the stack. This is done in
several subpasses:
* Register class preferencing. The RTL code is scanned to find
out which register class is best for each pseudo register.
The source file is `regclass.c'.
* Local register allocation (`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.
The option `-dl' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending
`.lreg' to the input file name.
* Global register allocation (`global.c'). This pass allocates
hard registers for the remaining pseudo registers (those
whose life spans are not contained in one basic block).
* Graph coloring register allocator. The files `ra.c',
`ra-build.c', `ra-colorize.c', `ra-debug.c', `ra-rewrite.c'
together with the header `ra.h' contain another register
allocator, which is used when the option `-fnew-ra' is given.
In that case it is run instead of the above mentioned local
and global register allocation passes, and the option `-dl'
causes a debugging dump of its work.
* 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 `reload.c' and `reload1.c', plus the header
`reload.h' used for communication between them.
The option `-dg' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending
`.greg' to the input file name.
* Instruction scheduling is repeated here to try to avoid pipeline
stalls due to memory loads generated for spilled pseudo registers.
The option `-dR' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.sched2'
to the input file name.
* 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
`bb-reorder.c', and the various prediction routines are in
`predict.c'.
The option `-dB' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.bbro' to
the input file name.
* 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
`reorg.c'.
The option `-dd' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.dbr' to
the input file name.
* 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.
* 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 `reg-stack.c'.
The options `-dk' causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending `.stack' to
the input file name.
* 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 `final.c' plus `insn-output.c'; the latter is
generated automatically from the machine description by the tool
`genoutput'. The header file `conditions.h' is used for
communication between these files.
* 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 `dbxout.c' for DBX
symbol table format, `sdbout.c' for SDB symbol table format,
`dwarfout.c' for DWARF symbol table format, files `dwarf2out.c' and
`dwarf2asm.c' for DWARF2 symbol table format, and `vmsdbgout.c'
for VMS debug symbol table format.
Some additional files are used by all or many passes:
* Every pass uses `machmode.def' and `machmode.h' which define the
machine modes.
* Several passes use `real.h', which defines the default
representation of floating point constants and how to operate on
them.
* All the passes that work with RTL use the header files `rtl.h' and
`rtl.def', and subroutines in file `rtl.c'. The tools `gen*' also
use these files to read and work with the machine description RTL.
* All the tools that read the machine description use support
routines found in `gensupport.c', `errors.c', and `read-rtl.c'.
* Several passes refer to the header file `insn-config.h' which
contains a few parameters (C macro definitions) generated
automatically from the machine description RTL by the tool
`genconfig'.
* Several passes use the instruction recognizer, which consists of
`recog.c' and `recog.h', plus the files `insn-recog.c' and
`insn-extract.c' that are generated automatically from the machine
description by the tools `genrecog' and `genextract'.
* Several passes use the header files `regs.h' which defines the
information recorded about pseudo register usage, and
`basic-block.h' which defines the information recorded about basic
blocks.
* `hard-reg-set.h' defines the type `HARD_REG_SET', a bit-vector
with a bit for each hard register, and some macros to manipulate
it. This type is just `int' if the machine has few enough hard
registers; otherwise it is an array of `int' and some of the
macros expand into loops.
* Several passes use instruction attributes. A definition of the
attributes defined for a particular machine is in file
`insn-attr.h', which is generated from the machine description by
the program `genattr'. The file `insn-attrtab.c' contains
subroutines to obtain the attribute values for insns and
information about processor pipeline characteristics for the
instruction scheduler. It is generated from the machine
description by the program `genattrtab'.
File: gccint.info, Node: Trees, Next: RTL, Prev: Passes, Up: Top
8 Trees: The intermediate representation used by the C and C++ front ends
*************************************************************************
This chapter documents the internal representation used by GCC to
represent C and C++ source programs. When presented with a C or C++
source program, GCC parses the program, performs semantic analysis
(including the generation of error messages), and then produces the
internal representation described here. This representation contains a
complete representation for the entire translation unit provided as
input to the front end. This representation is then typically processed
by a code-generator in order to produce machine code, but could also be
used in the creation of source browsers, intelligent editors, automatic
documentation generators, interpreters, and any other programs needing
the ability to process C or C++ code.
This chapter explains the internal representation. In particular, it
documents the internal representation for C and C++ source constructs,
and the macros, functions, and variables that can be used to access
these constructs. The C++ representation is largely a superset of the
representation used in the C front end. There is only one construct
used in C that does not appear in the C++ front end and that is the GNU
"nested function" extension. Many of the macros documented here do not
apply in C because the corresponding language constructs do not appear
in C.
If you are developing a "back end", be it is a code-generator or some
other tool, that uses this representation, you may occasionally find
that you need to ask questions not easily answered by the functions and
macros available here. If that situation occurs, it is quite likely
that GCC already supports the functionality you desire, but that the
interface is simply not documented here. In that case, you should ask
the GCC maintainers (via mail to <gcc@gcc.gnu.org>) about documenting
the functionality you require. Similarly, if you find yourself writing
functions that do not deal directly with your back end, but instead
might be useful to other people using the GCC front end, you should
submit your patches for inclusion in GCC.
* Menu:
* Deficiencies:: Topics net yet covered in this document.
* Tree overview:: All about `tree's.
* Types:: Fundamental and aggregate types.
* Scopes:: Namespaces and classes.
* Functions:: Overloading, function bodies, and linkage.
* Declarations:: Type declarations and variables.
* Attributes:: Declaration and type attributes.
* Expression trees:: From `typeid' to `throw'.
File: gccint.info, Node: Deficiencies, Next: Tree overview, Up: Trees
8.1 Deficiencies
================
There are many places in which this document is incomplet and incorrekt.
It is, as of yet, only _preliminary_ documentation.
File: gccint.info, Node: Tree overview, Next: Types, Prev: Deficiencies, Up: Trees
8.2 Overview
============
The central data structure used by the internal representation is the
`tree'. These nodes, while all of the C type `tree', are of many
varieties. A `tree' is a pointer type, but the object to which it
points may be of a variety of types. From this point forward, we will
refer to trees in ordinary type, rather than in `this font', except
when talking about the actual C type `tree'.
You can tell what kind of node a particular tree is by using the
`TREE_CODE' macro. Many, many macros take trees as input and return
trees as output. However, most macros require a certain kind of tree
node as input. In other words, there is a type-system for trees, but
it is not reflected in the C type-system.
For safety, it is useful to configure GCC with `--enable-checking'.
Although this results in a significant performance penalty (since all
tree types are checked at run-time), and is therefore inappropriate in a
release version, it is extremely helpful during the development process.
Many macros behave as predicates. Many, although not all, of these
predicates end in `_P'. Do not rely on the result type of these macros
being of any particular type. You may, however, rely on the fact that
the type can be compared to `0', so that statements like
if (TEST_P (t) && !TEST_P (y))
x = 1;
and
int i = (TEST_P (t) != 0);
are legal. Macros that return `int' values now may be changed to
return `tree' values, or other pointers in the future. Even those that
continue to return `int' may return multiple nonzero codes where
previously they returned only zero and one. Therefore, you should not
write code like
if (TEST_P (t) == 1)
as this code is not guaranteed to work correctly in the future.
You should not take the address of values returned by the macros or
functions described here. In particular, no guarantee is given that the
values are lvalues.
In general, the names of macros are all in uppercase, while the
names of functions are entirely in lowercase. There are rare
exceptions to this rule. You should assume that any macro or function
whose name is made up entirely of uppercase letters may evaluate its
arguments more than once. You may assume that a macro or function
whose name is made up entirely of lowercase letters will evaluate its
arguments only once.
The `error_mark_node' is a special tree. Its tree code is
`ERROR_MARK', but since there is only ever one node with that code, the
usual practice is to compare the tree against `error_mark_node'. (This
test is just a test for pointer equality.) If an error has occurred
during front-end processing the flag `errorcount' will be set. If the
front end has encountered code it cannot handle, it will issue a
message to the user and set `sorrycount'. When these flags are set,
any macro or function which normally returns a tree of a particular
kind may instead return the `error_mark_node'. Thus, if you intend to
do any processing of erroneous code, you must be prepared to deal with
the `error_mark_node'.
Occasionally, a particular tree slot (like an operand to an
expression, or a particular field in a declaration) will be referred to
as "reserved for the back end." These slots are used to store RTL when
the tree is converted to RTL for use by the GCC back end. However, if
that process is not taking place (e.g., if the front end is being hooked
up to an intelligent editor), then those slots may be used by the back
end presently in use.
If you encounter situations that do not match this documentation,
such as tree nodes of types not mentioned here, or macros documented to
return entities of a particular kind that instead return entities of
some different kind, you have found a bug, either in the front end or in
the documentation. Please report these bugs as you would any other bug.
* Menu:
* Macros and Functions::Macros and functions that can be used with all trees.
* Identifiers:: The names of things.
* Containers:: Lists and vectors.
File: gccint.info, Node: Macros and Functions, Next: Identifiers, Up: Tree overview
8.2.1 Trees
-----------
This section is not here yet.
File: gccint.info, Node: Identifiers, Next: Containers, Prev: Macros and Functions, Up: Tree overview
8.2.2 Identifiers
-----------------
An `