This is doc/gccint.info, produced by makeinfo version 4.3 from
doc/gccint.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

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

   Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002 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.1 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.2.2.
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.
* 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.

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

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

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


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

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

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

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

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

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


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

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

   The main goal of GCC was to make a good, fast compiler for machines
in the class that the GNU system aims to run on: 32-bit machines that
address 8-bit bytes and have several general registers.  Elegance,
theoretical power and simplicity are only secondary.

   GCC gets most of the information about the target machine from a
machine description which gives an algebraic formula for each of the
machine's instructions.  This is a very clean way to describe the
target.  But when the compiler needs information that is difficult to
express in this fashion, I have not hesitated to define an ad-hoc
parameter to the machine description.  The purpose of portability is to
reduce the total work needed on the compiler; it was not of interest
for its own sake.

   GCC does not contain machine dependent code, but it does contain code
that depends on machine parameters such as endianness (whether the most
significant byte has the highest or lowest address of the bytes in a
word) and the availability of autoincrement addressing.  In the
RTL-generation pass, it is often necessary to have multiple strategies
for generating code for a particular kind of syntax tree, strategies
that are usable for different combinations of parameters.  Often I have
not tried to address all possible cases, but only the common ones or
only the ones that I have encountered.  As a result, a new target may
require additional strategies.  You will know if this happens because
the compiler will call `abort'.  Fortunately, the new strategies can be
added in a machine-independent fashion, and will affect only the target
machines that need them.


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

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

   GCC is normally configured to use the same function calling
convention normally in use on the target system.  This is done with the
machine-description macros described (*note Target Macros::).

   However, returning of structure and union values is done differently
on some target machines.  As a result, functions compiled with PCC
returning such types cannot be called from code compiled with GCC, and
vice versa.  This does not cause trouble often because few Unix library
routines return structures or unions.

   GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
long in the same registers used for `int' or `double' return values.
(GCC typically allocates variables of such types in registers also.)
Structures and unions of other sizes are returned by storing them into
an address passed by the caller (usually in a register).  The
machine-description macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE'
tell GCC where to pass this address.

   By contrast, PCC on most target machines returns structures and
unions of any size by copying the data into an area of static storage,
and then returning the address of that storage as if it were a pointer
value.  The caller must copy the data from that memory area to the
place where the value is wanted.  This is slower than the method used
by GCC, and fails to be reentrant.

   On some target machines, such as RISC machines and the 80386, the
standard system convention is to pass to the subroutine the address of
where to return the value.  On these machines, GCC has been configured
to be compatible with the standard compiler, when this method is used.
It may not be compatible for structures of 1, 2, 4 or 8 bytes.

   GCC uses the system's standard convention for passing arguments.  On
some machines, the first few arguments are passed in registers; in
others, all are passed on the stack.  It would be possible to use
registers for argument passing on any machine, and this would probably
result in a significant speedup.  But the result would be complete
incompatibility with code that follows the standard convention.  So this
change is practical only if you are switching to GCC as the sole C
compiler for the system.  We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
compile the libraries with GCC.

   On some machines (particularly the Sparc), certain types of arguments
are passed "by invisible reference".  This means that the value is
stored in memory, and the address of the memory location is passed to
the subroutine.

   If you use `longjmp', beware of automatic variables.  ISO C says that
automatic variables that are not declared `volatile' have undefined
values after a `longjmp'.  And this is all GCC promises to do, because
it is very difficult to restore register variables correctly, and one
of GCC's features is that it can put variables in registers without
your asking it to.

   If you want a variable to be unaltered by `longjmp', and you don't
want to write `volatile' because old C compilers don't accept it, just
take the address of the variable.  If a variable's address is ever
taken, even if just to compute it and ignore it, then the variable
cannot go in a register:

     {
       int careful;
       &careful;
       ...
     }

   Code compiled with GCC may call certain library routines.  Most of
them handle arithmetic for which there are no instructions.  This
includes multiply and divide on some machines, and floating point
operations on any machine for which floating point support is disabled
with `-msoft-float'.  Some standard parts of the C library, such as
`bcopy' or `memcpy', are also called automatically.  The usual function
call interface is used for calling the library routines.

   Some of these routines can be defined in mostly machine-independent
C; they appear in `libgcc2.c'.  Others must be hand-written in assembly
language for each processor.  Wherever they are defined, they are
compiled into the support library, `libgcc.a', which is automatically
searched when you link programs with GCC.


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

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

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

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

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

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

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

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


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

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

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

* Menu:

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


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

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

   The configure and build process has a long and colorful history, and
can be confusing to anyone who doesn't know why things are the way they
are.  While there are other documents which describe the configuration
process in detail, here are a few things that everyone working on GCC
should know.

   There are three system names that the build knows about: the machine
you are building on ("build"), the machine that you are building for
("host"), and the machine that GCC will produce code for ("target").
When you configure GCC, you specify these with `--build=', `--host=',
and `--target='.

   Specifying the host without specifying the build should be avoided,
as `configure' may (and once did) assume that the host you specify is
also the build, which may not be true.

   If build, host, and target are all the same, this is called a
"native".  If build and host are the same but target is different, this
is called a "cross".  If build, host, and target are all different this
is called a "canadian" (for obscure reasons dealing with Canada's
political party and the background of the person working on the build
at that time).  If host and target are the same, but build is
different, you are using a cross-compiler to build a native for a
different system.  Some people call this a "host-x-host", "crossed
native", or "cross-built native".  If build and target are the same,
but host is different, you are using a cross compiler to build a cross
compiler that produces code for the machine you're building on.  This
is rare, so there is no common way of describing it (although I propose
calling it a "crossback").

   If build and host are the same, the GCC you are building will also be
