diff options
Diffstat (limited to 'contrib/gcc/doc/sourcebuild.texi')
| -rw-r--r-- | contrib/gcc/doc/sourcebuild.texi | 259 |
1 files changed, 177 insertions, 82 deletions
diff --git a/contrib/gcc/doc/sourcebuild.texi b/contrib/gcc/doc/sourcebuild.texi index c2222c0..af57f3a 100644 --- a/contrib/gcc/doc/sourcebuild.texi +++ b/contrib/gcc/doc/sourcebuild.texi @@ -1,4 +1,4 @@ -@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. @@ -14,7 +14,7 @@ which it is presumed that you are familiar. * Configure Terms:: Configuration terminology and history. * Top Level:: The top level source directory. * gcc Directory:: The @file{gcc} subdirectory. -* Test Suites:: The GCC test suites. +* Testsuites:: The GCC testsuites. @end menu @include configterms.texi @@ -44,7 +44,7 @@ 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 test suites. @xref{gcc Directory, , The +language front ends, and testsuites. @xref{gcc Directory, , The @file{gcc} Subdirectory}, for details. @item include @@ -91,7 +91,7 @@ configure, The GNU configure and build system}, for details. 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 -test suite. The files that are sources of GCC are documented in a +testsuite. The files that are sources of GCC are documented in a separate chapter. @xref{Passes, , Passes and Files of the Compiler}. @menu @@ -159,8 +159,8 @@ by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from which messages should not be extracted. @item testsuite -The GCC test suites (except for those for runtime libraries). -@xref{Test Suites}. +The GCC testsuites (except for those for runtime libraries). +@xref{Testsuites}. @end table @node Configuration @@ -168,14 +168,15 @@ The GCC test suites (except for those for runtime libraries). 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 @@ -191,10 +192,14 @@ files, kept in the top level directory, are used. FIXME: when is the 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 @@ -206,9 +211,22 @@ creating the output of @file{configure}. @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 @@ -258,7 +276,7 @@ headers to work with GCC, some other headers may also be installed in @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 @@ -432,6 +450,13 @@ files for that front end. @xref{Front End Directory, , The Front End 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 @@ -450,9 +475,9 @@ Details of source file suffixes for that language and @option{-x Entries in @code{default_compilers} in @file{gcc.c} for source file suffixes for that language. @item -Preferably test suites, which may be under @file{gcc/testsuite} or +Preferably testsuites, which may be under @file{gcc/testsuite} or runtime library directories. FIXME: document somewhere how to write -test suite harnesses. +testsuite harnesses. @item Probably a runtime library for the language, outside the @file{gcc} directory. FIXME: document this further. @@ -530,7 +555,12 @@ 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). +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 @@ -538,8 +568,11 @@ deprecated). @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 source directory. +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. @@ -547,9 +580,10 @@ for this, and should fail if an error occurs. 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 generated-manpages +This hook is a double-colon hook. +@item man Build generated man pages for the front end from Texinfo manuals -(@pxref{Man Page Generation}), in the source directory. This target +(@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. @@ -558,17 +592,26 @@ 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 srcextra +Copies its dependencies into the source directory. This generally should +be used for generated files such as @file{gcc/c-parse.c} 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 @@ -576,28 +619,28 @@ anything. @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 @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-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. +@item lang.opt +This file registers the set of switches that the front end accepts on +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 @@ -637,15 +680,15 @@ that should not be configured if this front end is not built. 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 @@ -732,6 +775,9 @@ following are also necessary: 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 @@ -741,39 +787,48 @@ but it would be unusual to add support for a target that does not have a maintainer when support is added. @end itemize -@node Test Suites -@section Test Suites +@node Testsuites +@section Testsuites -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 +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 test suite code. -* C Tests:: The C language test suites. -* libgcj Tests:: The Java library test suites. +* Test Idioms:: Idioms used in testsuite code. +* 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 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. +@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. Test cases should use @code{abort ()} to indicate failure and @code{exit (0)} for success; on some targets these may be redefined to indicate failure and success in other ways. -In the @file{gcc.dg} test suite, it is often necessary to test that an +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, @@ -831,26 +886,64 @@ 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. +FIXME: discuss non-C testsuites here. + +@node Ada Tests +@subsection Ada Language Testsuites + +The Ada testsuite includes executable tests from the ACATS 2.5 +testsuite, publicly available at +@uref{http://www.adaic.org/compilers/acats/2.5} + +These tests are integrated in the GCC testsuite 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 testsuite 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 +@subsection C Language Testsuites -GCC contains the following C language test suites, in the +GCC contains the following C language testsuites, in the @file{gcc/testsuite} directory: @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. +@item gcc.dg/compat +This subdirectory contains tests for binary compatibility using +@file{compat.exp}, which in turn uses the language-independent support +(@pxref{compat Testing, , Support for testing binary compatibility}). @item gcc.dg/cpp This subdirectory contains tests of the preprocessor. @item gcc.dg/debug @@ -872,7 +965,7 @@ FIXME: describe this. 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. @@ -881,7 +974,7 @@ FIXME: describe this. This directory should probably not be used for new tests. @item gcc.c-torture/compile -This test suite contains test cases that should compile, but do not +This testsuite 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 @@ -891,7 +984,7 @@ platforms, by the use of @file{.x} files, mostly these test cases should not contain platform dependencies. FIXME: discuss how defines such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. @item gcc.c-torture/execute -This test suite contains test cases that should compile, link and run; +This testsuite contains test cases that should compile, link and run; otherwise the same comments as for @file{gcc.c-torture/compile} apply. @item gcc.c-torture/execute/ieee This contains tests which are specific to IEEE floating point. @@ -928,14 +1021,14 @@ FIXME: merge in @file{testsuite/README.gcc} and discuss the format of test cases and magic comments more. @node libgcj Tests -@subsection The Java library test suites. +@subsection The Java library testsuites. 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} +Mauve testsuite. The @uref{http://sources.redhat.com/mauve/,,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 @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying @@ -949,8 +1042,8 @@ Update this file when adding new failing tests to Mauve, or when fixing bugs in libgcj that had caused Mauve test failures. The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,, -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 +Jacks} project provides a testsuite for Java compilers that can be used +to test changes that affect the GCJ front end. This testsuite is run as part of Java testing by placing the Jacks tree within the the libjava testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. @@ -976,10 +1069,13 @@ and call return percentages. All of these checks are requested via commands that appear in comments in the test's source file. Commands to check line counts are processed by default. Commands to check branch percentages and call return percentages are -processed if there is a file with the same basename as the source -file and a suffix @file{.x} that contains a line -@code{set gcov_verify_branches 1} or @code{set gcov_verify_calls 1}, -respectively. +processed if the @command{run-gcov} command has arguments @code{branches} +or @code{calls}, respectively. For example, the following specifies +checking both, as well as passing @code{-b} to @command{gcov}: + +@smallexample +@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} +@end smallexample A line count command appears within a comment on the source line that is expected to get the specified count and has the form @@ -1042,7 +1138,7 @@ about a specific optimization: @table @code @item tool -tool being tested, e.g., gcc +tool being tested, e.g., @command{gcc} @item profile_option options used to generate profile data @@ -1062,11 +1158,10 @@ torture tests @subsection Support for testing binary compatibility The file @file{compat.exp} provides language-independent support for -binary compatibility testing. It supports testing interoperability -of two compilers that follow the same ABI, or of multiple sets of -compiler options that should not affect binary compatibility. -It is intended to be used for test suites that complement ABI test -suites. +binary compatibility testing. It supports testing interoperability of +two compilers that follow the same ABI, or of multiple sets of +compiler options that should not affect binary compatibility. It is +intended to be used for testsuites that complement ABI testsuites. A test supported by this framework has three parts, each in a separate source file: a main program and two pieces that interact |
