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, optionally used as part of the ObjC runtime library when configured with --enable-objc-gc.

config
     Autoconf macros and Makefile fragments used throughout the tree.

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.

fixincludes
     The support for fixing system headers to work with GCC.  See fixincludes/README for more information.  The headers fixed by this mechanism are installed in LIBSUBDIR/include-fixed. Along with those headers, README-fixinc is also installed, as LIBSUBDIR/include-fixed/README.

gcc
     The main sources of GCC itself (except for runtime libraries), including optimizers, support for different target architectures, language front ends, and testsuites.  See The gcc Subdirectory, for details.

gnattools
     Support tools for GNAT.

include
     Headers for the libiberty library.

intl
     GNU libintl, from GNU gettext, for systems which do not include it in libc.

libada
     The Ada runtime library.

libatomic
     The runtime support library for atomic operations (e.g. for __sync and __atomic).

libcpp
     The C preprocessor library.

libdecnumber
     The Decimal Float support library.

libffi
     The libffi library, used as part of the Go runtime library.

libgcc
     The GCC runtime library.

libgfortran
     The Fortran runtime library.

libgo
     The Go runtime library.  The bulk of this library is mirrored from the master Go repository (https://github.com/golang/go).

libgomp
     The GNU Offloading and Multi Processing 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.

libitm
     The runtime support library for transactional memory.

libobjc
     The Objective-C and Objective-C++ runtime library.

libquadmath
     The runtime support library for quad-precision math operations.

libssp
     The Stack protector runtime library.

libstdc++-v3
     The C++ runtime library.

lto-plugin
     Plugin used by the linker if link-time optimizations are enabled.

maintainer-scripts
     Scripts used by the gccadmin account on gcc.gnu.org.

zlib
     The zlib compression library, used for compressing and uncompressing GCC's intermediate language in LTO object files.

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 testsuite.  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 c (for C), cp (for C++), objc (for Objective-C), objcp (for Objective-C++), and lto (for LTO) 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.

common
     Source files shared between the compiler drivers (such as gcc) and the compilers proper (such as cc1).  If an architecture defines target hooks shared between those places, it also has a subdirectory in common/config.  See Target Structure.

config
     Configuration files for supported architectures and operating systems.  See Anatomy of a Target Back End, for details of the files in this directory.

doc
     Texinfo documentation for GCC, together with automatically generated man pages and support for converting the installation manual to HTML.  See Documentation.

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.

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 testsuites (except for those for runtime libraries). See Testsuites.

Configuration in the gcc Directory
----------------------------------

The gcc directory is configured with an Autoconf-generated script configure.  The configure script is generated from configure.ac and aclocal.m4.  From the files configure.ac 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.

  * The file config.gcc is used to handle configuration specific to the particular target machine.  The file config.build is used to handle configuration specific to the particular build machine.  The 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.) See The config.build; config.host; and config.gcc Files, for details of the contents of these files.

  * 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.build; config.host; and config.gcc Files
...................................................

The 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 config.host file contains specific rules for particular systems which GCC will run on.  This is rarely needed.

The 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.

     [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.

GCC can also install <tgmath.h>.  It will do this when config.gcc sets use_gcc_tgmath to yes.

Building Documentation
----------------------

The main GCC documentation is in the form of manuals in Texinfo format.  These are installed in Info format; DVI versions may be generated by make dvi, PDF versions by make pdf, and HTML versions by make html.  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_v3.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)). PDF-formatted manuals are generated by make pdf, which uses texi2pdf (via the Makefile macro $(TEXI2PDF)).  HTML formatted manuals are generated by make html.  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_svn.  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, PostScript manuals by texi2dvi and dvips, and PDF manuals by texi2pdf. All Texinfo files that are parts of manuals must be version-controlled, 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 in the gcc subdirectory 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
COPYING3
     The GNU General Public License, Versions 2 and 3.

COPYING.LIB
COPYING3.LIB
     The GNU Lesser General Public License, Versions 2.1 and 3.

*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?

FIXME: document such files in subdirectories, at least config, c, 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.

  * A mention of the name under which the language's runtime library is recognized by --enable-shared=PACKAGE in the documentation of that option in gcc/doc/install.texi.

  * A mention of any special prerequisites for building the front end in the documentation of prerequisites 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 testsuites, which may be under gcc/testsuite or runtime library directories.  FIXME: document somewhere how to write testsuite 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.

  * Check targets in Makefile.def for the top-level Makefile to check just the compiler or the compiler and runtime library for the language.

