1 @c Copyright (C) 2002-2021 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Source Tree Structure and Build System
8 This chapter describes the structure of the GCC source tree, and how
9 GCC is built. The user documentation for building and installing GCC
10 is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
11 which it is presumed that you are familiar.
14 * Configure Terms:: Configuration terminology and history.
15 * Top Level:: The top level source directory.
16 * gcc Directory:: The @file{gcc} subdirectory.
19 @include configterms.texi
22 @section Top Level Source Directory
24 The top level source directory in a GCC distribution contains several
25 files and directories that are shared with other software
26 distributions such as that of GNU Binutils. It also contains several
27 subdirectories that contain parts of GCC and its runtime libraries:
31 The Boehm conservative garbage collector, optionally used as part of
32 the ObjC runtime library when configured with @option{--enable-objc-gc}.
35 Autoconf macros and Makefile fragments used throughout the tree.
38 Contributed scripts that may be found useful in conjunction with GCC@.
39 One of these, @file{contrib/texi2pod.pl}, is used to generate man
40 pages from Texinfo manuals as part of the GCC build process.
43 The support for fixing system headers to work with GCC@. See
44 @file{fixincludes/README} for more information. The headers fixed by
45 this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
46 Along with those headers, @file{README-fixinc} is also installed, as
47 @file{@var{libsubdir}/include-fixed/README}.
50 The main sources of GCC itself (except for runtime libraries),
51 including optimizers, support for different target architectures,
52 language front ends, and testsuites. @xref{gcc Directory, , The
53 @file{gcc} Subdirectory}, for details.
56 Support tools for GNAT.
59 Headers for the @code{libiberty} library.
62 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
63 include it in @code{libc}.
66 The Ada runtime library.
69 The runtime support library for atomic operations (e.g.@: for @code{__sync}
73 The C preprocessor library.
76 The Decimal Float support library.
79 The @code{libffi} library, used as part of the Go runtime library.
82 The GCC runtime library.
85 The Fortran runtime library.
88 The Go runtime library. The bulk of this library is mirrored from the
89 @uref{https://github.com/@/golang/go, master Go repository}.
92 The GNU Offloading and Multi Processing Runtime Library.
95 The @code{libiberty} library, used for portability and for some
96 generally useful data structures and algorithms. @xref{Top, ,
97 Introduction, libiberty, @sc{gnu} libiberty}, for more information
101 The runtime support library for transactional memory.
104 The Objective-C and Objective-C++ runtime library.
107 The runtime support library for quad-precision math operations.
110 The D standard and runtime library. The bulk of this library is mirrored
111 from the @uref{https://github.com/@/dlang, master D repositories}.
114 The Stack protector runtime library.
117 The C++ runtime library.
120 Plugin used by the linker if link-time optimizations are enabled.
122 @item maintainer-scripts
123 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
126 The @code{zlib} compression library, used for compressing and
127 uncompressing GCC's intermediate language in LTO object files.
130 The build system in the top level directory, including how recursion
131 into subdirectories works and how building runtime libraries for
132 multilibs is handled, is documented in a separate manual, included
133 with GNU Binutils. @xref{Top, , GNU configure and build system,
134 configure, The GNU configure and build system}, for details.
137 @section The @file{gcc} Subdirectory
139 The @file{gcc} directory contains many files that are part of the C
140 sources of GCC, other files used as part of the configuration and
141 build process, and subdirectories including documentation and a
142 testsuite. The files that are sources of GCC are documented in a
143 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
146 * Subdirectories:: Subdirectories of @file{gcc}.
147 * Configuration:: The configuration process, and the files it uses.
148 * Build:: The build system in the @file{gcc} directory.
149 * Makefile:: Targets in @file{gcc/Makefile}.
150 * Library Files:: Library source files and headers under @file{gcc/}.
151 * Headers:: Headers installed by GCC.
152 * Documentation:: Building documentation in GCC.
153 * Front End:: Anatomy of a language front end.
154 * Back End:: Anatomy of a target back end.
158 @subsection Subdirectories of @file{gcc}
160 The @file{gcc} directory contains the following subdirectories:
164 Subdirectories for various languages. Directories containing a file
165 @file{config-lang.in} are language subdirectories. The contents of
166 the subdirectories @file{c} (for C), @file{cp} (for C++),
167 @file{objc} (for Objective-C), @file{objcp} (for Objective-C++),
168 and @file{lto} (for LTO) are documented in this
169 manual (@pxref{Passes, , Passes and Files of the Compiler});
170 those for other languages are not. @xref{Front End, ,
171 Anatomy of a Language Front End}, for details of the files in these
175 Source files shared between the compiler drivers (such as
176 @command{gcc}) and the compilers proper (such as @file{cc1}). If an
177 architecture defines target hooks shared between those places, it also
178 has a subdirectory in @file{common/config}. @xref{Target Structure}.
181 Configuration files for supported architectures and operating
182 systems. @xref{Back End, , Anatomy of a Target Back End}, for
183 details of the files in this directory.
186 Texinfo documentation for GCC, together with automatically generated
187 man pages and support for converting the installation manual to
188 HTML@. @xref{Documentation}.
191 System headers installed by GCC, mainly those required by the C
192 standard of freestanding implementations. @xref{Headers, , Headers
193 Installed by GCC}, for details of when these and other headers are
197 Message catalogs with translations of messages produced by GCC into
198 various languages, @file{@var{language}.po}. This directory also
199 contains @file{gcc.pot}, the template for these message catalogues,
200 @file{exgettext}, a wrapper around @command{gettext} to extract the
201 messages from the GCC sources and create @file{gcc.pot}, which is run
202 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
203 which messages should not be extracted.
206 The GCC testsuites (except for those for runtime libraries).
211 @subsection Configuration in the @file{gcc} Directory
213 The @file{gcc} directory is configured with an Autoconf-generated
214 script @file{configure}. The @file{configure} script is generated
215 from @file{configure.ac} and @file{aclocal.m4}. From the files
216 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
217 file @file{config.in}. The file @file{cstamp-h.in} is used as a
221 * Config Fragments:: Scripts used by @file{configure}.
222 * System Config:: The @file{config.build}, @file{config.host}, and
223 @file{config.gcc} files.
224 * Configuration Files:: Files created by running @file{configure}.
227 @node Config Fragments
228 @subsubsection Scripts Used by @file{configure}
230 @file{configure} uses some other scripts to help in its work:
233 @item The standard GNU @file{config.sub} and @file{config.guess}
234 files, kept in the top level directory, are used.
236 @item The file @file{config.gcc} is used to handle configuration
237 specific to the particular target machine. The file
238 @file{config.build} is used to handle configuration specific to the
239 particular build machine. The file @file{config.host} is used to handle
240 configuration specific to the particular host machine. (In general,
241 these should only be used for features that cannot reasonably be tested in
242 Autoconf feature tests.)
243 @xref{System Config, , The @file{config.build}; @file{config.host};
244 and @file{config.gcc} Files}, for details of the contents of these files.
246 @item Each language subdirectory has a file
247 @file{@var{language}/config-lang.in} that is used for
248 front-end-specific configuration. @xref{Front End Config, , The Front
249 End @file{config-lang.in} File}, for details of this file.
251 @item A helper script @file{configure.frag} is used as part of
252 creating the output of @file{configure}.
256 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
258 The @file{config.build} file contains specific rules for particular systems
259 which GCC is built on. This should be used as rarely as possible, as the
260 behavior of the build system can always be detected by autoconf.
262 The @file{config.host} file contains specific rules for particular systems
263 which GCC will run on. This is rarely needed.
265 The @file{config.gcc} file contains specific rules for particular systems
266 which GCC will generate code for. This is usually needed.
268 Each file has a list of the shell variables it sets, with descriptions, at the
271 FIXME: document the contents of these files, and what variables should
272 be set to control build, host and target configuration.
274 @include configfiles.texi
277 @subsection Build System in the @file{gcc} Directory
279 FIXME: describe the build system, including what is built in what
280 stages. Also list the various source files that are used in the build
281 process but aren't source files of GCC itself and so aren't documented
282 below (@pxref{Passes}).
284 @include makefile.texi
287 @subsection Library Source Files and Headers under the @file{gcc} Directory
289 FIXME: list here, with explanation, all the C source files and headers
290 under the @file{gcc} directory that aren't built into the GCC
291 executable but rather are part of runtime libraries and object files,
292 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
293 Headers Installed by GCC}, for more information about the
294 @file{ginclude} directory.
297 @subsection Headers Installed by GCC
299 In general, GCC expects the system C library to provide most of the
300 headers to be used with it. However, GCC will fix those headers if
301 necessary to make them work with GCC, and will install some headers
302 required of freestanding implementations. These headers are installed
303 in @file{@var{libsubdir}/include}. Headers for non-C runtime
304 libraries are also installed by GCC; these are not documented here.
305 (FIXME: document them somewhere.)
307 Several of the headers GCC installs are in the @file{ginclude}
308 directory. These headers, @file{iso646.h},
309 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
310 are installed in @file{@var{libsubdir}/include},
311 unless the target Makefile fragment (@pxref{Target Fragment})
312 overrides this by setting @code{USER_H}.
314 In addition to these headers and those generated by fixing system
315 headers to work with GCC, some other headers may also be installed in
316 @file{@var{libsubdir}/include}. @file{config.gcc} may set
317 @code{extra_headers}; this specifies additional headers under
318 @file{config} to be installed on some systems.
320 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
321 This is done to cope with command-line options that change the
322 representation of floating point numbers.
324 GCC also installs its own version of @code{<limits.h>}; this is generated
325 from @file{glimits.h}, together with @file{limitx.h} and
326 @file{limity.h} if the system also has its own version of
327 @code{<limits.h>}. (GCC provides its own header because it is
328 required of ISO C freestanding implementations, but needs to include
329 the system header from its own header as well because other standards
330 such as POSIX specify additional values to be defined in
331 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
332 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
333 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
334 needs fixing, @file{syslimits.h} is the fixed copy.
336 GCC can also install @code{<tgmath.h>}. It will do this when
337 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
340 @subsection Building Documentation
342 The main GCC documentation is in the form of manuals in Texinfo
343 format. These are installed in Info format; DVI versions may be
344 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
345 HTML versions by @samp{make html}. In addition, some man pages are
346 generated from the Texinfo manuals, there are some other text files
347 with miscellaneous documentation, and runtime libraries have their own
348 documentation outside the @file{gcc} directory. FIXME: document the
349 documentation for runtime libraries somewhere.
352 * Texinfo Manuals:: GCC manuals in Texinfo format.
353 * Man Page Generation:: Generating man pages from Texinfo manuals.
354 * Miscellaneous Docs:: Miscellaneous text files with documentation.
357 @node Texinfo Manuals
358 @subsubsection Texinfo Manuals
360 The manuals for GCC as a whole, and the C and C++ front ends, are in
361 files @file{doc/*.texi}. Other front ends have their own manuals in
362 files @file{@var{language}/*.texi}. Common files
363 @file{doc/include/*.texi} are provided which may be included in
364 multiple manuals; the following files are in @file{doc/include}:
368 The GNU Free Documentation License.
370 The section ``Funding Free Software''.
371 @item gcc-common.texi
372 Common definitions for manuals.
374 The GNU General Public License.
376 A copy of @file{texinfo.tex} known to work with the GCC manuals.
379 DVI-formatted manuals are generated by @samp{make dvi}, which uses
380 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
381 PDF-formatted manuals are generated by @samp{make pdf}, which uses
382 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
383 formatted manuals are generated by @samp{make html}. Info
384 manuals are generated by @samp{make info} (which is run as part of
385 a bootstrap); this generates the manuals in the source directory,
386 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
387 and they are included in release distributions.
389 Manuals are also provided on the GCC web site, in both HTML and
390 PostScript forms. This is done via the script
391 @file{maintainer-scripts/update_web_docs_git}. Each manual to be
392 provided online must be listed in the definition of @code{MANUALS} in
393 that file; a file @file{@var{name}.texi} must only appear once in the
394 source tree, and the output manual must have the same name as the
395 source file. (However, other Texinfo files, included in manuals but
396 not themselves the root files of manuals, may have names that appear
397 more than once in the source tree.) The manual file
398 @file{@var{name}.texi} should only include other files in its own
399 directory or in @file{doc/include}. HTML manuals will be generated by
400 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
401 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
402 All Texinfo files that are parts of manuals must
403 be version-controlled, even if they are generated files, for the
404 generation of online manuals to work.
406 The installation manual, @file{doc/install.texi}, is also provided on
407 the GCC web site. The HTML version is generated by the script
408 @file{doc/install.texi2html}.
410 @node Man Page Generation
411 @subsubsection Man Page Generation
413 Because of user demand, in addition to full Texinfo manuals, man pages
414 are provided which contain extracts from those manuals. These man
415 pages are generated from the Texinfo manuals using
416 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
417 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
418 to @file{gcc.1}, but all the other man pages are generated from
421 Because many systems may not have the necessary tools installed to
422 generate the man pages, they are only generated if the
423 @file{configure} script detects that recent enough tools are
424 installed, and the Makefiles allow generating man pages to fail
425 without aborting the build. Man pages are also included in release
426 distributions. They are generated in the source directory.
428 Magic comments in Texinfo files starting @samp{@@c man} control what
429 parts of a Texinfo file go into a man page. Only a subset of Texinfo
430 is supported by @file{texi2pod.pl}, and it may be necessary to add
431 support for more Texinfo features to this script when generating new
432 man pages. To improve the man page output, some special Texinfo
433 macros are provided in @file{doc/include/gcc-common.texi} which
434 @file{texi2pod.pl} understands:
438 Use in the form @samp{@@table @@gcctabopt} for tables of options,
439 where for printed output the effect of @samp{@@code} is better than
440 that of @samp{@@option} but for man page output a different effect is
443 Use for summary lists of options in manuals.
445 Use at the end of each line inside @samp{@@gccoptlist}. This is
446 necessary to avoid problems with differences in how the
447 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
450 FIXME: describe the @file{texi2pod.pl} input language and magic
451 comments in more detail.
453 @node Miscellaneous Docs
454 @subsubsection Miscellaneous Documentation
456 In addition to the formal documentation that is installed by GCC,
457 there are several other text files in the @file{gcc} subdirectory
458 with miscellaneous documentation:
462 Notes on GCC's Native Language Support. FIXME: this should be part of
463 this manual rather than a separate file.
465 Notes on the Free Translation Project.
468 The GNU General Public License, Versions 2 and 3.
471 The GNU Lesser General Public License, Versions 2.1 and 3.
474 Change log files for various parts of GCC@.
476 Details of a few changes to the GCC front-end interface. FIXME: the
477 information in this file should be part of general documentation of
478 the front-end interface in this manual.
480 Information about new features in old versions of GCC@. (For recent
481 versions, the information is on the GCC web site.)
482 @item README.Portability
483 Information about portability issues when writing code in GCC@. FIXME:
484 why isn't this part of this manual or of the GCC Coding Conventions?
487 FIXME: document such files in subdirectories, at least @file{config},
488 @file{c}, @file{cp}, @file{objc}, @file{testsuite}.
491 @subsection Anatomy of a Language Front End
493 A front end for a language in GCC has the following parts:
497 A directory @file{@var{language}} under @file{gcc} containing source
498 files for that front end. @xref{Front End Directory, , The Front End
499 @file{@var{language}} Directory}, for details.
501 A mention of the language in the list of supported languages in
502 @file{gcc/doc/install.texi}.
504 A mention of the name under which the language's runtime library is
505 recognized by @option{--enable-shared=@var{package}} in the
506 documentation of that option in @file{gcc/doc/install.texi}.
508 A mention of any special prerequisites for building the front end in
509 the documentation of prerequisites in @file{gcc/doc/install.texi}.
511 Details of contributors to that front end in
512 @file{gcc/doc/contrib.texi}. If the details are in that front end's
513 own manual then there should be a link to that manual's list in
516 Information about support for that language in
517 @file{gcc/doc/frontends.texi}.
519 Information about standards for that language, and the front end's
520 support for them, in @file{gcc/doc/standards.texi}. This may be a
521 link to such information in the front end's own manual.
523 Details of source file suffixes for that language and @option{-x
524 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
526 Entries in @code{default_compilers} in @file{gcc.c} for source file
527 suffixes for that language.
529 Preferably testsuites, which may be under @file{gcc/testsuite} or
530 runtime library directories. FIXME: document somewhere how to write
533 Probably a runtime library for the language, outside the @file{gcc}
534 directory. FIXME: document this further.
536 Details of the directories of any runtime libraries in
537 @file{gcc/doc/sourcebuild.texi}.
539 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
540 to check just the compiler or the compiler and runtime library for the
544 If the front end is added to the official GCC source repository, the
545 following are also necessary:
549 At least one Bugzilla component for bugs in that front end and runtime
550 libraries. This category needs to be added to the Bugzilla database.
552 Normally, one or more maintainers of that front end listed in
555 Mentions on the GCC web site in @file{index.html} and
556 @file{frontends.html}, with any relevant links on
557 @file{readings.html}. (Front ends that are not an official part of
558 GCC may also be listed on @file{frontends.html}, with relevant links.)
560 A news item on @file{index.html}, and possibly an announcement on the
561 @email{gcc-announce@@gcc.gnu.org} mailing list.
563 The front end's manuals should be mentioned in
564 @file{maintainer-scripts/update_web_docs_git} (@pxref{Texinfo Manuals})
565 and the online manuals should be linked to from
566 @file{onlinedocs/index.html}.
568 Any old releases or CVS repositories of the front end, before its
569 inclusion in GCC, should be made available on the GCC web site at
570 @uref{https://gcc.gnu.org/pub/gcc/old-releases/}.
572 The release and snapshot script @file{maintainer-scripts/gcc_release}
573 should be updated to generate appropriate tarballs for this front end.
575 If this front end includes its own version files that include the
576 current date, @file{maintainer-scripts/update_version} should be
581 * Front End Directory:: The front end @file{@var{language}} directory.
582 * Front End Config:: The front end @file{config-lang.in} file.
583 * Front End Makefile:: The front end @file{Make-lang.in} file.
586 @node Front End Directory
587 @subsubsection The Front End @file{@var{language}} Directory
589 A front end @file{@var{language}} directory contains the source files
590 of that front end (but not of any runtime libraries, which should be
591 outside the @file{gcc} directory). This includes documentation, and
592 possibly some subsidiary programs built alongside the front end.
593 Certain files are special and other parts of the compiler depend on
598 This file is required in all language subdirectories. @xref{Front End
599 Config, , The Front End @file{config-lang.in} File}, for details of
602 This file is required in all language subdirectories. @xref{Front End
603 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
606 This file registers the set of switches that the front end accepts on
607 the command line, and their @option{--help} text. @xref{Options}.
609 This file provides entries for @code{default_compilers} in
610 @file{gcc.c} which override the default of giving an error that a
611 compiler for that language is not installed.
612 @item @var{language}-tree.def
613 This file, which need not exist, defines any language-specific tree
617 @node Front End Config
618 @subsubsection The Front End @file{config-lang.in} File
620 Each language subdirectory contains a @file{config-lang.in} file.
621 This file is a shell script that may define some variables describing
626 This definition must be present, and gives the name of the language
627 for some purposes such as arguments to @option{--enable-languages}.
629 If defined, this variable lists (space-separated) language front ends
630 other than C that this front end requires to be enabled (with the
631 names given being their @code{language} settings). For example, the
632 Obj-C++ front end depends on the C++ and ObjC front ends, so sets
633 @samp{lang_requires="objc c++"}.
634 @item subdir_requires
635 If defined, this variable lists (space-separated) front end directories
636 other than C that this front end requires to be present. For example,
637 the Objective-C++ front end uses source files from the C++ and
638 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
640 If defined, this variable lists (space-separated) targets in the top
641 level @file{Makefile} to build the runtime libraries for this
642 language, such as @code{target-libobjc}.
644 If defined, this variable lists (space-separated) top level
645 directories (parallel to @file{gcc}), apart from the runtime libraries,
646 that should not be configured if this front end is not built.
647 @item build_by_default
648 If defined to @samp{no}, this language front end is not built unless
649 enabled in a @option{--enable-languages} argument. Otherwise, front
650 ends are built by default, subject to any special logic in
651 @file{configure.ac} (as is present to disable the Ada front end if the
652 Ada compiler is not already installed).
654 If defined to @samp{yes}, this front end is built in stage1 of the
655 bootstrap. This is only relevant to front ends written in their own
658 If defined, a space-separated list of compiler executables that will
659 be run by the driver. The names here will each end
660 with @samp{\$(exeext)}.
662 If defined, a space-separated list of files that should be generated
663 by @file{configure} substituting values in them. This mechanism can
664 be used to create a file @file{@var{language}/Makefile} from
665 @file{@var{language}/Makefile.in}, but this is deprecated, building
666 everything from the single @file{gcc/Makefile} is preferred.
668 If defined, a space-separated list of files that should be scanned by
669 @file{gengtype.c} to generate the garbage collection tables and routines for
670 this language. This excludes the files that are common to all front
671 ends. @xref{Type Information}.
675 @node Front End Makefile
676 @subsubsection The Front End @file{Make-lang.in} File
678 Each language subdirectory contains a @file{Make-lang.in} file. It contains
679 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
680 setting of @code{language} in @file{config-lang.in}) for the following
681 values of @code{@var{hook}}, and any other Makefile rules required to
682 build those targets (which may if necessary use other Makefiles
683 specified in @code{outputs} in @file{config-lang.in}, although this is
684 deprecated). It also adds any testsuite targets that can use the
685 standard rule in @file{gcc/Makefile.in} to the variable
692 FIXME: exactly what goes in each of these targets?
694 Build an @command{etags} @file{TAGS} file in the language subdirectory
697 Build info documentation for the front end, in the build directory.
698 This target is only called by @samp{make bootstrap} if a suitable
699 version of @command{makeinfo} is available, so does not need to check
700 for this, and should fail if an error occurs.
702 Build DVI documentation for the front end, in the build directory.
703 This should be done using @code{$(TEXI2DVI)}, with appropriate
704 @option{-I} arguments pointing to directories of included files.
706 Build PDF documentation for the front end, in the build directory.
707 This should be done using @code{$(TEXI2PDF)}, with appropriate
708 @option{-I} arguments pointing to directories of included files.
710 Build HTML documentation for the front end, in the build directory.
712 Build generated man pages for the front end from Texinfo manuals
713 (@pxref{Man Page Generation}), in the build directory. This target
714 is only called if the necessary tools are available, but should ignore
715 errors so as not to stop the build if errors occur; man pages are
716 optional and the tools involved may be installed in a broken way.
718 Install everything that is part of the front end, apart from the
719 compiler executables listed in @code{compilers} in
720 @file{config-lang.in}.
722 Install info documentation for the front end, if it is present in the
723 source directory. This target should have dependencies on info files
724 that should be installed.
726 Install man pages for the front end. This target should ignore
729 Install headers needed for plugins.
731 Copies its dependencies into the source directory. This generally should
732 be used for generated files such as Bison output files which are not
733 version-controlled, but should be included in any release tarballs. This
734 target will be executed during a bootstrap if
735 @samp{--enable-generated-files-in-srcdir} was specified as a
736 @file{configure} option.
739 Copies its dependencies into the source directory. These targets will be
740 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
741 was specified as a @file{configure} option.
743 Uninstall files installed by installing the compiler. This is
744 currently documented not to be supported, so the hook need not do
749 @itemx maintainer-clean
750 The language parts of the standard GNU
751 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
752 Users, standards, GNU Coding Standards}, for details of the standard
753 targets. For GCC, @code{maintainer-clean} should delete
754 all generated files in the source directory that are not version-controlled,
755 but should not delete anything that is.
758 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
759 to a list of host object files that are used by that language.
762 @subsection Anatomy of a Target Back End
764 A back end for a target architecture in GCC has the following parts:
768 A directory @file{@var{machine}} under @file{gcc/config}, containing a
769 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
770 , Machine Descriptions}), header files @file{@var{machine}.h} and
771 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
772 (@pxref{Target Macros, , Target Description Macros and Functions}),
773 possibly a target Makefile fragment @file{t-@var{machine}}
774 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
775 some other files. The names of these files may be changed from the
776 defaults given by explicit specifications in @file{config.gcc}.
778 If necessary, a file @file{@var{machine}-modes.def} in the
779 @file{@var{machine}} directory, containing additional machine modes to
780 represent condition codes. @xref{Condition Code}, for further details.
782 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
783 directory, containing a list of target-specific options. You can also
784 add other option files using the @code{extra_options} variable in
785 @file{config.gcc}. @xref{Options}.
787 Entries in @file{config.gcc} (@pxref{System Config, , The
788 @file{config.gcc} File}) for the systems with this target
791 Documentation in @file{gcc/doc/invoke.texi} for any command-line
792 options supported by this target (@pxref{Run-time Target, , Run-time
793 Target Specification}). This means both entries in the summary table
794 of options and details of the individual options.
796 Documentation in @file{gcc/doc/extend.texi} for any target-specific
797 attributes supported (@pxref{Target Attributes, , Defining
798 target-specific uses of @code{__attribute__}}), including where the
799 same attribute is already supported on some targets, which are
800 enumerated in the manual.
802 Documentation in @file{gcc/doc/extend.texi} for any target-specific
805 Documentation in @file{gcc/doc/extend.texi} of any target-specific
806 built-in functions supported.
808 Documentation in @file{gcc/doc/extend.texi} of any target-specific
809 format checking styles supported.
811 Documentation in @file{gcc/doc/md.texi} of any target-specific
812 constraint letters (@pxref{Machine Constraints, , Constraints for
813 Particular Machines}).
815 A note in @file{gcc/doc/contrib.texi} under the person or people who
816 contributed the target support.
818 Entries in @file{gcc/doc/install.texi} for all target triplets
819 supported with this target architecture, giving details of any special
820 notes about installation for this target, or saying that there are no
821 special notes if there are none.
823 Possibly other support outside the @file{gcc} directory for runtime
824 libraries. FIXME: reference docs for this. The @code{libstdc++} porting
825 manual needs to be installed as info for this to work, or to be a
826 chapter of this manual.
829 The @file{@var{machine}.h} header is included very early in GCC's
830 standard sequence of header files, while @file{@var{machine}-protos.h}
831 is included late in the sequence. Thus @file{@var{machine}-protos.h}
832 can include declarations referencing types that are not defined when
833 @file{@var{machine}.h} is included, specifically including those from
834 @file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not
835 be available in every context where @file{@var{machine}-protos.h} is
836 included, in this file you should guard declarations using these types
837 inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE}
838 conditional code segments.
840 If the backend uses shared data structures that require @code{GTY} markers
841 for garbage collection (@pxref{Type Information}), you must declare those
842 in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}.
843 Any definitions required for building libgcc must also go in
844 @file{@var{machine}.h}.
846 GCC uses the macro @code{IN_TARGET_CODE} to distinguish between
847 machine-specific @file{.c} and @file{.cc} files and
848 machine-independent @file{.c} and @file{.cc} files. Machine-specific
849 files should use the directive:
852 #define IN_TARGET_CODE 1
855 before including @code{config.h}.
857 If the back end is added to the official GCC source repository, the
858 following are also necessary:
862 An entry for the target architecture in @file{readings.html} on the
863 GCC web site, with any relevant links.
865 Details of the properties of the back end and target architecture in
866 @file{backends.html} on the GCC web site.
868 A news item about the contribution of support for that target
869 architecture, in @file{index.html} on the GCC web site.
871 Normally, one or more maintainers of that target listed in
872 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
873 but it would be unusual to add support for a target that does not have
874 a maintainer when support is added.
876 Target triplets covering all @file{config.gcc} stanzas for the target,
877 in the list in @file{contrib/config-list.mk}.
883 GCC contains several testsuites to help maintain compiler quality.
884 Most of the runtime libraries and language front ends in GCC have
885 testsuites. Currently only the C language testsuites are documented
886 here; FIXME: document the others.
889 * Test Idioms:: Idioms used in testsuite code.
890 * Test Directives:: Directives used within DejaGnu tests.
891 * Ada Tests:: The Ada language testsuites.
892 * C Tests:: The C language testsuites.
893 * LTO Testing:: Support for testing link-time optimizations.
894 * gcov Testing:: Support for testing gcov.
895 * profopt Testing:: Support for testing profile-directed optimizations.
896 * compat Testing:: Support for testing binary compatibility.
897 * Torture Tests:: Support for torture testing using multiple options.
898 * GIMPLE Tests:: Support for testing GIMPLE passes.
899 * RTL Tests:: Support for testing RTL passes.
903 @section Idioms Used in Testsuite Code
905 In general, C testcases have a trailing @file{-@var{n}.c}, starting
906 with @file{-1.c}, in case other testcases with similar names are added
907 later. If the test is a test of some well-defined feature, it should
908 have a name referring to that feature such as
909 @file{@var{feature}-1.c}. If it does not test a well-defined feature
910 but just happens to exercise a bug somewhere in the compiler, and a
911 bug report has been filed for this bug in the GCC bug database,
912 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
913 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
914 and previously more generally, test cases are named after the date on
915 which they were added. This allows people to tell at a glance whether
916 a test failure is because of a recently found bug that has not yet
917 been fixed, or whether it may be a regression, but does not give any
918 other information about the bug or where discussion of it may be
919 found. Some other language testsuites follow similar conventions.
921 In the @file{gcc.dg} testsuite, it is often necessary to test that an
922 error is indeed a hard error and not just a warning---for example,
923 where it is a constraint violation in the C standard, which must
924 become an error with @option{-pedantic-errors}. The following idiom,
925 where the first line shown is line @var{line} of the file and the line
926 that generates the error, is used for this:
929 /* @{ dg-bogus "warning" "warning in place of error" @} */
930 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
933 It may be necessary to check that an expression is an integer constant
934 expression and has a certain value. To check that @code{@var{E}} has
935 value @code{@var{V}}, an idiom similar to the following is used:
938 char x[((E) == (V) ? 1 : -1)];
941 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
942 assertions about the types of expressions. See, for example,
943 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
944 exact rules for the types of conditional expressions in the C
945 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
947 It is useful to be able to test that optimizations are being made
948 properly. This cannot be done in all cases, but it can be done where
949 the optimization will lead to code being optimized away (for example,
950 where flow analysis or alias analysis should show that certain code
951 cannot be called) or to functions not being called because they have
952 been expanded as built-in functions. Such tests go in
953 @file{gcc.c-torture/execute}. Where code should be optimized away, a
954 call to a nonexistent function such as @code{link_failure ()} may be
955 inserted; a definition
968 will also be needed so that linking still succeeds when the test is
969 run without optimization. When all calls to a built-in function
970 should have been optimized and no calls to the non-built-in version of
971 the function should remain, that function may be defined as
972 @code{static} to call @code{abort ()} (although redeclaring a function
973 as static may not work on all targets).
975 All testcases must be portable. Target-specific testcases must have
976 appropriate code to avoid causing failures on unsupported systems;
977 unfortunately, the mechanisms for this differ by directory.
979 FIXME: discuss non-C testsuites here.
981 @node Test Directives
982 @section Directives used within DejaGnu tests
985 * Directives:: Syntax and descriptions of test directives.
986 * Selectors:: Selecting targets to which a test applies.
987 * Effective-Target Keywords:: Keywords describing target attributes.
988 * Add Options:: Features for @code{dg-add-options}
989 * Require Support:: Variants of @code{dg-require-@var{support}}
990 * Final Actions:: Commands for use in @code{dg-final}
994 @subsection Syntax and Descriptions of test directives
996 Test directives appear within comments in a test source file and begin
997 with @code{dg-}. Some of these are defined within DejaGnu and others
998 are local to the GCC testsuite.
1000 The order in which test directives appear in a test can be important:
1001 directives local to GCC sometimes override information used by the
1002 DejaGnu directives, which know nothing about the GCC directives, so the
1003 DejaGnu directives must precede GCC directives.
1005 Several test directives include selectors (@pxref{Selectors, , })
1006 which are usually preceded by the keyword @code{target} or @code{xfail}.
1008 @subsubsection Specify how to build the test
1011 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
1012 @var{do-what-keyword} specifies how the test is compiled and whether
1013 it is executed. It is one of:
1017 Compile with @option{-E} to run only the preprocessor.
1019 Compile with @option{-S} to produce an assembly code file.
1021 Compile with @option{-c} to produce a relocatable object file.
1023 Compile, assemble, and link to produce an executable file.
1025 Produce and run an executable file, which is expected to return
1029 The default is @code{compile}. That can be overridden for a set of
1030 tests by redefining @code{dg-do-what-default} within the @code{.exp}
1031 file for those tests.
1033 If the directive includes the optional @samp{@{ target @var{selector} @}}
1034 then the test is skipped unless the target system matches the
1037 If @var{do-what-keyword} is @code{run} and the directive includes
1038 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1039 then the test is expected to fail. The @code{xfail} clause is ignored
1040 for other values of @var{do-what-keyword}; those tests can use
1041 directive @code{dg-xfail-if}.
1044 @subsubsection Specify additional compiler options
1047 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1048 This DejaGnu directive provides a list of compiler options, to be used
1049 if the target system matches @var{selector}, that replace the default
1050 options used for this set of tests.
1052 @item @{ dg-add-options @var{feature} @dots{} @}
1053 Add any compiler options that are needed to access certain features.
1054 This directive does nothing on targets that enable the features by
1055 default, or that don't provide them at all. It must come after
1056 all @code{dg-options} directives.
1057 For supported values of @var{feature} see @ref{Add Options, ,}.
1059 @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
1060 This directive provides a list of compiler options, to be used
1061 if the target system matches @var{selector}, that are added to the default
1062 options used for this set of tests.
1065 @subsubsection Modify the test timeout value
1067 The normal timeout limit, in seconds, is found by searching the
1071 @item the value defined by an earlier @code{dg-timeout} directive in
1074 @item variable @var{tool_timeout} defined by the set of tests
1076 @item @var{gcc},@var{timeout} set in the target board
1082 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1083 Set the time limit for the compilation and for the execution of the test
1084 to the specified number of seconds.
1086 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1087 Multiply the normal time limit for compilation and execution of the test
1088 by the specified floating-point factor.
1091 @subsubsection Skip a test for some targets
1094 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1095 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1096 each element is a string of zero or more GCC options.
1097 Skip the test if all of the following conditions are met:
1099 @item the test system is included in @var{selector}
1101 @item for at least one of the option strings in @var{include-opts},
1102 every option from that string is in the set of options with which
1103 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1104 that matches any options; that is the default if @var{include-opts} is
1107 @item for each of the option strings in @var{exclude-opts}, at least one
1108 option from that string is not in the set of options with which the test
1109 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1110 that is the default if @var{exclude-opts} is not specified
1113 For example, to skip a test if option @code{-Os} is present:
1116 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
1119 To skip a test if both options @code{-O2} and @code{-g} are present:
1122 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
1125 To skip a test if either @code{-O2} or @code{-O3} is present:
1128 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
1131 To skip a test unless option @code{-Os} is present:
1134 /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
1137 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1138 but not if @code{-fpic} is also present:
1141 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1144 @item @{ dg-require-effective-target @var{keyword} [@{ target @var{selector} @}] @}
1145 Skip the test if the test target, including current multilib flags,
1146 is not covered by the effective-target keyword.
1147 If the directive includes the optional @samp{@{ @var{selector} @}}
1148 then the effective-target test is only performed if the target system
1149 matches the @var{selector}.
1150 This directive must appear after any @code{dg-do} directive in the test
1151 and before any @code{dg-additional-sources} directive.
1152 @xref{Effective-Target Keywords, , }.
1154 @item @{ dg-require-@var{support} args @}
1155 Skip the test if the target does not provide the required support.
1156 These directives must appear after any @code{dg-do} directive in the test
1157 and before any @code{dg-additional-sources} directive.
1158 They require at least one argument, which can be an empty string if the
1159 specific procedure does not examine the argument.
1160 @xref{Require Support, , }, for a complete list of these directives.
1163 @subsubsection Expect a test to fail for some targets
1166 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1167 Expect the test to fail if the conditions (which are the same as for
1168 @code{dg-skip-if}) are met. This does not affect the execute step.
1170 @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1171 Expect the execute step of a test to fail if the conditions (which are
1172 the same as for @code{dg-skip-if}) are met.
1175 @subsubsection Expect the compiler to crash
1178 @item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1179 Expect the compiler to crash with an internal compiler error and return
1180 a nonzero exit status if the conditions (which are the same as for
1181 @code{dg-skip-if}) are met. Used for tests that test bugs that have not been
1185 @subsubsection Expect the test executable to fail
1188 @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1189 Expect the test executable to return a nonzero exit status if the
1190 conditions (which are the same as for @code{dg-skip-if}) are met.
1193 @subsubsection Verify compiler messages
1194 Where @var{line} is an accepted argument for these commands, a value of @samp{0}
1195 can be used if there is no line associated with the message.
1198 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1199 This DejaGnu directive appears on a source line that is expected to get
1200 an error message, or else specifies the source line associated with the
1201 message. If there is no message for that line or if the text of that
1202 message is not matched by @var{regexp} then the check fails and
1203 @var{comment} is included in the @code{FAIL} message. The check does
1204 not look for the string @samp{error} unless it is part of @var{regexp}.
1206 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1207 This DejaGnu directive appears on a source line that is expected to get
1208 a warning message, or else specifies the source line associated with the
1209 message. If there is no message for that line or if the text of that
1210 message is not matched by @var{regexp} then the check fails and
1211 @var{comment} is included in the @code{FAIL} message. The check does
1212 not look for the string @samp{warning} unless it is part of @var{regexp}.
1214 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1215 The line is expected to get a message other than an error or warning.
1216 If there is no message for that line or if the text of that message is
1217 not matched by @var{regexp} then the check fails and @var{comment} is
1218 included in the @code{FAIL} message.
1220 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1221 This DejaGnu directive appears on a source line that should not get a
1222 message matching @var{regexp}, or else specifies the source line
1223 associated with the bogus message. It is usually used with @samp{xfail}
1224 to indicate that the message is a known problem for a particular set of
1227 @item @{ dg-line @var{linenumvar} @}
1228 This DejaGnu directive sets the variable @var{linenumvar} to the line number of
1229 the source line. The variable @var{linenumvar} can then be used in subsequent
1230 @code{dg-error}, @code{dg-warning}, @code{dg-message} and @code{dg-bogus}
1231 directives. For example:
1234 int a; /* @{ dg-line first_def_a @} */
1235 float a; /* @{ dg-error "conflicting types of" @} */
1236 /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */
1239 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1240 This DejaGnu directive indicates that the test is expected to fail due
1241 to compiler messages that are not handled by @samp{dg-error},
1242 @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail}
1243 has the same effect as @samp{target}.
1245 @item @{ dg-prune-output @var{regexp} @}
1246 Prune messages matching @var{regexp} from the test output.
1249 @subsubsection Verify output of the test executable
1252 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1253 This DejaGnu directive compares @var{regexp} to the combined output
1254 that the test executable writes to @file{stdout} and @file{stderr}.
1257 @subsubsection Specify environment variables for a test
1260 @item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @}
1261 Specify that the environment variable @var{var_name} needs to be set
1262 to @var{var_value} before invoking the compiler on the test file.
1264 @item @{ dg-set-target-env-var @var{var_name} "@var{var_value}" @}
1265 Specify that the environment variable @var{var_name} needs to be set
1266 to @var{var_value} before execution of the program created by the test.
1269 @subsubsection Specify additional files for a test
1272 @item @{ dg-additional-files "@var{filelist}" @}
1273 Specify additional files, other than source files, that must be copied
1274 to the system where the compiler runs.
1276 @item @{ dg-additional-sources "@var{filelist}" @}
1277 Specify additional source files to appear in the compile line
1278 following the main test file.
1281 @subsubsection Add checks at the end of a test
1284 @item @{ dg-final @{ @var{local-directive} @} @}
1285 This DejaGnu directive is placed within a comment anywhere in the
1286 source file and is processed after the test has been compiled and run.
1287 Multiple @samp{dg-final} commands are processed in the order in which
1288 they appear in the source file. @xref{Final Actions, , }, for a list
1289 of directives that can be used within @code{dg-final}.
1293 @subsection Selecting targets to which a test applies
1295 Several test directives include @var{selector}s to limit the targets
1296 for which a test is run or to declare that a test is expected to fail
1297 on particular targets.
1301 @item one or more target triplets, possibly including wildcard characters;
1302 use @samp{*-*-*} to match any target
1303 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1304 @item a logical expression
1307 Depending on the context, the selector specifies whether a test is
1308 skipped and reported as unsupported or is expected to fail. A context
1309 that allows either @samp{target} or @samp{xfail} also allows
1310 @samp{@{ target @var{selector1} xfail @var{selector2} @}}
1311 to skip the test for targets that don't match @var{selector1} and the
1312 test to fail for targets that match @var{selector2}.
1314 A selector expression appears within curly braces and uses a single
1315 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
1316 operand is another selector expression, an effective-target keyword,
1317 a single target triplet, or a list of target triplets within quotes or
1318 curly braces. For example:
1321 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1322 @{ target @{ powerpc*-*-* && lp64 @} @}
1323 @{ xfail @{ lp64 || vect_no_align @} @}
1326 @node Effective-Target Keywords
1327 @subsection Keywords describing target attributes
1329 Effective-target keywords identify sets of targets that support
1330 particular functionality. They are used to limit tests to be run only
1331 for particular targets, or to specify that particular sets of targets
1332 are expected to fail some tests.
1334 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1335 the GCC testsuite, with the exception of those that are documented as
1336 being local to a particular test directory.
1338 The @samp{effective target} takes into account all of the compiler options
1339 with which the test will be compiled, including the multilib options.
1340 By convention, keywords ending in @code{_nocache} can also include options
1341 specified for the particular test in an earlier @code{dg-options} or
1342 @code{dg-add-options} directive.
1344 @subsubsection Endianness
1348 Target uses big-endian memory order for multi-byte and multi-word data.
1351 Target uses little-endian memory order for multi-byte and multi-word data.
1354 @subsubsection Data type sizes
1358 Target has 32-bit @code{int}, @code{long}, and pointers.
1361 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1364 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1368 Target has 64-bit @code{double}.
1371 Target has @code{double} that is 64 bits or longer.
1374 Target has 128-bit @code{long double}.
1377 Target has @code{int} that is at 32 bits or longer.
1380 Target has @code{int} that is 16 bits or shorter.
1383 Target has 64-bit @code{long long}.
1386 Target has @code{int} and @code{long} with different sizes.
1389 Target has @code{short} and @code{int} with the same size.
1392 Target has pointers (@code{void *}) and @code{short} with the same size.
1395 Target has @code{int} and @code{float} with the same size.
1398 Target has pointers (@code{void *}) and @code{long} with the same size.
1401 Target supports @code{double} that is longer than @code{float}.
1403 @item large_long_double
1404 Target supports @code{long double} that is longer than @code{double}.
1407 Target has pointers that are 32 bits or longer.
1410 Target has a 20-bit or larger address space, so supports at least
1411 16-bit array and structure sizes.
1414 Target has a 24-bit or larger address space, so supports at least
1415 20-bit array and structure sizes.
1418 Target has a 32-bit or larger address space, so supports at least
1419 24-bit array and structure sizes.
1422 Target has @code{wchar_t} that is at least 4 bytes.
1425 Target has the @code{_Float@var{n}} type.
1428 Target has the @code{_Float@var{n}x} type.
1430 @item float@var{n}_runtime
1431 Target has the @code{_Float@var{n}} type, including runtime support
1432 for any options added with @code{dg-add-options}.
1434 @item float@var{n}x_runtime
1435 Target has the @code{_Float@var{n}x} type, including runtime support
1436 for any options added with @code{dg-add-options}.
1438 @item floatn_nx_runtime
1439 Target has runtime support for any options added with
1440 @code{dg-add-options} for any @code{_Float@var{n}} or
1441 @code{_Float@var{n}x} type.
1444 Target supports floating point infinite (@code{inf}) for type
1448 Target supports floating point infinite (@code{inf}) for type
1451 @subsubsection Fortran-specific attributes
1454 @item fortran_integer_16
1455 Target supports Fortran @code{integer} that is 16 bytes or longer.
1457 @item fortran_real_10
1458 Target supports Fortran @code{real} that is 10 bytes or longer.
1460 @item fortran_real_16
1461 Target supports Fortran @code{real} that is 16 bytes or longer.
1463 @item fortran_large_int
1464 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1466 @item fortran_large_real
1467 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1470 @subsubsection Vector-specific attributes
1473 @item vect_align_stack_vars
1474 The target's ABI allows stack variables to be aligned to the preferred
1478 Target supports both signed and unsigned averaging operations on vectors
1481 @item vect_mulhrs_hi
1482 Target supports both signed and unsigned multiply-high-with-round-and-scale
1483 operations on vectors of half-words.
1485 @item vect_sdiv_pow2_si
1486 Target supports signed division by constant power-of-2 operations
1487 on vectors of 4-byte integers.
1489 @item vect_condition
1490 Target supports vector conditional operations.
1492 @item vect_cond_mixed
1493 Target supports vector conditional operations where comparison operands
1494 have different type from the value operands.
1497 Target supports hardware vectors of @code{double}.
1499 @item vect_double_cond_arith
1500 Target supports conditional addition, subtraction, multiplication,
1501 division, minimum and maximum on vectors of @code{double}, via the
1502 @code{cond_} optabs.
1504 @item vect_element_align_preferred
1505 The target's preferred vector alignment is the same as the element
1509 Target supports hardware vectors of @code{float} when
1510 @option{-funsafe-math-optimizations} is in effect.
1512 @item vect_float_strict
1513 Target supports hardware vectors of @code{float} when
1514 @option{-funsafe-math-optimizations} is not in effect.
1515 This implies @code{vect_float}.
1518 Target supports hardware vectors of @code{int}.
1521 Target supports hardware vectors of @code{long}.
1523 @item vect_long_long
1524 Target supports hardware vectors of @code{long long}.
1526 @item vect_check_ptrs
1527 Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs}
1530 @item vect_fully_masked
1531 Target supports fully-masked (also known as fully-predicated) loops,
1532 so that vector loops can handle partial as well as full vectors.
1534 @item vect_masked_load
1535 Target supports vector masked loads.
1537 @item vect_masked_store
1538 Target supports vector masked stores.
1540 @item vect_scatter_store
1541 Target supports vector scatter stores.
1543 @item vect_aligned_arrays
1544 Target aligns arrays to vector alignment boundary.
1546 @item vect_hw_misalign
1547 Target supports a vector misalign access.
1550 Target does not support a vector alignment mechanism.
1552 @item vect_peeling_profitable
1553 Target might require to peel loops for alignment purposes.
1555 @item vect_no_int_min_max
1556 Target does not support a vector min and max instruction on @code{int}.
1558 @item vect_no_int_add
1559 Target does not support a vector add instruction on @code{int}.
1561 @item vect_no_bitwise
1562 Target does not support vector bitwise instructions.
1565 Target supports comparison of @code{bool} vectors for at least one
1569 Target supports addition of @code{char} vectors for at least one
1572 @item vect_char_mult
1573 Target supports @code{vector char} multiplication.
1575 @item vect_short_mult
1576 Target supports @code{vector short} multiplication.
1579 Target supports @code{vector int} multiplication.
1581 @item vect_long_mult
1582 Target supports 64 bit @code{vector long} multiplication.
1584 @item vect_extract_even_odd
1585 Target supports vector even/odd element extraction.
1587 @item vect_extract_even_odd_wide
1588 Target supports vector even/odd element extraction of vectors with elements
1589 @code{SImode} or larger.
1591 @item vect_interleave
1592 Target supports vector interleaving.
1595 Target supports vector interleaving and extract even/odd.
1597 @item vect_strided_wide
1598 Target supports vector interleaving and extract even/odd for wide
1602 Target supports vector permutation.
1604 @item vect_perm_byte
1605 Target supports permutation of vectors with 8-bit elements.
1607 @item vect_perm_short
1608 Target supports permutation of vectors with 16-bit elements.
1610 @item vect_perm3_byte
1611 Target supports permutation of vectors with 8-bit elements, and for the
1612 default vector length it is possible to permute:
1614 @{ a0, a1, a2, b0, b1, b2, @dots{} @}
1618 @{ a0, a0, a0, b0, b0, b0, @dots{} @}
1619 @{ a1, a1, a1, b1, b1, b1, @dots{} @}
1620 @{ a2, a2, a2, b2, b2, b2, @dots{} @}
1622 using only two-vector permutes, regardless of how long the sequence is.
1624 @item vect_perm3_int
1625 Like @code{vect_perm3_byte}, but for 32-bit elements.
1627 @item vect_perm3_short
1628 Like @code{vect_perm3_byte}, but for 16-bit elements.
1631 Target supports a hardware vector shift operation.
1633 @item vect_unaligned_possible
1634 Target prefers vectors to have an alignment greater than element
1635 alignment, but also allows unaligned vector accesses in some
1638 @item vect_variable_length
1639 Target has variable-length vectors.
1641 @item vect_widen_sum_hi_to_si
1642 Target supports a vector widening summation of @code{short} operands
1643 into @code{int} results, or can promote (unpack) from @code{short}
1646 @item vect_widen_sum_qi_to_hi
1647 Target supports a vector widening summation of @code{char} operands
1648 into @code{short} results, or can promote (unpack) from @code{char}
1651 @item vect_widen_sum_qi_to_si
1652 Target supports a vector widening summation of @code{char} operands
1653 into @code{int} results.
1655 @item vect_widen_mult_qi_to_hi
1656 Target supports a vector widening multiplication of @code{char} operands
1657 into @code{short} results, or can promote (unpack) from @code{char} to
1658 @code{short} and perform non-widening multiplication of @code{short}.
1660 @item vect_widen_mult_hi_to_si
1661 Target supports a vector widening multiplication of @code{short} operands
1662 into @code{int} results, or can promote (unpack) from @code{short} to
1663 @code{int} and perform non-widening multiplication of @code{int}.
1665 @item vect_widen_mult_si_to_di_pattern
1666 Target supports a vector widening multiplication of @code{int} operands
1667 into @code{long} results.
1670 Target supports a vector dot-product of @code{signed char}.
1673 Target supports a vector dot-product of @code{unsigned char}.
1676 Target supports a vector dot-product of @code{signed short}.
1679 Target supports a vector dot-product of @code{unsigned short}.
1681 @item vect_pack_trunc
1682 Target supports a vector demotion (packing) of @code{short} to @code{char}
1683 and from @code{int} to @code{short} using modulo arithmetic.
1686 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1687 and from @code{char} to @code{int}.
1689 @item vect_intfloat_cvt
1690 Target supports conversion from @code{signed int} to @code{float}.
1692 @item vect_uintfloat_cvt
1693 Target supports conversion from @code{unsigned int} to @code{float}.
1695 @item vect_floatint_cvt
1696 Target supports conversion from @code{float} to @code{signed int}.
1698 @item vect_floatuint_cvt
1699 Target supports conversion from @code{float} to @code{unsigned int}.
1701 @item vect_intdouble_cvt
1702 Target supports conversion from @code{signed int} to @code{double}.
1704 @item vect_doubleint_cvt
1705 Target supports conversion from @code{double} to @code{signed int}.
1707 @item vect_max_reduc
1708 Target supports max reduction for vectors.
1710 @item vect_sizes_16B_8B
1711 Target supports 16- and 8-bytes vectors.
1713 @item vect_sizes_32B_16B
1714 Target supports 32- and 16-bytes vectors.
1716 @item vect_logical_reduc
1717 Target supports AND, IOR and XOR reduction on vectors.
1719 @item vect_fold_extract_last
1720 Target supports the @code{fold_extract_last} optab.
1722 @item vect_len_load_store
1723 Target supports the @code{len_load} and @code{len_store} optabs.
1725 @item vect_partial_vectors_usage_1
1726 Target supports loop vectorization with partial vectors and
1727 @code{vect-partial-vector-usage} is set to 1.
1729 @item vect_partial_vectors_usage_2
1730 Target supports loop vectorization with partial vectors and
1731 @code{vect-partial-vector-usage} is set to 2.
1733 @item vect_partial_vectors
1734 Target supports loop vectorization with partial vectors and
1735 @code{vect-partial-vector-usage} is nonzero.
1738 @subsubsection Thread Local Storage attributes
1742 Target supports thread-local storage.
1745 Target supports native (rather than emulated) thread-local storage.
1748 Test system supports executing TLS executables.
1751 @subsubsection Decimal floating point attributes
1755 Targets supports compiling decimal floating point extension to C.
1758 Including the options used to compile this particular test, the
1759 target supports compiling decimal floating point extension to C.
1762 Test system can execute decimal floating point tests.
1765 Including the options used to compile this particular test, the
1766 test system can execute decimal floating point tests.
1769 Target generates decimal floating point instructions with current options.
1772 @subsubsection ARM-specific attributes
1776 ARM target generates 32-bit code.
1778 @item arm_little_endian
1779 ARM target that generates little-endian code.
1782 ARM target adheres to the ABI for the ARM Architecture.
1786 ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or
1787 equivalent options. Some multilibs may be incompatible with these
1791 @anchor{arm_fp_dp_ok}
1792 ARM target defines @code{__ARM_FP} with double-precision support using
1793 @code{-mfloat-abi=softfp} or equivalent options. Some multilibs may
1794 be incompatible with these options.
1797 ARM target adheres to the VFP and Advanced SIMD Register Arguments
1798 variant of the ABI for the ARM Architecture (as selected with
1799 @code{-mfloat-abi=hard}).
1802 ARM target uses emulated floating point operations.
1804 @item arm_hard_vfp_ok
1805 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
1806 Some multilibs may be incompatible with these options.
1809 ARM target supports @code{-mcpu=iwmmxt}.
1810 Some multilibs may be incompatible with this option.
1813 ARM target supports generating NEON instructions.
1815 @item arm_tune_string_ops_prefer_neon
1816 Test CPU tune supports inlining string operations with NEON instructions.
1819 Test system supports executing NEON instructions.
1822 Test system supports executing NEON v2 instructions.
1825 @anchor{arm_neon_ok}
1826 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
1827 options. Some multilibs may be incompatible with these options.
1829 @item arm_neon_ok_no_float_abi
1830 @anchor{arm_neon_ok_no_float_abi}
1831 ARM Target supports NEON with @code{-mfpu=neon}, but without any
1832 -mfloat-abi= option. Some multilibs may be incompatible with this
1836 @anchor{arm_neonv2_ok}
1837 ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible
1838 options. Some multilibs may be incompatible with these options.
1841 @anchor{arm_fp16_ok}
1842 Target supports options to generate VFP half-precision floating-point
1843 instructions. Some multilibs may be incompatible with these
1844 options. This test is valid for ARM only.
1847 Target supports executing VFP half-precision floating-point
1848 instructions. This test is valid for ARM only.
1850 @item arm_neon_fp16_ok
1851 @anchor{arm_neon_fp16_ok}
1852 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
1853 options, including @code{-mfp16-format=ieee} if necessary to obtain the
1854 @code{__fp16} type. Some multilibs may be incompatible with these options.
1856 @item arm_neon_fp16_hw
1857 Test system supports executing Neon half-precision float instructions.
1860 @item arm_fp16_alternative_ok
1861 ARM target supports the ARM FP16 alternative format. Some multilibs
1862 may be incompatible with the options needed.
1864 @item arm_fp16_none_ok
1865 ARM target supports specifying none as the ARM FP16 format.
1868 ARM target generates Thumb-1 code for @code{-mthumb}.
1871 ARM target generates Thumb-2 code for @code{-mthumb}.
1874 ARM target that is not using Thumb.
1877 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
1878 Some multilibs may be incompatible with these options.
1881 @anchor{arm_vfp3_ok}
1882 ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}.
1883 Some multilibs may be incompatible with these options.
1885 @item arm_arch_v8a_hard_ok
1886 @anchor{arm_arch_v8a_hard_ok}
1887 The compiler is targeting @code{arm*-*-*} and can compile and assemble code
1888 using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
1889 This is not enough to guarantee that linking works.
1891 @item arm_arch_v8a_hard_multilib
1892 The compiler is targeting @code{arm*-*-*} and can build programs using
1893 the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
1894 The target can also run the resulting binaries.
1897 ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}.
1898 Some multilibs may be incompatible with these options.
1900 @item arm_v8_neon_ok
1901 ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}.
1902 Some multilibs may be incompatible with these options.
1904 @item arm_v8_1a_neon_ok
1905 @anchor{arm_v8_1a_neon_ok}
1906 ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions.
1907 Some multilibs may be incompatible with these options.
1909 @item arm_v8_1a_neon_hw
1910 ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some
1911 multilibs may be incompatible with the options needed. Implies
1915 ARM target supports acquire-release instructions.
1917 @item arm_v8_2a_fp16_scalar_ok
1918 @anchor{arm_v8_2a_fp16_scalar_ok}
1919 ARM target supports options to generate instructions for ARMv8.2-A and
1920 scalar instructions from the FP16 extension. Some multilibs may be
1921 incompatible with these options.
1923 @item arm_v8_2a_fp16_scalar_hw
1924 ARM target supports executing instructions for ARMv8.2-A and scalar
1925 instructions from the FP16 extension. Some multilibs may be
1926 incompatible with these options. Implies arm_v8_2a_fp16_neon_ok.
1928 @item arm_v8_2a_fp16_neon_ok
1929 @anchor{arm_v8_2a_fp16_neon_ok}
1930 ARM target supports options to generate instructions from ARMv8.2-A with
1931 the FP16 extension. Some multilibs may be incompatible with these
1932 options. Implies arm_v8_2a_fp16_scalar_ok.
1934 @item arm_v8_2a_fp16_neon_hw
1935 ARM target supports executing instructions from ARMv8.2-A with the FP16
1936 extension. Some multilibs may be incompatible with these options.
1937 Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.
1939 @item arm_v8_2a_dotprod_neon_ok
1940 @anchor{arm_v8_2a_dotprod_neon_ok}
1941 ARM target supports options to generate instructions from ARMv8.2-A with
1942 the Dot Product extension. Some multilibs may be incompatible with these
1945 @item arm_v8_2a_dotprod_neon_hw
1946 ARM target supports executing instructions from ARMv8.2-A with the Dot
1947 Product extension. Some multilibs may be incompatible with these options.
1948 Implies arm_v8_2a_dotprod_neon_ok.
1950 @item arm_fp16fml_neon_ok
1951 @anchor{arm_fp16fml_neon_ok}
1952 ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS}
1953 half-precision floating-point instructions available from ARMv8.2-A and
1954 onwards. Some multilibs may be incompatible with these options.
1956 @item arm_v8_2a_bf16_neon_ok
1957 ARM target supports options to generate instructions from ARMv8.2-A with
1958 the BFloat16 extension (bf16). Some multilibs may be incompatible with these
1961 @item arm_v8_2a_i8mm_ok
1962 ARM target supports options to generate instructions from ARMv8.2-A with
1963 the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be
1964 incompatible with these options.
1966 @item arm_v8_1m_mve_ok
1967 ARM target supports options to generate instructions from ARMv8.1-M with
1968 the M-Profile Vector Extension (MVE). Some multilibs may be incompatible
1971 @item arm_v8_1m_mve_fp_ok
1972 ARM target supports options to generate instructions from ARMv8.1-M with
1973 the Half-precision floating-point instructions (HP), Floating-point Extension
1974 (FP) along with M-Profile Vector Extension (MVE). Some multilibs may be
1975 incompatible with these options.
1978 Test system supports executing MVE instructions.
1980 @item arm_v8m_main_cde
1981 ARM target supports options to generate instructions from ARMv8-M with
1982 the Custom Datapath Extension (CDE). Some multilibs may be incompatible
1985 @item arm_v8m_main_cde_fp
1986 ARM target supports options to generate instructions from ARMv8-M with
1987 the Custom Datapath Extension (CDE) and floating-point (VFP).
1988 Some multilibs may be incompatible with these options.
1990 @item arm_v8_1m_main_cde_mve
1991 ARM target supports options to generate instructions from ARMv8.1-M with
1992 the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE).
1993 Some multilibs may be incompatible with these options.
1995 @item arm_prefer_ldrd_strd
1996 ARM target prefers @code{LDRD} and @code{STRD} instructions over
1997 @code{LDM} and @code{STM} instructions.
1999 @item arm_thumb1_movt_ok
2000 ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW}
2001 and @code{MOVT} instructions available.
2003 @item arm_thumb1_cbz_ok
2004 ARM target generates Thumb-1 code for @code{-mthumb} with
2005 @code{CBZ} and @code{CBNZ} instructions available.
2007 @item arm_divmod_simode
2008 ARM target for which divmod transform is disabled, if it supports hardware
2012 ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse}
2015 @item arm_coproc1_ok
2016 @anchor{arm_coproc1_ok}
2017 ARM target supports the following coprocessor instructions: @code{CDP},
2018 @code{LDC}, @code{STC}, @code{MCR} and @code{MRC}.
2020 @item arm_coproc2_ok
2021 @anchor{arm_coproc2_ok}
2022 ARM target supports all the coprocessor instructions also listed as supported
2023 in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2},
2024 @code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}.
2026 @item arm_coproc3_ok
2027 @anchor{arm_coproc3_ok}
2028 ARM target supports all the coprocessor instructions also listed as supported
2029 in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}.
2031 @item arm_coproc4_ok
2032 ARM target supports all the coprocessor instructions also listed as supported
2033 in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}.
2036 @anchor{arm_simd32_ok}
2037 ARM Target supports options suitable for accessing the SIMD32 intrinsics from
2039 Some multilibs may be incompatible with these options.
2042 @anchor{arm_qbit_ok}
2043 ARM Target supports options suitable for accessing the Q-bit manipulation
2044 intrinsics from @code{arm_acle.h}.
2045 Some multilibs may be incompatible with these options.
2048 @anchor{arm_softfp_ok}
2049 ARM target supports the @code{-mfloat-abi=softfp} option.
2052 @anchor{arm_hard_ok}
2053 ARM target supports the @code{-mfloat-abi=hard} option.
2055 @item arm_v8_1_lob_ok
2056 @anchor{arm_v8_1_lob_ok}
2057 ARM Target supports executing the Armv8.1-M Mainline Low Overhead Loop
2058 instructions @code{DLS} and @code{LE}.
2059 Some multilibs may be incompatible with these options.
2061 @item arm_thumb2_ok_no_arm_v8_1_lob
2062 ARM target generates Thumb-2 code for @code{-mthumb} but does not
2063 support executing the Armv8.1-M Mainline Low Overhead Loop
2064 instructions @code{DLS} and @code{LE}.
2068 @subsubsection AArch64-specific attributes
2071 @item aarch64_asm_<ext>_ok
2072 AArch64 assembler supports the architecture extension @code{ext} via the
2073 @code{.arch_extension} pseudo-op.
2075 AArch64 target which generates instruction sequences for tiny memory model.
2077 AArch64 target which generates instruction sequences for small memory model.
2079 AArch64 target which generates instruction sequences for large memory model.
2080 @item aarch64_little_endian
2081 AArch64 target which generates instruction sequences for little endian.
2082 @item aarch64_big_endian
2083 AArch64 target which generates instruction sequences for big endian.
2084 @item aarch64_small_fpic
2085 Binutils installed on test system supports relocation types required by -fpic
2086 for AArch64 small memory model.
2087 @item aarch64_sve_hw
2088 AArch64 target that is able to generate and execute SVE code (regardless of
2089 whether it does so by default).
2090 @item aarch64_sve128_hw
2091 @itemx aarch64_sve256_hw
2092 @itemx aarch64_sve512_hw
2093 @itemx aarch64_sve1024_hw
2094 @itemx aarch64_sve2048_hw
2095 Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length.
2097 @item aarch64_fjcvtzs_hw
2098 AArch64 target that is able to generate and execute armv8.3-a FJCVTZS
2102 @subsubsection MIPS-specific attributes
2106 MIPS target supports 64-bit instructions.
2109 MIPS target does not produce MIPS16 code.
2111 @item mips16_attribute
2112 MIPS target can generate MIPS16 code.
2115 MIPS target is a Loongson-2E or -2F target using an ABI that supports
2116 the Loongson vector modes.
2119 MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA).
2121 @item mips_newabi_large_long_double
2122 MIPS target supports @code{long double} larger than @code{double}
2123 when using the new ABI.
2125 @item mpaired_single
2126 MIPS target supports @code{-mpaired-single}.
2129 @subsubsection MSP430-specific attributes
2133 MSP430 target has the small memory model enabled (@code{-msmall}).
2136 MSP430 target has the large memory model enabled (@code{-mlarge}).
2139 @subsubsection PowerPC-specific attributes
2144 PowerPC target supports executing hardware DFP instructions.
2147 PowerPC target supports executing VSX instructions (ISA 2.07).
2150 Test system supports executing 64-bit instructions.
2152 @item powerpc_altivec
2153 PowerPC target supports AltiVec.
2155 @item powerpc_altivec_ok
2156 PowerPC target supports @code{-maltivec}.
2158 @item powerpc_eabi_ok
2159 PowerPC target supports @code{-meabi}.
2162 PowerPC target supports @code{-mabi=elfv2}.
2165 PowerPC target supports floating-point registers.
2167 @item powerpc_hard_double
2168 PowerPC target supports hardware double-precision floating-point.
2170 @item powerpc_htm_ok
2171 PowerPC target supports @code{-mhtm}
2173 @item powerpc_p8vector_ok
2174 PowerPC target supports @code{-mpower8-vector}
2176 @item powerpc_popcntb_ok
2177 PowerPC target supports the @code{popcntb} instruction, indicating
2178 that this target supports @code{-mcpu=power5}.
2180 @item powerpc_ppu_ok
2181 PowerPC target supports @code{-mcpu=cell}.
2184 PowerPC target supports PowerPC SPE.
2186 @item powerpc_spe_nocache
2187 Including the options used to compile this particular test, the
2188 PowerPC target supports PowerPC SPE.
2191 PowerPC target supports PowerPC SPU.
2193 @item powerpc_vsx_ok
2194 PowerPC target supports @code{-mvsx}.
2196 @item powerpc_405_nocache
2197 Including the options used to compile this particular test, the
2198 PowerPC target supports PowerPC 405.
2201 PowerPC target supports executing reciprocal estimate instructions.
2204 PowerPC target supports executing AltiVec instructions.
2207 PowerPC target supports executing VSX instructions (ISA 2.06).
2210 PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu}
2211 setting is Power5 or later.
2214 PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu}
2215 setting is Power6 or later.
2218 PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu}
2219 setting is Power7 or later.
2222 PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu}
2223 setting is Power8 or later.
2226 PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu}
2227 setting is Power9 or later.
2230 @subsubsection Other hardware attributes
2232 @c Please keep this table sorted alphabetically.
2235 Target supports autoincrement/decrement addressing.
2238 Target supports compiling @code{avx} instructions.
2241 Target supports the execution of @code{avx} instructions.
2244 Target supports compiling @code{avx2} instructions.
2247 Target supports the execution of @code{avx2} instructions.
2250 Target supports the execution of @code{avxvnni} instructions.
2253 Target supports compiling @code{avx512f} instructions.
2255 @item avx512f_runtime
2256 Target supports the execution of @code{avx512f} instructions.
2258 @item avx512vp2intersect
2259 Target supports the execution of @code{avx512vp2intersect} instructions.
2262 Target supports the execution of @code{amx-tile} instructions.
2265 Target supports the execution of @code{amx-int8} instructions.
2268 Target supports the execution of @code{amx-bf16} instructions.
2271 Test system can execute AltiVec and Cell PPU instructions.
2274 Target uses a ColdFire FPU.
2277 Target supporting hardware divmod insn or divmod libcall.
2280 Target supporting hardware divmod insn or divmod libcall for SImode.
2283 Target supports FPU instructions.
2285 @item non_strict_align
2286 Target does not require strict alignment.
2289 The x86-64 target linker supports PIE with copy reloc.
2292 Target supports x86 @code{rdrand} instruction.
2295 Target has a square root instruction that the compiler can generate.
2298 Target supports compiling @code{sse} instructions.
2301 Target supports the execution of @code{sse} instructions.
2304 Target supports compiling @code{sse2} instructions.
2307 Target supports the execution of @code{sse2} instructions.
2309 @item sync_char_short
2310 Target supports atomic operations on @code{char} and @code{short}.
2313 Target supports atomic operations on @code{int} and @code{long}.
2316 Test environment appears to run executables on a simulator that
2317 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
2318 or @code{EM_SPARCV9} executables.
2320 @item vect_cmdline_needed
2321 Target requires a command line argument to enable a SIMD instruction set.
2324 Target supports the xorsign optab expansion.
2328 @subsubsection Environment attributes
2332 The language for the compiler under test is C.
2335 The language for the compiler under test is C++.
2338 Target provides a full C99 runtime.
2340 @item correct_iso_cpp_string_wchar_protos
2341 Target @code{string.h} and @code{wchar.h} headers provide C++ required
2342 overloads for @code{strchr} etc. functions.
2345 Target provides the D runtime.
2347 @item d_runtime_has_std_library
2348 Target provides the D standard library (Phobos).
2350 @item dummy_wcsftime
2351 Target uses a dummy @code{wcsftime} function that always returns zero.
2354 Target can truncate a file from a file descriptor, as used by
2355 @file{libgfortran/io/unix.c:fd_truncate}; i.e.@: @code{ftruncate} or
2359 Target provides @file{fenv.h} include file.
2361 @item fenv_exceptions
2362 Target supports @file{fenv.h} with all the standard IEEE exceptions
2363 and floating-point exceptions are raised by arithmetic operations.
2365 @item fenv_exceptions_dfp
2366 Target supports @file{fenv.h} with all the standard IEEE exceptions
2367 and floating-point exceptions are raised by arithmetic operations for
2368 decimal floating point.
2371 Target offers such file I/O library functions as @code{fopen},
2372 @code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time
2373 requirement for the presence of the functions in the library; even if
2374 they fail at runtime, the requirement is still regarded as satisfied.
2377 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
2378 Effectively, it is a target which supports no extra headers or libraries
2379 other than what is considered essential.
2382 Target supports @code{gettimeofday}.
2385 Target supports constructors with initialization priority arguments.
2387 @item inttypes_types
2388 Target has the basic signed and unsigned types in @code{inttypes.h}.
2389 This is for tests that GCC's notions of these types agree with those
2390 in the header, as some systems have only @code{inttypes.h}.
2393 Target might have errors of a few ULP in string to floating-point
2394 conversion functions and overflow is not always detected correctly by
2398 Target provides @code{mempcpy} function.
2401 Target supports @code{mmap}.
2404 Target supports Newlib.
2406 @item newlib_nano_io
2407 GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces
2408 the code size of Newlib formatted I/O functions.
2411 Target provides @code{pow10} function.
2414 Target can compile using @code{pthread.h} with no errors or warnings.
2417 Target has @code{pthread.h}.
2419 @item run_expensive_tests
2420 Expensive testcases (usually those that consume excessive amounts of CPU
2421 time) should be run on this target. This can be enabled by setting the
2422 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
2425 Test system runs executables on a simulator (i.e.@: slowly) rather than
2426 hardware (i.e.@: fast).
2429 Target has @code{signal.h}.
2432 Target supports the stabs debugging format.
2435 Target has the basic signed and unsigned C types in @code{stdint.h}.
2436 This will be obsolete when GCC ensures a working @code{stdint.h} for
2440 Target provides @code{stpcpy} function.
2443 Target supports trampolines.
2446 Target supports uClibc.
2449 Target does not use a status wrapper.
2451 @item vxworks_kernel
2452 Target is a VxWorks kernel.
2455 Target is a VxWorks RTP.
2458 Target supports wide characters.
2461 @subsubsection Other attributes
2464 @item R_flag_in_section
2465 Target supports the 'R' flag in .section directive in assembly inputs.
2467 @item automatic_stack_alignment
2468 Target supports automatic stack alignment.
2471 Target supports @option{-branch-cost=N}.
2474 Target uses @code{__cxa_atexit}.
2476 @item default_packed
2477 Target has packed layout of structure members by default.
2480 Target supports exceptions.
2482 @item exceptions_enabled
2483 Target supports exceptions and they are enabled in the current
2484 testing configuration.
2487 Target supports Graphite optimizations.
2490 Target supports fixed-point extension to C.
2493 Target supports OpenACC via @option{-fopenacc}.
2496 Target supports OpenMP via @option{-fopenmp}.
2499 Target supports @option{-fpic} and @option{-fPIC}.
2502 Target supports @option{-freorder-blocks-and-partition}.
2504 @item fstack_protector
2505 Target supports @option{-fstack-protector}.
2508 Target uses GNU @command{as}.
2511 Target supports @option{--gc-sections}.
2514 Target uses GNU @command{ld}.
2516 @item keeps_null_pointer_checks
2517 Target keeps null pointer checks, either due to the use of
2518 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
2521 Target is using an LLVM assembler and/or linker, instead of GNU Binutils.
2524 Compiler has been configured to support link-time optimization (LTO).
2526 @item lto_incremental
2527 Compiler and linker support link-time optimization relocatable linking
2528 with @option{-r} and @option{-flto} options.
2530 @item naked_functions
2531 Target supports the @code{naked} function attribute.
2533 @item named_sections
2534 Target supports named sections.
2536 @item natural_alignment_32
2537 Target uses natural alignment (aligned to type size) for types of
2540 @item target_natural_alignment_64
2541 Target uses natural alignment (aligned to type size) for types of
2545 Target supports the @code{noinit} variable attribute.
2548 Target does not generate PIC by default.
2550 @item o_flag_in_section
2551 Target supports the 'o' flag in .section directive in assembly inputs.
2554 Target has been configured for OpenACC/OpenMP offloading on AMD GCN.
2557 Target supports the @code{persistent} variable attribute.
2560 Target generates PIE by default.
2562 @item pcc_bitfield_type_matters
2563 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
2565 @item pe_aligned_commons
2566 Target supports @option{-mpe-aligned-commons}.
2569 Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
2572 Target supports @option{-rdynamic}.
2574 @item scalar_all_fma
2575 Target supports all four fused multiply-add optabs for both @code{float}
2576 and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab},
2577 @code{fnma_optab} and @code{fnms_optab}.
2579 @item section_anchors
2580 Target supports section anchors.
2583 Target defaults to short enums.
2586 @anchor{stack_size_et}
2587 Target has limited stack size. The stack size limit can be obtained using the
2588 STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature
2592 Target supports @option{-static}.
2594 @item static_libgfortran
2595 Target supports statically linking @samp{libgfortran}.
2597 @item string_merging
2598 Target supports merging string constants at link time.
2601 Target supports compiling and assembling UCN.
2604 Including the options used to compile this particular test, the
2605 target supports compiling and assembling UCN.
2607 @item unaligned_stack
2608 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
2609 or equal to the required vector alignment.
2611 @item vector_alignment_reachable
2612 Vector alignment is reachable for types of 32 bits or less.
2614 @item vector_alignment_reachable_for_64bit
2615 Vector alignment is reachable for types of 64 bits or less.
2617 @item wchar_t_char16_t_compatible
2618 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
2620 @item wchar_t_char32_t_compatible
2621 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
2624 Target uses comdat groups.
2626 @item indirect_calls
2627 Target supports indirect calls, i.e. calls where the target is not
2631 Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests.
2634 @subsubsection Local to tests in @code{gcc.target/i386}
2638 Target supports compiling @code{3dnow} instructions.
2641 Target supports compiling @code{aes} instructions.
2644 Target supports compiling @code{fma4} instructions.
2647 Target supports the @code{-mfentry} option that alters the
2648 position of profiling calls such that they precede the prologue.
2650 @item ms_hook_prologue
2651 Target supports attribute @code{ms_hook_prologue}.
2654 Target supports compiling @code{pclmul} instructions.
2657 Target supports compiling @code{sse3} instructions.
2660 Target supports compiling @code{sse4} instructions.
2663 Target supports compiling @code{sse4a} instructions.
2666 Target supports compiling @code{ssse3} instructions.
2669 Target supports compiling @code{vaes} instructions.
2672 Target supports compiling @code{vpclmul} instructions.
2675 Target supports compiling @code{xop} instructions.
2678 @subsubsection Local to tests in @code{gcc.test-framework}
2689 @subsection Features for @code{dg-add-options}
2691 The supported values of @var{feature} for directive @code{dg-add-options}
2696 @code{__ARM_FP} definition. Only ARM targets support this feature, and only then
2697 in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target
2701 @code{__ARM_FP} definition with double-precision support. Only ARM
2702 targets support this feature, and only then in certain modes; see the
2703 @ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}.
2706 NEON support. Only ARM targets support this feature, and only then
2707 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
2711 VFP half-precision floating point support. This does not select the
2712 FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or
2713 @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This
2714 feature is only supported by ARM targets and then only in certain
2715 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2719 @anchor{arm_fp16_ieee}
2720 ARM IEEE 754-2008 format VFP half-precision floating point support.
2721 This feature is only supported by ARM targets and then only in certain
2722 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2725 @item arm_fp16_alternative
2726 @anchor{arm_fp16_alternative}
2727 ARM Alternative format VFP half-precision floating point support.
2728 This feature is only supported by ARM targets and then only in certain
2729 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2733 NEON and half-precision floating point support. Only ARM targets
2734 support this feature, and only then in certain modes; see
2735 the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}.
2738 arm vfp3 floating point support; see
2739 the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}.
2741 @item arm_arch_v8a_hard
2742 Add options for ARMv8-A and the hard-float variant of the AAPCS,
2743 if this is supported by the compiler; see the
2744 @ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword.
2746 @item arm_v8_1a_neon
2747 Add options for ARMv8.1-A with Adv.SIMD support, if this is supported
2748 by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok}
2749 effective target keyword.
2751 @item arm_v8_2a_fp16_scalar
2752 Add options for ARMv8.2-A with scalar FP16 support, if this is
2753 supported by the target; see the
2754 @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective
2757 @item arm_v8_2a_fp16_neon
2758 Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is
2759 supported by the target; see the
2760 @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target
2763 @item arm_v8_2a_dotprod_neon
2764 Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is
2765 supported by the target; see the
2766 @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword.
2768 @item arm_fp16fml_neon
2769 Add options to enable generation of the @code{VFMAL} and @code{VFMSL}
2770 instructions, if this is supported by the target; see the
2771 @ref{arm_fp16fml_neon_ok} effective target keyword.
2773 @item bind_pic_locally
2774 Add the target-specific flags needed to enable functions to bind
2775 locally when using pic/PIC passes in the testsuite.
2778 Add the target-specific flags needed to use the @code{_Float@var{n}} type.
2781 Add the target-specific flags needed to use the @code{_Float@var{n}x} type.
2784 Add the target-specific flags needed to enable full IEEE
2787 @item mips16_attribute
2788 @code{mips16} function attributes.
2789 Only MIPS targets support this feature, and only then in certain modes.
2792 @anchor{stack_size_ao}
2793 Add the flags needed to define macro STACK_SIZE and set it to the stack size
2794 limit associated with the @ref{stack_size_et,,@code{stack_size} effective
2798 Add the target-specific flags needed to enable hardware square root
2799 instructions, if any.
2802 Add the target-specific flags needed to use thread-local storage.
2805 @node Require Support
2806 @subsection Variants of @code{dg-require-@var{support}}
2808 A few of the @code{dg-require} directives take arguments.
2811 @item dg-require-iconv @var{codeset}
2812 Skip the test if the target does not support iconv. @var{codeset} is
2813 the codeset to convert to.
2815 @item dg-require-profiling @var{profopt}
2816 Skip the test if the target does not support profiling with option
2819 @item dg-require-stack-check @var{check}
2820 Skip the test if the target does not support the @code{-fstack-check}
2821 option. If @var{check} is @code{""}, support for @code{-fstack-check}
2822 is checked, for @code{-fstack-check=("@var{check}")} otherwise.
2824 @item dg-require-stack-size @var{size}
2825 Skip the test if the target does not support a stack size of @var{size}.
2827 @item dg-require-visibility @var{vis}
2828 Skip the test if the target does not support the @code{visibility} attribute.
2829 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
2830 checked, for @code{visibility("@var{vis}")} otherwise.
2833 The original @code{dg-require} directives were defined before there
2834 was support for effective-target keywords. The directives that do not
2835 take arguments could be replaced with effective-target keywords.
2838 @item dg-require-alias ""
2839 Skip the test if the target does not support the @samp{alias} attribute.
2841 @item dg-require-ascii-locale ""
2842 Skip the test if the host does not support an ASCII locale.
2844 @item dg-require-compat-dfp ""
2845 Skip this test unless both compilers in a @file{compat} testsuite
2846 support decimal floating point.
2848 @item dg-require-cxa-atexit ""
2849 Skip the test if the target does not support @code{__cxa_atexit}.
2850 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
2852 @item dg-require-dll ""
2853 Skip the test if the target does not support DLL attributes.
2855 @item dg-require-dot ""
2856 Skip the test if the host does not have @command{dot}.
2858 @item dg-require-fork ""
2859 Skip the test if the target does not support @code{fork}.
2861 @item dg-require-gc-sections ""
2862 Skip the test if the target's linker does not support the
2863 @code{--gc-sections} flags.
2864 This is equivalent to @code{dg-require-effective-target gc-sections}.
2866 @item dg-require-host-local ""
2867 Skip the test if the host is remote, rather than the same as the build
2868 system. Some tests are incompatible with DejaGnu's handling of remote
2869 hosts, which involves copying the source file to the host and compiling
2870 it with a relative path and "@code{-o a.out}".
2872 @item dg-require-mkfifo ""
2873 Skip the test if the target does not support @code{mkfifo}.
2875 @item dg-require-named-sections ""
2876 Skip the test is the target does not support named sections.
2877 This is equivalent to @code{dg-require-effective-target named_sections}.
2879 @item dg-require-weak ""
2880 Skip the test if the target does not support weak symbols.
2882 @item dg-require-weak-override ""
2883 Skip the test if the target does not support overriding weak symbols.
2887 @subsection Commands for use in @code{dg-final}
2889 The GCC testsuite defines the following directives to be used within
2892 @subsubsection Scan a particular file
2895 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2896 Passes if @var{regexp} matches text in @var{filename}.
2897 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2898 Passes if @var{regexp} does not match text in @var{filename}.
2899 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
2900 Passes if @var{regexp} matches in Fortran module @var{module}.
2901 @item dg-check-dot @var{filename}
2902 Passes if @var{filename} is a valid @file{.dot} file (by running
2903 @code{dot -Tpng} on it, and verifying the exit code is 0).
2906 @subsubsection Scan the assembly output
2909 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
2910 Passes if @var{regex} matches text in the test's assembler output.
2912 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
2913 Passes if @var{regex} does not match text in the test's assembler output.
2915 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
2916 Passes if @var{regex} is matched exactly @var{num} times in the test's
2919 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
2920 Passes if @var{regex} matches text in the test's demangled assembler output.
2922 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
2923 Passes if @var{regex} does not match text in the test's demangled assembler
2926 @item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
2927 Passes if @var{functions} are all in @var{section}. The caller needs to
2928 allow for @code{USER_LABEL_PREFIX} and different section name conventions.
2930 @item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
2931 Passes if @var{functions} are all in @var{section}in @var{filename}.
2932 The same caveats as for @code{scan-assembler-symbol-section} apply.
2934 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2935 Passes if @var{symbol} is defined as a hidden symbol in the test's
2938 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2939 Passes if @var{symbol} is not defined as a hidden symbol in the test's
2942 @item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @}]]
2943 Looks through the source file for comments that give the expected assembly
2944 output for selected functions. Each line of expected output starts with the
2945 prefix string @var{prefix} and the expected output for a function as a whole
2946 is followed by a line that starts with the string @var{terminator}.
2947 Specifying an empty terminator is equivalent to specifying @samp{"*/"}.
2949 @var{options}, if specified, is a list of regular expressions, each of
2950 which matches a full command-line option. A non-empty list prevents
2951 the test from running unless all of the given options are present on the
2952 command line. This can help if a source file is compiled both with
2953 and without optimization, since it is rarely useful to check the full
2954 function body for unoptimized code.
2956 The first line of the expected output for a function @var{fn} has the form:
2959 @var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}]
2962 Subsequent lines of the expected output also start with @var{prefix}.
2963 In both cases, whitespace after @var{prefix} is not significant.
2965 The test discards assembly directives such as @code{.cfi_startproc}
2966 and local label definitions such as @code{.LFB0} from the compiler's
2967 assembly output. It then matches the result against the expected
2968 output for a function as a single regular expression. This means that
2969 later lines can use backslashes to refer back to @samp{(@dots{})}
2970 captures on earlier lines. For example:
2973 /* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */
2977 ** mov (z[0-9]+\.b), w0
2978 ** add z0\.b, p0/m, z0\.b, \1
2981 svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @}
2985 ** mov (z[0-9]+\.b), b0
2986 ** add z1\.b, p0/m, z1\.b, \1
2989 svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @}
2992 checks whether the implementations of @code{add_w0_s8_m} and
2993 @code{add_b0_s8_m} match the regular expressions given. The test only
2994 runs when @samp{-DCHECK_ASM} is passed on the command line.
2996 It is possible to create non-capturing multi-line regular expression
2997 groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the
2998 @samp{(}, @samp{|} and @samp{)} on separate lines (each still using
2999 @var{prefix}). For example:
3005 ** fcmge p0\.h, p0/z, z1\.h, z0\.h
3007 ** fcmle p0\.h, p0/z, z0\.h, z1\.h
3011 svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @}
3014 checks whether @code{cmple_f16_tied} is implemented by the
3015 @code{fcmge} instruction followed by @code{ret} or by the
3016 @code{fcmle} instruction followed by @code{ret}. The test is
3017 still a single regular rexpression.
3019 A line containing just:
3025 stands for zero or more unmatched lines; the whitespace after
3026 @var{prefix} is again not significant.
3030 @subsubsection Scan optimization dump files
3032 These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree},
3033 @code{offload-tree}, @code{rtl}, @code{offload-rtl}, @code{ipa}, and
3037 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3038 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
3040 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3041 Passes if @var{regex} does not match text in the dump file with suffix
3044 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
3045 Passes if @var{regex} is found exactly @var{num} times in the dump file
3046 with suffix @var{suffix}.
3048 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3049 Passes if @var{regex} matches demangled text in the dump file with
3050 suffix @var{suffix}.
3052 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3053 Passes if @var{regex} does not match demangled text in the dump file with
3054 suffix @var{suffix}.
3057 The @var{suffix} argument which describes the dump file to be scanned
3058 may contain a glob pattern that must expand to exactly one file
3059 name. This is useful if, e.g., different pass instances are executed
3060 depending on torture testing command-line flags, producing dump files
3061 whose names differ only in their pass instance number suffix. For
3062 example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for
3063 occurrences of the string ``code has been optimized'', use:
3065 /* @{ dg-options "-fdump-tree-mypass" @} */
3066 /* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */
3070 @subsubsection Check for output files
3073 @item output-exists [@{ target/xfail @var{selector} @}]
3074 Passes if compiler output file exists.
3076 @item output-exists-not [@{ target/xfail @var{selector} @}]
3077 Passes if compiler output file does not exist.
3079 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
3080 Passes if the pattern is present in the final executable.
3082 @item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}]
3083 Passes if the pattern is absent from the final executable.
3086 @subsubsection Checks for @command{gcov} tests
3089 @item run-gcov @var{sourcefile}
3090 Check line counts in @command{gcov} tests.
3092 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
3093 Check branch and/or call counts, in addition to line counts, in
3094 @command{gcov} tests.
3096 @item run-gcov-pytest @{ @var{sourcefile} @var{pytest_file} @}
3097 Check output of @command{gcov} intermediate format with a pytest
3101 @subsubsection Clean up generated test files
3103 Usually the test-framework removes files that were generated during
3104 testing. If a testcase, for example, uses any dumping mechanism to
3105 inspect a passes dump file, the testsuite recognized the dump option
3106 passed to the tool and schedules a final cleanup to remove these files.
3108 There are, however, following additional cleanup directives that can be
3109 used to annotate a testcase "manually".
3111 @item cleanup-coverage-files
3112 Removes coverage data files generated for this test.
3114 @item cleanup-modules "@var{list-of-extra-modules}"
3115 Removes Fortran module files generated for this test, excluding the
3116 module names listed in keep-modules.
3117 Cleaning up module files is usually done automatically by the testsuite
3118 by looking at the source files and removing the modules after the test
3129 ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
3130 ! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
3133 @item keep-modules "@var{list-of-modules-not-to-delete}"
3134 Whitespace separated list of module names that should not be deleted by
3136 If the list of modules is empty, all modules defined in this file are kept.
3138 module maybe_unneeded
3139 end module maybe_unneeded
3144 ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
3145 ! @{ dg-final @{ keep-modules "" @} @} ! keep all
3148 @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}"
3149 Whitespace separated list of suffixes that should not be deleted
3150 automatically in a testcase that uses @option{-save-temps}.
3152 // @{ dg-options "-save-temps -fpch-preprocess -I." @}
3153 int main() @{ return 0; @}
3154 // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file
3155 // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i
3156 // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o
3159 @item cleanup-profile-file
3160 Removes profiling files generated for this test.
3165 @section Ada Language Testsuites
3167 The Ada testsuite includes executable tests from the ACATS
3168 testsuite, publicly available at
3169 @uref{http://www.ada-auth.org/acats.html}.
3171 These tests are integrated in the GCC testsuite in the
3172 @file{ada/acats} directory, and
3173 enabled automatically when running @code{make check}, assuming
3174 the Ada language has been enabled when configuring GCC@.
3176 You can also run the Ada testsuite independently, using
3177 @code{make check-ada}, or run a subset of the tests by specifying which
3178 chapter to run, e.g.:
3181 $ make check-ada CHAPTERS="c3 c9"
3184 The tests are organized by directory, each directory corresponding to
3185 a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
3186 to chapter 9, which deals with tasking features of the language.
3188 The tests are run using two @command{sh} scripts: @file{run_acats} and
3189 @file{run_all.sh}. To run the tests using a simulator or a cross
3190 target, see the small
3191 customization section at the top of @file{run_all.sh}.
3193 These tests are run using the build tree: they can be run without doing
3194 a @code{make install}.
3197 @section C Language Testsuites
3199 GCC contains the following C language testsuites, in the
3200 @file{gcc/testsuite} directory:
3204 This contains tests of particular features of the C compiler, using the
3205 more modern @samp{dg} harness. Correctness tests for various compiler
3206 features should go here if possible.
3208 Magic comments determine whether the file
3209 is preprocessed, compiled, linked or run. In these tests, error and warning
3210 message texts are compared against expected texts or regular expressions
3211 given in comments. These tests are run with the options @samp{-ansi -pedantic}
3212 unless other options are given in the test. Except as noted below they
3213 are not run with multiple optimization options.
3215 This subdirectory contains tests for binary compatibility using
3216 @file{lib/compat.exp}, which in turn uses the language-independent support
3217 (@pxref{compat Testing, , Support for testing binary compatibility}).
3219 This subdirectory contains tests of the preprocessor.
3221 This subdirectory contains tests for debug formats. Tests in this
3222 subdirectory are run for each debug format that the compiler supports.
3224 This subdirectory contains tests of the @option{-Wformat} format
3225 checking. Tests in this directory are run with and without
3227 @item gcc.dg/noncompile
3228 This subdirectory contains tests of code that should not compile and
3229 does not need any special compilation options. They are run with
3230 multiple optimization options, since sometimes invalid code crashes
3231 the compiler with optimization.
3232 @item gcc.dg/special
3233 FIXME: describe this.
3236 This contains particular code fragments which have historically broken easily.
3237 These tests are run with multiple optimization options, so tests for features
3238 which only break at some optimization levels belong here. This also contains
3239 tests to check that certain optimizations occur. It might be worthwhile to
3240 separate the correctness tests cleanly from the code quality tests, but
3241 it hasn't been done yet.
3243 @item gcc.c-torture/compat
3244 FIXME: describe this.
3246 This directory should probably not be used for new tests.
3247 @item gcc.c-torture/compile
3248 This testsuite contains test cases that should compile, but do not
3249 need to link or run. These test cases are compiled with several
3250 different combinations of optimization options. All warnings are
3251 disabled for these test cases, so this directory is not suitable if
3252 you wish to test for the presence or absence of compiler warnings.
3253 While special options can be set, and tests disabled on specific
3254 platforms, by the use of @file{.x} files, mostly these test cases
3255 should not contain platform dependencies. FIXME: discuss how defines
3256 such as @code{STACK_SIZE} are used.
3257 @item gcc.c-torture/execute
3258 This testsuite contains test cases that should compile, link and run;
3259 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
3260 @item gcc.c-torture/execute/ieee
3261 This contains tests which are specific to IEEE floating point.
3262 @item gcc.c-torture/unsorted
3263 FIXME: describe this.
3265 This directory should probably not be used for new tests.
3266 @item gcc.misc-tests
3267 This directory contains C tests that require special handling. Some
3268 of these tests have individual expect files, and others share
3269 special-purpose expect files:
3272 @item @code{bprob*.c}
3273 Test @option{-fbranch-probabilities} using
3274 @file{gcc.misc-tests/bprob.exp}, which
3275 in turn uses the generic, language-independent framework
3276 (@pxref{profopt Testing, , Support for testing profile-directed
3279 @item @code{gcov*.c}
3280 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
3281 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
3283 @item @code{i386-pf-*.c}
3284 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
3287 @item gcc.test-framework
3290 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
3295 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
3296 test cases and magic comments more.
3299 @section Support for testing link-time optimizations
3301 Tests for link-time optimizations usually require multiple source files
3302 that are compiled separately, perhaps with different sets of options.
3303 There are several special-purpose test directives used for these tests.
3306 @item @{ dg-lto-do @var{do-what-keyword} @}
3307 @var{do-what-keyword} specifies how the test is compiled and whether
3308 it is executed. It is one of:
3312 Compile with @option{-c} to produce a relocatable object file.
3314 Compile, assemble, and link to produce an executable file.
3316 Produce and run an executable file, which is expected to return
3320 The default is @code{assemble}. That can be overridden for a set of
3321 tests by redefining @code{dg-do-what-default} within the @code{.exp}
3322 file for those tests.
3324 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
3325 @samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
3326 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
3328 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
3329 This directive provides a list of one or more sets of compiler options
3330 to override @var{LTO_OPTIONS}. Each test will be compiled and run with
3331 each of these sets of options.
3333 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
3334 This directive adds @var{options} to the linker options used.
3336 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
3337 This directive removes @var{options} from the set of linker options used.
3341 @section Support for testing @command{gcov}
3343 Language-independent support for testing @command{gcov}, and for checking
3344 that branch profiling produces expected values, is provided by the
3345 expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
3346 in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
3347 @command{gcov} test contains the following DejaGnu commands within comments:
3350 @{ dg-options "--coverage" @}
3351 @{ dg-do run @{ target native @} @}
3352 @{ dg-final @{ run-gcov sourcefile @} @}
3355 Checks of @command{gcov} output can include line counts, branch percentages,
3356 and call return percentages. All of these checks are requested via
3357 commands that appear in comments in the test's source file.
3358 Commands to check line counts are processed by default.
3359 Commands to check branch percentages and call return percentages are
3360 processed if the @command{run-gcov} command has arguments @code{branches}
3361 or @code{calls}, respectively. For example, the following specifies
3362 checking both, as well as passing @option{-b} to @command{gcov}:
3365 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
3368 A line count command appears within a comment on the source line
3369 that is expected to get the specified count and has the form
3370 @code{count(@var{cnt})}. A test should only check line counts for
3371 lines that will get the same count for any architecture.
3373 Commands to check branch percentages (@code{branch}) and call
3374 return percentages (@code{returns}) are very similar to each other.
3375 A beginning command appears on or before the first of a range of
3376 lines that will report the percentage, and the ending command
3377 follows that range of lines. The beginning command can include a
3378 list of percentages, all of which are expected to be found within
3379 the range. A range is terminated by the next command of the same
3380 kind. A command @code{branch(end)} or @code{returns(end)} marks
3381 the end of a range without starting a new one. For example:
3384 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
3385 /* @r{branch(end)} */
3389 For a call return percentage, the value specified is the
3390 percentage of calls reported to return. For a branch percentage,
3391 the value is either the expected percentage or 100 minus that
3392 value, since the direction of a branch can differ depending on the
3393 target or the optimization level.
3395 Not all branches and calls need to be checked. A test should not
3396 check for branches that might be optimized away or replaced with
3397 predicated instructions. Don't check for calls inserted by the
3398 compiler or ones that might be inlined or optimized away.
3400 A single test can check for combinations of line counts, branch
3401 percentages, and call return percentages. The command to check a
3402 line count must appear on the line that will report that count, but
3403 commands to check branch percentages and call return percentages can
3404 bracket the lines that report them.
3406 @node profopt Testing
3407 @section Support for testing profile-directed optimizations
3409 The file @file{profopt.exp} provides language-independent support for
3410 checking correct execution of a test built with profile-directed
3411 optimization. This testing requires that a test program be built and
3412 executed twice. The first time it is compiled to generate profile
3413 data, and the second time it is compiled to use the data that was
3414 generated during the first execution. The second execution is to
3415 verify that the test produces the expected results.
3417 To check that the optimization actually generated better code, a
3418 test can be built and run a third time with normal optimizations to
3419 verify that the performance is better with the profile-directed
3420 optimizations. @file{profopt.exp} has the beginnings of this kind
3423 @file{profopt.exp} provides generic support for profile-directed
3424 optimizations. Each set of tests that uses it provides information
3425 about a specific optimization:
3429 tool being tested, e.g., @command{gcc}
3431 @item profile_option
3432 options used to generate profile data
3434 @item feedback_option
3435 options used to optimize using that profile data
3438 suffix of profile data files
3440 @item PROFOPT_OPTIONS
3441 list of options with which to run each test, similar to the lists for
3444 @item @{ dg-final-generate @{ @var{local-directive} @} @}
3445 This directive is similar to @code{dg-final}, but the
3446 @var{local-directive} is run after the generation of profile data.
3448 @item @{ dg-final-use @{ @var{local-directive} @} @}
3449 The @var{local-directive} is run after the profile data have been
3453 @node compat Testing
3454 @section Support for testing binary compatibility
3456 The file @file{compat.exp} provides language-independent support for
3457 binary compatibility testing. It supports testing interoperability of
3458 two compilers that follow the same ABI, or of multiple sets of
3459 compiler options that should not affect binary compatibility. It is
3460 intended to be used for testsuites that complement ABI testsuites.
3462 A test supported by this framework has three parts, each in a
3463 separate source file: a main program and two pieces that interact
3464 with each other to split up the functionality being tested.
3467 @item @var{testname}_main.@var{suffix}
3468 Contains the main program, which calls a function in file
3469 @file{@var{testname}_x.@var{suffix}}.
3471 @item @var{testname}_x.@var{suffix}
3472 Contains at least one call to a function in
3473 @file{@var{testname}_y.@var{suffix}}.
3475 @item @var{testname}_y.@var{suffix}
3476 Shares data with, or gets arguments from,
3477 @file{@var{testname}_x.@var{suffix}}.
3480 Within each test, the main program and one functional piece are
3481 compiled by the GCC under test. The other piece can be compiled by
3482 an alternate compiler. If no alternate compiler is specified,
3483 then all three source files are all compiled by the GCC under test.
3484 You can specify pairs of sets of compiler options. The first element
3485 of such a pair specifies options used with the GCC under test, and the
3486 second element of the pair specifies options used with the alternate
3487 compiler. Each test is compiled with each pair of options.
3489 @file{compat.exp} defines default pairs of compiler options.
3490 These can be overridden by defining the environment variable
3491 @env{COMPAT_OPTIONS} as:
3494 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
3495 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
3498 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
3499 used by the compiler under test and @var{alti} used by the alternate
3500 compiler. For example, with
3501 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
3502 the test is first built with @option{-g -O0} by the compiler under
3503 test and with @option{-O3} by the alternate compiler. The test is
3504 built a second time using @option{-fpic} by the compiler under test
3505 and @option{-fPIC -O2} by the alternate compiler.
3507 An alternate compiler is specified by defining an environment
3508 variable to be the full pathname of an installed compiler; for C
3509 define @env{ALT_CC_UNDER_TEST}, and for C++ define
3510 @env{ALT_CXX_UNDER_TEST}. These will be written to the
3511 @file{site.exp} file used by DejaGnu. The default is to build each
3512 test with the compiler under test using the first of each pair of
3513 compiler options from @env{COMPAT_OPTIONS}. When
3514 @env{ALT_CC_UNDER_TEST} or
3515 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
3516 the compiler under test but with combinations of the options from
3517 @env{COMPAT_OPTIONS}.
3519 To run only the C++ compatibility suite using the compiler under test
3520 and another version of GCC using specific compiler options, do the
3521 following from @file{@var{objdir}/gcc}:
3526 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
3527 COMPAT_OPTIONS="@var{lists as shown above}" \
3529 RUNTESTFLAGS="compat.exp"
3532 A test that fails when the source files are compiled with different
3533 compilers, but passes when the files are compiled with the same
3534 compiler, demonstrates incompatibility of the generated code or
3535 runtime support. A test that fails for the alternate compiler but
3536 passes for the compiler under test probably tests for a bug that was
3537 fixed in the compiler under test but is present in the alternate
3540 The binary compatibility tests support a small number of test framework
3541 commands that appear within comments in a test file.
3545 These commands can be used in @file{@var{testname}_main.@var{suffix}}
3546 to skip the test if specific support is not available on the target.
3549 The specified options are used for compiling this particular source
3550 file, appended to the options from @env{COMPAT_OPTIONS}. When this
3551 command appears in @file{@var{testname}_main.@var{suffix}} the options
3552 are also used to link the test program.
3555 This command can be used in a secondary source file to specify that
3556 compilation is expected to fail for particular options on particular
3561 @section Support for torture testing using multiple options
3563 Throughout the compiler testsuite there are several directories whose
3564 tests are run multiple times, each with a different set of options.
3565 These are known as torture tests.
3566 @file{lib/torture-options.exp} defines procedures to
3571 Initialize use of torture lists.
3572 @item set-torture-options
3573 Set lists of torture options to use for tests with and without loops.
3574 Optionally combine a set of torture options with a set of other
3575 options, as is done with Objective-C runtime options.
3576 @item torture-finish
3577 Finalize use of torture lists.
3580 The @file{.exp} file for a set of tests that use torture options must
3581 include calls to these three procedures if:
3584 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
3586 @item It calls @var{$@{tool@}}@code{-torture} or
3587 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
3588 @code{fortran}, or @code{objc}.
3590 @item It calls @code{dg-pch}.
3593 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
3594 to call the torture procedures if the tests should use the list in
3595 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
3597 Most uses of torture options can override the default lists by defining
3598 @var{TORTURE_OPTIONS} or add to the default list by defining
3599 @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
3600 file or add them to the @file{site.exp} file; for example
3603 set ADDITIONAL_TORTURE_OPTIONS [list \
3604 @{ -O2 -ftree-loop-linear @} \
3605 @{ -O2 -fpeel-loops @} ]
3609 @section Support for testing GIMPLE passes
3611 As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
3612 that the function body will be GIMPLE, rather than C. The compiler requires
3613 the option @option{-fgimple} to enable this functionality. For example:
3616 /* @{ dg-do compile @} */
3617 /* @{ dg-options "-O -fgimple" @} */
3619 void __GIMPLE (startwith ("dse2")) foo ()
3637 a_1 = __PHI (bb_3: a_2, bb_4: a_3);
3644 The @code{startwith} argument indicates at which pass to begin.
3646 Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple})
3647 to make tree dumps more closely follow the format accepted by the GIMPLE
3650 Example DejaGnu tests of GIMPLE can be seen in the source tree at
3651 @file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
3653 The @code{__GIMPLE} parser is integrated with the C tokenizer and
3654 preprocessor, so it should be possible to use macros to build out
3658 @section Support for testing RTL passes
3660 As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
3661 function body will be RTL, rather than C. For example:
3664 double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
3667 [...snip; various directives go in here...]
3668 ) ;; function "test"
3672 The @code{startwith} argument indicates at which pass to begin.
3674 The parser expects the RTL body to be in the format emitted by this
3679 print_rtx_function (FILE *outfile, function *fn, bool compact);
3682 when "compact" is true. So you can capture RTL in the correct format
3683 from the debugger using:
3686 (gdb) print_rtx_function (stderr, cfun, true);
3689 and copy and paste the output into the body of the C function.
3691 Example DejaGnu tests of RTL can be seen in the source tree under
3692 @file{gcc/testsuite/gcc.dg/rtl}.
3694 The @code{__RTL} parser is not integrated with the C tokenizer or
3695 preprocessor, and works simply by reading the relevant lines within
3696 the braces. In particular, the RTL body must be on separate lines from
3697 the enclosing braces, and the preprocessor is not usable within it.