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.

     [file configterms.texi not included]

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.  See The gcc Subdirectory, 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.  See Introduction (GNU libiberty), 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.  See GNU configure and build system (The GNU configure and build system), for details.

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.  See Passes and Files of the Compiler.

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 (see Passes and Files of the Compiler); those for other languages are not. See Anatomy of a Language Front End, for details of the files in these directories.

config
     Configuration files for supported architectures and operating systems.  See Anatomy of a Target 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.  See 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.  See Headers Installed by GCC, 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). See Test Suites.

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.

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.)  See The config.gcc File, 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.  See The Front End config-lang.in File, for details of this file.

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

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 configfiles.texi not included]

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 (see Passes).

     [file makefile.texi not included]

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.  See Headers Installed by GCC, for more information about the ginclude directory.

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

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

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

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

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

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

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.

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.

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.

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.

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.  See The Front End LANGUAGE 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 (see Texinfo Manuals) and the online manuals should be linked to from onlinedocs/index.html.

  * Any old releases or CVS repositories of the front end, before its inclusion in GCC, should be made available on the GCC FTP site ftp://gcc.gnu.org/pub/gcc/old-releases/.

  * The release and snapshot script maintainer-scripts/gcc_release should be updated to generate appropriate tarballs for this front end. The associated maintainer-scripts/snapshot-README and maintainer-scripts/snapshot-index.html files should be updated to list the tarballs and diffs for this front end.

  * If this front end includes its own version files that include the current date, maintainer-scripts/update_version should be updated accordingly.

  * CVSROOT/modules in the GCC CVS repository should be updated.

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.  See The Front End config-lang.in File, 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 (see 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. See Standard Targets for Users (GNU Coding Standards), 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.

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

Each language subdirectory contains a config-lang.in file.  In addition the main directory contains c-config-lang.in, which contains limited information for the C language.  This file is a shell script that may define some variables describing the language:

language
     This definition must be present, and gives the name of the language for some purposes such as arguments to --enable-languages.

lang_requires
     If defined, this variable lists (space-separated) language front ends other than C that this front end requires to be enabled (with the names given being their language settings).  For example, the Java front end depends on the C++ front end, so sets lang_requires=c++.

target_libs
     If defined, this variable lists (space-separated) targets in the top level Makefile to build the runtime libraries for this language, such as target-libobjc.

lang_dirs
     If defined, this variable lists (space-separated) top level directories (parallel to gcc), apart from the runtime libraries, that should not be configured if this front end is not built.

build_by_default
     If defined to no, this language front end is not built unless enabled in a --enable-languages argument.  Otherwise, front ends are built by default, subject to any special logic in configure.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.

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. See Type Information.

Anatomy of a Target Back End
----------------------------

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

  * A directory MACHINE under gcc/config, containing a machine description MACHINE.md file (see Machine Descriptions), header files MACHINE.h and MACHINE-protos.h and a source file MACHINE.c (see Target Description Macros and Functions), possibly a target Makefile fragment t-MACHINE (see 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 config.gcc.

  * If necessary, a file MACHINE-modes.def in the MACHINE directory, containing additional machine modes to represent condition codes.  See Condition Code, for further details.

  * Entries in config.gcc (see The config.gcc File) for the systems with this target architecture.

  * Documentation in gcc/doc/invoke.texi for any command-line options supported by this target (see Run-time Target Specification).  This means both entries in the summary table of options and details of the individual options.

  * Documentation in gcc/doc/extend.texi for any target-specific attributes supported (see Defining target-specific uses of __attribute__), including where the same attribute is already supported on some targets, which are enumerated in the manual.

  * Documentation in gcc/doc/extend.texi for any target-specific pragmas supported.

  * Documentation in gcc/doc/extend.texi of any target-specific built-in functions supported.

  * Documentation in gcc/doc/md.texi of any target-specific constraint letters (see Constraints for Particular Machines).

  * A note in gcc/doc/contrib.texi under the person or people who contributed the target support.

  * Entries in gcc/doc/install.texi for all target triplets supported with this target architecture, giving details of any special notes about installation for this target, or saying that there are no special notes if there are none.

  * Possibly other support outside the gcc directory for runtime libraries.  FIXME: reference docs for this.  The libstdc++ porting manual needs to be installed as info for this to work, or to be a chapter of this manual.

If the back end is added to the official GCC CVS repository, the following are also necessary:

  * An entry for the target architecture in readings.html on the GCC web site, with any relevant links.

  * A news item about the contribution of support for that target architecture, in index.html on the GCC web site.

  * Normally, one or more maintainers of that target listed in MAINTAINERS.  Some existing architectures may be unmaintained, but it would be unusual to add support for a target that does not have a maintainer when support is added.

Test Suites
===========

GCC contains several test suites to help maintain compiler quality. Most of the runtime libraries and language front ends in GCC have test suites.  Currently only the C language test suites are documented here; FIXME: document the others.

Idioms Used in Test Suite Code
------------------------------

In the gcc.c-torture test suites, test cases are commonly 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.  In other test suites, more descriptive names are used.  In general C test cases have a trailing -N.c, starting with -1.c, in case other test cases with similar names are added later.

Test cases should use abort () to indicate failure and exit (0) for success; on some targets these may be redefined to indicate failure and success in other ways.

In the gcc.dg test suite, it is often necessary to test that an error is indeed a hard error and not just a warning---for example, where it is a constraint violation in the C standard, which must become an error with -pedantic-errors.  The following idiom, where the first line shown is line LINE of the file and the line that generates the error, is used for this:

     /* { dg-bogus "warning" "warning in place of error" } */
     /* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */

It may be necessary to check that an expression is an integer constant expression and has a certain value.  To check that E has value V, an idiom similar to the following is used:

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

In gcc.dg tests, __typeof__ is sometimes used to make assertions about the types of expressions.  See, for example, gcc.dg/c99-condexpr-1.c.  The more subtle uses depend on the exact rules for the types of conditional expressions in the C standard; see, for example, gcc.dg/c99-intconst-1.c.

It is useful to be able to test that optimizations are being made properly.  This cannot be done in all cases, but it can be done where the optimization will lead to code being optimized away (for example, where flow analysis or alias analysis should show that certain code cannot be called) or to functions not being called because they have been expanded as built-in functions.  Such tests go in gcc.c-torture/execute.  Where code should be optimized away, a call to a nonexistent function such as link_failure () may be inserted; a definition

     #ifndef __OPTIMIZE__
     void
     link_failure (void)
     {
       abort ();
     }
     #endif

will also be needed so that linking still succeeds when the test is run without optimization.  When all calls to a built-in function should have been optimized and no calls to the non-built-in version of the function should remain, that function may be defined as static to call abort () (although redeclaring a function as static may not work on all targets).

All testcases must be portable.  Target-specific testcases must have appropriate code to avoid causing failures on unsupported systems; unfortunately, the mechanisms for this differ by directory.

FIXME: discuss non-C test suites here.

C Language Test Suites
----------------------

GCC contains the following C language test suites, in the gcc/testsuite directory:

gcc.dg
     This contains tests of particular features of the C compiler, using the more modern dg harness.  Correctness tests for various compiler features should go here if possible.

     Magic comments determine whether the file is preprocessed, compiled, linked or run.  In these tests, error and warning message texts are compared against expected texts or regular expressions given in comments.  These tests are run with the options -ansi -pedantic unless other options are given in the test.  Except as noted below they are not run with multiple optimization options.

gcc.dg/cpp
     This subdirectory contains tests of the preprocessor.

gcc.dg/debug
     This subdirectory contains tests for debug formats.  Tests in this subdirectory are run for each debug format that the compiler supports.

gcc.dg/format
     This subdirectory contains tests of the -Wformat format checking.  Tests in this directory are run with and without -DWIDE.

gcc.dg/noncompile
     This subdirectory contains tests of code that should not compile and does not need any special compilation options.  They are run with multiple optimization options, since sometimes invalid code crashes the compiler with optimization.

gcc.dg/special
     FIXME: describe this.

gcc.c-torture
     This contains particular code fragments which have historically broken easily. These tests are run with multiple optimization options, so tests for features which only break at some optimization levels belong here.  This also contains tests to check that certain optimizations occur.  It might be worthwhile to separate the correctness tests cleanly from the code quality tests, but it hasn't been done yet.

gcc.c-torture/compat
     FIXME: describe this.

     This directory should probably not be used for new tests.

gcc.c-torture/compile
     This test suite contains test cases that should compile, but do not need to link or run.  These test cases are compiled with several different combinations of optimization options.  All warnings are disabled for these test cases, so this directory is not suitable if you wish to test for the presence or absence of compiler warnings. While special options can be set, and tests disabled on specific platforms, by the use of .x files, mostly these test cases should not contain platform dependencies.  FIXME: discuss how defines such as NO_LABEL_VALUES and STACK_SIZE are used.

gcc.c-torture/execute
     This test suite contains test cases that should compile, link and run; otherwise the same comments as for gcc.c-torture/compile apply.

gcc.c-torture/execute/ieee
     This contains tests which are specific to IEEE floating point.

gcc.c-torture/unsorted
     FIXME: describe this.

     This directory should probably not be used for new tests.

gcc.c-torture/misc-tests
     FIXME: describe this, when it should be used for new tests and when it shouldn't.

FIXME: merge in testsuite/README.gcc and discuss the format of test cases and magic comments more.

The Java library test suites.
-----------------------------

Runtime tests are executed via make check from the testsuite directory of the libjava hierarchy in the build tree.  Additional runtime tests can be checked into this testsuite.

Regression testing of the core packages in libgcj is also covered by the Mauve test suite.  The Mauve Project develops tests for the Java Class Libraries.  These tests are run as part of libgcj testing by placing the Mauve tree within the libjava testsuite sources at libjava/testsuite/libjava.mauve/mauve, or by specifying the location of that tree when invoking make, as in make MAUVEDIR=~/mauve check.

To detect regressions, a mechanism in mauve.exp compares the failures for a test run against the list of expected failures in libjava/testsuite/libjava.mauve/xfails from the source hierarchy. Update this file when adding new failing tests to Mauve, or when fixing bugs in libgcj that had caused Mauve test failures.

The Jacks project provides a test suite for Java compilers that can be used to test changes that affect the GCJ front end.  This test suite is run as part of Java testing by placing the Jacks tree within the the libjava testsuite sources at libjava/testsuite/libjava.jacks/jacks.

We encourage developers to contribute test cases to Mauve and Jacks.