Installing GCC: Testing

Before you install GCC, we encourage you to run the testsuites and to compare your results with results from a similar configuration that have been submitted to the gcc-testresults mailing list. Some of these archived results are linked from the build status lists at https://gcc.gnu.org/buildstat.html, although not everyone who reports a successful build runs the testsuites and submits the results. This step is optional and may require you to download additional software, but it can give you confidence in your new GCC installation or point out problems before you install and start using your new GCC.

First, you must have downloaded the testsuites. These are part of the full distribution, but if you downloaded the “core” compiler plus any front ends, you must download the testsuites separately.

Second, you must have the testing tools installed. This includes DejaGnu, Tcl, and Expect; the DejaGnu site has links to these. Some optional tests also require Python3 and pytest module.

If the directories where runtest and expect were installed are not in the PATH, you may need to set the following environment variables appropriately, as in the following example (which assumes that DejaGnu has been installed under /usr/local):

TCL_LIBRARY = /usr/local/share/tcl8.0
DEJAGNULIBS = /usr/local/share/dejagnu

(On systems such as Cygwin, these paths are required to be actual paths, not mounts or links; presumably this is due to some lack of portability in the DejaGnu code.)

Finally, you can run the testsuite (which may take a long time):

cd objdir; make -k check

This will test various components of GCC, such as compiler front ends and runtime libraries. While running the testsuite, DejaGnu might emit some harmless messages resembling ‘WARNING: Couldn't find the global config file.’ or ‘WARNING: Couldn't find tool init file’ that can be ignored.

If you are testing a cross-compiler, you may want to run the testsuite on a simulator as described at https://gcc.gnu.org/simtest-howto.html.

How can you run the testsuite on selected tests?

In order to run sets of tests selectively, there are targets ‘make check-gcc’ and language specific ‘make check-c’, ‘make check-c++’, ‘make check-d’ ‘make check-fortran’, ‘make check-ada’, ‘make check-objc’, ‘make check-obj-c++’, ‘make check-lto’ in the gcc subdirectory of the object directory. You can also just run ‘make check’ in a subdirectory of the object directory.

A more selective way to just run all gcc execute tests in the testsuite is to use

make check-gcc RUNTESTFLAGS="execute.exp other-options"

Likewise, in order to run only the g++ “old-deja” tests in the testsuite with filenames matching ‘9805*’, you would use

make check-g++ RUNTESTFLAGS="old-deja.exp=9805* other-options"

The file-matching expression following filename.exp= is treated as a series of whitespace-delimited glob expressions so that multiple patterns may be passed, although any whitespace must either be escaped or surrounded by single quotes if multiple expressions are desired. For example,

make check-g++ RUNTESTFLAGS="old-deja.exp=9805*\ virtual2.c other-options"
make check-g++ RUNTESTFLAGS="'old-deja.exp=9805* virtual2.c' other-options"

The *.exp files are located in the testsuite directories of the GCC source, the most important ones being compile.exp, execute.exp, dg.exp and old-deja.exp. To get a list of the possible *.exp files, pipe the output of ‘make check’ into a file and look at the ‘Running … .exp’ lines.

Passing options and running multiple testsuites

You can pass multiple options to the testsuite using the ‘--target_board’ option of DejaGNU, either passed as part of ‘RUNTESTFLAGS’, or directly to runtest if you prefer to work outside the makefiles. For example,

make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fmerge-constants"

will run the standard g++ testsuites (“unix” is the target name for a standard native testsuite situation), passing ‘-O3 -fmerge-constants’ to the compiler on every test, i.e., slashes separate options.

You can run the testsuites multiple times using combinations of options with a syntax similar to the brace expansion of popular shells:

…"--target_board=arm-sim\{-mhard-float,-msoft-float\}\{-O1,-O2,-O3,\}"

(Note the empty option caused by the trailing comma in the final group.) The following will run each testsuite eight times using the ‘arm-sim’ target, as if you had specified all possible combinations yourself:

--target_board='arm-sim/-mhard-float/-O1 \
                arm-sim/-mhard-float/-O2 \
                arm-sim/-mhard-float/-O3 \
                arm-sim/-mhard-float \
                arm-sim/-msoft-float/-O1 \
                arm-sim/-msoft-float/-O2 \
                arm-sim/-msoft-float/-O3 \
                arm-sim/-msoft-float'

They can be combined as many times as you wish, in arbitrary ways. This list:

…"--target_board=unix/-Wextra\{-O3,-fno-strength\}\{-fomit-frame,\}"

will generate four combinations, all involving ‘-Wextra’.

The disadvantage to this method is that the testsuites are run in serial, which is a waste on multiprocessor systems. For users with GNU Make and a shell which performs brace expansion, you can run the testsuites in parallel by having the shell perform the combinations and make do the parallel runs. Instead of using ‘--target_board’, use a special makefile target:

make -jN check-testsuite//test-target/option1/option2/…

For example,

make -j3 check-gcc//sh-hms-sim/{-m1,-m2,-m3,-m3e,-m4}/{,-nofpu}

will run three concurrent “make-gcc” testsuites, eventually testing all ten combinations as described above. Note that this is currently only supported in the gcc subdirectory. (To see how this works, try typing echo before the example given here.)

How to interpret test results

The result of running the testsuite are various *.sum and *.log files in the testsuite subdirectories. The *.log files contain a detailed log of the compiler invocations and the corresponding results, the *.sum files summarize the results. These summaries contain status codes for all tests:

It is normal for some tests to report unexpected failures. At the current time the testing harness does not allow fine grained control over whether or not a test is expected to fail. This problem should be fixed in future releases.

Submitting test results

If you want to report the results to the GCC project, use the contrib/test_summary shell script. Start it in the objdir with

srcdir/contrib/test_summary -p your_commentary.txt \
    -m gcc-testresults@gcc.gnu.org |sh

This script uses the Mail program to send the results, so make sure it is in your PATH. The file your_commentary.txt is prepended to the testsuite summary and should contain any special remarks you have on your results or your build environment. Please do not edit the testsuite result block or the subject line, as these messages may be automatically processed.


Return to the GCC Installation page