If the front end is added to the official GCC source repository, the following are also necessary:

  * At least one Bugzilla component for bugs in that front end and runtime libraries.  This category needs to be added to the Bugzilla 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_svn (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.

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

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 built 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.  See The Front End Make-lang.in File, for details of its contents.

lang.opt
     This file registers the set of switches that the front end accepts on the command line, and their --help text.  See Options.

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. 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 Obj-C++ front end depends on the C++ and ObjC front ends, so sets lang_requires="objc c++".

subdir_requires
     If defined, this variable lists (space-separated) front end directories other than C that this front end requires to be present.  For example, the Objective-C++ front end uses source files from the C++ and Objective-C front ends, so sets subdir_requires="cp objc".

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.ac (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 stage1 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 will be run by the driver.  The names here will each end with \$(exeext).

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.

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

Each language subdirectory contains a Make-lang.in file.  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).  It also adds any testsuite targets that can use the standard rule in gcc/Makefile.in to the variable lang_checks.

all.cross
start.encap
rest.encap
     FIXME: exactly what goes in each of these targets?

tags
     Build an etags TAGS file in the language subdirectory in the source tree.

info
     Build info documentation for the front end, in the build 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.

pdf
     Build PDF documentation for the front end, in the build directory. This should be done using $(TEXI2PDF), with appropriate -I arguments pointing to directories of included files.

html
     Build HTML documentation for the front end, in the build directory.

man
     Build generated man pages for the front end from Texinfo manuals (see 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.

install-common
     Install everything that is part of the front end, apart from the compiler executables listed in compilers in config-lang.in.

install-info
     Install info documentation for the front end, if it is present in the source directory.  This target should have dependencies on info files that should be installed.

install-man
     Install man pages for the front end.  This target should ignore errors.

install-plugin
     Install headers needed for plugins.

srcextra
     Copies its dependencies into the source directory.  This generally should be used for generated files such as Bison output files which are not version-controlled, but should be included in any release tarballs.  This target will be executed during a bootstrap if --enable-generated-files-in-srcdir was specified as a configure option.

srcinfo
srcman
     Copies its dependencies into the source directory.  These targets will be executed during a bootstrap if --enable-generated-files-in-srcdir was specified as a configure option.

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
maintainer-clean
     The language parts of the standard GNU *clean targets.  See Standard Targets for Users (GNU Coding Standards), for details of the standard targets.  For GCC, maintainer-clean should delete all generated files in the source directory that are not version-controlled, but should not delete anything that is.

Make-lang.in must also define a variable LANG_OBJS to a list of host object files that are used by that language.

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.

  * An optional MACHINE.opt file in the MACHINE directory, containing a list of target-specific options.  You can also add other option files using the extra_options variable in config.gcc.  See Options.

  * 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/extend.texi of any target-specific format checking styles 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 source repository, the following are also necessary:

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

  * Details of the properties of the back end and target architecture in backends.html on the GCC web site.

  * 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.

  * Target triplets covering all config.gcc stanzas for the target, in the list in contrib/config-list.mk.

Testsuites
**********

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.

Idioms Used in Testsuite Code
=============================

In general, C testcases have a trailing -N.c, starting with -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 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, prBUG-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.

In the 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 -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 testsuites here.

Directives used within DejaGnu tests
====================================

Syntax and Descriptions of test directives
------------------------------------------

Test directives appear within comments in a test source file and begin with dg-.  Some of these are defined within DejaGnu and others are local to the GCC testsuite.

The order in which test directives appear in a test can be important: directives local to GCC sometimes override information used by the DejaGnu directives, which know nothing about the GCC directives, so the DejaGnu directives must precede GCC directives.

Several test directives include selectors (see Selectors) which are usually preceded by the keyword target or xfail.

Specify how to build the test
.............................

{ dg-do DO-WHAT-KEYWORD [{ target/xfail SELECTOR }] }
     DO-WHAT-KEYWORD specifies how the test is compiled and whether it is executed.  It is one of:

     preprocess
          Compile with -E to run only the preprocessor.

     compile
          Compile with -S to produce an assembly code file.

     assemble
          Compile with -c to produce a relocatable object file.

     link
          Compile, assemble, and link to produce an executable file.

     run
          Produce and run an executable file, which is expected to return an exit code of 0.

     The default is compile.  That can be overridden for a set of tests by redefining dg-do-what-default within the .exp file for those tests.

     If the directive includes the optional { target SELECTOR } then the test is skipped unless the target system matches the SELECTOR.

     If DO-WHAT-KEYWORD is run and the directive includes the optional { xfail SELECTOR } and the selector is met then the test is expected to fail.  The xfail clause is ignored for other values of DO-WHAT-KEYWORD; those tests can use directive dg-xfail-if.

Specify additional compiler options
...................................

{ dg-options OPTIONS [{ target SELECTOR }] }
     This DejaGnu directive provides a list of compiler options, to be used if the target system matches SELECTOR, that replace the default options used for this set of tests.

{ dg-add-options FEATURE ... }
     Add any compiler options that are needed to access certain features. This directive does nothing on targets that enable the features by default, or that don't provide them at all.  It must come after all dg-options directives. For supported values of FEATURE see Add Options.

{ dg-additional-options OPTIONS [{ target SELECTOR }] }
     This directive provides a list of compiler options, to be used if the target system matches SELECTOR, that are added to the default options used for this set of tests.

Modify the test timeout value
.............................

The normal timeout limit, in seconds, is found by searching the following in order:

  * the value defined by an earlier dg-timeout directive in the test

  * variable TOOL_TIMEOUT defined by the set of tests

  * GCC,TIMEOUT set in the target board

  * 300

{ dg-timeout N [{target SELECTOR }] }
     Set the time limit for the compilation and for the execution of the test to the specified number of seconds.

{ dg-timeout-factor X [{ target SELECTOR }] }
     Multiply the normal time limit for compilation and execution of the test by the specified floating-point factor.

Skip a test for some targets
............................

{ dg-skip-if COMMENT { SELECTOR } [{ INCLUDE-OPTS } [{ EXCLUDE-OPTS }]] }
     Arguments INCLUDE-OPTS and EXCLUDE-OPTS are lists in which each element is a string of zero or more GCC options. Skip the test if all of the following conditions are met:

       * the test system is included in SELECTOR

       * for at least one of the option strings in INCLUDE-OPTS, every option from that string is in the set of options with which the test would be compiled; use "*" for an INCLUDE-OPTS list that matches any options; that is the default if INCLUDE-OPTS is not specified

       * for each of the option strings in EXCLUDE-OPTS, at least one option from that string is not in the set of options with which the test would be compiled; use "" for an empty EXCLUDE-OPTS list; that is the default if EXCLUDE-OPTS is not specified

     For example, to skip a test if option -Os is present:

          /* { dg-skip-if "" { *-*-* }  { "-Os" } { "" } } */

     To skip a test if both options -O2 and -g are present:

          /* { dg-skip-if "" { *-*-* }  { "-O2 -g" } { "" } } */

     To skip a test if either -O2 or -O3 is present:

          /* { dg-skip-if "" { *-*-* }  { "-O2" "-O3" } { "" } } */

     To skip a test unless option -Os is present:

          /* { dg-skip-if "" { *-*-* }  { "*" } { "-Os" } } */

     To skip a test if either -O2 or -O3 is used with -g but not if -fpic is also present:

          /* { dg-skip-if "" { *-*-* }  { "-O2 -g" "-O3 -g" } { "-fpic" } } */

{ dg-require-effective-target KEYWORD [{ SELECTOR }] }
     Skip the test if the test target, including current multilib flags, is not covered by the effective-target keyword. If the directive includes the optional { SELECTOR } then the effective-target test is only performed if the target system matches the SELECTOR. This directive must appear after any dg-do directive in the test and before any dg-additional-sources directive. See Effective-Target Keywords.

{ dg-require-SUPPORT args }
     Skip the test if the target does not provide the required support. These directives must appear after any dg-do directive in the test and before any dg-additional-sources directive. They require at least one argument, which can be an empty string if the specific procedure does not examine the argument. See Require Support, for a complete list of these directives.

Expect a test to fail for some targets
......................................

{ dg-xfail-if COMMENT { SELECTOR } [{ INCLUDE-OPTS } [{ EXCLUDE-OPTS }]] }
     Expect the test to fail if the conditions (which are the same as for dg-skip-if) are met.  This does not affect the execute step.

{ dg-xfail-run-if COMMENT { SELECTOR } [{ INCLUDE-OPTS } [{ EXCLUDE-OPTS }]] }
     Expect the execute step of a test to fail if the conditions (which are the same as for dg-skip-if) are met.

Expect the test executable to fail
..................................

{ dg-shouldfail COMMENT [{ SELECTOR } [{ INCLUDE-OPTS } [{ EXCLUDE-OPTS }]]] }
     Expect the test executable to return a nonzero exit status if the conditions (which are the same as for dg-skip-if) are met.

Verify compiler messages
........................

{ dg-error REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] ]] }
     This DejaGnu directive appears on a source line that is expected to get an error message, or else specifies the source line associated with the message.  If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the FAIL message.  The check does not look for the string error unless it is part of REGEXP.

{ dg-warning REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] ]] }
     This DejaGnu directive appears on a source line that is expected to get a warning message, or else specifies the source line associated with the message.  If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the FAIL message.  The check does not look for the string warning unless it is part of REGEXP.

{ dg-message REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] ]] }
     The line is expected to get a message other than an error or warning. If there is no message for that line or if the text of that message is not matched by REGEXP then the check fails and COMMENT is included in the FAIL message.

{ dg-bogus REGEXP [COMMENT [{ target/xfail SELECTOR } [LINE] ]] }
     This DejaGnu directive appears on a source line that should not get a message matching REGEXP, or else specifies the source line associated with the bogus message.  It is usually used with xfail to indicate that the message is a known problem for a particular set of targets.

