sourcebuild.texi

理解和实践操作系统的一本好书

@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation,
@c Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Source Tree
@chapter 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 (@uref{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 @file{gcc} subdirectory.
* Testsuites::      The GCC testsuites.
@end menu

@include configterms.texi

@node Top Level
@section 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:

@table @file
@item boehm-gc
The Boehm conservative garbage collector, used as part of the Java
runtime library.

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

@item fastjar
An implementation of the @command{jar} command, used with the Java
front end.

@item gcc
The main sources of GCC itself (except for runtime libraries),
including optimizers, support for different target architectures,
language front ends, and testsuites.  @xref{gcc Directory, , The
@file{gcc} Subdirectory}, for details.

@item include
Headers for the @code{libiberty} library.

@item libada
The Ada runtime library.

@item libcpp
The C preprocessor library.

@item libgfortran
The Fortran runtime library.

@item libffi
The @code{libffi} library, used as part of the Java runtime library.

@item libiberty
The @code{libiberty} library, used for portability and for some
generally useful data structures and algorithms.  @xref{Top, ,
Introduction, libiberty, @sc{gnu} libiberty}, for more information
about this library.

@item libjava
The Java runtime library.

@item libmudflap
The @code{libmudflap} library, used for instrumenting pointer and array
dereferencing operations.

@item libobjc
The Objective-C and Objective-C++ runtime library.

@item libstdc++-v3
The C++ runtime library.

@item maintainer-scripts
Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.

@item zlib
The @code{zlib} compression library, used by the Java front end and as
part of the Java runtime library.
@end table

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.  @xref{Top, , GNU configure and build system,
configure, The GNU configure and build system}, for details.

@node gcc Directory
@section The @file{gcc} Subdirectory

The @file{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.  @xref{Passes, , Passes and Files of the Compiler}.

@menu
* Subdirectories:: Subdirectories of @file{gcc}.
* Configuration::  The configuration process, and the files it uses.
* Build::          The build system in the @file{gcc} directory.
* Makefile::       Targets in @file{gcc/Makefile}.
* Library Files::  Library source files and headers under @file{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.
@end menu

@node Subdirectories
@subsection Subdirectories of @file{gcc}

The @file{gcc} directory contains the following subdirectories:

@table @file
@item @var{language}
Subdirectories for various languages.  Directories containing a file
@file{config-lang.in} are language subdirectories.  The contents of
the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C)
and @file{objcp} (for Objective-C++) are documented in this manual
(@pxref{Passes, , Passes and Files of the Compiler}); those for other
languages are not.  @xref{Front End, , Anatomy of a Language Front End},
for details of the files in these directories.

@item config
Configuration files for supported architectures and operating
systems.  @xref{Back End, , Anatomy of a Target Back End}, for
details of the files in this directory.

@item doc
Texinfo documentation for GCC, together with automatically generated
man pages and support for converting the installation manual to
HTML@.  @xref{Documentation}.

@item fixinc
The support for fixing system headers to work with GCC@.  See
@file{fixinc/README} for more information.  The headers fixed by this
mechanism are installed in @file{@var{libsubdir}/include}.  Along with
those headers, @file{README-fixinc} is also installed, as
@file{@var{libsubdir}/include/README}.

@item ginclude
System headers installed by GCC, mainly those required by the C
standard of freestanding implementations.  @xref{Headers, , Headers
Installed by GCC}, for details of when these and other headers are
installed.

@item intl
GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
include it in libc.  Properly, this directory should be at top level,
parallel to the @file{gcc} directory.

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

@item testsuite
The GCC testsuites (except for those for runtime libraries).
@xref{Testsuites}.
@end table

@node Configuration
@subsection Configuration in the @file{gcc} Directory

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

@menu
* Config Fragments::     Scripts used by @file{configure}.
* System Config::        The @file{config.build}, @file{config.host}, and
                         @file{config.gcc} files.
* Configuration Files::  Files created by running @file{configure}.
@end menu

@node Config Fragments
@subsubsection Scripts Used by @file{configure}

@file{configure} uses some other scripts to help in its work:

@itemize @bullet
@item The standard GNU @file{config.sub} and @file{config.guess}
files, kept in the top level directory, are used.  FIXME: when is the
@file{config.guess} file in the @file{gcc} directory (that just calls
the top level one) used?

@item The file @file{config.gcc} is used to handle configuration
specific to the particular target machine.  The file
@file{config.build} is used to handle configuration specific to the
particular build machine.  The file @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.)
@xref{System Config, , The @file{config.build}; @file{config.host};
and @file{config.gcc} Files}, for details of the contents of these files.

@item Each language subdirectory has a file
@file{@var{language}/config-lang.in} that is used for
front-end-specific configuration.  @xref{Front End Config, , The Front
End @file{config-lang.in} File}, for details of this file.

@item A helper script @file{configure.frag} is used as part of
creating the output of @file{configure}.
@end itemize

@node System Config
@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files

The @file{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 @file{config.host} file contains specific rules for particular systems
which GCC will run on.  This is rarely needed.

The @file{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.

@include configfiles.texi

@node Build
@subsection Build System in the @file{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 (@pxref{Passes}).

@include makefile.texi

@node Library Files
@subsection Library Source Files and Headers under the @file{gcc} Directory

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

@node Headers
@subsection 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 @file{@var{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 @file{ginclude}
directory.  These headers, @file{iso646.h},
@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
are installed in @file{@var{libsubdir}/include},
unless the target Makefile fragment (@pxref{Target Fragment})
overrides this by setting @code{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
@file{@var{libsubdir}/include}.  @file{config.gcc} may set
@code{extra_headers}; this specifies additional headers under
@file{config} to be installed on some systems.

GCC installs its own version of @code{<float.h>}, from @file{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 @code{<limits.h>}; this is generated
from @file{glimits.h}, together with @file{limitx.h} and
@file{limity.h} if the system also has its own version of
@code{<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
@code{<limits.h>}.)  The system's @code{<limits.h>} header is used via
@file{@var{libsubdir}/include/syslimits.h}, which is copied from
@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
needs fixing, @file{syslimits.h} is the fixed copy.

GCC can also install @code{<tgmath.h>}.  It will do this when
@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.