diff options
Diffstat (limited to 'contrib/gcc/doc/sourcebuild.texi')
| -rw-r--r-- | contrib/gcc/doc/sourcebuild.texi | 354 |
1 files changed, 303 insertions, 51 deletions
diff --git a/contrib/gcc/doc/sourcebuild.texi b/contrib/gcc/doc/sourcebuild.texi index 89778691fbdd..c60dcfaff728 100644 --- a/contrib/gcc/doc/sourcebuild.texi +++ b/contrib/gcc/doc/sourcebuild.texi @@ -124,7 +124,7 @@ 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 thie directory. +details of the files in this directory. @item doc Texinfo documentation for GCC, together with automatically generated @@ -155,7 +155,7 @@ 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 @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from +by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from which messages should not be extracted. @item testsuite @@ -246,8 +246,8 @@ libraries are also installed by GCC; these are not documented here. Several of the headers GCC installs are in the @file{ginclude} directory. These headers, @file{iso646.h}, -@file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and -@file{varargs.h}, are installed in @file{@var{libsubdir}/include}, +@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}. @@ -255,12 +255,13 @@ 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 normally installs -a @code{<float.h>} file; these are kept as -@file{config/float-@var{format}.h}, where @var{format} is specified by -a @code{float_format} setting in @file{config.gcc}, and a setting -@samp{float_format=none} disables installation of this header. GCC -also installs its own version of @code{<limits.h>}; this is generated +@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 @@ -277,7 +278,7 @@ needs fixing, @file{syslimits.h} is the fixed copy. 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 @command{make dvi}. In addition, some man pages are +generated by @samp{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 @file{gcc} directory. FIXME: document the @@ -311,9 +312,9 @@ The GNU General Public License. A copy of @file{texinfo.tex} known to work with the GCC manuals. @end table -DVI formatted manuals are generated by @command{make dvi}, which uses +DVI formatted manuals are generated by @samp{make dvi}, which uses @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info -manuals are generated by @command{make info} (which is run as part of +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. @@ -329,7 +330,7 @@ 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 -@command{makeinfo --html} and PostScript manuals by @command{texi2dvi} +@samp{makeinfo --html} and PostScript manuals by @command{texi2dvi} and @command{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. @@ -492,6 +493,9 @@ inclusion in GCC, should be made available on the GCC FTP site @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 @@ -537,7 +541,7 @@ deprecated). FIXME: exactly what goes in each of these targets? @item info Build info documentation for the front end, in the source directory. -This target is only called by @command{make bootstrap} if a suitable +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 @@ -607,9 +611,10 @@ codes. @node Front End Config @subsubsection The Front End @file{config-lang.in} File -Each language subdirectory contains a @file{config-lang.in} file. -This file is a shell script that may define some variables describing -the language: +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 @@ -652,6 +657,12 @@ 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}. + @end table @node Back End @@ -671,6 +682,10 @@ possibly a target Makefile fragment @file{t-@var{machine}} 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 Entries in @file{config.gcc} (@pxref{System Config, , The @file{config.gcc} File}) for the systems with this target architecture. @@ -736,9 +751,12 @@ suites. Currently only the C language test suites 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 test suite code. +* C Tests:: The C language test suites. +* libgcj Tests:: The Java library test suites. +* 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 @@ -810,6 +828,10 @@ 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 test suites here. @node C Tests @@ -819,6 +841,42 @@ GCC contains the following C language test suites, in the @file{gcc/testsuite} directory: @table @file +@item gcc.dg +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 +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/cpp +This subdirectory contains tests of the preprocessor. +@item gcc.dg/debug +This subdirectory contains tests for debug formats. Tests in this +subdirectory are run for each debug format that the compiler supports. +@item gcc.dg/format +This subdirectory contains tests of the @option{-Wformat} format +checking. Tests in this directory are run with and without +@option{-DWIDE}. +@item 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. +@item gcc.dg/special +FIXME: describe this. + +@item 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. + @item gcc.c-torture/compat FIXME: describe this. @@ -836,37 +894,35 @@ 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; 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. @item gcc.c-torture/unsorted FIXME: describe this. This directory should probably not be used for new tests. -@item gcc.dg -This test suite contains tests using the more modern @samp{dg} harness. -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/cpp -This subdirectory contains tests of the preprocessor. -@item gcc.dg/debug -This subdirectory contains tests for debug formats. Tests in this -subdirectory are run for each debug format that the compiler supports. -@item gcc.dg/format -This subdirectory contains tests of the @option{-Wformat} format -checking. Tests in this directory are run with and without -@option{-DWIDE}. -@item 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. -@item gcc.dg/special -FIXME: describe this. @item gcc.c-torture/misc-tests -FIXME: describe this, when it should be used for new tests and when it -shouldn't. +This directory contains C tests that require special handling. Some +of these tests have individual expect files, and others share +special-purpose expect files: + +@table @file +@item @code{bprob*.c} +Test @option{-fbranch-probabilities} using @file{bprob.exp}, which +in turn uses the generic, language-independent framework +(@pxref{profopt Testing, , Support for testing profile-directed +optimizations}). + +@item @code{dg-*.c} +Test the testsuite itself using @file{dg-test.exp}. + +@item @code{gcov*.c} +Test @command{gcov} output using @file{gcov.exp}, which in turn uses the +language-independent support (@pxref{gcov Testing, , Support for testing gcov}). + +@item @code{i386-pf-*.c} +Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. +@end table + @end table FIXME: merge in @file{testsuite/README.gcc} and discuss the format of @@ -882,12 +938,208 @@ 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} develops tests for the Java Class Libraries. These tests are run as part -of libgcj testing by specifying the location of the Mauve tree when invoking -@samp{make}, as in @samp{make MAUVEDIR=~/mauve check}. +of libgcj testing by placing the Mauve tree within the libjava testsuite +sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying +the location of that tree when invoking @samp{make}, as in +@samp{make MAUVEDIR=~/mauve check}. + +To detect regressions, a mechanism in @file{mauve.exp} compares the +failures for a test run against the list of expected failures in +@file{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 @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. There is no automated -mechanism to run the Jacks suite as part of GCJ testing. +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 @file{libjava/testsuite/libjava.jacks/jacks}. We encourage developers to contribute test cases to Mauve and Jacks. + +@node gcov Testing +@subsection Support for testing @command{gcov} + +Language-independent support for testing @command{gcov}, and for checking +that branch profiling produces expected values, is provided by the +expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures +in @file{gcc.dg.exp} to compile and run the test program. A typical +@command{gcov} test contains the following DejaGNU commands within comments: + +@smallexample +@{ dg-options "-fprofile-arcs -ftest-coverage" @} +@{ dg-do run @{ target native @} @} +@{ dg-final @{ run-gcov sourcefile @} @} +@end smallexample + +Checks of @command{gcov} output can include line counts, branch percentages, +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. + +A line count command appears within a comment on the source line +that is expected to get the specified count and has the form +@code{count(@var{cnt})}. A test should only check line counts for +lines that will get the same count for any architecture. + +Commands to check branch percentages (@code{branch}) and call +return percentages (@code{returns}) are very similar to each other. +A beginning command appears on or before the first of a range of +lines that will report the percentage, and the ending command +follows that range of lines. The beginning command can include a +list of percentages, all of which are expected to be found within +the range. A range is terminated by the next command of the same +kind. A command @code{branch(end)} or @code{returns(end)} marks +the end of a range without starting a new one. For example: + +@smallexample +if (i > 10 && j > i && j < 20) /* branch(27 50 75) */ + /* branch(end) */ + foo (i, j); +@end smallexample + +For a call return percentage, the value specified is the +percentage of calls reported to return. For a branch percentage, +the value is either the expected percentage or 100 minus that +value, since the direction of a branch can differ depending on the +target or the optimization level. + +Not all branches and calls need to be checked. A test should not +check for branches that might be optimized away or replaced with +predicated instructions. Don't check for calls inserted by the +compiler or ones that might be inlined or optimized away. + +A single test can check for combinations of line counts, branch +percentages, and call return percentages. The command to check a +line count must appear on the line that will report that count, but +commands to check branch percentages and call return percentages can +bracket the lines that report them. + +@node profopt Testing +@subsection Support for testing profile-directed optimizations + +The file @file{profopt.exp} provides language-independent support for +checking correct execution of a test built with profile-directed +optimization. This testing requires that a test program be built and +executed twice. The first time it is compiled to generate profile +data, and the second time it is compiled to use the data that was +generated during the first execution. The second execution is to +verify that the test produces the expected results. + +To check that the optimization actually generated better code, a +test can be built and run a third time with normal optimizations to +verify that the performance is better with the profile-directed +optimizations. @file{profopt.exp} has the beginnings of this kind +of support. + +@file{profopt.exp} provides generic support for profile-directed +optimizations. Each set of tests that uses it provides information +about a specific optimization: + +@table @code +@item tool +tool being tested, e.g., gcc + +@item profile_option +options used to generate profile data + +@item feedback_option +options used to optimize using that profile data + +@item prof_ext +suffix of profile data files + +@item PROFOPT_OPTIONS +list of options with which to run each test, similar to the lists for +torture tests +@end table + +@node compat Testing +@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. + +A test supported by this framework has three parts, each in a +separate source file: a main program and two pieces that interact +with each other to split up the functionality being tested. + +@table @file +@item @var{testname}_main.@var{suffix} +Contains the main program, which calls a function in file +@file{@var{testname}_x.@var{suffix}}. + +@item @var{testname}_x.@var{suffix} +Contains at least one call to a function in +@file{@var{testname}_y.@var{suffix}}. + +@item @var{testname}_y.@var{suffix} +Shares data with, or gets arguments from, +@file{@var{testname}_x.@var{suffix}}. +@end table + +Within each test, the main program and one functional piece are +compiled by the GCC under test. The other piece can be compiled by +an alternate compiler. If no alternate compiler is specified, +then all three source files are all compiled by the GCC under test. +It's also possible to specify a pair of lists of compiler options, +one list for each compiler, so that each test will be compiled with +each pair of options. + +@file{compat.exp} defines default pairs of compiler options. +These can be overridden by defining the environment variable +@env{COMPAT_OPTIONS} as: + +@smallexample +COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] + ...[list @{@var{tstn}@} @{@var{altn}@}]]" +@end smallexample + +where @var{tsti} and @var{alti} are lists of options, with @var{tsti} +used by the compiler under test and @var{alti} used by the alternate +compiler. For example, with +@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, +the test is first built with @code{-g -O0} by the compiler under +test and with @code{-O3} by the alternate compiler. The test is +built a second time using @code{-fpic} by the compiler under test +and @code{-fPIC -O2} by the alternate compiler. + +An alternate compiler is specified by defining an environment +variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full +pathname of an installed compiler. That will be written to the +@file{site.exp} file used by DejaGNU. The default is to build each +test with the compiler under test using the first of each pair of +compiler options from @env{COMPAT_OPTIONS}. When +@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using +the compiler under test but with combinations of the options from +@env{COMPAT_OPTIONS}. + +To run only the C++ compatibility suite using the compiler under test +and another version of GCC using specific compiler options, do the +following from @file{@var{objdir}/gcc}: + +@smallexample +rm site.exp +make -k \ + ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ + COMPAT_OPTIONS="lists as shown above" \ + check-c++ \ + RUNTESTFLAGS="compat.exp" +@end smallexample + +A test that fails when the source files are compiled with different +compilers, but passes when the files are compiled with the same +compiler, demonstrates incompatibility of the generated code or +runtime support. A test that fails for the alternate compiler but +passes for the compiler under test probably tests for a bug that was +fixed in the compiler under test but is present in the alternate +compiler. |