{ dg-excess-errors COMMENT [{ target/xfail SELECTOR }] }
     This DejaGnu directive indicates that the test is expected to fail due to compiler messages that are not handled by dg-error, dg-warning or dg-bogus.  For this directive xfail has the same effect as target.

{ dg-prune-output REGEXP }
     Prune messages matching REGEXP from the test output.

Verify output of the test executable
....................................

{ dg-output REGEXP [{ target/xfail SELECTOR }] }
     This DejaGnu directive compares REGEXP to the combined output that the test executable writes to stdout and stderr.

Specify additional files for a test
...................................

{ dg-additional-files "FILELIST" }
     Specify additional files, other than source files, that must be copied to the system where the compiler runs.

{ dg-additional-sources "FILELIST" }
     Specify additional source files to appear in the compile line following the main test file.

Add checks at the end of a test
...............................

{ dg-final { LOCAL-DIRECTIVE } }
     This DejaGnu directive is placed within a comment anywhere in the source file and is processed after the test has been compiled and run. Multiple dg-final commands are processed in the order in which they appear in the source file.  See Final Actions, for a list of directives that can be used within dg-final.

Selecting targets to which a test applies
-----------------------------------------

Several test directives include SELECTORs to limit the targets for which a test is run or to declare that a test is expected to fail on particular targets.

A selector is:

  * one or more target triplets, possibly including wildcard characters; use *-*-* to match any target

  * a single effective-target keyword (see Effective-Target Keywords)

  * a logical expression

Depending on the context, the selector specifies whether a test is skipped and reported as unsupported or is expected to fail.  A context that allows either target or xfail also allows { target SELECTOR1 xfail SELECTOR2 } to skip the test for targets that don't match SELECTOR1 and the test to fail for targets that match SELECTOR2.

A selector expression appears within curly braces and uses a single logical operator: one of !, &&, or ||.  An operand is another selector expression, an effective-target keyword, a single target triplet, or a list of target triplets within quotes or curly braces.  For example:

     { target { ! "hppa*-*-* ia64*-*-*" } }
     { target { powerpc*-*-* && lp64 } }
     { xfail { lp64 || vect_no_align } }

Keywords describing target attributes
-------------------------------------

Effective-target keywords identify sets of targets that support particular functionality.  They are used to limit tests to be run only for particular targets, or to specify that particular sets of targets are expected to fail some tests.

Effective-target keywords are defined in lib/target-supports.exp in the GCC testsuite, with the exception of those that are documented as being local to a particular test directory.

The effective target takes into account all of the compiler options with which the test will be compiled, including the multilib options. By convention, keywords ending in _nocache can also include options specified for the particular test in an earlier dg-options or dg-add-options directive.

Data type sizes
...............

ilp32
     Target has 32-bit int, long, and pointers.

lp64
     Target has 32-bit int, 64-bit long and pointers.

llp64
     Target has 32-bit int and long, 64-bit long long and pointers.

double64
     Target has 64-bit double.

double64plus
     Target has double that is 64 bits or longer.

longdouble128
     Target has 128-bit long double.

int32plus
     Target has int that is at 32 bits or longer.

int16
     Target has int that is 16 bits or shorter.

long_neq_int
     Target has int and long with different sizes.

large_double
     Target supports double that is longer than float.

large_long_double
     Target supports long double that is longer than double.

ptr32plus
     Target has pointers that are 32 bits or longer.

size32plus
     Target supports array and structure sizes that are 32 bits or longer.

4byte_wchar_t
     Target has wchar_t that is at least 4 bytes.

floatN
     Target has the _FloatN type.

floatNx
     Target has the _FloatNx type.

floatN_runtime
     Target has the _FloatN type, including runtime support for any options added with dg-add-options.

floatNx_runtime
     Target has the _FloatNx type, including runtime support for any options added with dg-add-options.

floatn_nx_runtime
     Target has runtime support for any options added with dg-add-options for any _FloatN or _FloatNx type.

Fortran-specific attributes
...........................

fortran_integer_16
     Target supports Fortran integer that is 16 bytes or longer.

fortran_large_int
     Target supports Fortran integer kinds larger than integer(8).

fortran_large_real
     Target supports Fortran real kinds larger than real(8).

Vector-specific attributes
..........................

vect_condition
     Target supports vector conditional operations.

vect_cond_mixed
     Target supports vector conditional operations where comparison operands have different type from the value operands.

vect_double
     Target supports hardware vectors of double.

vect_float
     Target supports hardware vectors of float.

vect_int
     Target supports hardware vectors of int.

vect_long
     Target supports hardware vectors of long.

vect_long_long
     Target supports hardware vectors of long long.

vect_aligned_arrays
     Target aligns arrays to vector alignment boundary.

vect_hw_misalign
     Target supports a vector misalign access.

vect_no_align
     Target does not support a vector alignment mechanism.

vect_no_int_min_max
     Target does not support a vector min and max instruction on int.

vect_no_int_add
     Target does not support a vector add instruction on int.

vect_no_bitwise
     Target does not support vector bitwise instructions.

vect_char_mult
     Target supports vector char multiplication.

vect_short_mult
     Target supports vector short multiplication.

vect_int_mult
     Target supports vector int multiplication.

vect_extract_even_odd
     Target supports vector even/odd element extraction.

vect_extract_even_odd_wide
     Target supports vector even/odd element extraction of vectors with elements SImode or larger.

vect_interleave
     Target supports vector interleaving.

vect_strided
     Target supports vector interleaving and extract even/odd.

vect_strided_wide
     Target supports vector interleaving and extract even/odd for wide element types.

vect_perm
     Target supports vector permutation.

vect_shift
     Target supports a hardware vector shift operation.

vect_widen_sum_hi_to_si
     Target supports a vector widening summation of short operands into int results, or can promote (unpack) from short to int.

vect_widen_sum_qi_to_hi
     Target supports a vector widening summation of char operands into short results, or can promote (unpack) from char to short.

vect_widen_sum_qi_to_si
     Target supports a vector widening summation of char operands into int results.

vect_widen_mult_qi_to_hi
     Target supports a vector widening multiplication of char operands into short results, or can promote (unpack) from char to short and perform non-widening multiplication of short.

vect_widen_mult_hi_to_si
     Target supports a vector widening multiplication of short operands into int results, or can promote (unpack) from short to int and perform non-widening multiplication of int.

vect_widen_mult_si_to_di_pattern
     Target supports a vector widening multiplication of int operands into long results.

vect_sdot_qi
     Target supports a vector dot-product of signed char.

vect_udot_qi
     Target supports a vector dot-product of unsigned char.

vect_sdot_hi
     Target supports a vector dot-product of signed short.

vect_udot_hi
     Target supports a vector dot-product of unsigned short.

vect_pack_trunc
     Target supports a vector demotion (packing) of short to char and from int to short using modulo arithmetic.

vect_unpack
     Target supports a vector promotion (unpacking) of char to short and from char to int.

vect_intfloat_cvt
     Target supports conversion from signed int to float.

vect_uintfloat_cvt
     Target supports conversion from unsigned int to float.

vect_floatint_cvt
     Target supports conversion from float to signed int.

vect_floatuint_cvt
     Target supports conversion from float to unsigned int.

vect_max_reduc
     Target supports max reduction for vectors.

