-@c Copyright (C) 2002, 2003 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@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 thie directory.
+details of the files in this directory.
@item doc
Texinfo documentation for GCC, together with automatically generated
The @file{gcc} directory is configured with an Autoconf-generated
script @file{configure}. The @file{configure} script is generated
-from @file{configure.in} and @file{aclocal.m4}. From the files
-@file{configure.in} and @file{acconfig.h}, Autoheader generates the
+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.gcc} file.
+* System Config:: The @file{config.build}, @file{config.host}, and
+ @file{config.gcc} files.
* Configuration Files:: Files created by running @file{configure}.
@end menu
the top level one) used?
@item The file @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.) @xref{System Config, , The
-@file{config.gcc} File}, for details of the contents of this file.
+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
@end itemize
@node System Config
-@subsubsection The @file{config.gcc} File
+@subsubsection The @file{config.build}, @file{config.host}, and @file{config.gcc} Files
-FIXME: document the contents of this file, and what variables should
+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
@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
+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
Entries in @code{default_compilers} in @file{gcc.c} for source file
suffixes for that language.
@item
-A bitmask in @file{opts.h} that flags each switch accepted by
-the front end, for example @code{CL_JAVA}.
-@item
Preferably test suites, which may be under @file{gcc/testsuite} or
runtime library directories. FIXME: document somewhere how to write
test suite harnesses.
@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}, and in @file{gnats.html} on the GCC web site, as
-well as being added to the Bugzilla database.
+@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}.
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).
+deprecated). Some hooks are defined by using a double-colon rule for
+@code{@var{hook}}, rather than by using a target of form
+@code{@var{lang}.@var{hook}}. These hooks are called ``double-colon
+hooks'' below. 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
@item all.build
Build info documentation for the front end, in the source 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.
+for this, and should fail if an error occurs. This hook is a
+double-colon hook.
@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.
+This hook is a double-colon hook.
@item generated-manpages
Build generated man pages for the front end from Texinfo manuals
(@pxref{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.
+This hook is a double-colon hook.
@item install-normal
FIXME: what is this target for?
@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} that are installed in @file{@var{libsubdir}} by
-the main @file{Makefile}.
+@file{config-lang.in}.
@item 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
-@command{makeinfo} was not installed.) This target should run the
-command @command{install-info} to update the info directory, but
-should ignore errors when running that command.
+source directory. This target should have dependencies on info files
+that should be installed. This hook is a double-colon hook.
@item install-man
Install man pages for the front end. This target should ignore
errors.
@item mostlyclean
@itemx clean
@itemx distclean
-@itemx extraclean
@itemx maintainer-clean
-Except for @code{extraclean}, the language parts of the standard GNU
+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. @code{extraclean} does @code{distclean} and also deletes
-anything likely to be found in the source directory that shouldn't be
-in the distribution. For GCC, @code{maintainer-clean} should delete
+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
@item lang.opt
This file registers the set of switches that the front end accepts on
-the command line. The file format is documented in each
-@file{lang.opt} file in the GCC tree. @file{lang.opt} is processed
-by the script @file{opts.sh}.
-@item lang-options.h
-This file provides entries for @code{documented_lang_options} in
-@file{toplev.c} describing command-line options the front end accepts
-for @option{--help} output.
+the command line, and their --help text. The file format is
+documented in the file @file{c.opt}. These files are processed by the
+script @file{opts.sh}.
@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
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.in} (as is present to disable the Ada front end if the
+@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 should
-be installed in @file{@var{libsubdir}}. The names here will each end
+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
@menu
* Test Idioms:: Idioms used in test suite code.
+* Ada Tests:: The Ada language test suites.
* C Tests:: The C language test suites.
* libgcj Tests:: The Java library test suites.
* gcov Testing:: Support for testing gcov.
@node Test Idioms
@subsection Idioms Used in Test Suite Code
-In the @file{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 @file{-@var{n}.c}, starting with @file{-1.c}, in
-case other test cases with similar names are added later.
+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.
Test cases should use @code{abort ()} to indicate failure and
@code{exit (0)} for success; on some targets these may be redefined to
FIXME: discuss non-C test suites here.
+@node Ada Tests
+@subsection Ada Language Test Suites
+
+The Ada test suite includes executable tests from the ACATS 2.5 test
+suite, publicly available at @uref{http://www.adaic.org/compilers/acats/2.5}
+
+These tests are integrated in the GCC test suite in the
+@file{gcc/testsuite/ada/acats} directory, and
+enabled automatically when running @code{make check}, assuming
+the Ada language has been enabled when configuring GCC.
+
+You can also run the Ada test suite independently, using
+@code{make check-ada}, or run a subset of the tests by specifying which
+chapter to run, e.g:
+
+@smallexample
+$ make check-ada CHAPTERS="c3 c9"
+@end smallexample
+
+The tests are organized by directory, each directory corresponding to
+a chapter of the Ada Reference Manual. So for example, c9 corresponds
+to chapter 9, which deals with tasking features of the language.
+
+There is also an extra chapter called @file{gcc} containing a template for
+creating new executable tests.
+
+The tests are run using two 'sh' scripts: run_acats and run_all.sh
+To run the tests using a simulator or a cross target, see the small
+customization section at the top of run_all.sh
+
+These tests are run using the build tree: they can be run without doing
+a @code{make install}.
+
@node C Tests
@subsection C Language Test Suites
@table @file
@item gcc.dg
-This contains tests of particular features of the C compiler, using the
+This contains tests of particular features of the C compiler, using the
more modern @samp{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
+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 @samp{-ansi -pedantic}
unless other options are given in the test. Except as noted below they
are not run with multiple optimization options.
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
+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.
@node libgcj Tests
@subsection The Java library test suites.
-Runtime tests are executed via @samp{make check} from the @samp{testsuite}
-directory of the libjava hierarchy in the build tree. Additional runtime
-tests can be checked into this testsuite.
+Runtime tests are executed via @samp{make check} in the
+@file{@var{target}/libjava/testsuite} directory in the build
+tree. Additional runtime tests can be checked into this testsuite.
Regression testing of the core packages in libgcj is also covered by the
Mauve test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project}