Subversion Repositories openrisc

@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, 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.

@node Documentation

@subsection Building Documentation

The main GCC documentation is in the form of manuals in Texinfo

format.  These are installed in Info format; DVI versions may be

generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and

HTML versions by @command{make html}.  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 @file{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.

@end menu

@node Texinfo Manuals

@subsubsection Texinfo Manuals

The manuals for GCC as a whole, and the C and C++ front ends, are in

files @file{doc/*.texi}.  Other front ends have their own manuals in

files @file{@var{language}/*.texi}.  Common files

@file{doc/include/*.texi} are provided which may be included in

multiple manuals; the following files are in @file{doc/include}:

@table @file

@item fdl.texi

The GNU Free Documentation License.

@item funding.texi

The section ``Funding Free Software''.

@item gcc-common.texi

Common definitions for manuals.

@item gpl.texi

The GNU General Public License.

@item texinfo.tex

A copy of @file{texinfo.tex} known to work with the GCC manuals.

@end table

DVI-formatted manuals are generated by @samp{make dvi}, which uses

@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).

PDF-formatted manuals are generated by @samp{make pdf}, which uses

@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML

formatted manuals are generated by @command{make html}.  Info

manuals are generated by @samp{make info} (which is run as part of

a bootstrap); this generates the manuals in the source directory,

using @command{makeinfo} via the Makefile macro @code{$(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

@file{maintainer-scripts/update_web_docs}.  Each manual to be

provided online must be listed in the definition of @code{MANUALS} in

that file; a file @file{@var{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

@file{@var{name}.texi} should only include other files in its own

directory or in @file{doc/include}.  HTML manuals will be generated by

@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}

and @command{dvips}, and PDF manuals by @command{texi2pdf}.

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, @file{doc/install.texi}, is also provided on

the GCC web site.  The HTML version is generated by the script

@file{doc/install.texi2html}.

@node Man Page Generation

@subsubsection 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

@file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for

@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference

to @file{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

@file{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 @samp{@@c man} control what

parts of a Texinfo file go into a man page.  Only a subset of Texinfo

is supported by @file{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 @file{doc/include/gcc-common.texi} which

@file{texi2pod.pl} understands:

@table @code

@item @@gcctabopt

Use in the form @samp{@@table @@gcctabopt} for tables of options,

where for printed output the effect of @samp{@@code} is better than

that of @samp{@@option} but for man page output a different effect is

wanted.

@item @@gccoptlist

Use for summary lists of options in manuals.

@item @@gol

Use at the end of each line inside @samp{@@gccoptlist}.  This is

necessary to avoid problems with differences in how the

@samp{@@gccoptlist} macro is handled by different Texinfo formatters.

@end table

FIXME: describe the @file{texi2pod.pl} input language and magic

comments in more detail.

@node Miscellaneous Docs

@subsubsection Miscellaneous Documentation

In addition to the formal documentation that is installed by GCC,

there are several other text files with miscellaneous documentation:

@table @file

@item ABOUT-GCC-NLS

Notes on GCC's Native Language Support.  FIXME: this should be part of

this manual rather than a separate file.

@item ABOUT-NLS

Notes on the Free Translation Project.

@item COPYING

The GNU General Public License.

@item COPYING.LIB

The GNU Lesser General Public License.

@item *ChangeLog*

@itemx */ChangeLog*

Change log files for various parts of GCC@.

@item 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.

@item ONEWS

Information about new features in old versions of GCC@.  (For recent

versions, the information is on the GCC web site.)

@item 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?

@item SERVICE

A pointer to the GNU Service Directory.

@end table

FIXME: document such files in subdirectories, at least @file{config},

@file{cp}, @file{objc}, @file{testsuite}.

@node Front End

@subsection Anatomy of a Language Front End

A front end for a language in GCC has the following parts:

@itemize @bullet

@item

A directory @file{@var{language}} under @file{gcc} containing source

files for that front end.  @xref{Front End Directory, , The Front End

@file{@var{language}} Directory}, for details.

@item

A mention of the language in the list of supported languages in

@file{gcc/doc/install.texi}.

@item

A mention of the name under which the language's runtime library is

recognized by @option{--enable-shared=@var{package}} in the

documentation of that option in @file{gcc/doc/install.texi}.

@item

A mention of any special prerequisites for building the front end in

the documentation of prerequisites in @file{gcc/doc/install.texi}.

@item

Details of contributors to that front end in

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

@file{contrib.texi}.

@item

Information about support for that language in

@file{gcc/doc/frontends.texi}.

@item

Information about standards for that language, and the front end's

support for them, in @file{gcc/doc/standards.texi}.  This may be a

link to such information in the front end's own manual.

@item

Details of source file suffixes for that language and @option{-x

@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.

@item

Entries in @code{default_compilers} in @file{gcc.c} for source file

suffixes for that language.

@item

Preferably testsuites, which may be under @file{gcc/testsuite} or

runtime library directories.  FIXME: document somewhere how to write

testsuite harnesses.

@item

Probably a runtime library for the language, outside the @file{gcc}

directory.  FIXME: document this further.

@item

Details of the directories of any runtime libraries in

@file{gcc/doc/sourcebuild.texi}.

@end itemize

If the front end is added to the official GCC CVS repository, the

following are also necessary:

@itemize @bullet

@item

At least one Bugzilla component for bugs in that front end and runtime

libraries.  This category needs to be mentioned in

@file{gcc/gccbug.in}, as well as being added to the Bugzilla database.

@item

Normally, one or more maintainers of that front end listed in

@file{MAINTAINERS}.

@item

Mentions on the GCC web site in @file{index.html} and

@file{frontends.html}, with any relevant links on

@file{readings.html}.  (Front ends that are not an official part of

GCC may also be listed on @file{frontends.html}, with relevant links.)

@item

A news item on @file{index.html}, and possibly an announcement on the

@email{gcc-announce@@gcc.gnu.org} mailing list.

@item

The front end's manuals should be mentioned in

@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})

and the online manuals should be linked to from

@file{onlinedocs/index.html}.

@item

Any old releases or CVS repositories of the front end, before its

inclusion in GCC, should be made available on the GCC FTP site

@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.

@item

The release and snapshot script @file{maintainer-scripts/gcc_release}

should be updated to generate appropriate tarballs for this front end.

The associated @file{maintainer-scripts/snapshot-README} and

@file{maintainer-scripts/snapshot-index.html} files should be updated

to list the tarballs and diffs for this front end.

@item

If this front end includes its own version files that include the

current date, @file{maintainer-scripts/update_version} should be

updated accordingly.

@item

@file{CVSROOT/modules} in the GCC CVS repository should be updated.

@end itemize

@menu

* Front End Directory::  The front end @file{@var{language}} directory.

* Front End Config::     The front end @file{config-lang.in} file.

@end menu

@node Front End Directory

@subsubsection The Front End @file{@var{language}} Directory

A front end @file{@var{language}} directory contains the source files

of that front end (but not of any runtime libraries, which should be

outside the @file{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:

@table @file

@item config-lang.in

This file is required in all language subdirectories.  @xref{Front End

Config, , The Front End @file{config-lang.in} File}, for details of

its contents

@item Make-lang.in

This file is required in all language subdirectories.  It contains

targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the

setting of @code{language} in @file{config-lang.in}) for the following

values of @code{@var{hook}}, and any other Makefile rules required to

build those targets (which may if necessary use other Makefiles

specified in @code{outputs} in @file{config-lang.in}, although this is

deprecated).  It also adds any testsuite targets that can use the

standard rule in @file{gcc/Makefile.in} to the variable

@code{lang_checks}.

@table @code

@itemx all.cross

@itemx start.encap

@itemx rest.encap

FIXME: exactly what goes in each of these targets?

@item tags

Build an @command{etags} @file{TAGS} file in the language subdirectory

in the source tree.

@item info

Build info documentation for the front end, in the build directory.

This target is only called by @samp{make bootstrap} if a suitable

version of @command{makeinfo} is available, so does not need to check

for this, and should fail if an error occurs.

@item dvi

Build DVI documentation for the front end, in the build directory.

This should be done using @code{$(TEXI2DVI)}, with appropriate

@option{-I} arguments pointing to directories of included files.

@item pdf

Build PDF documentation for the front end, in the build directory.

This should be done using @code{$(TEXI2PDF)}, with appropriate

@option{-I} arguments pointing to directories of included files.

@item html

Build HTML documentation for the front end, in the build directory.

@item man

Build generated man pages for the front end from Texinfo manuals

(@pxref{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.

@item install-common

Install everything that is part of the front end, apart from the

compiler executables listed in @code{compilers} in

@file{config-lang.in}.

@item 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.

@item install-man

Install man pages for the front end.  This target should ignore

errors.

@item srcextra

Copies its dependencies into the source directory.  This generally should

be used for generated files such as Bison output files which are not

present in CVS, but should be included in any release tarballs.  This

target will be executed during a bootstrap if

@samp{--enable-generated-files-in-srcdir} was specified as a

@file{configure} option.

@item srcinfo

@itemx srcman

Copies its dependencies into the source directory.  These targets will be

executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}

was specified as a @file{configure} option.

@item uninstall

Uninstall files installed by installing the compiler.  This is

currently documented not to be supported, so the hook need not do

anything.

@item mostlyclean

@itemx clean

@itemx distclean

@itemx maintainer-clean

The language parts of the standard GNU

@samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for

Users, standards, GNU Coding Standards}, for details of the standard

targets.  For GCC, @code{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@.

@item stage1

@itemx stage2

@itemx stage3

@itemx stage4

@itemx stageprofile

@itemx stagefeedback

Move to the stage directory files not included in @code{stagestuff} in

@file{config-lang.in} or otherwise moved by the main @file{Makefile}.

@end table

@item lang.opt

This file registers the set of switches that the front end accepts on

the command line, and their @option{--help} text.  @xref{Options}.

@item lang-specs.h

This file provides entries for @code{default_compilers} in

@file{gcc.c} which override the default of giving an error that a

compiler for that language is not installed.

@item @var{language}-tree.def

This file, which need not exist, defines any language-specific tree

codes.

@end table

@node Front End Config

@subsubsection The Front End @file{config-lang.in} File

Each language subdirectory contains a @file{config-lang.in} file.  In

addition the main directory contains @file{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:

@table @code

@item language

This definition must be present, and gives the name of the language

for some purposes such as arguments to @option{--enable-languages}.

@item 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 @code{language} settings).  For example, the

Java front end depends on the C++ front end, so sets

@samp{lang_requires=c++}.

@item subdir_requires

If defined, this variable lists (space-separated) front end directories

other than C that this front end requires to be present.  For example,

the Objective-C++ front end uses source files from the C++ and

Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.

@item target_libs

If defined, this variable lists (space-separated) targets in the top

level @file{Makefile} to build the runtime libraries for this

language, such as @code{target-libobjc}.

@item lang_dirs

If defined, this variable lists (space-separated) top level

directories (parallel to @file{gcc}), apart from the runtime libraries,

that should not be configured if this front end is not built.

@item build_by_default

If defined to @samp{no}, this language front end is not built unless

enabled in a @option{--enable-languages} argument.  Otherwise, front

ends are built by default, subject to any special logic in

@file{configure.ac} (as is present to disable the Ada front end if the

Ada compiler is not already installed).

@item boot_language

If defined to @samp{yes}, this front end is built in stage 1 of the

bootstrap.  This is only relevant to front ends written in their own

languages.

@item compilers

If defined, a space-separated list of compiler executables that will

be run by the driver.  The names here will each end

with @samp{\$(exeext)}.

@item stagestuff

If defined, a space-separated list of files that should be moved to

the @file{stage@var{n}} directories in each stage of bootstrap.

@item outputs

If defined, a space-separated list of files that should be generated

by @file{configure} substituting values in them.  This mechanism can

be used to create a file @file{@var{language}/Makefile} from

@file{@var{language}/Makefile.in}, but this is deprecated, building

everything from the single @file{gcc/Makefile} is preferred.

@item 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.  @xref{Type Information}.

@item need_gmp

If defined  to @samp{yes}, this frontend requires the GMP library.

Enables configure tests for GMP, which set @code{GMPLIBS} and

@code{GMPINC} appropriately.

@end table

@node Back End

@subsection Anatomy of a Target Back End

A back end for a target architecture in GCC has the following parts:

@itemize @bullet

@item

A directory @file{@var{machine}} under @file{gcc/config}, containing a

machine description @file{@var{machine}.md} file (@pxref{Machine Desc,

, Machine Descriptions}), header files @file{@var{machine}.h} and

@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}

(@pxref{Target Macros, , Target Description Macros and Functions}),

possibly a target Makefile fragment @file{t-@var{machine}}

(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe

some other files.  The names of these files may be changed from the

defaults given by explicit specifications in @file{config.gcc}.

@item

If necessary, a file @file{@var{machine}-modes.def} in the

@file{@var{machine}} directory, containing additional machine modes to

represent condition codes.  @xref{Condition Code}, for further details.

@item

An optional @file{@var{machine}.opt} file in the @file{@var{machine}}

directory, containing a list of target-specific options.  You can also

add other option files using the @code{extra_options} variable in

@file{config.gcc}.  @xref{Options}.

@item

Entries in @file{config.gcc} (@pxref{System Config, , The

@file{config.gcc} File}) for the systems with this target

architecture.

@item

Documentation in @file{gcc/doc/invoke.texi} for any command-line

options supported by this target (@pxref{Run-time Target, , Run-time

Target Specification}).  This means both entries in the summary table

of options and details of the individual options.

@item

Documentation in @file{gcc/doc/extend.texi} for any target-specific

attributes supported (@pxref{Target Attributes, , Defining

target-specific uses of @code{__attribute__}}), including where the

same attribute is already supported on some targets, which are

enumerated in the manual.

@item

Documentation in @file{gcc/doc/extend.texi} for any target-specific

pragmas supported.

@item

Documentation in @file{gcc/doc/extend.texi} of any target-specific

built-in functions supported.

@item

Documentation in @file{gcc/doc/extend.texi} of any target-specific

format checking styles supported.

@item

Documentation in @file{gcc/doc/md.texi} of any target-specific

constraint letters (@pxref{Machine Constraints, , Constraints for

Particular Machines}).

@item

A note in @file{gcc/doc/contrib.texi} under the person or people who

contributed the target support.

@item

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

@item

Possibly other support outside the @file{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.

@end itemize

If the back end is added to the official GCC CVS repository, the

following are also necessary:

@itemize @bullet

@item

An entry for the target architecture in @file{readings.html} on the

GCC web site, with any relevant links.

@item

Details of the properties of the back end and target architecture in

@file{backends.html} on the GCC web site.

@item

A news item about the contribution of support for that target

architecture, in @file{index.html} on the GCC web site.

@item

Normally, one or more maintainers of that target listed in

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

@end itemize

@node Testsuites

@section 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.

* Test Directives:: Directives used within DejaGnu tests.

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

@end menu

@node Test Idioms

@subsection Idioms Used in Testsuite Code

In general, C testcases have a trailing @file{-@var{n}.c}, starting

with @file{-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

@file{@var{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,

@file{pr@var{bug-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.

In the @file{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 @option{-pedantic-errors}.  The following idiom,

where the first line shown is line @var{line} of the file and the line

that generates the error, is used for this:

@smallexample

/* @{ dg-bogus "warning" "warning in place of error" @} */

/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */

@end smallexample

It may be necessary to check that an expression is an integer constant

expression and has a certain value.  To check that @code{@var{E}} has

value @code{@var{V}}, an idiom similar to the following is used:

@smallexample

char x[((E) == (V) ? 1 : -1)];

@end smallexample

In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make

assertions about the types of expressions.  See, for example,

@file{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, @file{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

@file{gcc.c-torture/execute}.  Where code should be optimized away, a

call to a nonexistent function such as @code{link_failure ()} may be

inserted; a definition

@smallexample

#ifndef __OPTIMIZE__

void

link_failure (void)

@{

  abort ();

@}

#endif

@end smallexample

@noindent

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

@code{static} to call @code{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.

@node Test Directives

@subsection Directives used within DejaGnu tests

Test directives appear within comments in a test source file and begin

with @code{dg-}.  Some of these are defined within DejaGnu and others

are local to the GCC testsuite.

The order in which test directives appear in a test can be important:

directives local to GCC sometimes override information used by the

DejaGnu directives, which know nothing about the GCC directives, so the

DejaGnu directives must precede GCC directives.

Several test directives include selectors which are usually preceded by

the keyword @code{target} or @code{xfail}.  A selector is: one or more

target triplets, possibly including wildcard characters; a single

effective-target keyword; or a logical expression.  Depending on the

context, the selector specifies whether a test is skipped and reported

as unsupported or is expected to fail.  Use @samp{*-*-*} to match any

target.

Effective-target keywords are defined in @file{target-supports.exp} in

the GCC testsuite.

A selector expression appears within curly braces and uses a single