Thread Local Storage attributes
...............................

tls
     Target supports thread-local storage.

tls_native
     Target supports native (rather than emulated) thread-local storage.

tls_runtime
     Test system supports executing TLS executables.

Decimal floating point attributes
.................................

dfp
     Targets supports compiling decimal floating point extension to C.

dfp_nocache
     Including the options used to compile this particular test, the target supports compiling decimal floating point extension to C.

dfprt
     Test system can execute decimal floating point tests.

dfprt_nocache
     Including the options used to compile this particular test, the test system can execute decimal floating point tests.

hard_dfp
     Target generates decimal floating point instructions with current options.

ARM-specific attributes
.......................

arm32
     ARM target generates 32-bit code.

arm_eabi
     ARM target adheres to the ABI for the ARM Architecture.

arm_fp_ok
     ARM target defines __ARM_FP using -mfloat-abi=softfp or equivalent options.  Some multilibs may be incompatible with these options.

arm_hf_eabi
     ARM target adheres to the VFP and Advanced SIMD Register Arguments variant of the ABI for the ARM Architecture (as selected with -mfloat-abi=hard).

arm_hard_vfp_ok
     ARM target supports -mfpu=vfp -mfloat-abi=hard. Some multilibs may be incompatible with these options.

arm_iwmmxt_ok
     ARM target supports -mcpu=iwmmxt. Some multilibs may be incompatible with this option.

arm_neon
     ARM target supports generating NEON instructions.

arm_tune_string_ops_prefer_neon
     Test CPU tune supports inlining string operations with NEON instructions.

arm_neon_hw
     Test system supports executing NEON instructions.

arm_neonv2_hw
     Test system supports executing NEON v2 instructions.

arm_neon_ok
     ARM Target supports -mfpu=neon -mfloat-abi=softfp or compatible options.  Some multilibs may be incompatible with these options.

arm_neonv2_ok
     ARM Target supports -mfpu=neon-vfpv4 -mfloat-abi=softfp or compatible options.  Some multilibs may be incompatible with these options.

arm_fp16_ok
     Target supports options to generate VFP half-precision floating-point instructions.  Some multilibs may be incompatible with these options.  This test is valid for ARM only.

arm_fp16_hw
     Target supports executing VFP half-precision floating-point instructions.  This test is valid for ARM only.

arm_neon_fp16_ok
     ARM Target supports -mfpu=neon-fp16 -mfloat-abi=softfp or compatible options, including -mfp16-format=ieee if necessary to obtain the __fp16 type.  Some multilibs may be incompatible with these options.

arm_neon_fp16_hw
     Test system supports executing Neon half-precision float instructions. (Implies previous.)

arm_fp16_alternative_ok
     ARM target supports the ARM FP16 alternative format.  Some multilibs may be incompatible with the options needed.

arm_fp16_none_ok
     ARM target supports specifying none as the ARM FP16 format.

arm_thumb1_ok
     ARM target generates Thumb-1 code for -mthumb.

arm_thumb2_ok
     ARM target generates Thumb-2 code for -mthumb.

arm_vfp_ok
     ARM target supports -mfpu=vfp -mfloat-abi=softfp. Some multilibs may be incompatible with these options.

arm_vfp3_ok
     ARM target supports -mfpu=vfp3 -mfloat-abi=softfp. Some multilibs may be incompatible with these options.

arm_v8_vfp_ok
     ARM target supports -mfpu=fp-armv8 -mfloat-abi=softfp. Some multilibs may be incompatible with these options.

arm_v8_neon_ok
     ARM target supports -mfpu=neon-fp-armv8 -mfloat-abi=softfp. Some multilibs may be incompatible with these options.

arm_v8_1a_neon_ok
     ARM target supports options to generate ARMv8.1 Adv.SIMD instructions. Some multilibs may be incompatible with these options.

arm_v8_1a_neon_hw
     ARM target supports executing ARMv8.1 Adv.SIMD instructions.  Some multilibs may be incompatible with the options needed.  Implies arm_v8_1a_neon_ok.

arm_acq_rel
     ARM target supports acquire-release instructions.

arm_v8_2a_fp16_scalar_ok
     ARM target supports options to generate instructions for ARMv8.2 and scalar instructions from the FP16 extension.  Some multilibs may be incompatible with these options.

arm_v8_2a_fp16_scalar_hw
     ARM target supports executing instructions for ARMv8.2 and scalar instructions from the FP16 extension.  Some multilibs may be incompatible with these options.  Implies arm_v8_2a_fp16_neon_ok.

arm_v8_2a_fp16_neon_ok
     ARM target supports options to generate instructions from ARMv8.2 with the FP16 extension.  Some multilibs may be incompatible with these options.  Implies arm_v8_2a_fp16_scalar_ok.

arm_v8_2a_fp16_neon_hw
     ARM target supports executing instructions from ARMv8.2 with the FP16 extension.  Some multilibs may be incompatible with these options. Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.

arm_prefer_ldrd_strd
     ARM target prefers LDRD and STRD instructions over LDM and STM instructions.

arm_thumb1_movt_ok
     ARM target generates Thumb-1 code for -mthumb with MOVW and MOVT instructions available.

arm_thumb1_cbz_ok
     ARM target generates Thumb-1 code for -mthumb with CBZ and CBNZ instructions available.

arm_divmod_simode
     ARM target for which divmod transform is disabled, if it supports hardware div instruction.

arm_cmse_ok
     ARM target supports ARMv8-M Security Extensions, enabled by the -mcmse option.

arm_coproc1_ok
     ARM target supports the following coprocessor instructions: CDP, LDC, STC, MCR and MRC.

arm_coproc2_ok
     ARM target supports all the coprocessor instructions also listed as supported in arm_coproc1_ok in addition to the following: CDP2, LDC2, LDC2l, STC2, STC2l, MCR2 and MRC2.

arm_coproc3_ok
     ARM target supports all the coprocessor instructions also listed as supported in arm_coproc2_ok in addition the following: MCRR and MRRC.

arm_coproc4_ok
     ARM target supports all the coprocessor instructions also listed as supported in arm_coproc3_ok in addition the following: MCRR2 and MRRC2.

AArch64-specific attributes
...........................

aarch64_asm_<ext>_ok
     AArch64 assembler supports the architecture extension ext via the .arch_extension pseudo-op.

aarch64_tiny
     AArch64 target which generates instruction sequences for tiny memory model.

aarch64_small
     AArch64 target which generates instruction sequences for small memory model.

aarch64_large
     AArch64 target which generates instruction sequences for large memory model.

aarch64_little_endian
     AArch64 target which generates instruction sequences for little endian.

aarch64_big_endian
     AArch64 target which generates instruction sequences for big endian.

aarch64_small_fpic
     Binutils installed on test system supports relocation types required by -fpic for AArch64 small memory model.

MIPS-specific attributes
........................

mips64
     MIPS target supports 64-bit instructions.

nomips16
     MIPS target does not produce MIPS16 code.

mips16_attribute
     MIPS target can generate MIPS16 code.

mips_loongson
     MIPS target is a Loongson-2E or -2F target using an ABI that supports the Loongson vector modes.

mips_msa
     MIPS target supports -mmsa, MIPS SIMD Architecture (MSA).