used to build the target libraries (like `libstdc++').  If build and
host are different, you must have already build and installed a cross
compiler that will be used to build the target libraries (if you
configured with `--target=foo-bar', this compiler will be called
`foo-bar-gcc').

   In the case of target libraries, the machine you're building for is
the machine you specified with `--target'.  So, build is the machine
you're building on (no change there), host is the machine you're
building for (the target libraries are built for the target, so host is
the target you specified), and target doesn't apply (because you're not
building a compiler, you're building libraries).  The configure/make
process will adjust these variables as needed.  It also sets
`$with_cross_host' to the original `--host' value in case you need it.

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


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

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

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

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

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

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

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

`include'
     Headers for the `libiberty' library.

`libf2c'
     The Fortran runtime library.

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

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

`libjava'
     The Java runtime library.

`libobjc'
     The Objective-C runtime library.

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

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

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

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


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

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

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

* Menu:

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


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

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

   The `gcc' directory contains the following subdirectories:

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

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

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

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

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

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

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

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


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

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

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

* Menu:

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


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

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

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

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

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

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

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


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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

   The following configuration headers are created from the Makefile,
using `mkconfig.sh', rather than directly by `configure'.  `config.h',
`hconfig.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.

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

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

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


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

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

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


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

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

`all'
     This is the default target.  Depending on what your
     build/host/target configuration is, it coordinates all the things
     that need to be built.

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

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

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

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

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

`maintainer-clean'
     Distclean plus any file that can be generated from other files.
     Note that additional tools may be required beyond what is normally
     needed to build gcc.

`install'
     Installs gcc.

`uninstall'
     Deletes installed files.

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

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

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

`bootstrap'
     Builds gcc three times--once with the native compiler, once with
     the native-built compiler it just built, and once with the
     compiler it built the second time.  In theory, the last two should
     produce the same results, which `make compare' can check.  Each
     step of this process is called a "stage", and the results of each
     stage N (N = 1...3) are copied to a subdirectory `stageN/'.

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

`bubblestrap'
     Once bootstrapped, this incrementally rebuilds each of the three
     stages, one at a time.  It does this by "bubbling" the stages up
     from their subdirectories, rebuilding them, and copying them back
     to their subdirectories.  This will allow you to, for example,
     quickly rebuild a bootstrapped compiler after changing the
     sources, without having to do a full bootstrap.

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

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


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

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

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


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

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

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

   Several of the headers GCC installs are in the `ginclude' directory.
These headers, `iso646.h', `stdarg.h', `stdbool.h', `stddef.h' and
`varargs.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 normally installs a `<float.h>' file; these are kept as
`config/float-FORMAT.h', where FORMAT is specified by a `float_format'
setting in `config.gcc', and a setting `float_format=none' disables
installation of this header.  GCC also installs its own version of
`<limits.h>'; this is generated from `glimits.h', together with
`limitx.h' and `limity.h' if the system also has its own version of
`<limits.h>'.  (GCC provides its own header because it is required of
ISO C freestanding implementations, but needs to include the system
header from its own header as well because other standards such as
POSIX specify additional values to be defined in `<limits.h>'.)  The
system's `<limits.h>' header is used via
`LIBSUBDIR/include/syslimits.h', which is copied from `gsyslimits.h' if
it does not need fixing to work with GCC; if it needs fixing,
`syslimits.h' is the fixed copy.


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

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

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

* Menu:

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


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

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

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

`fdl.texi'
     The GNU Free Documentation License.

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

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

`gpl.texi'
     The GNU General Public License.

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

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

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

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


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

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

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

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

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

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

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

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

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


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

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

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

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

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

`COPYING'
     The GNU General Public License.

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

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

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

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

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

`SERVICE'
     A pointer to the GNU Service Directory.

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


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

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

   * 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 test suites, which may be under `gcc/testsuite' or
     runtime library directories.  FIXME: document somewhere how to
     write test suite 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 GNATS category for bugs in that front end and runtime
     libraries.  This category needs to be mentioned in
     `gcc/gccbug.in', and in `gnats.html' on the GCC web site, as well
     as being added to the GNATS 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.

   * 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

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

    `all.build'
    `all.cross'
    `start.encap'
    `rest.encap'
          FIXME: exactly what goes in each of these targets?

    `info'
          Build info documentation for the front end, in the source
          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.

    `generated-manpages'
          Build generated man pages for the front end from Texinfo
          manuals (*note Man Page Generation::), in the source
          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' that are installed in `LIBSUBDIR' by the
          main `Makefile'.

    `install-info'
          Install info documentation for the front end, if it is
          present in the source directory.  (It may not be present if a
          suitable version of `makeinfo' was not installed.)  This
          target should run the command `install-info' to update the
          info directory, but should ignore errors when running that
          command.

    `install-man'
          Install man pages for the front end.  This target should
          ignore errors.

    `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'
    `extraclean'
    `maintainer-clean'
          Except for `extraclean', the language parts of the standard
          GNU `*clean' targets. *Note Standard Targets for Users:
          (standards)Standard Targets, for details of the standard
          targets.  `extraclean' does `distclean' and also deletes
          anything likely to be found in the source directory that
          shouldn't be in the distribution.  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'
          Move to the stage directory files not included in
          `stagestuff' in `config-lang.in' or otherwise moved by the
          main `Makefile'.

`lang-options.h'
     This file provides entries for `documented_lang_options' in
     `toplev.c' describing command-line options the front end accepts
     for `--help' output.

`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

The Front End `config-lang.in' File
...................................

   Each language subdirectory contains a `config-lang.in' file.  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.in' (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
     should be installed in `LIBSUBDIR'.  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.

