| cc Copyright (C) 2002-2026 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{https://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 c++tools | |
| Contains the sources for the g++-mapper-server, a tool used with | |
| C++ modules. | |
| @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 gotools | |
| Support tools for Go. | |
| @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 libatomic | |
| The runtime support library for atomic operations (e.g.@: for @code{__sync} | |
| and @code{__atomic}). | |
| @item libbacktrace | |
| A library that allows GCC to produce backtraces when it crashes. | |
| @item libcc1 | |
| A library that allows GDB to make use of the compiler. | |
| @item libcody | |
| A compiler dynamism library to allow communication between compilers and | |
| build systems, for purposes such as C++ modules. | |
| @item libcpp | |
| The C preprocessor library. | |
| @item libdecnumber | |
| The Decimal Float support library. | |
| @item libffi | |
| The @code{libffi} library, used as part of the Go runtime library. | |
| @item libga68 | |
| The Algol 68 runtime library. | |
| @item libgcc | |
| The GCC runtime library. | |
| @item libgcobol | |
| The COBOL runtime library. | |
| @item libgfortran | |
| The Fortran runtime library. | |
| @item libgm2 | |
| The Modula-2 runtime library. | |
| @item libgo | |
| The Go runtime library. The bulk of this library is mirrored from the | |
| @uref{https://github.com/@/golang/go, master Go repository}. | |
| @item libgomp | |
| The GNU Offloading and Multi Processing 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 libitm | |
| The runtime support library for transactional memory. | |
| @item libobjc | |
| The Objective-C and Objective-C++ runtime library. | |
| @item libphobos | |
| The D standard and runtime library. The bulk of this library is mirrored | |
| from the @uref{https://github.com/@/dlang, master D repositories}. | |
| @item libquadmath | |
| The runtime support library for quad-precision math operations. | |
| @item libsanitizer | |
| Libraries for various sanitizers. The bulk of this directory is mirrored | |
| from the @uref{https://github.com/google/sanitizers, Google sanitizers | |
| repositories}. | |
| @item libssp | |
| The Stack protector runtime library. | |
| @item libstdc++-v3 | |
| The C++ runtime library. | |
| @item libvtv | |
| The vtable verification library. | |
| @item lto-plugin | |
| Plugin used by the linker 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 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. | |
| @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{c} (for C), @file{cp} (for C++), @file{m2} | |
| (for Modula-2), | |
| @file{objc} (for Objective-C), @file{objcp} (for Objective-C++), | |
| and @file{lto} (for LTO) 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 common | |
| Source files shared between the compiler drivers (such as | |
| @command{gcc}) and the compilers proper (such as @file{cc1}). If an | |
| architecture defines target hooks shared between those places, it also | |
| has a subdirectory in @file{common/config}. @xref{Target Structure}. | |
| @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 defined by the C | |
| standard that do not declare functions with external linkage. | |
| @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 | |
| of its own, mainly headers that do not declare functions with external | |
| linkage. 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. They're installed at the | |
| top of the @file{include} tree, unless the optional @samp{/././} | |
| sequence appears in the name, marking the beginning of the name under | |
| which the header should be installed. | |
| GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. | |
| This is done to cope with command-line options that change the | |
| representation of floating point numbers. | |
| GCC also installs its own version of @code{<limits.h>}; this is generated | |
| from @file{glimits.h}, together with @file{limitx.h} and | |
| @file{limity.h} if the system also has its own version of | |
| @code{<limits.h>}. (GCC provides its own header because it does not | |
| declare functions with external linkage, 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{<limits.h>}.) The system's @code{<limits.h>} 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{<tgmath.h>}. 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_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_git}. 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. | |
| @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{c}, @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.cc} 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_git} (@pxref{Texinfo Manuals}) | |
| and the online manuals should be linked to from | |
| @file{onlinedocs/index.html}. | |
| @item | |
| If the front end has its own manual with its own index of options, the | |
| generated @file{Option-Index.html} should be added to | |
| @code{PER_LANGUAGE_OPTION_INDEXES} in @file{gcc/regenerate-opt-urls.py} | |
| and to @code{OPT_URLS_HTML_DEPS} in @file{gcc/Makefile.in}. | |
| @item | |
| Any old releases or CVS repositories of the front end, before its | |
| inclusion in GCC, should be made available on the GCC web site at | |
| @uref{https://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.cc} 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. | |
| 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 | |
| Obj-C++ front end depends on the C++ and ObjC front ends, so sets | |
| @samp{lang_requires="objc 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.cc} 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 | |
| @item 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 | |
| An entry in @file{gcc/regenerate-opt-urls.py}'s TARGET_SPECIFIC_PAGES | |
| dictionary mapping from target-specific HTML documentation pages | |
| to the target specific source directory. | |
| @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 | |
| The @file{@var{machine}.h} header is included very early in GCC's | |
| standard sequence of header files, while @file{@var{machine}-protos.h} | |
| is included late in the sequence. Thus @file{@var{machine}-protos.h} | |
| can include declarations referencing types that are not defined when | |
| @file{@var{machine}.h} is included, specifically including those from | |
| @file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not | |
| be available in every context where @file{@var{machine}-protos.h} is | |
| included, in this file you should guard declarations using these types | |
| inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE} | |
| conditional code segments. | |
| If the backend uses shared data structures that require @code{GTY} markers | |
| for garbage collection (@pxref{Type Information}), you must declare those | |
| in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}. | |
| Any definitions required for building libgcc must also go in | |
| @file{@var{machine}.h}. | |
| GCC uses the macro @code{IN_TARGET_CODE} to distinguish between | |
| machine-specific @file{.c} and @file{.cc} files and | |
| machine-independent @file{.c} and @file{.cc} files. Machine-specific | |
| files should use the directive: | |
| @example | |
| #define IN_TARGET_CODE 1 | |
| @end example | |
| before including @code{config.h}. | |
| 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. | |
| @item | |
| Target triplets covering all @file{config.gcc} stanzas for the target, | |
| in the list in @file{contrib/config-list.mk}. | |
| @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. | |
| * 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. | |
| * GIMPLE Tests:: Support for testing GIMPLE passes. | |
| * RTL Tests:: Support for testing RTL passes. | |
| @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} | |
| * Remove Options:: Features for @code{dg-remove-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, ,}. | |
| @item @{ dg-remove-options @var{feature} @dots{} @} | |
| Remove any compiler options that are needed to access certain features. | |
| This directive does nothing on targets that disable the features by | |
| default, or that don't provide them at all. It must come after | |
| all @code{dg-options} and @code{dg-add-options} directives. | |
| For supported values of @var{feature} see @ref{Remove Options, ,}. | |
| @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @} | |
| This directive provides a list of compiler options, to be used | |
| if the target system matches @var{selector}, that are added to the default | |
| options used for this set of tests. | |
| @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-do-if @var{action} @{ @var{selector} @} @} | |
| Same as dg-do if the selector matches and the test hasn't already been | |
| marked as unsupported. Use it to override an action on a target while | |
| leaving the default action alone for other targets. | |
| @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} [@{ target @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 compiler to crash | |
| @table @code | |
| @item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} | |
| Expect the compiler to crash with an internal compiler error and return | |
| a nonzero exit status if the conditions (which are the same as for | |
| @code{dg-skip-if}) are met. Used for tests that test bugs that have not been | |
| fixed yet. | |
| @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 | |
| Where @var{line} is an accepted argument for these commands, a value of @samp{0} | |
| can be used if there is no line associated with the message. | |
| @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-note @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @} | |
| The line is expected to get a @samp{note} 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. | |
| By default, any @emph{excess} @samp{note} messages are pruned, meaning | |
| their appearance doesn't trigger @emph{excess errors}. | |
| However, if @samp{dg-note} is used at least once in a testcase, | |
| they're not pruned and instead must @emph{all} be handled explicitly. | |
| Thus, if looking for just single instances of messages with | |
| @samp{note: } prefixes without caring for all of them, use | |
| @samp{dg-message "note: [@dots{}]"} instead of @samp{dg-note}, or use | |
| @samp{dg-note} together with @samp{dg-prune-output "note: "}. | |
| @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-line @var{linenumvar} @} | |
| This DejaGnu directive sets the variable @var{linenumvar} to the line number of | |
| the source line. The variable @var{linenumvar} can then be used in subsequent | |
| @code{dg-error}, @code{dg-warning}, @code{dg-message}, @code{dg-note} | |
| and @code{dg-bogus} | |
| directives. For example: | |
| @smallexample | |
| int a; /* @{ dg-line first_def_a @} */ | |
| float a; /* @{ dg-error "conflicting types of" @} */ | |
| /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */ | |
| @end smallexample | |
| @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}, @code{dg-message}, @samp{dg-note} 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}. | |
| @item @{ dg-output-file @var{file} [@{ target/xfail @var{selector} @}] @} | |
| Compares the content of @var{file} against the combined output that the | |
| test executable writes to @file{stdout} and @file{stderr}. | |
| @end table | |
| @subsubsection Specify environment variables for a test | |
| @table @code | |
| @item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @} | |
| Specify that the environment variable @var{var_name} needs to be set | |
| to @var{var_value} before invoking the compiler on the test file. | |
| @item @{ dg-set-target-env-var @var{var_name} "@var{var_value}" @} | |
| Specify that the environment variable @var{var_name} needs to be set | |
| to @var{var_value} before execution of the program created by the test. | |
| @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}" [@{ \[linkonly\] \[target @var{selector}\] @}] @} | |
| Specify additional source files to appear in the compile line | |
| following the main test file. | |
| If the directive includes the optional @samp{@{ @var{selector} @}} | |
| then the additional sources are only added if the target system | |
| matches the @var{selector}. | |
| If @samp{linkonly} is specified, additional sources are used only in | |
| @samp{link} and @samp{run} tests; they are reported as unsupported and | |
| discarded in other kinds of tests that direct the compiler to output to | |
| a single 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; | |
| use @samp{*-*-*} to match any target | |
| @item a single effective-target keyword (@pxref{Effective-Target Keywords}) | |
| @item a list of compiler options that should be included or excluded | |
| (as described in more detail below) | |
| @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. A context | |
| that allows either @samp{target} or @samp{xfail} also allows | |
| @samp{@{ target @var{selector1} xfail @var{selector2} @}} | |
| to skip the test for targets that don't match @var{selector1} and the | |
| test to fail for targets that match @var{selector2}. | |
| A selector expression appears within curly braces and uses a single | |
| logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An | |
| operand is one of the following: | |
| @itemize @bullet | |
| @item | |
| another selector expression, in curly braces | |
| @item | |
| an effective-target keyword, such as @code{lp64} | |
| @item | |
| a single target triplet | |
| @item | |
| a list of target triplets within quotes or curly braces | |
| @item | |
| one of the following: | |
| @table @samp | |
| @item @{ any-opts @var{opt1} @dots{} @var{optn} @} | |
| Each of @var{opt1} to @var{optn} is a space-separated list of option globs. | |
| The selector expression evaluates to true if, for one of these strings, | |
| every glob in the string matches an option that was passed to the compiler. | |
| For example: | |
| @smallexample | |
| @{ any-opts "-O3 -flto" "-O[2g]" @} | |
| @end smallexample | |
| is true if any of the following are true: | |
| @itemize @bullet | |
| @item | |
| @option{-O2} was passed to the compiler | |
| @item | |
| @option{-Og} was passed to the compiler | |
| @item | |
| both @option{-O3} and @option{-flto} were passed to the compiler | |
| @end itemize | |
| This kind of selector can only be used within @code{dg-final} directives. | |
| Use @code{dg-skip-if}, @code{dg-xfail-if} or @code{dg-xfail-run-if} to | |
| skip whole tests based on options, or to mark them as expected to fail | |
| with certain options. | |
| @item @{ no-opts @var{opt1} @dots{} @var{optn} @} | |
| As for @code{any-opts} above, each of @var{opt1} to @var{optn} is a | |
| space-separated list of option globs. The selector expression | |
| evaluates to true if, for all of these strings, there is at least | |
| one glob that does not match an option that was passed to the compiler. | |
| It is shorthand for: | |
| @smallexample | |
| @{ ! @{ any-opts @var{opt1} @dots{} @var{optn} @} @} | |
| @end smallexample | |
| For example: | |
| @smallexample | |
| @{ no-opts "-O3 -flto" "-O[2g]" @} | |
| @end smallexample | |
| is true if all of the following are true: | |
| @itemize @bullet | |
| @item | |
| @option{-O2} was not passed to the compiler | |
| @item | |
| @option{-Og} was not passed to the compiler | |
| @item | |
| at least one of @option{-O3} or @option{-flto} was not passed to the compiler | |
| @end itemize | |
| Like @code{any-opts}, this kind of selector can only be used within | |
| @code{dg-final} directives. | |
| @end table | |
| @end itemize | |
| Here are some examples of full target selectors: | |
| @smallexample | |
| @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} | |
| @{ target @{ powerpc*-*-* && lp64 @} @} | |
| @{ xfail @{ lp64 || vect_no_align @} @} | |
| @{ xfail @{ aarch64*-*-* && @{ any-opts "-O2" @} @} @} | |
| @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. Effective-target keywords | |
| matching @file{auto-host.h} macros can be generated from definitions | |
| in @file{lib/et-static.def}. | |
| 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 Object file format | |
| This identifies the object file format emitted by the compiler. Matching | |
| assembler output often depends on content that differs between file formats. | |
| @table @code | |
| @item elf | |
| Target uses the ELF file format (note that ELFv2 is matched specifically for | |
| the powerpc platform, below). | |
| @item macho | |
| Target uses the Mach-O file format (currently applies only to Darwin / macOS). | |
| @item pe | |
| Target uses the PE/COFF file format (e.g. for Windows). | |
| @end table | |
| @subsubsection Endianness | |
| @table @code | |
| @item be | |
| Target uses big-endian memory order for multi-byte and multi-word data. | |
| @item le | |
| Target uses little-endian memory order for multi-byte and multi-word data. | |
| @end table | |
| @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 longdouble128 | |
| Target has 128-bit @code{long double}. | |
| @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 longlong64 | |
| Target has 64-bit @code{long long}. | |
| @item long_neq_int | |
| Target has @code{int} and @code{long} with different sizes. | |
| @item short_eq_int | |
| Target has @code{short} and @code{int} with the same size. | |
| @item ptr_eq_short | |
| Target has pointers (@code{void *}) and @code{short} with the same size. | |
| @item int_eq_float | |
| Target has @code{int} and @code{float} with the same size. | |
| @item ptr_eq_long | |
| Target has pointers (@code{void *}) and @code{long} with the same size. | |
| @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 size20plus | |
| Target has a 20-bit or larger address space, so supports at least | |
| 16-bit array and structure sizes. | |
| @item size24plus | |
| Target has a 24-bit or larger address space, so supports at least | |
| 20-bit array and structure sizes. | |
| @item size32plus | |
| Target has a 32-bit or larger address space, so supports at least | |
| 24-bit array and structure sizes. | |
| @item 4byte_wchar_t | |
| Target has @code{wchar_t} that is at least 4 bytes. | |
| @item float@var{n} | |
| Target has the @code{_Float@var{n}} type. | |
| @item float@var{n}x | |
| Target has the @code{_Float@var{n}x} type. | |
| @item float@var{n}_runtime | |
| Target has the @code{_Float@var{n}} type, including runtime support | |
| for any options added with @code{dg-add-options}. | |
| @item float@var{n}x_runtime | |
| Target has the @code{_Float@var{n}x} type, including runtime support | |
| for any options added with @code{dg-add-options}. | |
| @item floatn_nx_runtime | |
| Target has runtime support for any options added with | |
| @code{dg-add-options} for any @code{_Float@var{n}} or | |
| @code{_Float@var{n}x} type. | |
| @item inf | |
| Target supports floating point infinite (@code{inf}) for type | |
| @code{double}. | |
| @item inff | |
| Target supports floating point infinite (@code{inf}) for type | |
| @code{float}. | |
| @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_real_10 | |
| Target supports Fortran @code{real} that is 10 bytes or longer. | |
| @item fortran_real_16 | |
| Target supports Fortran @code{real} 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_align_stack_vars | |
| The target's ABI allows stack variables to be aligned to the preferred | |
| vector alignment. | |
| @item vect_avg_qi | |
| Target supports both signed and unsigned averaging operations on vectors | |
| of bytes. | |
| @item vect_mulhrs_hi | |
| Target supports both signed and unsigned multiply-high-with-round-and-scale | |
| operations on vectors of half-words. | |
| @item vect_sdiv_pow2_si | |
| Target supports signed division by constant power-of-2 operations | |
| on vectors of 4-byte integers. | |
| @item vect_condition | |
| Target supports vector conditional operations. | |
| @item vect_cond_mixed | |
| Target supports vector conditional operations where comparison operands | |
| have different type from the value operands. | |
| @item vect_double | |
| Target supports hardware vectors of @code{double}. | |
| @item vect_double_cond_arith | |
| Target supports conditional addition, subtraction, multiplication, | |
| division, minimum and maximum on vectors of @code{double}, via the | |
| @code{cond_} optabs. | |
| @item vect_element_align_preferred | |
| The target's preferred vector alignment is the same as the element | |
| alignment. | |
| @item vect_float | |
| Target supports hardware vectors of @code{float} when | |
| @option{-funsafe-math-optimizations} is in effect. | |
| @item vect_float_strict | |
| Target supports hardware vectors of @code{float} when | |
| @option{-funsafe-math-optimizations} is not in effect. | |
| This implies @code{vect_float}. | |
| @item vect_early_break | |
| Target supports vectorization codegen of loops with early breaks. | |
| This requires an implementation of the cbranch optab for vectors. | |
| @item vect_early_break_hw | |
| Target supports hardware vectorization and running of loops with early breaks. | |
| This requires an implementation of the cbranch optab for vectors. | |
| @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_check_ptrs | |
| Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs} | |
| optabs on vectors. | |
| @item vect_fully_masked | |
| Target supports fully-masked (also known as fully-predicated) loops, | |
| so that vector loops can handle partial as well as full vectors. | |
| @item vect_masked_load | |
| Target supports vector masked loads. | |
| @item vect_masked_store | |
| Target supports vector masked stores. | |
| @item vect_gather_load_ifn | |
| Target supports vector gather loads using internal functions | |
| (rather than via built-in functions or emulation). | |
| @item vect_scatter_store | |
| Target supports vector scatter stores. | |
| @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_peeling_profitable | |
| Target might require to peel loops for alignment purposes. | |
| @item vect_no_int_min_max | |
| Target does not support a vector min and 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_bool_cmp | |
| Target supports comparison of @code{bool} vectors for at least one | |
| vector length. | |
| @item vect_char_add | |
| Target supports addition of @code{char} vectors for at least one | |
| vector length. | |
| @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_long_mult | |
| Target supports 64 bit @code{vector long} 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_perm_byte | |
| Target supports permutation of vectors with 8-bit elements. | |
| @item vect_perm_short | |
| Target supports permutation of vectors with 16-bit elements. | |
| @item vect_perm3_byte | |
| Target supports permutation of vectors with 8-bit elements, and for the | |
| default vector length it is possible to permute: | |
| @example | |
| @{ a0, a1, a2, b0, b1, b2, @dots{} @} | |
| @end example | |
| to: | |
| @example | |
| @{ a0, a0, a0, b0, b0, b0, @dots{} @} | |
| @{ a1, a1, a1, b1, b1, b1, @dots{} @} | |
| @{ a2, a2, a2, b2, b2, b2, @dots{} @} | |
| @end example | |
| using only two-vector permutes, regardless of how long the sequence is. | |
| @item vect_perm3_int | |
| Like @code{vect_perm3_byte}, but for 32-bit elements. | |
| @item vect_perm3_short | |
| Like @code{vect_perm3_byte}, but for 16-bit elements. | |
| @item vect_shift | |
| Target supports a hardware vector shift operation. | |
| @item vect_unaligned_possible | |
| Target prefers vectors to have an alignment greater than element | |
| alignment, but also allows unaligned vector accesses in some | |
| circumstances. | |
| @item vect_variable_length | |
| Target has variable-length vectors. | |
| @item vect64 | |
| Target supports vectors of 64 bits. | |
| @item vect32 | |
| Target supports vectors of 32 bits. | |
| @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_widen_mult_si_to_di_pattern | |
| Target supports a vector widening multiplication of @code{int} operands | |
| into @code{long} results. | |
| @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_usdot_qi | |
| Target supports a vector dot-product where one operand of the multiply is | |
| @code{signed char} and the other 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}. | |
| @item vect_intdouble_cvt | |
| Target supports conversion from @code{signed int} to @code{double}. | |
| @item vect_doubleint_cvt | |
| Target supports conversion from @code{double} to @code{signed int}. | |
| @item vect_max_reduc | |
| Target supports max reduction for vectors. | |
| @item vect_sizes_16B_8B | |
| Target supports 16- and 8-bytes vectors. | |
| @item vect_sizes_32B_16B | |
| Target supports 32- and 16-bytes vectors. | |
| @item vect_logical_reduc | |
| Target supports AND, IOR and XOR reduction on vectors. | |
| @item vect_fold_extract_last | |
| Target supports the @code{fold_extract_last} optab. | |
| @item vect_len_load_store | |
| Target supports the @code{len_load} and @code{len_store} optabs. | |
| @item vect_partial_vectors_usage_1 | |
| Target supports loop vectorization with partial vectors and | |
| @code{vect-partial-vector-usage} is set to 1. | |
| @item vect_partial_vectors_usage_2 | |
| Target supports loop vectorization with partial vectors and | |
| @code{vect-partial-vector-usage} is set to 2. | |
| @item vect_partial_vectors | |
| Target supports loop vectorization with partial vectors and | |
| @code{vect-partial-vector-usage} is nonzero. | |
| @item vect_slp_v2qi_store_align | |
| Target supports vectorization of 2-byte char stores with 2-byte aligned | |
| address at plain @option{-O2}. | |
| @item vect_slp_v4qi_store_align | |
| Target supports vectorization of 4-byte char stores with 4-byte aligned | |
| address at plain @option{-O2}. | |
| @item vect_slp_v4qi_store_unalign | |
| Target supports vectorization of 4-byte char stores with unaligned address | |
| at plain @option{-O2}. | |
| @item struct_4char_block_move | |
| Target supports block move for 8-byte aligned 4-byte size struct initialization. | |
| @item vect_slp_v4qi_store_unalign_1 | |
| Target supports vectorization of 4-byte char stores with unaligned address | |
| or store them with constant pool at plain @option{-O2}. | |
| @item struct_8char_block_move | |
| Target supports block move for 8-byte aligned 8-byte size struct initialization. | |
| @item vect_slp_v8qi_store_unalign_1 | |
| Target supports vectorization of 8-byte char stores with unaligned address | |
| or store them with constant pool at plain @option{-O2}. | |
| @item struct_16char_block_move | |
| Target supports block move for 8-byte aligned 16-byte size struct | |
| initialization. | |
| @item vect_slp_v16qi_store_unalign_1 | |
| Target supports vectorization of 16-byte char stores with unaligned address | |
| or store them with constant pool at plain @option{-O2}. | |
| @item vect_slp_v2hi_store_align | |
| Target supports vectorization of 4-byte short stores with 4-byte aligned | |
| addressat plain @option{-O2}. | |
| @item vect_slp_v2hi_store_unalign | |
| Target supports vectorization of 4-byte short stores with unaligned address | |
| at plain @option{-O2}. | |
| @item vect_slp_v4hi_store_unalign | |
| Target supports vectorization of 8-byte short stores with unaligned address | |
| at plain @option{-O2}. | |
| @item vect_slp_v2si_store_align | |
| Target supports vectorization of 8-byte int stores with 8-byte aligned address | |
| at plain @option{-O2}. | |
| @item vect_slp_v4si_store_unalign | |
| Target supports vectorization of 16-byte int stores with unaligned address | |
| at plain @option{-O2}. | |
| @end table | |
| @subsubsection Thread Local Storage attributes | |
| @table @code | |
| @item tls | |
| Target supports thread-local storage. | |
| @item tls_link | |
| Target supports linking TLS executables. | |
| @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. | |
| @item dfp_bid | |
| Target uses the BID format for decimal floating point. | |
| @end table | |
| @subsubsection ARM-specific attributes | |
| @table @code | |
| @item arm32 | |
| ARM target generates 32-bit code. | |
| @item arm_little_endian | |
| ARM target that generates little-endian code. | |
| @item arm_eabi | |
| ARM target adheres to the ABI for the ARM Architecture. | |
| @item arm_fp_ok | |
| @anchor{arm_fp_ok} | |
| ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or | |
| equivalent options. Some multilibs may be incompatible with these | |
| options. | |
| @item arm_fp_dp_ok | |
| @anchor{arm_fp_dp_ok} | |
| ARM target defines @code{__ARM_FP} with double-precision support using | |
| @code{-mfloat-abi=softfp} or equivalent options. Some multilibs may | |
| be incompatible with these options. | |
| @item arm_hf_eabi | |
| ARM target adheres to the VFP and Advanced SIMD Register Arguments | |
| variant of the ABI for the ARM Architecture (as selected with | |
| @code{-mfloat-abi=hard}). | |
| @item arm_softfloat | |
| ARM target uses emulated floating point operations. | |
| @item arm_hard_vfp_ok | |
| ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_neon | |
| ARM target supports generating NEON instructions. | |
| @item arm_tune_string_ops_prefer_neon | |
| Test CPU tune supports inlining string operations with NEON instructions. | |
| @item arm_neon_hw | |
| Test system supports executing NEON instructions. | |
| @item arm_neonv2_hw | |
| Test system supports executing NEON v2 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_ok_no_float_abi | |
| @anchor{arm_neon_ok_no_float_abi} | |
| ARM Target supports NEON with @code{-mfpu=neon}, but without any | |
| -mfloat-abi= option. Some multilibs may be incompatible with this | |
| option. | |
| @item arm_neonv2_ok | |
| @anchor{arm_neonv2_ok} | |
| ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible | |
| options. Some multilibs may be incompatible with these options. | |
| @item arm_fp16_ok | |
| @anchor{arm_fp16_ok} | |
| Target supports options to generate VFP half-precision floating-point | |
| instructions. Some multilibs may be incompatible with these | |
| options. This test is valid for ARM only. | |
| @item arm_fp16_hw | |
| Target supports executing VFP half-precision floating-point | |
| instructions. This test is valid for ARM only. | |
| @item arm_neon_fp16_ok | |
| @anchor{arm_neon_fp16_ok} | |
| ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible | |
| options, including @code{-mfp16-format=ieee} if necessary to obtain the | |
| @code{__fp16} type. Some multilibs may be incompatible with these options. | |
| @item arm_neon_fp16_hw | |
| Test system supports executing Neon half-precision float instructions. | |
| (Implies @code{arm_neon_fp16_ok}.) | |
| @item arm_fp16_alternative_ok | |
| ARM target supports the ARM FP16 alternative format. Some multilibs | |
| may be incompatible with the options needed. | |
| @item arm_fp16_alternative_hw | |
| Test system supports executing VFP half-precision floating-point | |
| instructions in the ARM FP16 alternative format. (Implies | |
| @code{arm_fp16_alternative_ok}.) | |
| @item arm_fp16_none_ok | |
| ARM target supports specifying none as the ARM FP16 format. | |
| @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_nothumb | |
| ARM target that is not using Thumb. | |
| @item arm_vfp_ok | |
| ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_vfp3_ok | |
| @anchor{arm_vfp3_ok} | |
| ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_arch_v8a_hard_ok | |
| @anchor{arm_arch_v8a_hard_ok} | |
| The compiler is targeting @code{arm*-*-*} and can compile and assemble code | |
| using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}. | |
| This is not enough to guarantee that linking works. | |
| @item arm_arch_v8a_hard_multilib | |
| The compiler is targeting @code{arm*-*-*} and can build programs using | |
| the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}. | |
| The target can also run the resulting binaries. | |
| @item arm_v8_vfp_ok | |
| ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_v8_neon_ok | |
| ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_v8_1a_neon_ok | |
| @anchor{arm_v8_1a_neon_ok} | |
| ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_v8_1a_neon_hw | |
| ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some | |
| multilibs may be incompatible with the options needed. Implies | |
| arm_v8_1a_neon_ok. | |
| @item arm_acq_rel | |
| ARM target supports acquire-release instructions. | |
| @item arm_v8_2a_fp16_scalar_ok | |
| @anchor{arm_v8_2a_fp16_scalar_ok} | |
| ARM target supports options to generate instructions for ARMv8.2-A and | |
| scalar instructions from the FP16 extension. Some multilibs may be | |
| incompatible with these options. | |
| @item arm_v8_2a_fp16_scalar_hw | |
| ARM target supports executing instructions for ARMv8.2-A and scalar | |
| instructions from the FP16 extension. Some multilibs may be | |
| incompatible with these options. Implies arm_v8_2a_fp16_neon_ok. | |
| @item arm_v8_2a_fp16_neon_ok | |
| @anchor{arm_v8_2a_fp16_neon_ok} | |
| ARM target supports options to generate instructions from ARMv8.2-A with | |
| the FP16 extension. Some multilibs may be incompatible with these | |
| options. Implies arm_v8_2a_fp16_scalar_ok. | |
| @item arm_v8_2a_fp16_neon_hw | |
| ARM target supports executing instructions from ARMv8.2-A with the FP16 | |
| extension. Some multilibs may be incompatible with these options. | |
| Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw. | |
| @item arm_v8_2a_dotprod_neon_ok | |
| @anchor{arm_v8_2a_dotprod_neon_ok} | |
| ARM target supports options to generate instructions from ARMv8.2-A with | |
| the Dot Product extension. Some multilibs may be incompatible with these | |
| options. | |
| @item arm_v8_2a_dotprod_neon_hw | |
| ARM target supports executing instructions from ARMv8.2-A with the Dot | |
| Product extension. Some multilibs may be incompatible with these options. | |
| Implies arm_v8_2a_dotprod_neon_ok. | |
| @item arm_v8_2a_i8mm_neon_hw | |
| ARM target supports executing instructions from ARMv8.2-A with the 8-bit | |
| Matrix Multiply extension. Some multilibs may be incompatible with these | |
| options. Implies arm_v8_2a_i8mm_ok. | |
| @item arm_fp16fml_neon_ok | |
| @anchor{arm_fp16fml_neon_ok} | |
| ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS} | |
| half-precision floating-point instructions available from ARMv8.2-A and | |
| onwards. Some multilibs may be incompatible with these options. | |
| @item arm_v8_2a_bf16_neon_ok | |
| ARM target supports options to generate instructions from ARMv8.2-A with | |
| the BFloat16 extension (bf16). Some multilibs may be incompatible with these | |
| options. | |
| @item arm_v8_2a_i8mm_ok | |
| ARM target supports options to generate instructions from ARMv8.2-A with | |
| the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be | |
| incompatible with these options. | |
| @item arm_v8_1m_mve_ok | |
| ARM target supports options to generate instructions from ARMv8.1-M with | |
| the M-Profile Vector Extension (MVE). Some multilibs may be incompatible | |
| with these options. | |
| @item arm_v8_1m_mve_link | |
| ARM target supports linking programs using the options selected by | |
| @code{arm_v8_1m_mve_ok}. Some multilibs may be incompatible with these | |
| options. | |
| @item arm_v8_1m_mve_fp_ok | |
| ARM target supports options to generate instructions from ARMv8.1-M with | |
| the Half-precision floating-point instructions (HP), Floating-point Extension | |
| (FP) along with M-Profile Vector Extension (MVE). Some multilibs may be | |
| incompatible with these options. | |
| @item arm_v8_1m_mve_nofp_ok | |
| ARM target supports options to generate instructions from ARMv8.1-M | |
| with the M-Profile Vector Extension (MVE) but without the | |
| Half-precision floating-point instructions (HP) and Floating-point | |
| Extension (FP). Some multilibs may be incompatible with these options. | |
| @item arm_mve_hw | |
| Test system supports executing MVE instructions. | |
| @item arm_v8m_main_cde | |
| ARM target supports options to generate instructions from ARMv8-M with | |
| the Custom Datapath Extension (CDE). Some multilibs may be incompatible | |
| with these options. | |
| @item arm_v8m_main_cde_fp | |
| ARM target supports options to generate instructions from ARMv8-M with | |
| the Custom Datapath Extension (CDE) and floating-point (VFP). | |
| Some multilibs may be incompatible with these options. | |
| @item arm_v8_1m_main_cde_mve | |
| Arm target supports options to generate instructions from Armv8.1-M with | |
| the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE). | |
| Some multilibs may be incompatible with these options. | |
| @item arm_v8_1m_main_cde_mve_fp | |
| Arm target supports options to generate instructions from Armv8.1-M | |
| with the Custom Datapath Extension (CDE) and M-Profile Vector | |
| Extension (MVE) with floating-point support. Some multilibs may be | |
| incompatible with these options. | |
| @item arm_pacbti_hw | |
| Test system supports executing Pointer Authentication and Branch Target | |
| Identification instructions. | |
| @item arm_prefer_ldrd_strd | |
| ARM target prefers @code{LDRD} and @code{STRD} instructions over | |
| @code{LDM} and @code{STM} instructions. | |
| @item arm_thumb1_movt_ok | |
| ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW} | |
| and @code{MOVT} instructions available. | |
| @item arm_thumb1_cbz_ok | |
| ARM target generates Thumb-1 code for @code{-mthumb} with | |
| @code{CBZ} and @code{CBNZ} instructions available. | |
| @item arm_divmod_simode | |
| ARM target for which divmod transform is disabled, if it supports hardware | |
| div instruction. | |
| @item arm_cmse_ok | |
| ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse} | |
| option. | |
| @item arm_cmse_hw | |
| Test system supports executing CMSE instructions. | |
| @item arm_coproc1_ok | |
| @anchor{arm_coproc1_ok} | |
| ARM target supports the following coprocessor instructions: @code{CDP}, | |
| @code{LDC}, @code{STC}, @code{MCR} and @code{MRC}. | |
| @item arm_coproc2_ok | |
| @anchor{arm_coproc2_ok} | |
| ARM target supports all the coprocessor instructions also listed as supported | |
| in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2}, | |
| @code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}. | |
| @item arm_coproc3_ok | |
| @anchor{arm_coproc3_ok} | |
| ARM target supports all the coprocessor instructions also listed as supported | |
| in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}. | |
| @item arm_coproc4_ok | |
| ARM target supports all the coprocessor instructions also listed as supported | |
| in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}. | |
| @item arm_simd32_ok | |
| @anchor{arm_simd32_ok} | |
| ARM Target supports options suitable for accessing the SIMD32 intrinsics from | |
| @code{arm_acle.h}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_sat_ok | |
| @anchor{arm_sat_ok} | |
| ARM Target supports options suitable for accessing the saturation | |
| intrinsics from @code{arm_acle.h}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_dsp_ok | |
| @anchor{arm_dsp_ok} | |
| ARM Target supports options suitable for accessing the DSP intrinsics | |
| from @code{arm_acle.h}. | |
| Some multilibs may be incompatible with these options. | |
| @item arm_softfp_ok | |
| @anchor{arm_softfp_ok} | |
| ARM target supports the @code{-mfloat-abi=softfp} option. | |
| @item arm_hard_ok | |
| @anchor{arm_hard_ok} | |
| ARM target supports the @code{-mfloat-abi=hard} option. | |
| @item arm_mve | |
| @anchor{arm_mve} | |
| ARM target supports generating MVE instructions. | |
| @item arm_v8_1m_lob_hw | |
| @anchor{arm_v8_1m_lob_hw} | |
| ARM Target supports executing the Armv8.1-M Mainline Low Overhead Loop | |
| instructions @code{DLS} and @code{LE}. | |
| Some multilibs may be incompatible with these options. | |
| @item mbranch_protection_ok | |
| ARM target supporting @code{-mbranch-protection=standard}. | |
| @item arm_pacbti_hw | |
| Test system supports for executing non nop pacbti instructions. | |
| @item arm_mixed_fp | |
| On Arm targets, true when the target uses hardware instructions for | |
| single-precision floatint-point values, but software emulation for | |
| double-precision values. | |
| @end table | |
| @subsubsection AArch64-specific attributes | |
| @table @code | |
| @item aarch64_asm_<ext>_ok | |
| AArch64 assembler supports the architecture extension @code{ext} via the | |
| @code{.arch_extension} pseudo-op. | |
| @item aarch64_tiny | |
| AArch64 target which generates instruction sequences for tiny memory model. | |
| @item aarch64_small | |
| AArch64 target which generates instruction sequences for small memory model. | |
| @item aarch64_large | |
| AArch64 target which generates instruction sequences for large memory model. | |
| @item aarch64_little_endian | |
| AArch64 target which generates instruction sequences for little endian. | |
| @item aarch64_big_endian | |
| AArch64 target which generates instruction sequences for big endian. | |
| @item aarch64_mbig_endian | |
| AArch64 target supporting big endian code generation with @code{-mbig-endian}. | |
| @item aarch64_small_fpic | |
| Binutils installed on test system supports relocation types required by -fpic | |
| for AArch64 small memory model. | |
| @item aarch64_sme | |
| AArch64 target that generates instructions for SME. | |
| @item aarch64_sme2 | |
| AArch64 target that generates instructions for SME2. | |
| @item aarch64_lut_hw | |
| AArch64 target that is able to generate and execute LUT instructions. | |
| @item aarch64_sve_hw | |
| AArch64 target that is able to generate and execute SVE code (regardless of | |
| whether it does so by default). | |
| @item aarch64_sve128_hw | |
| @itemx aarch64_sve256_hw | |
| @itemx aarch64_sve512_hw | |
| @itemx aarch64_sve1024_hw | |
| @itemx aarch64_sve2048_hw | |
| Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length. | |
| @item aarch64_sve2_hw | |
| AArch64 target that is able to generate and execute SVE2 code (regardless of | |
| whether it does so by default). | |
| @item aarch64_sve2p1_hw | |
| AArch64 target that is able to generate and execute SVE2.1 code (regardless of | |
| whether it does so by default). | |
| @item aarch64_sme_hw | |
| AArch64 target that is able to generate and execute SME code (regardless of | |
| whether it does so by default). | |
| @item aarch64_fjcvtzs_hw | |
| AArch64 target that is able to generate and execute armv8.3-a FJCVTZS | |
| instruction. | |
| @end table | |
| @subsubsection LoongArch specific attributes | |
| @table @code | |
| @item loongarch_sx | |
| LoongArch target that generates instructions for SX. | |
| @item loongarch_asx | |
| LoongArch target that generates instructions for ASX. | |
| @item loongarch_sx_hw | |
| LoongArch target that is able to generate and execute SX code. | |
| @item loongarch_asx_hw | |
| LoongArch target that is able to generate and execute ASX code. | |
| @item loongarch_call36_support | |
| LoongArch binutils supports call36 relocation. | |
| @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_msa | |
| MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA). | |
| @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 MSP430-specific attributes | |
| @table @code | |
| @item msp430_small | |
| MSP430 target has the small memory model enabled (@code{-msmall}). | |
| @item msp430_large | |
| MSP430 target has the large memory model enabled (@code{-mlarge}). | |
| @end table | |
| @subsubsection nvptx-specific attributes | |
| @table @code | |
| @item nvptx_default_ptx_isa_version_at_least_6_0 | |
| nvptx code by default compiles for at least PTX ISA version 6.0. | |
| @item nvptx_runtime_alias_ptx | |
| The nvptx runtime environment supports the PTX ISA directive | |
| @code{.alias}. | |
| @item nvptx_runtime_alloca_ptx | |
| The nvptx runtime environment supports PTX 'alloca'. | |
| @item nvptx_softstack | |
| nvptx @option{-msoft-stack} is enabled. | |
| @end table | |
| @subsubsection PowerPC-specific attributes | |
| @table @code | |
| @item dfp_hw | |
| PowerPC target supports executing hardware DFP instructions. | |
| @item p8vector_hw | |
| PowerPC target supports executing VSX instructions (ISA 2.07). | |
| @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_eabi_ok | |
| PowerPC target supports @code{-meabi}. | |
| @item powerpc_elfv2 | |
| PowerPC target supports @code{-mabi=elfv2}. | |
| @item powerpc_fprs | |
| PowerPC target supports floating-point registers. | |
| @item powerpc_hard_double | |
| PowerPC target supports hardware double-precision floating-point. | |
| @item powerpc_htm_ok | |
| PowerPC target supports @code{-mhtm} | |
| @item powerpc_popcntb_ok | |
| PowerPC target supports the @code{popcntb} instruction, indicating | |
| that this target supports @code{-mcpu=power5}. | |
| @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 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 ppc_recip_hw | |
| PowerPC target supports executing reciprocal estimate instructions. | |
| @item vmx_hw | |
| PowerPC target supports executing AltiVec instructions. | |
| @item vsx_hw | |
| PowerPC target supports executing VSX instructions (ISA 2.06). | |
| @item has_arch_pwr5 | |
| PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu} | |
| setting is Power5 or later. | |
| @item has_arch_pwr6 | |
| PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu} | |
| setting is Power6 or later. | |
| @item has_arch_pwr7 | |
| PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu} | |
| setting is Power7 or later. | |
| @item has_arch_pwr8 | |
| PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu} | |
| setting is Power8 or later. | |
| @item has_arch_pwr9 | |
| PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu} | |
| setting is Power9 or later. | |
| @end table | |
| @subsubsection RISC-V specific attributes | |
| @table @code | |
| @item rv32 | |
| Test system has an integer register width of 32 bits. | |
| @item rv64 | |
| Test system has an integer register width of 64 bits. | |
| @item riscv_a | |
| Test target architecture has support for the A extension. | |
| @item riscv_b_ok | |
| Test target architecture can execute code with B extension enabled. | |
| @item riscv_v_ok | |
| Test target architecture can execute code with V extension enabled. | |
| @item riscv_zaamo | |
| Test target architecture has support for the zaamo extension. | |
| @item riscv_zabha | |
| Test target architecture has support for the zabha extension. | |
| @item riscv_zacas | |
| Test target architecture has support for the zacas extension. | |
| @item riscv_zalrsc | |
| Test target architecture has support for the zalrsc extension. | |
| @item riscv_zbc | |
| Test target architecture has support for the zbc extension. | |
| @item riscv_zbc_ok | |
| Test target architecture can execute code with zbc extension enabled. | |
| @item riscv_zbkb | |
| Test target architecture has support for the zbkb extension. | |
| @item riscv_zbkb_ok | |
| Test target architecture can execute code with zbkb extension enabled. | |
| @item riscv_zbkc | |
| Test target architecture has support for the zbkc extension. | |
| @item riscv_zbkc_ok | |
| Test target architecture can execute code with zbkc extension enabled. | |
| @item riscv_ztso | |
| Test target architecture has support for the ztso extension. | |
| @end table | |
| @subsubsection CORE-V specific attributes | |
| @table @code | |
| @item cv_mac | |
| Test system has support for the CORE-V MAC extension. | |
| @item cv_alu | |
| Test system has support for the CORE-V ALU extension. | |
| @item cv_elw | |
| Test system has support for the CORE-V ELW extension. | |
| @item cv_simd | |
| Test system has support for the CORE-V SIMD extension. | |
| @item cv_bi | |
| Test system has support for the CORE-V BI extension. | |
| @end table | |
| @subsubsection Other hardware attributes | |
| @c Please keep this table sorted alphabetically. | |
| @table @code | |
| @item autoincdec | |
| Target supports autoincrement/decrement addressing. | |
| @item acev1 | |
| Target supports the execution of @code{acev1} instructions. | |
| @item amx_avx512 | |
| Target supports the execution of @code{amx-avx512} instructions. | |
| @item amx_bf16 | |
| Target supports the execution of @code{amx-bf16} instructions. | |
| @item amx_complex | |
| Target supports the execution of @code{amx-complex} instructions. | |
| @item amx_fp16 | |
| Target supports the execution of @code{amx-fp16} instructions. | |
| @item amx_fp8 | |
| Target supports the execution of @code{amx-fp8} instructions. | |
| @item amx_int8 | |
| Target supports the execution of @code{amx-int8} instructions. | |
| @item amx_movrs | |
| Target supports the execution of @code{amx-movrs} instructions. | |
| @item amx_tile | |
| Target supports the execution of @code{amx-tile} instructions. | |
| @item avx | |
| Target supports compiling @code{avx} instructions. | |
| @item avx_runtime | |
| Target supports the execution of @code{avx} instructions. | |
| @item avx10v2aux | |
| Target supports the execution of @code{avx10v2aux} instructions. | |
| @item avx10v1aux | |
| Target supports the execution of @code{avx10v1aux} instructions. | |
| @item avx10.1 | |
| Target supports the execution of @code{avx10.1} instructions. | |
| @item avx10.2 | |
| Target supports the execution of @code{avx10.2} instructions. | |
| @item avx2 | |
| Target supports compiling @code{avx2} instructions. | |
| @item avx2_runtime | |
| Target supports the execution of @code{avx2} instructions. | |
| @item avxvnni | |
| Target supports the execution of @code{avxvnni} instructions. | |
| @item avx512f | |
| Target supports compiling @code{avx512f} instructions. | |
| @item avx512f_runtime | |
| Target supports the execution of @code{avx512f} instructions. | |
| @item avx512vp2intersect | |
| Target supports the execution of @code{avx512vp2intersect} instructions. | |
| @item avxifma | |
| Target supports the execution of @code{avxifma} instructions. | |
| @item avxneconvert | |
| Target supports the execution of @code{avxneconvert} instructions. | |
| @item avxvnniint8 | |
| Target supports the execution of @code{avxvnniint8} instructions. | |
| @item avxvnniint16 | |
| Target supports the execution of @code{avxvnniint16} instructions. | |
| @item can_deref_null | |
| Target runtime permits dereferencing a null pointer without trapping, for | |
| example because address zero is mapped and readable. | |
| @item cbcond_hw | |
| Test system can execute SPARC compare-and-branch (@code{cbcond}) | |
| instructions. | |
| @item cell_hw | |
| Test system can execute AltiVec and Cell PPU instructions. | |
| @item clz | |
| Target supports a clz optab on int. | |
| @item clzl | |
| Target supports a clz optab on long. | |
| @item clzll | |
| Target supports a clz optab on long long. | |
| @item clzsi | |
| Target has a @code{clzsi2} pattern, which can be an expander, so a | |
| @code{.CLZ} internal function call on a 32-bit unsigned integer can be | |
| expanded. | |
| @item ctz | |
| Target supports a ctz optab on int. | |
| @item ctzl | |
| Target supports a ctz optab on long. | |
| @item ctzll | |
| Target supports a ctz optab on long long. | |
| @item ctzsi | |
| Target has a @code{ctzsi2} pattern, which can be an expander, so a | |
| @code{.CTZ} internal function call on a 32-bit unsigned integer can be | |
| expanded. | |
| @item cmpccxadd | |
| Target supports the execution of @code{cmpccxadd} instructions. | |
| @item coldfire_fpu | |
| Target uses a ColdFire FPU. | |
| @item divmod | |
| Target supporting hardware divmod insn or divmod libcall. | |
| @item divmod_simode | |
| Target supporting hardware divmod insn or divmod libcall for SImode. | |
| @item hard_float | |
| Target supports FPU instructions. | |
| @item movrs | |
| Target supports the execution of @code{movrs} instructions. | |
| @item non_strict_align | |
| Target does not require strict alignment. | |
| @item opt_mstrict_align | |
| Target supports @option{-mstrict-align} and @option{-mno-strict-align}. | |
| @item pie_copyreloc | |
| The x86-64 target linker supports PIE with copy reloc. | |
| @item popcount | |
| Target supports a popcount optab on int. | |
| @item popcountl | |
| Target supports a popcount optab on long. | |
| @item popcountll | |
| Target supports a popcount optab on long long. | |
| @item prefetchi | |
| Target supports the execution of @code{prefetchi} instructions. | |
| @item raoint | |
| Target supports the execution of @code{raoint} instructions. | |
| @item rdrand | |
| Target supports x86 @code{rdrand} instruction. | |
| @item sha512 | |
| Target supports the execution of @code{sha512} instructions. | |
| @item sm3 | |
| Target supports the execution of @code{sm3} instructions. | |
| @item sm4 | |
| Target supports the execution of @code{sm4} instructions. | |
| @item sqrt_insn | |
| Target has a square root instruction that the compiler can generate. | |
| @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 user_msr | |
| Target supports the execution of @code{user_msr} instructions. | |
| @item vect_cmdline_needed | |
| Target requires a command line argument to enable a SIMD instruction set. | |
| @item x86 | |
| Target is ia32 or x86_64. | |
| @item xorsign | |
| Target supports the xorsign optab expansion. | |
| @item ifn_copysign | |
| Target supports the copysign optab expansion of float and double for | |
| both scalar and vector modes. | |
| @end table | |
| @subsubsection Environment attributes | |
| @table @code | |
| @item alarm | |
| Target supports @code{alarm}. | |
| @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 cfi | |
| Target supports DWARF CFI directives. | |
| @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 d_runtime | |
| Target provides the D runtime. | |
| @item d_runtime_has_std_library | |
| Target provides the D standard library (Phobos). | |
| @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 fenv | |
| Target provides @file{fenv.h} include file. | |
| @item fenv_exceptions | |
| Target supports @file{fenv.h} with all the standard IEEE exceptions | |
| and floating-point exceptions are raised by arithmetic operations. | |
| @item fenv_exceptions_dfp | |
| Target supports @file{fenv.h} with all the standard IEEE exceptions | |
| and floating-point exceptions are raised by arithmetic operations for | |
| decimal floating point. | |
| @item fileio | |
| Target offers such file I/O library functions as @code{fopen}, | |
| @code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time | |
| requirement for the presence of the functions in the library; even if | |
| they fail at runtime, the requirement is still regarded as satisfied. | |
| @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 hostedlib | |
| Target is not @samp{freestanding}, and, if the language is C++, | |
| @code{libstdc++}'s hosted mode is not disabled. | |
| @item gettimeofday | |
| Target supports @code{gettimeofday}. | |
| @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 mempcpy | |
| Target provides @code{mempcpy} function. | |
| @item mmap | |
| Target supports @code{mmap}. | |
| @item newlib | |
| Target supports Newlib. | |
| @item newlib_nano_io | |
| GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces | |
| the code size of Newlib formatted I/O functions. | |
| @item posix_memalign | |
| Target supports @code{posix_memalign}. | |
| @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 sleep | |
| Target supports @code{sleep}. | |
| @item sockets | |
| Target can compile using @code{sys/socket.h} with no errors or warnings. | |
| @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 signal | |
| Target has @code{signal.h}. | |
| @item stabs | |
| Target supports the stabs debugging format. | |
| @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 stdint_types_mbig_endian | |
| Target accepts the option @option{-mbig-endian} and @code{stdint.h} | |
| can be included without error when @option{-mbig-endian} is passed. | |
| @item stpcpy | |
| Target provides @code{stpcpy} function. | |
| @item strndup | |
| Target provides @code{strndup} function. | |
| @item sysconf | |
| Target supports @code{sysconf}. | |
| @item trampolines | |
| Target supports trampolines. | |
| @item variadic_mi_thunk | |
| Target supports C++ virtual variadic function calls with multiple inheritance. | |
| @item two_plus_gigs | |
| Target supports linking programs with 2+GiB of data. | |
| @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. | |
| @item weak_undefined | |
| Target supports weak undefined symbols | |
| @end table | |
| @subsubsection Other attributes | |
| @table @code | |
| @item asm_goto_with_outputs | |
| Target supports 'asm goto' with outputs. | |
| @item automatic_stack_alignment | |
| Target supports automatic stack alignment. | |
| @item branch_cost | |
| Target supports @option{-branch-cost=N}. | |
| @item checking | |
| Compiler has been configured with internal checking enabled. | |
| @item const_volatile_readonly_section | |
| Target places const volatile variables in readonly sections. | |
| @item cxa_atexit | |
| Target uses @code{__cxa_atexit}. | |
| @item default_packed | |
| @anchor{default_packed} | |
| Target has packed layout of structure members by default. | |
| @item exceptions | |
| Target supports exception handling. | |
| Note that this is orthogonal to effective-target @code{exceptions_enabled}. | |
| @item exceptions_enabled | |
| Testing configuration has exception handling enabled. | |
| Note that this is orthogonal to effective-target @code{exceptions}. | |
| @item using_sjlj_exceptions | |
| Target uses @code{setjmp} and @code{longjmp} for implementing exceptions. | |
| @item fgraphite | |
| Target supports Graphite optimizations. | |
| @item fixed_point | |
| Target supports fixed-point extension to C. | |
| @item bitint | |
| Target supports _BitInt(N). | |
| @item bitint128 | |
| Target supports _BitInt(128). | |
| @item bitint575 | |
| Target supports _BitInt(575). | |
| @item bitint65535 | |
| Target supports _BitInt(65535). | |
| @item fopenacc | |
| Target supports OpenACC via @option{-fopenacc}. | |
| @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 gld | |
| Target uses GNU @command{ld}. | |
| @item gnu_retain | |
| Target supports GNU retain. | |
| @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 ld_at_file | |
| Target supports GNU style response files. | |
| @item llvm_binutils | |
| Target is using an LLVM assembler and/or linker, instead of GNU Binutils. | |
| @item lra | |
| Target supports local register allocator (LRA). | |
| This must not be called (results in @code{ERROR}) for targets that | |
| don't do register allocation, and therefore neither use nor don't use | |
| LRA. | |
| @item lto | |
| Compiler has been configured to support link-time optimization (LTO). | |
| @item lto_incremental | |
| Compiler and linker support link-time optimization relocatable linking | |
| with @option{-r} and @option{-flto} options. | |
| @item thread_fence | |
| Target implements @code{__atomic_thread_fence} without relying on | |
| non-implemented @code{__sync_synchronize()}. | |
| @item naked_functions | |
| Target supports the @code{naked} function attribute. | |
| @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 tail_call | |
| Target supports tail-call optimizations. | |
| @item target_natural_alignment_64 | |
| Target uses natural alignment (aligned to type size) for types of | |
| 64 bits or less. | |
| @item no_alignment_constraints | |
| Target defines __BIGGEST_ALIGNMENT__=1. Hence target imposes | |
| no alignment constraints. This is similar, but not necessarily | |
| the same as @ref{default_packed}. Although @code{BIGGEST_FIELD_ALIGNMENT} | |
| defaults to @code{BIGGEST_ALIGNMENT} for most targets, it is possible | |
| for a target to set those two with different values and have different | |
| alignment constraints for aggregate and non-aggregate types. | |
| @item noinit | |
| Target supports the @code{noinit} variable attribute. | |
| @item nonpic | |
| Target does not generate PIC by default. | |
| @item offload_gcn | |
| Target has been configured for OpenACC/OpenMP offloading on AMD GCN. | |
| @item persistent | |
| Target supports the @code{persistent} variable attribute. | |
| @item pie_enabled | |
| Target generates PIE 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 pie | |
| Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}. | |
| @item linker_plugin | |
| Target supports the linker plugin. | |
| @item rdynamic | |
| Target supports @option{-rdynamic}. | |
| @item scalar_all_fma | |
| Target supports all four fused multiply-add optabs for both @code{float} | |
| and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab}, | |
| @code{fnma_optab} and @code{fnms_optab}. | |
| @item section_anchors | |
| Target supports section anchors. | |
| @item shared_jump_tables | |
| Target makes the copies of a loop switch dispatch that | |
| @option{-fduplicate-switch-dispatch} creates share one jump table, with the | |
| current multilib and test options. Use it only in test directives. | |
| @item shf_gnu_retain | |
| Target supports @code{SHF_GNU_RETAIN}. | |
| @item shf_link_order | |
| Target supports @code{SHF_LINK_ORDER}. | |
| @item short_enums | |
| Target defaults to short enums. | |
| @item sht_init_array | |
| Target supports @code{SHT_INIT_ARRAY} and @code{SHT_PREINIT_ARRAY} sections. | |
| @item solaris_as | |
| Target uses the Solaris @command{as}. | |
| @item solaris_ld | |
| Target uses the Solaris @command{ld}. | |
| @item stack_size | |
| @anchor{stack_size_et} | |
| Target has limited stack size. The stack size limit can be obtained using the | |
| STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature | |
| @code{stack_size}}. | |
| Note that for certain targets, stack size limits are relevant for | |
| execution only, and therefore considered only if @code{dg-do run} is | |
| in effect, otherwise unlimited. | |
| @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 strub | |
| Target supports attribute @code{strub} for stack scrubbing. | |
| @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 vma_equals_lma | |
| Target generates executable with VMA equal to LMA for .data section. | |
| @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}. | |
| @item comdat_group | |
| Target uses comdat groups. | |
| @item indirect_calls | |
| Target supports indirect calls, i.e. calls where the target is not | |
| constant. | |
| @item lgccjit | |
| Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests. | |
| @item __OPTIMIZE__ | |
| Optimizations are enabled (@code{__OPTIMIZE__}) per the current | |
| compiler flags. | |
| @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 mfentry | |
| Target supports the @code{-mfentry} option that alters the | |
| position of profiling calls such that they precede the prologue. | |
| @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.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_fp | |
| @code{__ARM_FP} definition. Only ARM targets support this feature, and only then | |
| in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target | |
| keyword}. | |
| @item arm_fp_dp | |
| @code{__ARM_FP} definition with double-precision support. Only ARM | |
| targets support this feature, and only then in certain modes; see the | |
| @ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}. | |
| @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_fp16 | |
| VFP half-precision floating point support. This does not select the | |
| FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or | |
| @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This | |
| feature is only supported by ARM targets and then only in certain | |
| modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target | |
| keyword}. | |
| @item arm_fp16_ieee | |
| @anchor{arm_fp16_ieee} | |
| ARM IEEE 754-2008 format VFP half-precision floating point support. | |
| This feature is only supported by ARM targets and then only in certain | |
| modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target | |
| keyword}. | |
| @item arm_fp16_alternative | |
| @anchor{arm_fp16_alternative} | |
| ARM Alternative format VFP half-precision floating point support. | |
| This feature is only supported by ARM targets and then only in certain | |
| modes; see the @ref{arm_fp16_ok,,arm_fp16_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_fp16_ok,,arm_neon_fp16_ok effective target keyword}. | |
| @item arm_vfp3 | |
| arm vfp3 floating point support; see | |
| the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}. | |
| @item arm_arch_v8a_hard | |
| Add options for ARMv8-A and the hard-float variant of the AAPCS, | |
| if this is supported by the compiler; see the | |
| @ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword. | |
| @item arm_v8_1a_neon | |
| Add options for ARMv8.1-A with Adv.SIMD support, if this is supported | |
| by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok} | |
| effective target keyword. | |
| @item arm_v8_2a_fp16_scalar | |
| Add options for ARMv8.2-A with scalar FP16 support, if this is | |
| supported by the target; see the | |
| @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective | |
| target keyword. | |
| @item arm_v8_2a_fp16_neon | |
| Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is | |
| supported by the target; see the | |
| @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target | |
| keyword. | |
| @item arm_v8_2a_dotprod_neon | |
| Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is | |
| supported by the target; see the | |
| @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword. | |
| @item arm_fp16fml_neon | |
| Add options to enable generation of the @code{VFMAL} and @code{VFMSL} | |
| instructions, if this is supported by the target; see the | |
| @ref{arm_fp16fml_neon_ok} effective target keyword. | |
| @item arm_dsp | |
| Add options for ARM DSP intrinsics support, if this is supported by | |
| the target; see the @ref{arm_dsp_ok,,arm_dsp_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 check_function_bodies | |
| Add the target-specific flags needed to use | |
| @code{check-function-bodies} from @code{dg-final}. | |
| These options are also added automatically by: | |
| @smallexample | |
| /* @{ dg-final @{ check-function-bodies @dots{} @} @dots{} @} */ | |
| @end smallexample | |
| @item float@var{n} | |
| Add the target-specific flags needed to use the @code{_Float@var{n}} type. | |
| @item float@var{n}x | |
| Add the target-specific flags needed to use the @code{_Float@var{n}x} type. | |
| @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 nvptx_alias_ptx | |
| Enable using the PTX ISA directive @code{.alias} on nvptx targets. | |
| @item nvptx_alloca_ptx | |
| Enable PTX 'alloca' on nvptx targets. | |
| @item riscv_a | |
| Add the 'A' extension to the -march string on RISC-V targets. | |
| @item riscv_zaamo | |
| Add the zaamo extension to the -march string on RISC-V targets. | |
| @item riscv_zabha | |
| Add the zabha extension to the -march string on RISC-V targets. | |
| @item riscv_zacas | |
| Add the zacas extension to the -march string on RISC-V targets. | |
| @item riscv_zalrsc | |
| Add the zalrsc extension to the -march string on RISC-V targets. | |
| @item riscv_ztso | |
| Add the ztso extension to the -march string on RISC-V targets. | |
| @item stack_size | |
| @anchor{stack_size_ao} | |
| Add the flags needed to define macro STACK_SIZE and set it to the stack size | |
| limit associated with the @ref{stack_size_et,,@code{stack_size} effective | |
| target}. | |
| @item sqrt_insn | |
| Add the target-specific flags needed to enable hardware square root | |
| instructions, if any. | |
| @item tls | |
| Add the target-specific flags needed to use thread-local storage. | |
| @item vect_early_break | |
| Add the target-specific flags needed to enable early break vectorization for | |
| a target, if any. This requires the target to have an implementation of the | |
| @code{cbranch} optab. | |
| @item weak_undefined | |
| Add the flags needed to enable support for weak undefined symbols. | |
| @end table | |
| @node Remove Options | |
| @subsection Features for @code{dg-remove-options} | |
| The supported values of @var{feature} for directive @code{dg-remove-options} | |
| are: | |
| @table @code | |
| @item riscv_a | |
| Remove the 'A' extension and all implied extensions from the -march string on | |
| RISC-V targets. | |
| @item riscv_zaamo | |
| Remove the zaamo extension from the -march string on RISC-V. If the 'A' | |
| extension is present downgrade it to zalrsc. | |
| @item riscv_zabha | |
| Remove the zabha extension and implied zaamo extension from the -march string | |
| on RISC-V. | |
| @item riscv_zacas | |
| Remove the zacas extension and implied zaamo extension from the -march string | |
| on RISC-V. | |
| @item riscv_zalrsc | |
| Remove the zalrsc extension from the -march string on RISC-V. If the 'A' | |
| extension is present downgrade it to zaamo. | |
| @item riscv_ztso | |
| Remove the ztso extension from the -march string on RISC-V targets. | |
| @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-stack-check @var{check} | |
| Skip the test if the target does not support the @code{-fstack-check} | |
| option. If @var{check} is @code{""}, support for @code{-fstack-check} | |
| is checked, for @code{-fstack-check=("@var{check}")} otherwise. | |
| @item dg-require-stack-size @var{size} | |
| Skip the test if the target does not support a stack size of @var{size}. | |
| @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-ascii-locale "" | |
| Skip the test if the host does not support an ASCII locale. | |
| @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-dot "" | |
| Skip the test if the host does not have @command{dot}. | |
| @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-linker-plugin "" | |
| Skip the test is the target does not support the linker plugin. | |
| This is equivalent to @code{dg-require-effective-target linker_plugin}. | |
| @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}. | |
| @item dg-check-dot @var{filename} | |
| Passes if @var{filename} is a valid @file{.dot} file (by running | |
| @code{dot -Tpng} on it, and verifying the exit code is 0). | |
| @item scan-sarif-file @var{regexp} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regexp} matches text in the file generated by | |
| @option{-fdiagnostics-format=sarif-file}. | |
| @item scan-sarif-file-not @var{regexp} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regexp} does not match text in the file generated by | |
| @option{-fdiagnostics-format=sarif-file}. | |
| @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, | |
| excluding LTO sections. | |
| @item scan-raw-assembler @var{regex} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regex} matches text in the test's assembler output, | |
| including LTO sections. | |
| @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regex} does not match text in the test's assembler output, | |
| excluding LTO sections. | |
| @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, excluding LTO sections. | |
| @item scan-assembler-bound @var{regex} @var{cmp} @var{num} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regex} is matched @var{cmp} @var{num} times in the test's | |
| assembler output, excluding LTO sections. @var{cmp} is a comparator. | |
| @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{regex} matches text in the test's demangled assembler output, | |
| excluding LTO sections. | |
| @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, excluding LTO sections. | |
| @item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{functions} are all in @var{section}. The caller needs to | |
| allow for @code{USER_LABEL_PREFIX} and different section name conventions. | |
| @item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}] | |
| Passes if @var{functions} are all in @var{section}in @var{filename}. | |
| The same caveats as for @code{scan-assembler-symbol-section} apply. | |
| @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. | |
| @item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @} [@var{matched}]]] | |
| Looks through the source file for comments that give the expected assembly | |
| output for selected functions. Each line of expected output starts with the | |
| prefix string @var{prefix} and the expected output for a function as a whole | |
| is followed by a line that starts with the string @var{terminator}. | |
| Specifying an empty terminator is equivalent to specifying @samp{"*/"}. | |
| @var{options}, if specified, is a list of regular expressions, each of | |
| which matches a full command-line option. A non-empty list prevents | |
| the test from running unless all of the given options are present on the | |
| command line. This can help if a source file is compiled both with | |
| and without optimization, since it is rarely useful to check the full | |
| function body for unoptimized code. | |
| The first line of the expected output for a function @var{fn} has the form: | |
| @smallexample | |
| @var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}] | |
| @end smallexample | |
| Subsequent lines of the expected output also start with @var{prefix}. | |
| In both cases, whitespace after @var{prefix} is not significant. | |
| Depending on the configuration (see | |
| @code{configure_check-function-bodies} in | |
| @file{gcc/testsuite/lib/scanasm.exp}), the test may discard from the | |
| compiler's assembly output directives such as @code{.cfi_startproc}, | |
| local label definitions such as @code{.LFB0}, and more. This behavior | |
| can be overridden using the optional @var{matched} argument, which | |
| specifies a regexp for lines that should not be discarded in this way. | |
| The test then matches the result against the expected | |
| output for a function as a single regular expression. This means that | |
| later lines can use backslashes to refer back to @samp{(@dots{})} | |
| captures on earlier lines. For example: | |
| @smallexample | |
| /* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */ | |
| @dots{} | |
| /* | |
| ** add_w0_s8_m: | |
| ** mov (z[0-9]+\.b), w0 | |
| ** add z0\.b, p0/m, z0\.b, \1 | |
| ** ret | |
| */ | |
| svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @} | |
| @dots{} | |
| /* | |
| ** add_b0_s8_m: | |
| ** mov (z[0-9]+\.b), b0 | |
| ** add z1\.b, p0/m, z1\.b, \1 | |
| ** ret | |
| */ | |
| svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @} | |
| @end smallexample | |
| checks whether the implementations of @code{add_w0_s8_m} and | |
| @code{add_b0_s8_m} match the regular expressions given. The test only | |
| runs when @samp{-DCHECK_ASM} is passed on the command line. | |
| It is possible to create non-capturing multi-line regular expression | |
| groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the | |
| @samp{(}, @samp{|} and @samp{)} on separate lines (each still using | |
| @var{prefix}). For example: | |
| @smallexample | |
| /* | |
| ** cmple_f16_tied: | |
| ** ( | |
| ** fcmge p0\.h, p0/z, z1\.h, z0\.h | |
| ** | | |
| ** fcmle p0\.h, p0/z, z0\.h, z1\.h | |
| ** ) | |
| ** ret | |
| */ | |
| svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @} | |
| @end smallexample | |
| checks whether @code{cmple_f16_tied} is implemented by the | |
| @code{fcmge} instruction followed by @code{ret} or by the | |
| @code{fcmle} instruction followed by @code{ret}. The test is | |
| still a single regular rexpression. | |
| A line containing just: | |
| @smallexample | |
| @var{prefix} ... | |
| @end smallexample | |
| stands for zero or more unmatched lines; the whitespace after | |
| @var{prefix} is again not significant. | |
| @code{check-function-bodies} automatically adds the same options as: | |
| @smallexample | |
| /* @{ dg-add-options check_function_bodies @} */ | |
| @end smallexample | |
| For this reason, @code{check-function-bodies} must come after the final | |
| @code{dg-options} directive. | |
| @end table | |
| @subsubsection Scan object metadata with readelf | |
| These commands inspect the linked test output file with @command{readelf}. | |
| They are mainly intended for LTO tests. | |
| These commands take a single @var{regex} and test whether it is present | |
| in (or absent from, for @samp{-not}) the corresponding @command{readelf} | |
| output. | |
| @table @code | |
| @item object-readelf-attributes @var{regex} [@{ target/xfail @var{selector} @}] | |
| Runs @command{readelf -A} and checks that @var{regex} matches. | |
| @item object-readelf-attributes-not @var{regex} [@{ target/xfail @var{selector} @}] | |
| Runs @command{readelf -A} and checks that @var{regex} does not match. | |
| @item object-readelf-notes @var{regex} [@{ target/xfail @var{selector} @}] | |
| Runs @command{readelf -n} and checks that @var{regex} matches. | |
| @item object-readelf-notes-not @var{regex} [@{ target/xfail @var{selector} @}] | |
| Runs @command{readelf -n} and checks that @var{regex} does not match. | |
| @end table | |
| @subsubsection Scan optimization dump files | |
| These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree}, | |
| @code{offload-tree}, @code{rtl}, @code{ltrans-rtl}, @code{offload-rtl}, | |
| @code{ipa}, @code{offload-ipa}, and @code{wpa-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 | |
| The @var{suffix} argument which describes the dump file to be scanned | |
| may contain a glob pattern that must expand to exactly one file | |
| name. This is useful if, e.g., different pass instances are executed | |
| depending on torture testing command-line flags, producing dump files | |
| whose names differ only in their pass instance number suffix. For | |
| example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for | |
| occurrences of the string ``code has been optimized'', use: | |
| @smallexample | |
| /* @{ dg-options "-fdump-tree-mypass" @} */ | |
| /* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */ | |
| @end smallexample | |
| The @code{offload-@dots{}} ones by default separately scan the dump | |
| file of each enabled offload target. | |
| You may use the @code{only_for_offload_target} wrapper to restrict the | |
| scanning to one specific offload target: | |
| @smallexample | |
| /* @{ dg-do link @{ target offload_target_amdgcn @} @} */ | |
| /* @{ dg-additional-options -foffload-options=-fdump-ipa-simdclone-details @} */ | |
| /* @{ dg-final @{ only_for_offload_target amdgcn-amdhsa scan-offload-ipa-dump @var{regex_amdgcn} simdclone @} @} */ | |
| @end smallexample | |
| This test case is active if GCN offload compilation is enabled (but | |
| potentially also additional offload targets). | |
| The @code{simdclone} IPA dump file is (potentially) produced for all | |
| offload targets, but only the GCN offload one is scanned. | |
| If a test case doesn't have a @samp{@{ target @var{selector} @}}, and | |
| you need to scan, for example, for different @var{regex}es for each of | |
| host and potentially several offload targets, use a pattern like this: | |
| @smallexample | |
| /* @{ dg-final @{ scan-tree-dump @var{regex_host} optimized @} @} | |
| @{ dg-final @{ only_for_offload_target amdgcn-amdhsa scan-offload-tree-dump @var{regex_amdgcn} optimized @{ target offload_target_amdgcn @} @} @} | |
| @{ dg-final @{ only_for_offload_target nvptx-none scan-offload-tree-dump @var{regex_nvptx} optimized @{ target offload_target_nvptx @} @} @} */ | |
| @end smallexample | |
| Here, unconditionally @var{regex_host} is scanned for in the host dump | |
| file. | |
| If GCN offloading compilation is actually enabled, @var{regex_amdgcn} | |
| is scanned for in the GCN offload compilation dump file. | |
| If nvptx offloading compilation is actually enabled, @var{regex_nvptx} | |
| is scanned for in the nvptx offload compilation dump file. | |
| @subsubsection Check for output files | |
| @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. | |
| @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] | |
| Passes if the pattern is present in the final executable. | |
| @item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}] | |
| Passes if the pattern is absent from 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. | |
| @item run-gcov-pytest @{ @var{sourcefile} @var{pytest_file} @} | |
| Check output of @command{gcov} intermediate format with a pytest | |
| script. | |
| @end table | |
| @subsubsection Clean up generated test files | |
| Usually the test-framework removes files that were generated during | |
| testing. If a testcase, for example, uses any dumping mechanism to | |
| inspect a passes dump file, the testsuite recognized the dump option | |
| passed to the tool and schedules a final cleanup to remove these files. | |
| There are, however, following additional cleanup directives that can be | |
| used to annotate a testcase "manually". | |
| @table @code | |
| @item cleanup-coverage-files | |
| Removes coverage data files generated for this test. | |
| @item cleanup-modules "@var{list-of-extra-modules}" | |
| Removes Fortran module files generated for this test, excluding the | |
| module names listed in keep-modules. | |
| Cleaning up module files is usually done automatically by the testsuite | |
| by looking at the source files and removing the modules after the test | |
| has been executed. | |
| @smallexample | |
| module MoD1 | |
| end module MoD1 | |
| module Mod2 | |
| end module Mod2 | |
| module moD3 | |
| end module moD3 | |
| module mod4 | |
| end module mod4 | |
| ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant | |
| ! @{ dg-final @{ keep-modules "mod3 mod4" @} @} | |
| @end smallexample | |
| @item keep-modules "@var{list-of-modules-not-to-delete}" | |
| Whitespace separated list of module names that should not be deleted by | |
| cleanup-modules. | |
| If the list of modules is empty, all modules defined in this file are kept. | |
| @smallexample | |
| module maybe_unneeded | |
| end module maybe_unneeded | |
| module keep1 | |
| end module keep1 | |
| module keep2 | |
| end module keep2 | |
| ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two | |
| ! @{ dg-final @{ keep-modules "" @} @} ! keep all | |
| @end smallexample | |
| @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}" | |
| Whitespace separated list of suffixes that should not be deleted | |
| automatically in a testcase that uses @option{-save-temps}. | |
| @smallexample | |
| // @{ dg-options "-save-temps -fpch-preprocess -I." @} | |
| int main() @{ return 0; @} | |
| // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file | |
| // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i | |
| // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o | |
| @end smallexample | |
| @item cleanup-profile-file | |
| Removes profiling files generated for this test. | |
| @end table | |
| @node Ada Tests | |
| @section Ada Language Testsuites | |
| The Ada testsuite includes executable tests from the ACATS | |
| testsuite, publicly available at | |
| @uref{http://www.ada-auth.org/acats.html}. | |
| 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. | |
| 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{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 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 ar-link | |
| Similar to @code{link}, but combine all but the first source file into | |
| an archive file before the final link. | |
| @item incr-link | |
| As with @code{ar-link}, but combine the files into an object file | |
| using incremental linking, rather than an archive file. This enables | |
| testing the incremental linking features of the LTO front end. | |
| @item run | |
| Produce and run an executable file, which is expected to return | |
| an exit code of 0. | |
| @end table | |
| The default is @code{run}. 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}. Every test file will be compiled and | |
| run once for each of these sets of options. Individual source files | |
| within a test may also use @code{dg-options} to specify additional | |
| options to include. | |
| @item @{ dg-lto-additional-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} | |
| This is similar to @code{dg-lto-options}, but rather than overriding | |
| @var{LTO_OPTIONS}, it appends the given options to each of the sets | |
| specified in @var{LTO_OPTIONS}. This can be used to add a given list | |
| of options to every compilation of all source files in the test, | |
| without otherwise changing which combinations of options are tested. | |
| @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 "--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 basic 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 | |
| The file @file{struct-layout-1.exp} provides a few more test cases | |
| exercising pseudo-randomly generated structure layouts. | |
| Defining @env{RUN_ALL_COMPAT_TESTS} would increase the number of | |
| generated tests to yield even more coverage. As an example, to modify | |
| the above test command to run the maximum number of ABI tests for C++, do: | |
| @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 struct-layout-1.exp" \ | |
| RUN_ALL_COMPAT_TESTS=1 | |
| @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 | |
| @node GIMPLE Tests | |
| @section Support for testing GIMPLE passes | |
| As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate | |
| that the function body will be GIMPLE, rather than C. The compiler requires | |
| the option @option{-fgimple} to enable this functionality. For example: | |
| @smallexample | |
| /* @{ dg-do compile @} */ | |
| /* @{ dg-options "-O -fgimple" @} */ | |
| void __GIMPLE (startwith ("dse2")) foo () | |
| @{ | |
| int a; | |
| bb_2: | |
| if (a > 4) | |
| goto bb_3; | |
| else | |
| goto bb_4; | |
| bb_3: | |
| a_2 = 10; | |
| goto bb_5; | |
| bb_4: | |
| a_3 = 20; | |
| bb_5: | |
| a_1 = __PHI (bb_3: a_2, bb_4: a_3); | |
| a_4 = a_1 + 4; | |
| return; | |
| @} | |
| @end smallexample | |
| The @code{startwith} argument indicates at which pass to begin. | |
| Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple}) | |
| to make tree dumps more closely follow the format accepted by the GIMPLE | |
| parser. | |
| Example DejaGnu tests of GIMPLE can be seen in the source tree at | |
| @file{gcc/testsuite/gcc.dg/gimplefe-*.c}. | |
| The @code{__GIMPLE} parser is integrated with the C tokenizer and | |
| preprocessor, so it should be possible to use macros to build out | |
| test coverage. | |
| @node RTL Tests | |
| @section Support for testing RTL passes | |
| As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the | |
| function body will be RTL, rather than C. For example: | |
| @smallexample | |
| double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b) | |
| @{ | |
| (function "test" | |
| [...snip; various directives go in here...] | |
| ) ;; function "test" | |
| @} | |
| @end smallexample | |
| The @code{startwith} argument indicates at which pass to begin. | |
| The parser expects the RTL body to be in the format emitted by this | |
| dumping function: | |
| @smallexample | |
| DEBUG_FUNCTION void | |
| print_rtx_function (FILE *outfile, function *fn, bool compact); | |
| @end smallexample | |
| when "compact" is true. So you can capture RTL in the correct format | |
| from the debugger using: | |
| @smallexample | |
| (gdb) print_rtx_function (stderr, cfun, true); | |
| @end smallexample | |
| and copy and paste the output into the body of the C function. | |
| Example DejaGnu tests of RTL can be seen in the source tree under | |
| @file{gcc/testsuite/gcc.dg/rtl}. | |
| The @code{__RTL} parser is not integrated with the C tokenizer or | |
| preprocessor, and works simply by reading the relevant lines within | |
| the braces. In particular, the RTL body must be on separate lines from | |
| the enclosing braces, and the preprocessor is not usable within it. |