mips_newabi_large_long_double
     MIPS target supports long double larger than double when using the new ABI.

mpaired_single
     MIPS target supports -mpaired-single.

PowerPC-specific attributes
...........................

dfp_hw
     PowerPC target supports executing hardware DFP instructions.

p8vector_hw
     PowerPC target supports executing VSX instructions (ISA 2.07).

powerpc64
     Test system supports executing 64-bit instructions.

powerpc_altivec
     PowerPC target supports AltiVec.

powerpc_altivec_ok
     PowerPC target supports -maltivec.

powerpc_eabi_ok
     PowerPC target supports -meabi.

powerpc_elfv2
     PowerPC target supports -mabi=elfv2.

powerpc_fprs
     PowerPC target supports floating-point registers.

powerpc_hard_double
     PowerPC target supports hardware double-precision floating-point.

powerpc_htm_ok
     PowerPC target supports -mhtm

powerpc_p8vector_ok
     PowerPC target supports -mpower8-vector

powerpc_popcntb_ok
     PowerPC target supports the popcntb instruction, indicating that this target supports -mcpu=power5.

powerpc_ppu_ok
     PowerPC target supports -mcpu=cell.

powerpc_spe
     PowerPC target supports PowerPC SPE.

powerpc_spe_nocache
     Including the options used to compile this particular test, the PowerPC target supports PowerPC SPE.

powerpc_spu
     PowerPC target supports PowerPC SPU.

powerpc_vsx_ok
     PowerPC target supports -mvsx.

powerpc_405_nocache
     Including the options used to compile this particular test, the PowerPC target supports PowerPC 405.

ppc_recip_hw
     PowerPC target supports executing reciprocal estimate instructions.

spu_auto_overlay
     SPU target has toolchain that supports automatic overlay generation.

vmx_hw
     PowerPC target supports executing AltiVec instructions.

vsx_hw
     PowerPC target supports executing VSX instructions (ISA 2.06).

Other hardware attributes
.........................

avx
     Target supports compiling avx instructions.

avx_runtime
     Target supports the execution of avx instructions.

cell_hw
     Test system can execute AltiVec and Cell PPU instructions.

coldfire_fpu
     Target uses a ColdFire FPU.

hard_float
     Target supports FPU instructions.

non_strict_align
     Target does not require strict alignment.

sqrt_insn
     Target has a square root instruction that the compiler can generate.

sse
     Target supports compiling sse instructions.

sse_runtime
     Target supports the execution of sse instructions.

sse2
     Target supports compiling sse2 instructions.

sse2_runtime
     Target supports the execution of sse2 instructions.

sync_char_short
     Target supports atomic operations on char and short.

sync_int_long
     Target supports atomic operations on int and long.

ultrasparc_hw
     Test environment appears to run executables on a simulator that accepts only EM_SPARC executables and chokes on EM_SPARC32PLUS or EM_SPARCV9 executables.

vect_cmdline_needed
     Target requires a command line argument to enable a SIMD instruction set.

pie_copyreloc
     The x86-64 target linker supports PIE with copy reloc.

divmod
     Target supporting hardware divmod insn or divmod libcall.

divmod_simode
     Target supporting hardware divmod insn or divmod libcall for SImode.

Environment attributes
......................

c
     The language for the compiler under test is C.

c++
     The language for the compiler under test is C++.

c99_runtime
     Target provides a full C99 runtime.

correct_iso_cpp_string_wchar_protos
     Target string.h and wchar.h headers provide C++ required overloads for strchr etc. functions.

dummy_wcsftime
     Target uses a dummy wcsftime function that always returns zero.

fd_truncate
     Target can truncate a file from a file descriptor, as used by libgfortran/io/unix.c:fd_truncate; i.e. ftruncate or chsize.

freestanding
     Target is freestanding as defined in section 4 of the C99 standard. Effectively, it is a target which supports no extra headers or libraries other than what is considered essential.

gettimeofday
     Target supports gettimeofday.

init_priority
     Target supports constructors with initialization priority arguments.

inttypes_types
     Target has the basic signed and unsigned types in inttypes.h. This is for tests that GCC's notions of these types agree with those in the header, as some systems have only inttypes.h.

lax_strtofp
     Target might have errors of a few ULP in string to floating-point conversion functions and overflow is not always detected correctly by those functions.

mempcpy
     Target provides mempcpy function.

mmap
     Target supports mmap.

newlib
     Target supports Newlib.

pow10
     Target provides pow10 function.

pthread
     Target can compile using pthread.h with no errors or warnings.

pthread_h
     Target has pthread.h.

run_expensive_tests
     Expensive testcases (usually those that consume excessive amounts of CPU time) should be run on this target.  This can be enabled by setting the GCC_TEST_RUN_EXPENSIVE environment variable to a non-empty string.

simulator
     Test system runs executables on a simulator (i.e. slowly) rather than hardware (i.e. fast).

stabs
     Target supports the stabs debugging format.

stdint_types
     Target has the basic signed and unsigned C types in stdint.h. This will be obsolete when GCC ensures a working stdint.h for all targets.

stpcpy
     Target provides stpcpy function.

trampolines
     Target supports trampolines.

uclibc
     Target supports uClibc.

unwrapped
     Target does not use a status wrapper.

vxworks_kernel
     Target is a VxWorks kernel.

vxworks_rtp
     Target is a VxWorks RTP.

wchar
     Target supports wide characters.

Other attributes
................

automatic_stack_alignment
     Target supports automatic stack alignment.

cilkplus_runtime
     Target supports the Cilk Plus runtime library.

cxa_atexit
     Target uses __cxa_atexit.

default_packed
     Target has packed layout of structure members by default.

fgraphite
     Target supports Graphite optimizations.

fixed_point
     Target supports fixed-point extension to C.

fopenacc
     Target supports OpenACC via -fopenacc.

fopenmp
     Target supports OpenMP via -fopenmp.

fpic
     Target supports -fpic and -fPIC.

freorder
     Target supports -freorder-blocks-and-partition.

fstack_protector
     Target supports -fstack-protector.

gas
     Target uses GNU as.

gc_sections
     Target supports --gc-sections.

gld
     Target uses GNU ld.

keeps_null_pointer_checks
     Target keeps null pointer checks, either due to the use of -fno-delete-null-pointer-checks or hardwired into the target.

lto
     Compiler has been configured to support link-time optimization (LTO).

naked_functions
     Target supports the naked function attribute.

named_sections
     Target supports named sections.

natural_alignment_32
     Target uses natural alignment (aligned to type size) for types of 32 bits or less.

target_natural_alignment_64
     Target uses natural alignment (aligned to type size) for types of 64 bits or less.

nonpic
     Target does not generate PIC by default.

pie_enabled
     Target generates PIE by default.

pcc_bitfield_type_matters
     Target defines PCC_BITFIELD_TYPE_MATTERS.

pe_aligned_commons
     Target supports -mpe-aligned-commons.

pie
     Target supports -pie, -fpie and -fPIE.

rdynamic
     Target supports -rdynamic.

section_anchors
     Target supports section anchors.

short_enums
     Target defaults to short enums.

static
     Target supports -static.

static_libgfortran
     Target supports statically linking libgfortran.

