@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @node Source Tree @chapter 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 (@uref{http://gcc.gnu.org/install/}), with which it is presumed that you are familiar. @menu * Configure Terms:: Configuration terminology and history. * Top Level:: The top level source directory. * gcc Directory:: The @file{gcc} subdirectory. @end menu @include configterms.texi @node Top Level @section 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: @table @file @item boehm-gc The Boehm conservative garbage collector, used as part of the Java runtime library. @item config Autoconf macros and Makefile fragments used throughout the tree. @item contrib Contributed scripts that may be found useful in conjunction with GCC@. One of these, @file{contrib/texi2pod.pl}, is used to generate man pages from Texinfo manuals as part of the GCC build process. @item fixincludes The support for fixing system headers to work with GCC@. See @file{fixincludes/README} for more information. The headers fixed by this mechanism are installed in @file{@var{libsubdir}/include-fixed}. Along with those headers, @file{README-fixinc} is also installed, as @file{@var{libsubdir}/include-fixed/README}. @item gcc The main sources of GCC itself (except for runtime libraries), including optimizers, support for different target architectures, language front ends, and testsuites. @xref{gcc Directory, , The @file{gcc} Subdirectory}, for details. @item gnattools Support tools for GNAT. @item include Headers for the @code{libiberty} library. @item intl GNU @code{libintl}, from GNU @code{gettext}, for systems which do not include it in @code{libc}. @item libada The Ada runtime library. @item libcpp The C preprocessor library. @item libdecnumber The Decimal Float support library. @item libffi The @code{libffi} library, used as part of the Java runtime library. @item libgcc The GCC runtime library. @item libgfortran The Fortran runtime library. @item libgo The Go runtime library. The bulk of this library is mirrored from the @uref{http://code.google.com/@/p/@/go, master Go repository}. @item libgomp The GNU OpenMP runtime library. @item libiberty The @code{libiberty} library, used for portability and for some generally useful data structures and algorithms. @xref{Top, , Introduction, libiberty, @sc{gnu} libiberty}, for more information about this library. @item libjava The Java runtime library. @item libmudflap The @code{libmudflap} library, used for instrumenting pointer and array dereferencing operations. @item libobjc The Objective-C and Objective-C++ runtime library. @item libssp The Stack protector runtime library. @item libstdc++-v3 The C++ runtime library. @item lto-plugin Plugin used by @command{gold} if link-time optimizations are enabled. @item maintainer-scripts Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. @item zlib The @code{zlib} compression library, used by the Java front end, as part of the Java runtime library, and for compressing and uncompressing GCC's intermediate language in LTO object files. @end table 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. @xref{Top, , GNU configure and build system, configure, The GNU configure and build system}, for details. @node gcc Directory @section The @file{gcc} Subdirectory The @file{gcc} directory contains many files that are part of the C sources of GCC, other files used as part of the configuration and build process, and subdirectories including documentation and a testsuite. The files that are sources of GCC are documented in a separate chapter. @xref{Passes, , Passes and Files of the Compiler}. @menu * Subdirectories:: Subdirectories of @file{gcc}. * Configuration:: The configuration process, and the files it uses. * Build:: The build system in the @file{gcc} directory. * Makefile:: Targets in @file{gcc/Makefile}. * Library Files:: Library source files and headers under @file{gcc/}. * Headers:: Headers installed by GCC. * Documentation:: Building documentation in GCC. * Front End:: Anatomy of a language front end. * Back End:: Anatomy of a target back end. @end menu @node Subdirectories @subsection Subdirectories of @file{gcc} The @file{gcc} directory contains the following subdirectories: @table @file @item @var{language} Subdirectories for various languages. Directories containing a file @file{config-lang.in} are language subdirectories. The contents of the subdirectories @file{cp} (for C++), @file{lto} (for LTO), @file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are documented in this manual (@pxref{Passes, , Passes and Files of the Compiler}); those for other languages are not. @xref{Front End, , Anatomy of a Language Front End}, for details of the files in these directories. @item config Configuration files for supported architectures and operating systems. @xref{Back End, , Anatomy of a Target Back End}, for details of the files in this directory. @item doc Texinfo documentation for GCC, together with automatically generated man pages and support for converting the installation manual to HTML@. @xref{Documentation}. @item ginclude System headers installed by GCC, mainly those required by the C standard of freestanding implementations. @xref{Headers, , Headers Installed by GCC}, for details of when these and other headers are installed. @item po Message catalogs with translations of messages produced by GCC into various languages, @file{@var{language}.po}. This directory also contains @file{gcc.pot}, the template for these message catalogues, @file{exgettext}, a wrapper around @command{gettext} to extract the messages from the GCC sources and create @file{gcc.pot}, which is run by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from which messages should not be extracted. @item testsuite The GCC testsuites (except for those for runtime libraries). @xref{Testsuites}. @end table @node Configuration @subsection Configuration in the @file{gcc} Directory The @file{gcc} directory is configured with an Autoconf-generated script @file{configure}. The @file{configure} script is generated from @file{configure.ac} and @file{aclocal.m4}. From the files @file{configure.ac} and @file{acconfig.h}, Autoheader generates the file @file{config.in}. The file @file{cstamp-h.in} is used as a timestamp. @menu * Config Fragments:: Scripts used by @file{configure}. * System Config:: The @file{config.build}, @file{config.host}, and @file{config.gcc} files. * Configuration Files:: Files created by running @file{configure}. @end menu @node Config Fragments @subsubsection Scripts Used by @file{configure} @file{configure} uses some other scripts to help in its work: @itemize @bullet @item The standard GNU @file{config.sub} and @file{config.guess} files, kept in the top level directory, are used. @item The file @file{config.gcc} is used to handle configuration specific to the particular target machine. The file @file{config.build} is used to handle configuration specific to the particular build machine. The file @file{config.host} is used to handle configuration specific to the particular host machine. (In general, these should only be used for features that cannot reasonably be tested in Autoconf feature tests.) @xref{System Config, , The @file{config.build}; @file{config.host}; and @file{config.gcc} Files}, for details of the contents of these files. @item Each language subdirectory has a file @file{@var{language}/config-lang.in} that is used for front-end-specific configuration. @xref{Front End Config, , The Front End @file{config-lang.in} File}, for details of this file. @item A helper script @file{configure.frag} is used as part of creating the output of @file{configure}. @end itemize @node System Config @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files The @file{config.build} file contains specific rules for particular systems which GCC is built on. This should be used as rarely as possible, as the behavior of the build system can always be detected by autoconf. The @file{config.host} file contains specific rules for particular systems which GCC will run on. This is rarely needed. The @file{config.gcc} file contains specific rules for particular systems which GCC will generate code for. This is usually needed. Each file has a list of the shell variables it sets, with descriptions, at the top of the file. FIXME: document the contents of these files, and what variables should be set to control build, host and target configuration. @include configfiles.texi @node Build @subsection Build System in the @file{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 (@pxref{Passes}). @include makefile.texi @node Library Files @subsection Library Source Files and Headers under the @file{gcc} Directory FIXME: list here, with explanation, all the C source files and headers under the @file{gcc} directory that aren't built into the GCC executable but rather are part of runtime libraries and object files, such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , Headers Installed by GCC}, for more information about the @file{ginclude} directory. @node Headers @subsection 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 @file{@var{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 @file{ginclude} directory. These headers, @file{iso646.h}, @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, are installed in @file{@var{libsubdir}/include}, unless the target Makefile fragment (@pxref{Target Fragment}) overrides this by setting @code{USER_H}. In addition to these headers and those generated by fixing system headers to work with GCC, some other headers may also be installed in @file{@var{libsubdir}/include}. @file{config.gcc} may set @code{extra_headers}; this specifies additional headers under @file{config} to be installed on some systems. GCC installs its own version of @code{}, from @file{ginclude/float.h}. This is done to cope with command-line options that change the representation of floating point numbers. GCC also installs its own version of @code{}; this is generated from @file{glimits.h}, together with @file{limitx.h} and @file{limity.h} if the system also has its own version of @code{}. (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 @code{}.) The system's @code{} header is used via @file{@var{libsubdir}/include/syslimits.h}, which is copied from @file{gsyslimits.h} if it does not need fixing to work with GCC; if it needs fixing, @file{syslimits.h} is the fixed copy. GCC can also install @code{}. It will do this when @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}. @node Documentation @subsection 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 @samp{make dvi}, PDF versions by @samp{make pdf}, and HTML versions by @samp{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 @file{gcc} directory. FIXME: document the documentation for runtime libraries somewhere. @menu * Texinfo Manuals:: GCC manuals in Texinfo format. * Man Page Generation:: Generating man pages from Texinfo manuals. * Miscellaneous Docs:: Miscellaneous text files with documentation. @end menu @node Texinfo Manuals @subsubsection Texinfo Manuals The manuals for GCC as a whole, and the C and C++ front ends, are in files @file{doc/*.texi}. Other front ends have their own manuals in files @file{@var{language}/*.texi}. Common files @file{doc/include/*.texi} are provided which may be included in multiple manuals; the following files are in @file{doc/include}: @table @file @item fdl.texi The GNU Free Documentation License. @item funding.texi The section ``Funding Free Software''. @item gcc-common.texi Common definitions for manuals. @item gpl.texi @itemx gpl_v3.texi The GNU General Public License. @item texinfo.tex A copy of @file{texinfo.tex} known to work with the GCC manuals. @end table DVI-formatted manuals are generated by @samp{make dvi}, which uses @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). PDF-formatted manuals are generated by @samp{make pdf}, which uses @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML formatted manuals are generated by @samp{make html}. Info manuals are generated by @samp{make info} (which is run as part of a bootstrap); this generates the manuals in the source directory, using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, and they are included in release distributions. Manuals are also provided on the GCC web site, in both HTML and PostScript forms. This is done via the script @file{maintainer-scripts/update_web_docs_svn}. Each manual to be provided online must be listed in the definition of @code{MANUALS} in that file; a file @file{@var{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 @file{@var{name}.texi} should only include other files in its own directory or in @file{doc/include}. HTML manuals will be generated by @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} and @command{dvips}, and PDF manuals by @command{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, @file{doc/install.texi}, is also provided on the GCC web site. The HTML version is generated by the script @file{doc/install.texi2html}. @node Man Page Generation @subsubsection 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 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference to @file{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 @file{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 @samp{@@c man} control what parts of a Texinfo file go into a man page. Only a subset of Texinfo is supported by @file{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 @file{doc/include/gcc-common.texi} which @file{texi2pod.pl} understands: @table @code @item @@gcctabopt Use in the form @samp{@@table @@gcctabopt} for tables of options, where for printed output the effect of @samp{@@code} is better than that of @samp{@@option} but for man page output a different effect is wanted. @item @@gccoptlist Use for summary lists of options in manuals. @item @@gol Use at the end of each line inside @samp{@@gccoptlist}. This is necessary to avoid problems with differences in how the @samp{@@gccoptlist} macro is handled by different Texinfo formatters. @end table FIXME: describe the @file{texi2pod.pl} input language and magic comments in more detail. @node Miscellaneous Docs @subsubsection Miscellaneous Documentation In addition to the formal documentation that is installed by GCC, there are several other text files in the @file{gcc} subdirectory with miscellaneous documentation: @table @file @item ABOUT-GCC-NLS Notes on GCC's Native Language Support. FIXME: this should be part of this manual rather than a separate file. @item ABOUT-NLS Notes on the Free Translation Project. @item COPYING @itemx COPYING3 The GNU General Public License, Versions 2 and 3. @item COPYING.LIB @itemx COPYING3.LIB The GNU Lesser General Public License, Versions 2.1 and 3. @item *ChangeLog* @itemx */ChangeLog* Change log files for various parts of GCC@. @item 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. @item ONEWS Information about new features in old versions of GCC@. (For recent versions, the information is on the GCC web site.) @item 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? @end table FIXME: document such files in subdirectories, at least @file{config}, @file{cp}, @file{objc}, @file{testsuite}. @node Front End @subsection Anatomy of a Language Front End A front end for a language in GCC has the following parts: @itemize @bullet @item A directory @file{@var{language}} under @file{gcc} containing source files for that front end. @xref{Front End Directory, , The Front End @file{@var{language}} Directory}, for details. @item A mention of the language in the list of supported languages in @file{gcc/doc/install.texi}. @item A mention of the name under which the language's runtime library is recognized by @option{--enable-shared=@var{package}} in the documentation of that option in @file{gcc/doc/install.texi}. @item A mention of any special prerequisites for building the front end in the documentation of prerequisites in @file{gcc/doc/install.texi}. @item Details of contributors to that front end in @file{gcc/doc/contrib.texi}. If the details are in that front end's own manual then there should be a link to that manual's list in @file{contrib.texi}. @item Information about support for that language in @file{gcc/doc/frontends.texi}. @item Information about standards for that language, and the front end's support for them, in @file{gcc/doc/standards.texi}. This may be a link to such information in the front end's own manual. @item Details of source file suffixes for that language and @option{-x @var{lang}} options supported, in @file{gcc/doc/invoke.texi}. @item Entries in @code{default_compilers} in @file{gcc.c} for source file suffixes for that language. @item Preferably testsuites, which may be under @file{gcc/testsuite} or runtime library directories. FIXME: document somewhere how to write testsuite harnesses. @item Probably a runtime library for the language, outside the @file{gcc} directory. FIXME: document this further. @item Details of the directories of any runtime libraries in @file{gcc/doc/sourcebuild.texi}. @item Check targets in @file{Makefile.def} for the top-level @file{Makefile} to check just the compiler or the compiler and runtime library for the language. @end itemize If the front end is added to the official GCC source repository, the following are also necessary: @itemize @bullet @item At least one Bugzilla component for bugs in that front end and runtime libraries. This category needs to be added to the Bugzilla database. @item Normally, one or more maintainers of that front end listed in @file{MAINTAINERS}. @item Mentions on the GCC web site in @file{index.html} and @file{frontends.html}, with any relevant links on @file{readings.html}. (Front ends that are not an official part of GCC may also be listed on @file{frontends.html}, with relevant links.) @item A news item on @file{index.html}, and possibly an announcement on the @email{gcc-announce@@gcc.gnu.org} mailing list. @item The front end's manuals should be mentioned in @file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals}) and the online manuals should be linked to from @file{onlinedocs/index.html}. @item Any old releases or CVS repositories of the front end, before its inclusion in GCC, should be made available on the GCC FTP site @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. @item The release and snapshot script @file{maintainer-scripts/gcc_release} should be updated to generate appropriate tarballs for this front end. @item If this front end includes its own version files that include the current date, @file{maintainer-scripts/update_version} should be updated accordingly. @end itemize @menu * Front End Directory:: The front end @file{@var{language}} directory. * Front End Config:: The front end @file{config-lang.in} file. * Front End Makefile:: The front end @file{Make-lang.in} file. @end menu @node Front End Directory @subsubsection The Front End @file{@var{language}} Directory A front end @file{@var{language}} directory contains the source files of that front end (but not of any runtime libraries, which should be outside the @file{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: @table @file @item config-lang.in This file is required in all language subdirectories. @xref{Front End Config, , The Front End @file{config-lang.in} File}, for details of its contents @item Make-lang.in This file is required in all language subdirectories. @xref{Front End Makefile, , The Front End @file{Make-lang.in} File}, for details of its contents. @item lang.opt This file registers the set of switches that the front end accepts on the command line, and their @option{--help} text. @xref{Options}. @item lang-specs.h This file provides entries for @code{default_compilers} in @file{gcc.c} which override the default of giving an error that a compiler for that language is not installed. @item @var{language}-tree.def This file, which need not exist, defines any language-specific tree codes. @end table @node Front End Config @subsubsection The Front End @file{config-lang.in} File Each language subdirectory contains a @file{config-lang.in} file. In addition the main directory contains @file{c-config-lang.in}, which contains limited information for the C language. This file is a shell script that may define some variables describing the language: @table @code @item language This definition must be present, and gives the name of the language for some purposes such as arguments to @option{--enable-languages}. @item 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 @code{language} settings). For example, the Java front end depends on the C++ front end, so sets @samp{lang_requires=c++}. @item 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 @samp{subdir_requires="cp objc"}. @item target_libs If defined, this variable lists (space-separated) targets in the top level @file{Makefile} to build the runtime libraries for this language, such as @code{target-libobjc}. @item lang_dirs If defined, this variable lists (space-separated) top level directories (parallel to @file{gcc}), apart from the runtime libraries, that should not be configured if this front end is not built. @item build_by_default If defined to @samp{no}, this language front end is not built unless enabled in a @option{--enable-languages} argument. Otherwise, front ends are built by default, subject to any special logic in @file{configure.ac} (as is present to disable the Ada front end if the Ada compiler is not already installed). @item boot_language If defined to @samp{yes}, this front end is built in stage1 of the bootstrap. This is only relevant to front ends written in their own languages. @item compilers If defined, a space-separated list of compiler executables that will be run by the driver. The names here will each end with @samp{\$(exeext)}. @item outputs If defined, a space-separated list of files that should be generated by @file{configure} substituting values in them. This mechanism can be used to create a file @file{@var{language}/Makefile} from @file{@var{language}/Makefile.in}, but this is deprecated, building everything from the single @file{gcc/Makefile} is preferred. @item gtfiles If defined, a space-separated list of files that should be scanned by @file{gengtype.c} to generate the garbage collection tables and routines for this language. This excludes the files that are common to all front ends. @xref{Type Information}. @end table @node Front End Makefile @subsubsection The Front End @file{Make-lang.in} File Each language subdirectory contains a @file{Make-lang.in} file. It contains targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the setting of @code{language} in @file{config-lang.in}) for the following values of @code{@var{hook}}, and any other Makefile rules required to build those targets (which may if necessary use other Makefiles specified in @code{outputs} in @file{config-lang.in}, although this is deprecated). It also adds any testsuite targets that can use the standard rule in @file{gcc/Makefile.in} to the variable @code{lang_checks}. @table @code @itemx all.cross @itemx start.encap @itemx rest.encap FIXME: exactly what goes in each of these targets? @item tags Build an @command{etags} @file{TAGS} file in the language subdirectory in the source tree. @item info Build info documentation for the front end, in the build directory. This target is only called by @samp{make bootstrap} if a suitable version of @command{makeinfo} is available, so does not need to check for this, and should fail if an error occurs. @item dvi Build DVI documentation for the front end, in the build directory. This should be done using @code{$(TEXI2DVI)}, with appropriate @option{-I} arguments pointing to directories of included files. @item pdf Build PDF documentation for the front end, in the build directory. This should be done using @code{$(TEXI2PDF)}, with appropriate @option{-I} arguments pointing to directories of included files. @item html Build HTML documentation for the front end, in the build directory. @item man Build generated man pages for the front end from Texinfo manuals (@pxref{Man Page Generation}), in the build directory. This target is only called if the necessary tools are available, but should ignore errors so as not to stop the build if errors occur; man pages are optional and the tools involved may be installed in a broken way. @item install-common Install everything that is part of the front end, apart from the compiler executables listed in @code{compilers} in @file{config-lang.in}. @item 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. @item install-man Install man pages for the front end. This target should ignore errors. @item install-plugin Install headers needed for plugins. @item 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 @samp{--enable-generated-files-in-srcdir} was specified as a @file{configure} option. @item srcinfo @itemx srcman Copies its dependencies into the source directory. These targets will be executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} was specified as a @file{configure} option. @item uninstall Uninstall files installed by installing the compiler. This is currently documented not to be supported, so the hook need not do anything. @item mostlyclean @itemx clean @itemx distclean @itemx maintainer-clean The language parts of the standard GNU @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for Users, standards, GNU Coding Standards}, for details of the standard targets. For GCC, @code{maintainer-clean} should delete all generated files in the source directory that are not version-controlled, but should not delete anything that is. @end table @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS} to a list of host object files that are used by that language. @node Back End @subsection Anatomy of a Target Back End A back end for a target architecture in GCC has the following parts: @itemize @bullet @item A directory @file{@var{machine}} under @file{gcc/config}, containing a machine description @file{@var{machine}.md} file (@pxref{Machine Desc, , Machine Descriptions}), header files @file{@var{machine}.h} and @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} (@pxref{Target Macros, , Target Description Macros and Functions}), possibly a target Makefile fragment @file{t-@var{machine}} (@pxref{Target Fragment, , 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 @file{config.gcc}. @item If necessary, a file @file{@var{machine}-modes.def} in the @file{@var{machine}} directory, containing additional machine modes to represent condition codes. @xref{Condition Code}, for further details. @item An optional @file{@var{machine}.opt} file in the @file{@var{machine}} directory, containing a list of target-specific options. You can also add other option files using the @code{extra_options} variable in @file{config.gcc}. @xref{Options}. @item Entries in @file{config.gcc} (@pxref{System Config, , The @file{config.gcc} File}) for the systems with this target architecture. @item Documentation in @file{gcc/doc/invoke.texi} for any command-line options supported by this target (@pxref{Run-time Target, , Run-time Target Specification}). This means both entries in the summary table of options and details of the individual options. @item Documentation in @file{gcc/doc/extend.texi} for any target-specific attributes supported (@pxref{Target Attributes, , Defining target-specific uses of @code{__attribute__}}), including where the same attribute is already supported on some targets, which are enumerated in the manual. @item Documentation in @file{gcc/doc/extend.texi} for any target-specific pragmas supported. @item Documentation in @file{gcc/doc/extend.texi} of any target-specific built-in functions supported. @item Documentation in @file{gcc/doc/extend.texi} of any target-specific format checking styles supported. @item Documentation in @file{gcc/doc/md.texi} of any target-specific constraint letters (@pxref{Machine Constraints, , Constraints for Particular Machines}). @item A note in @file{gcc/doc/contrib.texi} under the person or people who contributed the target support. @item Entries in @file{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. @item Possibly other support outside the @file{gcc} directory for runtime libraries. FIXME: reference docs for this. The @code{libstdc++} porting manual needs to be installed as info for this to work, or to be a chapter of this manual. @end itemize If the back end is added to the official GCC source repository, the following are also necessary: @itemize @bullet @item An entry for the target architecture in @file{readings.html} on the GCC web site, with any relevant links. @item Details of the properties of the back end and target architecture in @file{backends.html} on the GCC web site. @item A news item about the contribution of support for that target architecture, in @file{index.html} on the GCC web site. @item Normally, one or more maintainers of that target listed in @file{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. @end itemize @node Testsuites @chapter 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. @menu * Test Idioms:: Idioms used in testsuite code. * Test Directives:: Directives used within DejaGnu tests. * Ada Tests:: The Ada language testsuites. * C Tests:: The C language testsuites. * libgcj Tests:: The Java library testsuites. * LTO Testing:: Support for testing link-time optimizations. * gcov Testing:: Support for testing gcov. * profopt Testing:: Support for testing profile-directed optimizations. * compat Testing:: Support for testing binary compatibility. * Torture Tests:: Support for torture testing using multiple options. @end menu @node Test Idioms @section Idioms Used in Testsuite Code In general, C testcases have a trailing @file{-@var{n}.c}, starting with @file{-1.c}, in case other testcases with similar names are added later. If the test is a test of some well-defined feature, it should have a name referring to that feature such as @file{@var{feature}-1.c}. If it does not test a well-defined feature but just happens to exercise a bug somewhere in the compiler, and a bug report has been filed for this bug in the GCC bug database, @file{pr@var{bug-number}-1.c} is the appropriate form of name. Otherwise (for miscellaneous bugs not filed in the GCC bug database), and previously more generally, test cases are named after the date on which they were added. This allows people to tell at a glance whether a test failure is because of a recently found bug that has not yet been fixed, or whether it may be a regression, but does not give any other information about the bug or where discussion of it may be found. Some other language testsuites follow similar conventions. In the @file{gcc.dg} testsuite, it is often necessary to test that an error is indeed a hard error and not just a warning---for example, where it is a constraint violation in the C standard, which must become an error with @option{-pedantic-errors}. The following idiom, where the first line shown is line @var{line} of the file and the line that generates the error, is used for this: @smallexample /* @{ dg-bogus "warning" "warning in place of error" @} */ /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ @end smallexample It may be necessary to check that an expression is an integer constant expression and has a certain value. To check that @code{@var{E}} has value @code{@var{V}}, an idiom similar to the following is used: @smallexample char x[((E) == (V) ? 1 : -1)]; @end smallexample In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make assertions about the types of expressions. See, for example, @file{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, @file{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 @file{gcc.c-torture/execute}. Where code should be optimized away, a call to a nonexistent function such as @code{link_failure ()} may be inserted; a definition @smallexample #ifndef __OPTIMIZE__ void link_failure (void) @{ abort (); @} #endif @end smallexample @noindent 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 @code{static} to call @code{abort ()} (although redeclaring a function as static may not work on all targets). All testcases must be portable. Target-specific testcases must have appropriate code to avoid causing failures on unsupported systems; unfortunately, the mechanisms for this differ by directory. FIXME: discuss non-C testsuites here. @node Test Directives @section Directives used within DejaGnu tests @menu * Directives:: Syntax and descriptions of test directives. * Selectors:: Selecting targets to which a test applies. * Effective-Target Keywords:: Keywords describing target attributes. * Add Options:: Features for @code{dg-add-options} * Require Support:: Variants of @code{dg-require-@var{support}} * Final Actions:: Commands for use in @code{dg-final} @end menu @node Directives @subsection Syntax and Descriptions of test directives Test directives appear within comments in a test source file and begin with @code{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 (@pxref{Selectors, , }) which are usually preceded by the keyword @code{target} or @code{xfail}. @subsubsection Specify how to build the test @table @code @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} @var{do-what-keyword} specifies how the test is compiled and whether it is executed. It is one of: @table @code @item preprocess Compile with @option{-E} to run only the preprocessor. @item compile Compile with @option{-S} to produce an assembly code file. @item assemble Compile with @option{-c} to produce a relocatable object file. @item link Compile, assemble, and link to produce an executable file. @item run Produce and run an executable file, which is expected to return an exit code of 0. @end table The default is @code{compile}. That can be overridden for a set of tests by redefining @code{dg-do-what-default} within the @code{.exp} file for those tests. If the directive includes the optional @samp{@{ target @var{selector} @}} then the test is skipped unless the target system matches the @var{selector}. If @var{do-what-keyword} is @code{run} and the directive includes the optional @samp{@{ xfail @var{selector} @}} and the selector is met then the test is expected to fail. The @code{xfail} clause is ignored for other values of @var{do-what-keyword}; those tests can use directive @code{dg-xfail-if}. @end table @subsubsection Specify additional compiler options @table @code @item @{ dg-options @var{options} [@{ target @var{selector} @}] @} This DejaGnu directive provides a list of compiler options, to be used if the target system matches @var{selector}, that replace the default options used for this set of tests. @item @{ dg-add-options @var{feature} @dots{} @} 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 @code{dg-options} directives. For supported values of @var{feature} see @ref{Add Options, ,}. @end table @subsubsection Modify the test timeout value The normal timeout limit, in seconds, is found by searching the following in order: @itemize @bullet @item the value defined by an earlier @code{dg-timeout} directive in the test @item variable @var{tool_timeout} defined by the set of tests @item @var{gcc},@var{timeout} set in the target board @item 300 @end itemize @table @code @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @} Set the time limit for the compilation and for the execution of the test to the specified number of seconds. @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @} Multiply the normal time limit for compilation and execution of the test by the specified floating-point factor. @end table @subsubsection Skip a test for some targets @table @code @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} Arguments @var{include-opts} and @var{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: @itemize @bullet @item the test system is included in @var{selector} @item for at least one of the option strings in @var{include-opts}, every option from that string is in the set of options with which the test would be compiled; use @samp{"*"} for an @var{include-opts} list that matches any options; that is the default if @var{include-opts} is not specified @item for each of the option strings in @var{exclude-opts}, at least one option from that string is not in the set of options with which the test would be compiled; use @samp{""} for an empty @var{exclude-opts} list; that is the default if @var{exclude-opts} is not specified @end itemize For example, to skip a test if option @code{-Os} is present: @smallexample /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */ @end smallexample To skip a test if both options @code{-O2} and @code{-g} are present: @smallexample /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */ @end smallexample To skip a test if either @code{-O2} or @code{-O3} is present: @smallexample /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */ @end smallexample To skip a test unless option @code{-Os} is present: @smallexample /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */ @end smallexample To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g} but not if @code{-fpic} is also present: @smallexample /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */ @end smallexample @item @{ dg-require-effective-target @var{keyword} [@{ @var{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 @samp{@{ @var{selector} @}} then the effective-target test is only performed if the target system matches the @var{selector}. This directive must appear after any @code{dg-do} directive in the test and before any @code{dg-additional-sources} directive. @xref{Effective-Target Keywords, , }. @item @{ dg-require-@var{support} args @} Skip the test if the target does not provide the required support. These directives must appear after any @code{dg-do} directive in the test and before any @code{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. @xref{Require Support, , }, for a complete list of these directives. @end table @subsubsection Expect a test to fail for some targets @table @code @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} Expect the test to fail if the conditions (which are the same as for @code{dg-skip-if}) are met. This does not affect the execute step. @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} Expect the execute step of a test to fail if the conditions (which are the same as for @code{dg-skip-if}) are met. @end table @subsubsection Expect the test executable to fail @table @code @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} Expect the test executable to return a nonzero exit status if the conditions (which are the same as for @code{dg-skip-if}) are met. @end table @subsubsection Verify compiler messages @table @code @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{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 @var{regexp} then the check fails and @var{comment} is included in the @code{FAIL} message. The check does not look for the string @samp{error} unless it is part of @var{regexp}. @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{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 @var{regexp} then the check fails and @var{comment} is included in the @code{FAIL} message. The check does not look for the string @samp{warning} unless it is part of @var{regexp}. @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{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 @var{regexp} then the check fails and @var{comment} is included in the @code{FAIL} message. @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} This DejaGnu directive appears on a source line that should not get a message matching @var{regexp}, or else specifies the source line associated with the bogus message. It is usually used with @samp{xfail} to indicate that the message is a known problem for a particular set of targets. @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} This DejaGnu directive indicates that the test is expected to fail due to compiler messages that are not handled by @samp{dg-error}, @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail} has the same effect as @samp{target}. @item @{ dg-prune-output @var{regexp} @} Prune messages matching @var{regexp} from the test output. @end table @subsubsection Verify output of the test executable @table @code @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} This DejaGnu directive compares @var{regexp} to the combined output that the test executable writes to @file{stdout} and @file{stderr}. @end table @subsubsection Specify additional files for a test @table @code @item @{ dg-additional-files "@var{filelist}" @} Specify additional files, other than source files, that must be copied to the system where the compiler runs. @item @{ dg-additional-sources "@var{filelist}" @} Specify additional source files to appear in the compile line following the main test file. @end table @subsubsection Add checks at the end of a test @table @code @item @{ dg-final @{ @var{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 @samp{dg-final} commands are processed in the order in which they appear in the source file. @xref{Final Actions, , }, for a list of directives that can be used within @code{dg-final}. @end table @node Selectors @subsection Selecting targets to which a test applies Several test directives include @var{selector}s 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: @itemize @bullet @item one or more target triplets, possibly including wildcard characters @item a single effective-target keyword (@pxref{Effective-Target Keywords}) @item a logical expression @end itemize Depending on the context, the selector specifies whether a test is skipped and reported as unsupported or is expected to fail. Use @samp{*-*-*} to match any target. A selector expression appears within curly braces and uses a single logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. 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: @smallexample @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} @{ target @{ powerpc*-*-* && lp64 @} @} @{ xfail @{ lp64 || vect_no_align @} @} @end smallexample @node Effective-Target Keywords @subsection 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 @file{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 @samp{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 @code{_nocache} can also include options specified for the particular test in an earlier @code{dg-options} or @code{dg-add-options} directive. @subsubsection Data type sizes @table @code @item ilp32 Target has 32-bit @code{int}, @code{long}, and pointers. @item lp64 Target has 32-bit @code{int}, 64-bit @code{long} and pointers. @item llp64 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long} and pointers. @item double64 Target has 64-bit @code{double}. @item double64plus Target has @code{double} that is 64 bits or longer. @item int32plus Target has @code{int} that is at 32 bits or longer. @item int16 Target has @code{int} that is 16 bits or shorter. @item large_double Target supports @code{double} that is longer than @code{float}. @item large_long_double Target supports @code{long double} that is longer than @code{double}. @item ptr32plus Target has pointers that are 32 bits or longer. @item size32plus Target supports array and structure sizes that are 32 bits or longer. @item 4byte_wchar_t Target has @code{wchar_t} that is at least 4 bytes. @end table @subsubsection Fortran-specific attributes @table @code @item fortran_integer_16 Target supports Fortran @code{integer} that is 16 bytes or longer. @item fortran_large_int Target supports Fortran @code{integer} kinds larger than @code{integer(8)}. @item fortran_large_real Target supports Fortran @code{real} kinds larger than @code{real(8)}. @end table @subsubsection Vector-specific attributes @table @code @item vect_condition Target supports vector conditional operations. @item vect_double Target supports hardware vectors of @code{double}. @item vect_float Target supports hardware vectors of @code{float}. @item vect_int Target supports hardware vectors of @code{int}. @item vect_long Target supports hardware vectors of @code{long}. @item vect_long_long Target supports hardware vectors of @code{long long}. @item vect_aligned_arrays Target aligns arrays to vector alignment boundary. @item vect_hw_misalign Target supports a vector misalign access. @item vect_no_align Target does not support a vector alignment mechanism. @item vect_no_int_max Target does not support a vector max instruction on @code{int}. @item vect_no_int_add Target does not support a vector add instruction on @code{int}. @item vect_no_bitwise Target does not support vector bitwise instructions. @item vect_char_mult Target supports @code{vector char} multiplication. @item vect_short_mult Target supports @code{vector short} multiplication. @item vect_int_mult Target supports @code{vector int} multiplication. @item vect_extract_even_odd Target supports vector even/odd element extraction. @item vect_extract_even_odd_wide Target supports vector even/odd element extraction of vectors with elements @code{SImode} or larger. @item vect_interleave Target supports vector interleaving. @item vect_strided Target supports vector interleaving and extract even/odd. @item vect_strided_wide Target supports vector interleaving and extract even/odd for wide element types. @item vect_perm Target supports vector permutation. @item vect_shift Target supports a hardware vector shift operation. @item vect_widen_sum_hi_to_si Target supports a vector widening summation of @code{short} operands into @code{int} results, or can promote (unpack) from @code{short} to @code{int}. @item vect_widen_sum_qi_to_hi Target supports a vector widening summation of @code{char} operands into @code{short} results, or can promote (unpack) from @code{char} to @code{short}. @item vect_widen_sum_qi_to_si Target supports a vector widening summation of @code{char} operands into @code{int} results. @item vect_widen_mult_qi_to_hi Target supports a vector widening multiplication of @code{char} operands into @code{short} results, or can promote (unpack) from @code{char} to @code{short} and perform non-widening multiplication of @code{short}. @item vect_widen_mult_hi_to_si Target supports a vector widening multiplication of @code{short} operands into @code{int} results, or can promote (unpack) from @code{short} to @code{int} and perform non-widening multiplication of @code{int}. @item vect_sdot_qi Target supports a vector dot-product of @code{signed char}. @item vect_udot_qi Target supports a vector dot-product of @code{unsigned char}. @item vect_sdot_hi Target supports a vector dot-product of @code{signed short}. @item vect_udot_hi Target supports a vector dot-product of @code{unsigned short}. @item vect_pack_trunc Target supports a vector demotion (packing) of @code{short} to @code{char} and from @code{int} to @code{short} using modulo arithmetic. @item vect_unpack Target supports a vector promotion (unpacking) of @code{char} to @code{short} and from @code{char} to @code{int}. @item vect_intfloat_cvt Target supports conversion from @code{signed int} to @code{float}. @item vect_uintfloat_cvt Target supports conversion from @code{unsigned int} to @code{float}. @item vect_floatint_cvt Target supports conversion from @code{float} to @code{signed int}. @item vect_floatuint_cvt Target supports conversion from @code{float} to @code{unsigned int}. @end table @subsubsection Thread Local Storage attributes @table @code @item tls Target supports thread-local storage. @item tls_native Target supports native (rather than emulated) thread-local storage. @item tls_runtime Test system supports executing TLS executables. @end table @subsubsection Decimal floating point attributes @table @code @item dfp Targets supports compiling decimal floating point extension to C. @item dfp_nocache Including the options used to compile this particular test, the target supports compiling decimal floating point extension to C. @item dfprt Test system can execute decimal floating point tests. @item dfprt_nocache Including the options used to compile this particular test, the test system can execute decimal floating point tests. @item hard_dfp Target generates decimal floating point instructions with current options. @end table @subsubsection ARM-specific attributes @table @code @item arm32 ARM target generates 32-bit code. @item arm_eabi ARM target adheres to the ABI for the ARM Architecture. @item arm_hard_vfp_ok ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. Some multilibs may be incompatible with these options. @item arm_iwmmxt_ok ARM target supports @code{-mcpu=iwmmxt}. Some multilibs may be incompatible with this option. @item arm_neon ARM target supports generating NEON instructions. @item arm_neon_hw Test system supports executing NEON instructions. @item arm_neon_ok @anchor{arm_neon_ok} ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible options. Some multilibs may be incompatible with these options. @item arm_neon_fp16_ok @anchor{arm_neon_fp16_ok} ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible options. Some multilibs may be incompatible with these options. @item arm_thumb1_ok ARM target generates Thumb-1 code for @code{-mthumb}. @item arm_thumb2_ok ARM target generates Thumb-2 code for @code{-mthumb}. @item arm_vfp_ok ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. Some multilibs may be incompatible with these options. @end table @subsubsection MIPS-specific attributes @table @code @item mips64 MIPS target supports 64-bit instructions. @item nomips16 MIPS target does not produce MIPS16 code. @item mips16_attribute MIPS target can generate MIPS16 code. @item mips_loongson MIPS target is a Loongson-2E or -2F target using an ABI that supports the Loongson vector modes. @item mips_newabi_large_long_double MIPS target supports @code{long double} larger than @code{double} when using the new ABI. @item mpaired_single MIPS target supports @code{-mpaired-single}. @end table @subsubsection PowerPC-specific attributes @table @code @item powerpc64 Test system supports executing 64-bit instructions. @item powerpc_altivec PowerPC target supports AltiVec. @item powerpc_altivec_ok PowerPC target supports @code{-maltivec}. @item powerpc_fprs PowerPC target supports floating-point registers. @item powerpc_hard_double PowerPC target supports hardware double-precision floating-point. @item powerpc_ppu_ok PowerPC target supports @code{-mcpu=cell}. @item powerpc_spe PowerPC target supports PowerPC SPE. @item powerpc_spe_nocache Including the options used to compile this particular test, the PowerPC target supports PowerPC SPE. @item powerpc_spu PowerPC target supports PowerPC SPU. @item spu_auto_overlay SPU target has toolchain that supports automatic overlay generation. @item powerpc_vsx_ok PowerPC target supports @code{-mvsx}. @item powerpc_405_nocache Including the options used to compile this particular test, the PowerPC target supports PowerPC 405. @item vmx_hw PowerPC target supports executing AltiVec instructions. @end table @subsubsection Other hardware attributes @table @code @item avx Target supports compiling AVX instructions. @item cell_hw Test system can execute AltiVec and Cell PPU instructions. @item coldfire_fpu Target uses a ColdFire FPU. @item hard_float Target supports FPU instructions. @item sse Target supports compiling @code{sse} instructions. @item sse_runtime Target supports the execution of @code{sse} instructions. @item sse2 Target supports compiling @code{sse2} instructions. @item sse2_runtime Target supports the execution of @code{sse2} instructions. @item sync_char_short Target supports atomic operations on @code{char} and @code{short}. @item sync_int_long Target supports atomic operations on @code{int} and @code{long}. @item ultrasparc_hw Test environment appears to run executables on a simulator that accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS} or @code{EM_SPARCV9} executables. @item vect_cmdline_needed Target requires a command line argument to enable a SIMD instruction set. @end table @subsubsection Environment attributes @table @code @item c The language for the compiler under test is C. @item c++ The language for the compiler under test is C++. @item c99_runtime Target provides a full C99 runtime. @item correct_iso_cpp_string_wchar_protos Target @code{string.h} and @code{wchar.h} headers provide C++ required overloads for @code{strchr} etc. functions. @item dummy_wcsftime Target uses a dummy @code{wcsftime} function that always returns zero. @item fd_truncate Target can truncate a file from a file descriptor, as used by @file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or @code{chsize}. @item freestanding Target is @samp{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. @item init_priority Target supports constructors with initialization priority arguments. @item inttypes_types Target has the basic signed and unsigned types in @code{inttypes.h}. This is for tests that GCC's notions of these types agree with those in the header, as some systems have only @code{inttypes.h}. @item 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. @item newlib Target supports Newlib. @item pow10 Target provides @code{pow10} function. @item pthread Target can compile using @code{pthread.h} with no errors or warnings. @item pthread_h Target has @code{pthread.h}. @item 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 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string. @item simulator Test system runs executables on a simulator (i.e. slowly) rather than hardware (i.e. fast). @item stdint_types Target has the basic signed and unsigned C types in @code{stdint.h}. This will be obsolete when GCC ensures a working @code{stdint.h} for all targets. @item trampolines Target supports trampolines. @item uclibc Target supports uClibc. @item unwrapped Target does not use a status wrapper. @item vxworks_kernel Target is a VxWorks kernel. @item vxworks_rtp Target is a VxWorks RTP. @item wchar Target supports wide characters. @end table @subsubsection Other attributes @table @code @item automatic_stack_alignment Target supports automatic stack alignment. @item cxa_atexit Target uses @code{__cxa_atexit}. @item default_packed Target has packed layout of structure members by default. @item fgraphite Target supports Graphite optimizations. @item fixed_point Target supports fixed-point extension to C. @item fopenmp Target supports OpenMP via @option{-fopenmp}. @item fpic Target supports @option{-fpic} and @option{-fPIC}. @item freorder Target supports @option{-freorder-blocks-and-partition}. @item fstack_protector Target supports @option{-fstack-protector}. @item gas Target uses GNU @command{as}. @item gc_sections Target supports @option{--gc-sections}. @item keeps_null_pointer_checks Target keeps null pointer checks, either due to the use of @option{-fno-delete-null-pointer-checks} or hardwired into the target. @item lto Compiler has been configured to support link-time optimization (LTO). @item named_sections Target supports named sections. @item natural_alignment_32 Target uses natural alignment (aligned to type size) for types of 32 bits or less. @item target_natural_alignment_64 Target uses natural alignment (aligned to type size) for types of 64 bits or less. @item nonpic Target does not generate PIC by default. @item pcc_bitfield_type_matters Target defines @code{PCC_BITFIELD_TYPE_MATTERS}. @item pe_aligned_commons Target supports @option{-mpe-aligned-commons}. @item section_anchors Target supports section anchors. @item short_enums Target defaults to short enums. @item static Target supports @option{-static}. @item static_libgfortran Target supports statically linking @samp{libgfortran}. @item string_merging Target supports merging string constants at link time. @item ucn Target supports compiling and assembling UCN. @item ucn_nocache Including the options used to compile this particular test, the target supports compiling and assembling UCN. @item unaligned_stack Target does not guarantee that its @code{STACK_BOUNDARY} is greater than or equal to the required vector alignment. @item vector_alignment_reachable Vector alignment is reachable for types of 32 bits or less. @item vector_alignment_reachable_for_64bit Vector alignment is reachable for types of 64 bits or less. @item wchar_t_char16_t_compatible Target supports @code{wchar_t} that is compatible with @code{char16_t}. @item wchar_t_char32_t_compatible Target supports @code{wchar_t} that is compatible with @code{char32_t}. @end table @subsubsection Local to tests in @code{gcc.target/i386} @table @code @item 3dnow Target supports compiling @code{3dnow} instructions. @item aes Target supports compiling @code{aes} instructions. @item fma4 Target supports compiling @code{fma4} instructions. @item ms_hook_prologue Target supports attribute @code{ms_hook_prologue}. @item pclmul Target supports compiling @code{pclmul} instructions. @item sse3 Target supports compiling @code{sse3} instructions. @item sse4 Target supports compiling @code{sse4} instructions. @item sse4a Target supports compiling @code{sse4a} instructions. @item ssse3 Target supports compiling @code{ssse3} instructions. @item vaes Target supports compiling @code{vaes} instructions. @item vpclmul Target supports compiling @code{vpclmul} instructions. @item xop Target supports compiling @code{xop} instructions. @end table @subsubsection Local to tests in @code{gcc.target/spu/ea} @table @code @item ealib Target @code{__ea} library functions are available. @end table @subsubsection Local to tests in @code{gcc.test-framework} @table @code @item no Always returns 0. @item yes Always returns 1. @end table @node Add Options @subsection Features for @code{dg-add-options} The supported values of @var{feature} for directive @code{dg-add-options} are: @table @code @item arm_neon NEON support. Only ARM targets support this feature, and only then in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target keyword}. @item arm_neon_fp16 NEON and half-precision floating point support. Only ARM targets support this feature, and only then in certain modes; see the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}. @item bind_pic_locally Add the target-specific flags needed to enable functions to bind locally when using pic/PIC passes in the testsuite. @item c99_runtime Add the target-specific flags needed to access the C99 runtime. @item ieee Add the target-specific flags needed to enable full IEEE compliance mode. @item mips16_attribute @code{mips16} function attributes. Only MIPS targets support this feature, and only then in certain modes. @item tls Add the target-specific flags needed to use thread-local storage. @end table @node Require Support @subsection Variants of @code{dg-require-@var{support}} A few of the @code{dg-require} directives take arguments. @table @code @item dg-require-iconv @var{codeset} Skip the test if the target does not support iconv. @var{codeset} is the codeset to convert to. @item dg-require-profiling @var{profopt} Skip the test if the target does not support profiling with option @var{profopt}. @item dg-require-visibility @var{vis} Skip the test if the target does not support the @code{visibility} attribute. If @var{vis} is @code{""}, support for @code{visibility("hidden")} is checked, for @code{visibility("@var{vis}")} otherwise. @end table The original @code{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. @table @code @item dg-require-alias "" Skip the test if the target does not support the @samp{alias} attribute. @item dg-require-compat-dfp "" Skip this test unless both compilers in a @file{compat} testsuite support decimal floating point. @item dg-require-cxa-atexit "" Skip the test if the target does not support @code{__cxa_atexit}. This is equivalent to @code{dg-require-effective-target cxa_atexit}. @item dg-require-dll "" Skip the test if the target does not support DLL attributes. @item dg-require-fork "" Skip the test if the target does not support @code{fork}. @item dg-require-gc-sections "" Skip the test if the target's linker does not support the @code{--gc-sections} flags. This is equivalent to @code{dg-require-effective-target gc-sections}. @item 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 "@code{-o a.out}". @item dg-require-mkfifo "" Skip the test if the target does not support @code{mkfifo}. @item dg-require-named-sections "" Skip the test is the target does not support named sections. This is equivalent to @code{dg-require-effective-target named_sections}. @item dg-require-weak "" Skip the test if the target does not support weak symbols. @item dg-require-weak-override "" Skip the test if the target does not support overriding weak symbols. @end table @node Final Actions @subsection Commands for use in @code{dg-final} The GCC testsuite defines the following directives to be used within @code{dg-final}. @subsubsection Scan a particular file @table @code @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] Passes if @var{regexp} matches text in @var{filename}. @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] Passes if @var{regexp} does not match text in @var{filename}. @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}] Passes if @var{regexp} matches in Fortran module @var{module}. @end table @subsubsection Scan the assembly output @table @code @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] Passes if @var{regex} matches text in the test's assembler output. @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] Passes if @var{regex} does not match text in the test's assembler output. @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] Passes if @var{regex} is matched exactly @var{num} times in the test's assembler output. @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] Passes if @var{regex} matches text in the test's demangled assembler output. @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] Passes if @var{regex} does not match text in the test's demangled assembler output. @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] Passes if @var{symbol} is defined as a hidden symbol in the test's assembly output. @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] Passes if @var{symbol} is not defined as a hidden symbol in the test's assembly output. @end table @subsubsection Scan optimization dump files These commands are available for @var{kind} of @code{tree}, @code{rtl}, and @code{ipa}. @table @code @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] Passes if @var{regex} does not match text in the dump file with suffix @var{suffix}. @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] Passes if @var{regex} is found exactly @var{num} times in the dump file with suffix @var{suffix}. @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] Passes if @var{regex} matches demangled text in the dump file with suffix @var{suffix}. @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] Passes if @var{regex} does not match demangled text in the dump file with suffix @var{suffix}. @end table @subsubsection Verify that an output files exists or not @table @code @item output-exists [@{ target/xfail @var{selector} @}] Passes if compiler output file exists. @item output-exists-not [@{ target/xfail @var{selector} @}] Passes if compiler output file does not exist. @end table @subsubsection Check for LTO tests @table @code @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] Passes if the pattern is present in the final executable. @end table @subsubsection Checks for @command{gcov} tests @table @code @item run-gcov @var{sourcefile} Check line counts in @command{gcov} tests. @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} Check branch and/or call counts, in addition to line counts, in @command{gcov} tests. @end table @subsubsection Clean up generated test files @table @code @item cleanup-coverage-files Removes coverage data files generated for this test. @item cleanup-ipa-dump @var{suffix} Removes IPA dump files generated for this test. @item cleanup-modules Removes Fortran module files generated for this test. @item cleanup-profile-file Removes profiling files generated for this test. @item cleanup-repo-files Removes files generated for this test for @option{-frepo}. @item cleanup-rtl-dump @var{suffix} Removes RTL dump files generated for this test. @item cleanup-saved-temps Removes files for the current test which were kept for @option{-save-temps}. @item cleanup-tree-dump @var{suffix} Removes tree dump files matching @var{suffix} which were generated for this test. @end table @node Ada Tests @section Ada Language Testsuites The Ada testsuite includes executable tests from the ACATS 2.5 testsuite, publicly available at @uref{http://www.adaic.org/compilers/acats/2.5}. These tests are integrated in the GCC testsuite in the @file{ada/acats} directory, and enabled automatically when running @code{make check}, assuming the Ada language has been enabled when configuring GCC@. You can also run the Ada testsuite independently, using @code{make check-ada}, or run a subset of the tests by specifying which chapter to run, e.g.: @smallexample $ make check-ada CHAPTERS="c3 c9" @end smallexample The tests are organized by directory, each directory corresponding to a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds to chapter 9, which deals with tasking features of the language. There is also an extra chapter called @file{gcc} containing a template for creating new executable tests, although this is deprecated in favor of the @file{gnat.dg} testsuite. The tests are run using two @command{sh} scripts: @file{run_acats} and @file{run_all.sh}. To run the tests using a simulator or a cross target, see the small customization section at the top of @file{run_all.sh}. These tests are run using the build tree: they can be run without doing a @code{make install}. @node C Tests @section C Language Testsuites GCC contains the following C language testsuites, in the @file{gcc/testsuite} directory: @table @file @item gcc.dg This contains tests of particular features of the C compiler, using the more modern @samp{dg} harness. Correctness tests for various compiler features should go here if possible. Magic comments determine whether the file is preprocessed, compiled, linked or run. In these tests, error and warning message texts are compared against expected texts or regular expressions given in comments. These tests are run with the options @samp{-ansi -pedantic} unless other options are given in the test. Except as noted below they are not run with multiple optimization options. @item gcc.dg/compat This subdirectory contains tests for binary compatibility using @file{lib/compat.exp}, which in turn uses the language-independent support (@pxref{compat Testing, , Support for testing binary compatibility}). @item gcc.dg/cpp This subdirectory contains tests of the preprocessor. @item gcc.dg/debug This subdirectory contains tests for debug formats. Tests in this subdirectory are run for each debug format that the compiler supports. @item gcc.dg/format This subdirectory contains tests of the @option{-Wformat} format checking. Tests in this directory are run with and without @option{-DWIDE}. @item gcc.dg/noncompile This subdirectory contains tests of code that should not compile and does not need any special compilation options. They are run with multiple optimization options, since sometimes invalid code crashes the compiler with optimization. @item gcc.dg/special FIXME: describe this. @item gcc.c-torture This contains particular code fragments which have historically broken easily. These tests are run with multiple optimization options, so tests for features which only break at some optimization levels belong here. This also contains tests to check that certain optimizations occur. It might be worthwhile to separate the correctness tests cleanly from the code quality tests, but it hasn't been done yet. @item gcc.c-torture/compat FIXME: describe this. This directory should probably not be used for new tests. @item 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 @file{.x} files, mostly these test cases should not contain platform dependencies. FIXME: discuss how defines such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. @item gcc.c-torture/execute This testsuite contains test cases that should compile, link and run; otherwise the same comments as for @file{gcc.c-torture/compile} apply. @item gcc.c-torture/execute/ieee This contains tests which are specific to IEEE floating point. @item gcc.c-torture/unsorted FIXME: describe this. This directory should probably not be used for new tests. @item 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: @table @file @item @code{bprob*.c} Test @option{-fbranch-probabilities} using @file{gcc.misc-tests/bprob.exp}, which in turn uses the generic, language-independent framework (@pxref{profopt Testing, , Support for testing profile-directed optimizations}). @item @code{gcov*.c} Test @command{gcov} output using @file{gcov.exp}, which in turn uses the language-independent support (@pxref{gcov Testing, , Support for testing gcov}). @item @code{i386-pf-*.c} Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. @end table @item gcc.test-framework @table @file @item @code{dg-*.c} Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}. @end table @end table FIXME: merge in @file{testsuite/README.gcc} and discuss the format of test cases and magic comments more. @node libgcj Tests @section The Java library testsuites. Runtime tests are executed via @samp{make check} in the @file{@var{target}/libjava/testsuite} directory in the build tree. Additional runtime tests can be checked into this testsuite. Regression testing of the core packages in libgcj is also covered by the Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} develops tests for the Java Class Libraries. These tests are run as part of libgcj testing by placing the Mauve tree within the libjava testsuite sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying the location of that tree when invoking @samp{make}, as in @samp{make MAUVEDIR=~/mauve check}. To detect regressions, a mechanism in @file{mauve.exp} compares the failures for a test run against the list of expected failures in @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. Update this file when adding new failing tests to Mauve, or when fixing bugs in libgcj that had caused Mauve test failures. We encourage developers to contribute test cases to Mauve. @node LTO Testing @section 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. @table @code @item @{ dg-lto-do @var{do-what-keyword} @} @var{do-what-keyword} specifies how the test is compiled and whether it is executed. It is one of: @table @code @item assemble Compile with @option{-c} to produce a relocatable object file. @item link Compile, assemble, and link to produce an executable file. @item run Produce and run an executable file, which is expected to return an exit code of 0. @end table The default is @code{assemble}. That can be overridden for a set of tests by redefining @code{dg-do-what-default} within the @code{.exp} file for those tests. Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional @samp{target} or @samp{xfail} list. Use @code{dg-skip-if}, @code{dg-xfail-if}, or @code{dg-xfail-run-if}. @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} This directive provides a list of one or more sets of compiler options to override @var{LTO_OPTIONS}. Each test will be compiled and run with each of these sets of options. @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@} This directive adds @var{options} to the linker options used. @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@} This directive removes @var{options} from the set of linker options used. @end table @node gcov Testing @section Support for testing @command{gcov} Language-independent support for testing @command{gcov}, and for checking that branch profiling produces expected values, is provided by the expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures in @file{lib/gcc-dg.exp} to compile and run the test program. A typical @command{gcov} test contains the following DejaGnu commands within comments: @smallexample @{ dg-options "-fprofile-arcs -ftest-coverage" @} @{ dg-do run @{ target native @} @} @{ dg-final @{ run-gcov sourcefile @} @} @end smallexample Checks of @command{gcov} output can include line counts, branch percentages, and call return percentages. All of these checks are requested via commands that appear in comments in the test's source file. Commands to check line counts are processed by default. Commands to check branch percentages and call return percentages are processed if the @command{run-gcov} command has arguments @code{branches} or @code{calls}, respectively. For example, the following specifies checking both, as well as passing @option{-b} to @command{gcov}: @smallexample @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} @end smallexample A line count command appears within a comment on the source line that is expected to get the specified count and has the form @code{count(@var{cnt})}. A test should only check line counts for lines that will get the same count for any architecture. Commands to check branch percentages (@code{branch}) and call return percentages (@code{returns}) are very similar to each other. A beginning command appears on or before the first of a range of lines that will report the percentage, and the ending command follows that range of lines. The beginning command can include a list of percentages, all of which are expected to be found within the range. A range is terminated by the next command of the same kind. A command @code{branch(end)} or @code{returns(end)} marks the end of a range without starting a new one. For example: @smallexample if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ /* @r{branch(end)} */ foo (i, j); @end smallexample For a call return percentage, the value specified is the percentage of calls reported to return. For a branch percentage, the value is either the expected percentage or 100 minus that value, since the direction of a branch can differ depending on the target or the optimization level. Not all branches and calls need to be checked. A test should not check for branches that might be optimized away or replaced with predicated instructions. Don't check for calls inserted by the compiler or ones that might be inlined or optimized away. A single test can check for combinations of line counts, branch percentages, and call return percentages. The command to check a line count must appear on the line that will report that count, but commands to check branch percentages and call return percentages can bracket the lines that report them. @node profopt Testing @section Support for testing profile-directed optimizations The file @file{profopt.exp} provides language-independent support for checking correct execution of a test built with profile-directed optimization. This testing requires that a test program be built and executed twice. The first time it is compiled to generate profile data, and the second time it is compiled to use the data that was generated during the first execution. The second execution is to verify that the test produces the expected results. To check that the optimization actually generated better code, a test can be built and run a third time with normal optimizations to verify that the performance is better with the profile-directed optimizations. @file{profopt.exp} has the beginnings of this kind of support. @file{profopt.exp} provides generic support for profile-directed optimizations. Each set of tests that uses it provides information about a specific optimization: @table @code @item tool tool being tested, e.g., @command{gcc} @item profile_option options used to generate profile data @item feedback_option options used to optimize using that profile data @item prof_ext suffix of profile data files @item PROFOPT_OPTIONS list of options with which to run each test, similar to the lists for torture tests @item @{ dg-final-generate @{ @var{local-directive} @} @} This directive is similar to @code{dg-final}, but the @var{local-directive} is run after the generation of profile data. @item @{ dg-final-use @{ @var{local-directive} @} @} The @var{local-directive} is run after the profile data have been used. @end table @node compat Testing @section Support for testing binary compatibility The file @file{compat.exp} provides language-independent support for binary compatibility testing. It supports testing interoperability of two compilers that follow the same ABI, or of multiple sets of compiler options that should not affect binary compatibility. It is intended to be used for 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. @table @file @item @var{testname}_main.@var{suffix} Contains the main program, which calls a function in file @file{@var{testname}_x.@var{suffix}}. @item @var{testname}_x.@var{suffix} Contains at least one call to a function in @file{@var{testname}_y.@var{suffix}}. @item @var{testname}_y.@var{suffix} Shares data with, or gets arguments from, @file{@var{testname}_x.@var{suffix}}. @end table Within each test, the main program and one functional piece are compiled by the GCC under test. The other piece can be compiled by an alternate compiler. If no alternate compiler is specified, then all three source files are all compiled by the GCC under test. 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. @file{compat.exp} defines default pairs of compiler options. These can be overridden by defining the environment variable @env{COMPAT_OPTIONS} as: @smallexample COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]" @end smallexample where @var{tsti} and @var{alti} are lists of options, with @var{tsti} used by the compiler under test and @var{alti} used by the alternate compiler. For example, with @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, the test is first built with @option{-g -O0} by the compiler under test and with @option{-O3} by the alternate compiler. The test is built a second time using @option{-fpic} by the compiler under test and @option{-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 @env{ALT_CC_UNDER_TEST}, and for C++ define @env{ALT_CXX_UNDER_TEST}. These will be written to the @file{site.exp} file used by DejaGnu. The default is to build each test with the compiler under test using the first of each pair of compiler options from @env{COMPAT_OPTIONS}. When @env{ALT_CC_UNDER_TEST} or @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using the compiler under test but with combinations of the options from @env{COMPAT_OPTIONS}. To run only the C++ compatibility suite using the compiler under test and another version of GCC using specific compiler options, do the following from @file{@var{objdir}/gcc}: @smallexample rm site.exp make -k \ ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ COMPAT_OPTIONS="@var{lists as shown above}" \ check-c++ \ RUNTESTFLAGS="compat.exp" @end smallexample A test that fails when the source files are compiled with different compilers, but passes when the files are compiled with the same compiler, demonstrates incompatibility of the generated code or runtime support. A test that fails for the alternate compiler but passes for the compiler under test probably tests for a bug that was fixed in the compiler under test but is present in the alternate compiler. The binary compatibility tests support a small number of test framework commands that appear within comments in a test file. @table @code @item dg-require-* These commands can be used in @file{@var{testname}_main.@var{suffix}} to skip the test if specific support is not available on the target. @item dg-options The specified options are used for compiling this particular source file, appended to the options from @env{COMPAT_OPTIONS}. When this command appears in @file{@var{testname}_main.@var{suffix}} the options are also used to link the test program. @item 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. @end table @node Torture Tests @section 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. @file{lib/torture-options.exp} defines procedures to set up these lists: @table @code @item torture-init Initialize use of torture lists. @item 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. @item torture-finish Finalize use of torture lists. @end table The @file{.exp} file for a set of tests that use torture options must include calls to these three procedures if: @itemize @bullet @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}. @item It calls @var{$@{tool@}}@code{-torture} or @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c}, @code{fortran}, or @code{objc}. @item It calls @code{dg-pch}. @end itemize It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest} to call the torture procedures if the tests should use the list in @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}. Most uses of torture options can override the default lists by defining @var{TORTURE_OPTIONS} or add to the default list by defining @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc} file or add them to the @file{site.exp} file; for example @smallexample set ADDITIONAL_TORTURE_OPTIONS [list \ @{ -O2 -ftree-loop-linear @} \ @{ -O2 -fpeel-loops @} ] @end smallexample