string_merging
     Target supports merging string constants at link time.

ucn
     Target supports compiling and assembling UCN.

ucn_nocache
     Including the options used to compile this particular test, the target supports compiling and assembling UCN.

unaligned_stack
     Target does not guarantee that its STACK_BOUNDARY is greater than or equal to the required vector alignment.

vector_alignment_reachable
     Vector alignment is reachable for types of 32 bits or less.

vector_alignment_reachable_for_64bit
     Vector alignment is reachable for types of 64 bits or less.

wchar_t_char16_t_compatible
     Target supports wchar_t that is compatible with char16_t.

wchar_t_char32_t_compatible
     Target supports wchar_t that is compatible with char32_t.

comdat_group
     Target uses comdat groups.

Local to tests in gcc.target/i386
.................................

3dnow
     Target supports compiling 3dnow instructions.

aes
     Target supports compiling aes instructions.

fma4
     Target supports compiling fma4 instructions.

ms_hook_prologue
     Target supports attribute ms_hook_prologue.

pclmul
     Target supports compiling pclmul instructions.

sse3
     Target supports compiling sse3 instructions.

sse4
     Target supports compiling sse4 instructions.

sse4a
     Target supports compiling sse4a instructions.

ssse3
     Target supports compiling ssse3 instructions.

vaes
     Target supports compiling vaes instructions.

vpclmul
     Target supports compiling vpclmul instructions.

xop
     Target supports compiling xop instructions.

Local to tests in gcc.target/spu/ea
...................................

ealib
     Target __ea library functions are available.

Local to tests in gcc.test-framework
....................................

no
     Always returns 0.

yes
     Always returns 1.

Features for dg-add-options
---------------------------

The supported values of FEATURE for directive dg-add-options are:

arm_fp
     __ARM_FP definition.  Only ARM targets support this feature, and only then in certain modes; see the arm_fp_ok effective target keyword.

arm_neon
     NEON support.  Only ARM targets support this feature, and only then in certain modes; see the arm_neon_ok effective target keyword.

arm_fp16
     VFP half-precision floating point support.  This does not select the FP16 format; for that, use arm_fp16_ieee or arm_fp16_alternative instead.  This feature is only supported by ARM targets and then only in certain modes; see the arm_fp16_ok effective target keyword.

arm_fp16_ieee
     ARM IEEE 754-2008 format VFP half-precision floating point support. This feature is only supported by ARM targets and then only in certain modes; see the arm_fp16_ok effective target keyword.

arm_fp16_alternative
     ARM Alternative format VFP half-precision floating point support. This feature is only supported by ARM targets and then only in certain modes; see the arm_fp16_ok effective target keyword.

arm_neon_fp16
     NEON and half-precision floating point support.  Only ARM targets support this feature, and only then in certain modes; see the arm_neon_fp16_ok effective target keyword.

arm_vfp3
     arm vfp3 floating point support; see the arm_vfp3_ok effective target keyword.

arm_v8_1a_neon
     Add options for ARMv8.1 with Adv.SIMD support, if this is supported by the target; see the arm_v8_1a_neon_ok effective target keyword.

arm_v8_2a_fp16_scalar
     Add options for ARMv8.2 with scalar FP16 support, if this is supported by the target; see the arm_v8_2a_fp16_scalar_ok effective target keyword.

arm_v8_2a_fp16_neon
     Add options for ARMv8.2 with Adv.SIMD FP16 support, if this is supported by the target; see the arm_v8_2a_fp16_neon_ok effective target keyword.

bind_pic_locally
     Add the target-specific flags needed to enable functions to bind locally when using pic/PIC passes in the testsuite.

c99_runtime
     Add the target-specific flags needed to access the C99 runtime.

floatN
     Add the target-specific flags needed to use the _FloatN type.

floatNx
     Add the target-specific flags needed to use the _FloatNx type.

ieee
     Add the target-specific flags needed to enable full IEEE compliance mode.

mips16_attribute
     mips16 function attributes. Only MIPS targets support this feature, and only then in certain modes.

tls
     Add the target-specific flags needed to use thread-local storage.

Variants of dg-require-SUPPORT
------------------------------

A few of the dg-require directives take arguments.

dg-require-iconv CODESET
     Skip the test if the target does not support iconv.  CODESET is the codeset to convert to.

dg-require-profiling PROFOPT
     Skip the test if the target does not support profiling with option PROFOPT.

dg-require-visibility VIS
     Skip the test if the target does not support the visibility attribute. If VIS is "", support for visibility("hidden") is checked, for visibility("VIS") otherwise.

The original dg-require directives were defined before there was support for effective-target keywords.  The directives that do not take arguments could be replaced with effective-target keywords.

dg-require-alias ""
     Skip the test if the target does not support the alias attribute.

dg-require-ascii-locale ""
     Skip the test if the host does not support an ASCII locale.

dg-require-compat-dfp ""
     Skip this test unless both compilers in a compat testsuite support decimal floating point.

dg-require-cxa-atexit ""
     Skip the test if the target does not support __cxa_atexit. This is equivalent to dg-require-effective-target cxa_atexit.

dg-require-dll ""
     Skip the test if the target does not support DLL attributes.

dg-require-fork ""
     Skip the test if the target does not support fork.

dg-require-gc-sections ""
     Skip the test if the target's linker does not support the --gc-sections flags. This is equivalent to dg-require-effective-target gc-sections.

dg-require-host-local ""
     Skip the test if the host is remote, rather than the same as the build system.  Some tests are incompatible with DejaGnu's handling of remote hosts, which involves copying the source file to the host and compiling it with a relative path and "-o a.out".

dg-require-mkfifo ""
     Skip the test if the target does not support mkfifo.

dg-require-named-sections ""
     Skip the test is the target does not support named sections. This is equivalent to dg-require-effective-target named_sections.

dg-require-weak ""
     Skip the test if the target does not support weak symbols.

dg-require-weak-override ""
     Skip the test if the target does not support overriding weak symbols.

Commands for use in dg-final
----------------------------

The GCC testsuite defines the following directives to be used within dg-final.

Scan a particular file
......................

scan-file FILENAME REGEXP [{ target/xfail SELECTOR }]
     Passes if REGEXP matches text in FILENAME.

scan-file-not FILENAME REGEXP [{ target/xfail SELECTOR }]
     Passes if REGEXP does not match text in FILENAME.

scan-module MODULE REGEXP [{ target/xfail SELECTOR }]
     Passes if REGEXP matches in Fortran module MODULE.

Scan the assembly output
........................

scan-assembler REGEX [{ target/xfail SELECTOR }]
     Passes if REGEX matches text in the test's assembler output.

scan-assembler-not REGEX [{ target/xfail SELECTOR }]
     Passes if REGEX does not match text in the test's assembler output.

scan-assembler-times REGEX NUM [{ target/xfail SELECTOR }]
     Passes if REGEX is matched exactly NUM times in the test's assembler output.

scan-assembler-dem REGEX [{ target/xfail SELECTOR }]
     Passes if REGEX matches text in the test's demangled assembler output.

scan-assembler-dem-not REGEX [{ target/xfail SELECTOR }]
     Passes if REGEX does not match text in the test's demangled assembler output.

scan-hidden SYMBOL [{ target/xfail SELECTOR }]
     Passes if SYMBOL is defined as a hidden symbol in the test's assembly output.

scan-not-hidden SYMBOL [{ target/xfail SELECTOR }]
     Passes if SYMBOL is not defined as a hidden symbol in the test's assembly output.

Scan optimization dump files
............................

These commands are available for KIND of tree, rtl, and ipa.

scan-KIND-dump REGEX SUFFIX [{ target/xfail SELECTOR }]
     Passes if REGEX matches text in the dump file with suffix SUFFIX.

scan-KIND-dump-not REGEX SUFFIX [{ target/xfail SELECTOR }]
     Passes if REGEX does not match text in the dump file with suffix SUFFIX.

scan-KIND-dump-times REGEX NUM SUFFIX [{ target/xfail SELECTOR }]
     Passes if REGEX is found exactly NUM times in the dump file with suffix SUFFIX.

scan-KIND-dump-dem REGEX SUFFIX [{ target/xfail SELECTOR }]
     Passes if REGEX matches demangled text in the dump file with suffix SUFFIX.

scan-KIND-dump-dem-not REGEX SUFFIX [{ target/xfail SELECTOR }]
     Passes if REGEX does not match demangled text in the dump file with suffix SUFFIX.

Verify that an output files exists or not
.........................................

output-exists [{ target/xfail SELECTOR }]
     Passes if compiler output file exists.

output-exists-not [{ target/xfail SELECTOR }]
     Passes if compiler output file does not exist.

Check for LTO tests
...................

scan-symbol REGEXP [{ target/xfail SELECTOR }]
     Passes if the pattern is present in the final executable.

Checks for gcov tests
.....................

run-gcov SOURCEFILE
     Check line counts in gcov tests.

run-gcov [branches] [calls] { OPTS SOURCEFILE }
     Check branch and/or call counts, in addition to line counts, in gcov tests.

Clean up generated test files
.............................

Usually the test-framework removes files that were generated during testing. If a testcase, for example, uses any dumping mechanism to inspect a passes dump file, the testsuite recognized the dump option passed to the tool and schedules a final cleanup to remove these files.

There are, however, following additional cleanup directives that can be used to annotate a testcase "manually".

cleanup-coverage-files
     Removes coverage data files generated for this test.

cleanup-modules "LIST-OF-EXTRA-MODULES"
     Removes Fortran module files generated for this test, excluding the module names listed in keep-modules. Cleaning up module files is usually done automatically by the testsuite by looking at the source files and removing the modules after the test has been executed.

          module MoD1
          end module MoD1
          module Mod2
          end module Mod2
          module moD3
          end module moD3
          module mod4
          end module mod4
          ! { dg-final { cleanup-modules "mod1 mod2" } } ! redundant
          ! { dg-final { keep-modules "mod3 mod4" } }

keep-modules "LIST-OF-MODULES-NOT-TO-DELETE"
     Whitespace separated list of module names that should not be deleted by cleanup-modules. If the list of modules is empty, all modules defined in this file are kept.

          module maybe_unneeded
          end module maybe_unneeded
          module keep1
          end module keep1
          module keep2
          end module keep2
          ! { dg-final { keep-modules "keep1 keep2" } } ! just keep these two
          ! { dg-final { keep-modules "" } } ! keep all

dg-keep-saved-temps "LIST-OF-SUFFIXES-NOT-TO-DELETE"
     Whitespace separated list of suffixes that should not be deleted automatically in a testcase that uses -save-temps.

          // { dg-options "-save-temps -fpch-preprocess -I." }
          int main() { return 0; }
          // { dg-keep-saved-temps ".s" } ! just keep assembler file
          // { dg-keep-saved-temps ".s" ".i" } ! ... and .i
          // { dg-keep-saved-temps ".ii" ".o" } ! or just .ii and .o

cleanup-profile-file
     Removes profiling files generated for this test.

cleanup-repo-files
     Removes files generated for this test for -frepo.

Ada Language Testsuites
=======================

The Ada testsuite includes executable tests from the ACATS testsuite, publicly available at http://www.ada-auth.org/acats.html.

These tests are integrated in the GCC testsuite in the ada/acats directory, and enabled automatically when running make check, assuming the Ada language has been enabled when configuring GCC.

You can also run the Ada testsuite independently, using make check-ada, or run a subset of the tests by specifying which chapter to run, e.g.:

     $ make check-ada CHAPTERS="c3 c9"

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.

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 make install.

C Language Testsuites
=====================

GCC contains the following C language testsuites, 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/compat
     This subdirectory contains tests for binary compatibility using lib/compat.exp, which in turn uses the language-independent support (see Support for testing binary compatibility).

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 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 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 testsuite 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.misc-tests
     This directory contains C tests that require special handling.  Some of these tests have individual expect files, and others share special-purpose expect files:

     bprob*.c
          Test -fbranch-probabilities using gcc.misc-tests/bprob.exp, which in turn uses the generic, language-independent framework (see Support for testing profile-directed optimizations).

     gcov*.c
          Test gcov output using gcov.exp, which in turn uses the language-independent support (see Support for testing gcov).

     i386-pf-*.c
          Test i386-specific support for data prefetch using i386-prefetch.exp.

gcc.test-framework

     dg-*.c
          Test the testsuite itself using gcc.test-framework/test-framework.exp.

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

Support for testing link-time optimizations
===========================================

Tests for link-time optimizations usually require multiple source files that are compiled separately, perhaps with different sets of options. There are several special-purpose test directives used for these tests.

{ dg-lto-do DO-WHAT-KEYWORD }
     DO-WHAT-KEYWORD specifies how the test is compiled and whether it is executed.  It is one of:

     assemble
          Compile with -c to produce a relocatable object file.

     link
          Compile, assemble, and link to produce an executable file.

     run
          Produce and run an executable file, which is expected to return an exit code of 0.

     The default is assemble.  That can be overridden for a set of tests by redefining dg-do-what-default within the .exp file for those tests.

     Unlike dg-do, dg-lto-do does not support an optional target or xfail list.  Use dg-skip-if, dg-xfail-if, or dg-xfail-run-if.

{ dg-lto-options { { OPTIONS } [{ OPTIONS }] } [{ target SELECTOR }]}
     This directive provides a list of one or more sets of compiler options to override LTO_OPTIONS.  Each test will be compiled and run with each of these sets of options.

{ dg-extra-ld-options OPTIONS [{ target SELECTOR }]}
     This directive adds OPTIONS to the linker options used.

{ dg-suppress-ld-options OPTIONS [{ target SELECTOR }]}
     This directive removes OPTIONS from the set of linker options used.

Support for testing gcov
========================

Language-independent support for testing gcov, and for checking that branch profiling produces expected values, is provided by the expect file lib/gcov.exp.  gcov tests also rely on procedures in lib/gcc-dg.exp to compile and run the test program.  A typical gcov test contains the following DejaGnu commands within comments:

     { dg-options "-fprofile-arcs -ftest-coverage" }
     { dg-do run { target native } }
     { dg-final { run-gcov sourcefile } }

Checks of 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 the run-gcov command has arguments branches or calls, respectively.  For example, the following specifies checking both, as well as passing -b to gcov:

     { dg-final { run-gcov branches calls { -b sourcefile } } }

A line count command appears within a comment on the source line that is expected to get the specified count and has the form count(CNT).  A test should only check line counts for lines that will get the same count for any architecture.

Commands to check branch percentages (branch) and call return percentages (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 branch(end) or returns(end) marks the end of a range without starting a new one.  For example:

     if (i > 10 && j > i && j < 20)  /* branch(27 50 75) */
                                     /* branch(end) */
       foo (i, j);

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.

Support for testing profile-directed optimizations
==================================================

The 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.  profopt.exp has the beginnings of this kind of support.

profopt.exp provides generic support for profile-directed optimizations.  Each set of tests that uses it provides information about a specific optimization:

tool
     tool being tested, e.g., gcc

profile_option
     options used to generate profile data

feedback_option
     options used to optimize using that profile data

prof_ext
     suffix of profile data files

PROFOPT_OPTIONS
     list of options with which to run each test, similar to the lists for torture tests

{ dg-final-generate { LOCAL-DIRECTIVE } }
     This directive is similar to dg-final, but the LOCAL-DIRECTIVE is run after the generation of profile data.

{ dg-final-use { LOCAL-DIRECTIVE } }
     The LOCAL-DIRECTIVE is run after the profile data have been used.

Support for testing binary compatibility
========================================

The 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 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 with each other to split up the functionality being tested.

TESTNAME_main.SUFFIX
     Contains the main program, which calls a function in file TESTNAME_x.SUFFIX.

TESTNAME_x.SUFFIX
     Contains at least one call to a function in TESTNAME_y.SUFFIX.

TESTNAME_y.SUFFIX
     Shares data with, or gets arguments from, TESTNAME_x.SUFFIX.

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. You can specify pairs of sets of compiler options.  The first element of such a pair specifies options used with the GCC under test, and the second element of the pair specifies options used with the alternate compiler.  Each test is compiled with each pair of options.

compat.exp defines default pairs of compiler options. These can be overridden by defining the environment variable COMPAT_OPTIONS as:

     COMPAT_OPTIONS="[list [list {TST1} {ALT1}]
       ...[list {TSTN} {ALTN}]]"

where TSTI and ALTI are lists of options, with TSTI used by the compiler under test and ALTI used by the alternate compiler.  For example, with [list [list {-g -O0} {-O3}] [list {-fpic} {-fPIC -O2}]], the test is first built with -g -O0 by the compiler under test and with -O3 by the alternate compiler.  The test is built a second time using -fpic by the compiler under test and -fPIC -O2 by the alternate compiler.

An alternate compiler is specified by defining an environment variable to be the full pathname of an installed compiler; for C define ALT_CC_UNDER_TEST, and for C++ define ALT_CXX_UNDER_TEST.  These will be written to the 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 COMPAT_OPTIONS.  When ALT_CC_UNDER_TEST or ALT_CXX_UNDER_TEST is same, each test is built using the compiler under test but with combinations of the options from 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 OBJDIR/gcc:

     rm site.exp
     make -k \
       ALT_CXX_UNDER_TEST=${alt_prefix}/bin/g++ \
       COMPAT_OPTIONS="LISTS AS SHOWN ABOVE" \
       check-c++ \
       RUNTESTFLAGS="compat.exp"

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.

The binary compatibility tests support a small number of test framework commands that appear within comments in a test file.

dg-require-*
     These commands can be used in TESTNAME_main.SUFFIX to skip the test if specific support is not available on the target.

dg-options
     The specified options are used for compiling this particular source file, appended to the options from COMPAT_OPTIONS.  When this command appears in TESTNAME_main.SUFFIX the options are also used to link the test program.

dg-xfail-if
     This command can be used in a secondary source file to specify that compilation is expected to fail for particular options on particular targets.

Support for torture testing using multiple options
==================================================

Throughout the compiler testsuite there are several directories whose tests are run multiple times, each with a different set of options. These are known as torture tests. lib/torture-options.exp defines procedures to set up these lists:

torture-init
     Initialize use of torture lists.

set-torture-options
     Set lists of torture options to use for tests with and without loops. Optionally combine a set of torture options with a set of other options, as is done with Objective-C runtime options.

torture-finish
     Finalize use of torture lists.

The .exp file for a set of tests that use torture options must include calls to these three procedures if:

  * It calls gcc-dg-runtest and overrides DG_TORTURE_OPTIONS.

  * It calls ${TOOL}-torture or ${TOOL}-torture-execute, where TOOL is c, fortran, or objc.

  * It calls dg-pch.

It is not necessary for a .exp file that calls gcc-dg-runtest to call the torture procedures if the tests should use the list in DG_TORTURE_OPTIONS defined in gcc-dg.exp.

Most uses of torture options can override the default lists by defining TORTURE_OPTIONS or add to the default list by defining ADDITIONAL_TORTURE_OPTIONS.  Define these in a .dejagnurc file or add them to the site.exp file; for example

     set ADDITIONAL_TORTURE_OPTIONS  [list \
       { -O2 -ftree-loop-linear } \
       { -O2 -fpeel-loops } ]

Support for testing GIMPLE passes
=================================

As of gcc 7, C functions can be tagged with __GIMPLE to indicate that the function body will be GIMPLE, rather than C.  The compiler requires the option -fgimple to enable this functionality.  For example:

     /* { dg-do compile } */
     /* { dg-options "-O -fgimple" } */

     void __GIMPLE (startwith ("dse2")) foo ()
     {
       int a;

     bb_2:
       if (a > 4)
         goto bb_3;
       else
         goto bb_4;

     bb_3:
       a_2 = 10;
       goto bb_5;

     bb_4:
       a_3 = 20;

     bb_5:
       a_1 = __PHI (bb_3: a_2, bb_4: a_3);
       a_4 = a_1 + 4;

       return;
     }

The startwith argument indicates at which pass to begin.

Use the dump modifier -gimple (e.g. -fdump-tree-all-gimple) to make tree dumps more closely follow the format accepted by the GIMPLE parser.

Example DejaGnu tests of GIMPLE can be seen in the source tree at gcc/testsuite/gcc.dg/gimplefe-*.c.

The __GIMPLE parser is integrated with the C tokenizer and preprocessor, so it should be possible to use macros to build out test coverage.

Support for testing RTL passes
==============================

As of gcc 7, C functions can be tagged with __RTL to indicate that the function body will be RTL, rather than C.  For example:

     double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
     {
       (function "test"
          [...snip; various directives go in here...]
       ) ;; function "test"
     }

The startwith argument indicates at which pass to begin.

The parser expects the RTL body to be in the format emitted by this dumping function:

     DEBUG_FUNCTION void
     print_rtx_function (FILE *outfile, function *fn, bool compact);

when "compact" is true.  So you can capture RTL in the correct format from the debugger using:

     (gdb) print_rtx_function (stderr, cfun, true);

and copy and paste the output into the body of the C function.

Example DejaGnu tests of RTL can be seen in the source tree under gcc/testsuite/gcc.dg/rtl.

The __RTL parser is not integrated with the C tokenizer or preprocessor, and works simply by reading the relevant lines within the braces.  In particular, the RTL body must be on separate lines from the enclosing braces, and the preprocessor is not usable within it.