1 @c Copyright (C) 2002-2022 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{https://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 Contains the sources for the g++-mapper-server, a tool used with
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.
62 Headers for the @code{libiberty} library.
65 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
66 include it in @code{libc}.
69 The Ada runtime library.
72 The runtime support library for atomic operations (e.g.@: for @code{__sync}
76 A library that allows gcc to produce backtraces when it crashes.
79 A library that allows gdb to make use of the compiler.
82 A compiler dynamism library to allow communication between compilers and
83 build systems, for purposes such as C++ modules.
86 The C preprocessor library.
89 The Decimal Float support library.
92 The @code{libffi} library, used as part of the Go runtime library.
95 The GCC runtime library.
98 The Fortran runtime library.
101 The Go runtime library. The bulk of this library is mirrored from the
102 @uref{https://github.com/@/golang/go, master Go repository}.
105 The GNU Offloading and Multi Processing Runtime Library.
108 The @code{libiberty} library, used for portability and for some
109 generally useful data structures and algorithms. @xref{Top, ,
110 Introduction, libiberty, @sc{gnu} libiberty}, for more information
114 The runtime support library for transactional memory.
117 The Objective-C and Objective-C++ runtime library.
120 A library to allow OpenMP to Intel MIC targets.
123 The D standard and runtime library. The bulk of this library is mirrored
124 from the @uref{https://github.com/@/dlang, master D repositories}.
127 The runtime support library for quad-precision math operations.
130 Libraries for various sanitizers. The bulk of this directory is mirrored
131 from the @uref{https://github.com/google/sanitizers, Google sanitizers
135 The Stack protector runtime library.
138 The C++ runtime library.
141 The vtable verification library.
144 Plugin used by the linker if link-time optimizations are enabled.
146 @item maintainer-scripts
147 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
150 The @code{zlib} compression library, used for compressing and
151 uncompressing GCC's intermediate language in LTO object files.
154 The build system in the top level directory, including how recursion
155 into subdirectories works and how building runtime libraries for
156 multilibs is handled, is documented in a separate manual, included
157 with GNU Binutils. @xref{Top, , GNU configure and build system,
158 configure, The GNU configure and build system}, for details.
161 @section The @file{gcc} Subdirectory
163 The @file{gcc} directory contains many files that are part of the C
164 sources of GCC, other files used as part of the configuration and
165 build process, and subdirectories including documentation and a
166 testsuite. The files that are sources of GCC are documented in a
167 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
170 * Subdirectories:: Subdirectories of @file{gcc}.
171 * Configuration:: The configuration process, and the files it uses.
172 * Build:: The build system in the @file{gcc} directory.
173 * Makefile:: Targets in @file{gcc/Makefile}.
174 * Library Files:: Library source files and headers under @file{gcc/}.
175 * Headers:: Headers installed by GCC.
176 * Documentation:: Building documentation in GCC.
177 * Front End:: Anatomy of a language front end.
178 * Back End:: Anatomy of a target back end.
182 @subsection Subdirectories of @file{gcc}
184 The @file{gcc} directory contains the following subdirectories:
188 Subdirectories for various languages. Directories containing a file
189 @file{config-lang.in} are language subdirectories. The contents of
190 the subdirectories @file{c} (for C), @file{cp} (for C++),
191 @file{objc} (for Objective-C), @file{objcp} (for Objective-C++),
192 and @file{lto} (for LTO) are documented in this
193 manual (@pxref{Passes, , Passes and Files of the Compiler});
194 those for other languages are not. @xref{Front End, ,
195 Anatomy of a Language Front End}, for details of the files in these
199 Source files shared between the compiler drivers (such as
200 @command{gcc}) and the compilers proper (such as @file{cc1}). If an
201 architecture defines target hooks shared between those places, it also
202 has a subdirectory in @file{common/config}. @xref{Target Structure}.
205 Configuration files for supported architectures and operating
206 systems. @xref{Back End, , Anatomy of a Target Back End}, for
207 details of the files in this directory.
210 Texinfo documentation for GCC, together with automatically generated
211 man pages and support for converting the installation manual to
212 HTML@. @xref{Documentation}.
215 System headers installed by GCC, mainly those required by the C
216 standard of freestanding implementations. @xref{Headers, , Headers
217 Installed by GCC}, for details of when these and other headers are
221 Message catalogs with translations of messages produced by GCC into
222 various languages, @file{@var{language}.po}. This directory also
223 contains @file{gcc.pot}, the template for these message catalogues,
224 @file{exgettext}, a wrapper around @command{gettext} to extract the
225 messages from the GCC sources and create @file{gcc.pot}, which is run
226 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
227 which messages should not be extracted.
230 The GCC testsuites (except for those for runtime libraries).
235 @subsection Configuration in the @file{gcc} Directory
237 The @file{gcc} directory is configured with an Autoconf-generated
238 script @file{configure}. The @file{configure} script is generated
239 from @file{configure.ac} and @file{aclocal.m4}. From the files
240 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
241 file @file{config.in}. The file @file{cstamp-h.in} is used as a
245 * Config Fragments:: Scripts used by @file{configure}.
246 * System Config:: The @file{config.build}, @file{config.host}, and
247 @file{config.gcc} files.
248 * Configuration Files:: Files created by running @file{configure}.
251 @node Config Fragments
252 @subsubsection Scripts Used by @file{configure}
254 @file{configure} uses some other scripts to help in its work:
257 @item The standard GNU @file{config.sub} and @file{config.guess}
258 files, kept in the top level directory, are used.
260 @item The file @file{config.gcc} is used to handle configuration
261 specific to the particular target machine. The file
262 @file{config.build} is used to handle configuration specific to the
263 particular build machine. The file @file{config.host} is used to handle
264 configuration specific to the particular host machine. (In general,
265 these should only be used for features that cannot reasonably be tested in
266 Autoconf feature tests.)
267 @xref{System Config, , The @file{config.build}; @file{config.host};
268 and @file{config.gcc} Files}, for details of the contents of these files.
270 @item Each language subdirectory has a file
271 @file{@var{language}/config-lang.in} that is used for
272 front-end-specific configuration. @xref{Front End Config, , The Front
273 End @file{config-lang.in} File}, for details of this file.
275 @item A helper script @file{configure.frag} is used as part of
276 creating the output of @file{configure}.
280 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
282 The @file{config.build} file contains specific rules for particular systems
283 which GCC is built on. This should be used as rarely as possible, as the
284 behavior of the build system can always be detected by autoconf.
286 The @file{config.host} file contains specific rules for particular systems
287 which GCC will run on. This is rarely needed.
289 The @file{config.gcc} file contains specific rules for particular systems
290 which GCC will generate code for. This is usually needed.
292 Each file has a list of the shell variables it sets, with descriptions, at the
295 FIXME: document the contents of these files, and what variables should
296 be set to control build, host and target configuration.
298 @include configfiles.texi
301 @subsection Build System in the @file{gcc} Directory
303 FIXME: describe the build system, including what is built in what
304 stages. Also list the various source files that are used in the build
305 process but aren't source files of GCC itself and so aren't documented
306 below (@pxref{Passes}).
308 @include makefile.texi
311 @subsection Library Source Files and Headers under the @file{gcc} Directory
313 FIXME: list here, with explanation, all the C source files and headers
314 under the @file{gcc} directory that aren't built into the GCC
315 executable but rather are part of runtime libraries and object files,
316 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
317 Headers Installed by GCC}, for more information about the
318 @file{ginclude} directory.
321 @subsection Headers Installed by GCC
323 In general, GCC expects the system C library to provide most of the
324 headers to be used with it. However, GCC will fix those headers if
325 necessary to make them work with GCC, and will install some headers
326 required of freestanding implementations. These headers are installed
327 in @file{@var{libsubdir}/include}. Headers for non-C runtime
328 libraries are also installed by GCC; these are not documented here.
329 (FIXME: document them somewhere.)
331 Several of the headers GCC installs are in the @file{ginclude}
332 directory. These headers, @file{iso646.h},
333 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
334 are installed in @file{@var{libsubdir}/include},
335 unless the target Makefile fragment (@pxref{Target Fragment})
336 overrides this by setting @code{USER_H}.
338 In addition to these headers and those generated by fixing system
339 headers to work with GCC, some other headers may also be installed in
340 @file{@var{libsubdir}/include}. @file{config.gcc} may set
341 @code{extra_headers}; this specifies additional headers under
342 @file{config} to be installed on some systems.
344 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
345 This is done to cope with command-line options that change the
346 representation of floating point numbers.
348 GCC also installs its own version of @code{<limits.h>}; this is generated
349 from @file{glimits.h}, together with @file{limitx.h} and
350 @file{limity.h} if the system also has its own version of
351 @code{<limits.h>}. (GCC provides its own header because it is
352 required of ISO C freestanding implementations, but needs to include
353 the system header from its own header as well because other standards
354 such as POSIX specify additional values to be defined in
355 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
356 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
357 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
358 needs fixing, @file{syslimits.h} is the fixed copy.
360 GCC can also install @code{<tgmath.h>}. It will do this when
361 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
364 @subsection Building Documentation
366 The main GCC documentation is in the form of manuals in Texinfo
367 format. These are installed in Info format; DVI versions may be
368 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
369 HTML versions by @samp{make html}. In addition, some man pages are
370 generated from the Texinfo manuals, there are some other text files
371 with miscellaneous documentation, and runtime libraries have their own
372 documentation outside the @file{gcc} directory. FIXME: document the
373 documentation for runtime libraries somewhere.
376 * Texinfo Manuals:: GCC manuals in Texinfo format.
377 * Man Page Generation:: Generating man pages from Texinfo manuals.
378 * Miscellaneous Docs:: Miscellaneous text files with documentation.
381 @node Texinfo Manuals
382 @subsubsection Texinfo Manuals
384 The manuals for GCC as a whole, and the C and C++ front ends, are in
385 files @file{doc/*.texi}. Other front ends have their own manuals in
386 files @file{@var{language}/*.texi}. Common files
387 @file{doc/include/*.texi} are provided which may be included in
388 multiple manuals; the following files are in @file{doc/include}:
392 The GNU Free Documentation License.
394 The section ``Funding Free Software''.
395 @item gcc-common.texi
396 Common definitions for manuals.
398 The GNU General Public License.
400 A copy of @file{texinfo.tex} known to work with the GCC manuals.
403 DVI-formatted manuals are generated by @samp{make dvi}, which uses
404 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
405 PDF-formatted manuals are generated by @samp{make pdf}, which uses
406 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
407 formatted manuals are generated by @samp{make html}. Info
408 manuals are generated by @samp{make info} (which is run as part of
409 a bootstrap); this generates the manuals in the source directory,
410 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
411 and they are included in release distributions.
413 Manuals are also provided on the GCC web site, in both HTML and
414 PostScript forms. This is done via the script
415 @file{maintainer-scripts/update_web_docs_git}. Each manual to be
416 provided online must be listed in the definition of @code{MANUALS} in
417 that file; a file @file{@var{name}.texi} must only appear once in the
418 source tree, and the output manual must have the same name as the
419 source file. (However, other Texinfo files, included in manuals but
420 not themselves the root files of manuals, may have names that appear
421 more than once in the source tree.) The manual file
422 @file{@var{name}.texi} should only include other files in its own
423 directory or in @file{doc/include}. HTML manuals will be generated by
424 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
425 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
426 All Texinfo files that are parts of manuals must
427 be version-controlled, even if they are generated files, for the
428 generation of online manuals to work.
430 The installation manual, @file{doc/install.texi}, is also provided on
431 the GCC web site. The HTML version is generated by the script
432 @file{doc/install.texi2html}.
434 @node Man Page Generation
435 @subsubsection Man Page Generation
437 Because of user demand, in addition to full Texinfo manuals, man pages
438 are provided which contain extracts from those manuals. These man
439 pages are generated from the Texinfo manuals using
440 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
441 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
442 to @file{gcc.1}, but all the other man pages are generated from
445 Because many systems may not have the necessary tools installed to
446 generate the man pages, they are only generated if the
447 @file{configure} script detects that recent enough tools are
448 installed, and the Makefiles allow generating man pages to fail
449 without aborting the build. Man pages are also included in release
450 distributions. They are generated in the source directory.
452 Magic comments in Texinfo files starting @samp{@@c man} control what
453 parts of a Texinfo file go into a man page. Only a subset of Texinfo
454 is supported by @file{texi2pod.pl}, and it may be necessary to add
455 support for more Texinfo features to this script when generating new
456 man pages. To improve the man page output, some special Texinfo
457 macros are provided in @file{doc/include/gcc-common.texi} which
458 @file{texi2pod.pl} understands:
462 Use in the form @samp{@@table @@gcctabopt} for tables of options,
463 where for printed output the effect of @samp{@@code} is better than
464 that of @samp{@@option} but for man page output a different effect is
467 Use for summary lists of options in manuals.
469 Use at the end of each line inside @samp{@@gccoptlist}. This is
470 necessary to avoid problems with differences in how the
471 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
474 FIXME: describe the @file{texi2pod.pl} input language and magic
475 comments in more detail.
477 @node Miscellaneous Docs
478 @subsubsection Miscellaneous Documentation
480 In addition to the formal documentation that is installed by GCC,
481 there are several other text files in the @file{gcc} subdirectory
482 with miscellaneous documentation:
486 Notes on GCC's Native Language Support. FIXME: this should be part of
487 this manual rather than a separate file.
489 Notes on the Free Translation Project.
492 The GNU General Public License, Versions 2 and 3.
495 The GNU Lesser General Public License, Versions 2.1 and 3.
498 Change log files for various parts of GCC@.
500 Details of a few changes to the GCC front-end interface. FIXME: the
501 information in this file should be part of general documentation of
502 the front-end interface in this manual.
504 Information about new features in old versions of GCC@. (For recent
505 versions, the information is on the GCC web site.)
506 @item README.Portability
507 Information about portability issues when writing code in GCC@. FIXME:
508 why isn't this part of this manual or of the GCC Coding Conventions?
511 FIXME: document such files in subdirectories, at least @file{config},
512 @file{c}, @file{cp}, @file{objc}, @file{testsuite}.
515 @subsection Anatomy of a Language Front End
517 A front end for a language in GCC has the following parts:
521 A directory @file{@var{language}} under @file{gcc} containing source
522 files for that front end. @xref{Front End Directory, , The Front End
523 @file{@var{language}} Directory}, for details.
525 A mention of the language in the list of supported languages in
526 @file{gcc/doc/install.texi}.
528 A mention of the name under which the language's runtime library is
529 recognized by @option{--enable-shared=@var{package}} in the
530 documentation of that option in @file{gcc/doc/install.texi}.
532 A mention of any special prerequisites for building the front end in
533 the documentation of prerequisites in @file{gcc/doc/install.texi}.
535 Details of contributors to that front end in
536 @file{gcc/doc/contrib.texi}. If the details are in that front end's
537 own manual then there should be a link to that manual's list in
540 Information about support for that language in
541 @file{gcc/doc/frontends.texi}.
543 Information about standards for that language, and the front end's
544 support for them, in @file{gcc/doc/standards.texi}. This may be a
545 link to such information in the front end's own manual.
547 Details of source file suffixes for that language and @option{-x
548 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
550 Entries in @code{default_compilers} in @file{gcc.cc} for source file
551 suffixes for that language.
553 Preferably testsuites, which may be under @file{gcc/testsuite} or
554 runtime library directories. FIXME: document somewhere how to write
557 Probably a runtime library for the language, outside the @file{gcc}
558 directory. FIXME: document this further.
560 Details of the directories of any runtime libraries in
561 @file{gcc/doc/sourcebuild.texi}.
563 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
564 to check just the compiler or the compiler and runtime library for the
568 If the front end is added to the official GCC source repository, the
569 following are also necessary:
573 At least one Bugzilla component for bugs in that front end and runtime
574 libraries. This category needs to be added to the Bugzilla database.
576 Normally, one or more maintainers of that front end listed in
579 Mentions on the GCC web site in @file{index.html} and
580 @file{frontends.html}, with any relevant links on
581 @file{readings.html}. (Front ends that are not an official part of
582 GCC may also be listed on @file{frontends.html}, with relevant links.)
584 A news item on @file{index.html}, and possibly an announcement on the
585 @email{gcc-announce@@gcc.gnu.org} mailing list.
587 The front end's manuals should be mentioned in
588 @file{maintainer-scripts/update_web_docs_git} (@pxref{Texinfo Manuals})
589 and the online manuals should be linked to from
590 @file{onlinedocs/index.html}.
592 Any old releases or CVS repositories of the front end, before its
593 inclusion in GCC, should be made available on the GCC web site at
594 @uref{https://gcc.gnu.org/pub/gcc/old-releases/}.
596 The release and snapshot script @file{maintainer-scripts/gcc_release}
597 should be updated to generate appropriate tarballs for this front end.
599 If this front end includes its own version files that include the
600 current date, @file{maintainer-scripts/update_version} should be
605 * Front End Directory:: The front end @file{@var{language}} directory.
606 * Front End Config:: The front end @file{config-lang.in} file.
607 * Front End Makefile:: The front end @file{Make-lang.in} file.
610 @node Front End Directory
611 @subsubsection The Front End @file{@var{language}} Directory
613 A front end @file{@var{language}} directory contains the source files
614 of that front end (but not of any runtime libraries, which should be
615 outside the @file{gcc} directory). This includes documentation, and
616 possibly some subsidiary programs built alongside the front end.
617 Certain files are special and other parts of the compiler depend on
622 This file is required in all language subdirectories. @xref{Front End
623 Config, , The Front End @file{config-lang.in} File}, for details of
626 This file is required in all language subdirectories. @xref{Front End
627 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
630 This file registers the set of switches that the front end accepts on
631 the command line, and their @option{--help} text. @xref{Options}.
633 This file provides entries for @code{default_compilers} in
634 @file{gcc.cc} which override the default of giving an error that a
635 compiler for that language is not installed.
636 @item @var{language}-tree.def
637 This file, which need not exist, defines any language-specific tree
641 @node Front End Config
642 @subsubsection The Front End @file{config-lang.in} File
644 Each language subdirectory contains a @file{config-lang.in} file.
645 This file is a shell script that may define some variables describing
650 This definition must be present, and gives the name of the language
651 for some purposes such as arguments to @option{--enable-languages}.
653 If defined, this variable lists (space-separated) language front ends
654 other than C that this front end requires to be enabled (with the
655 names given being their @code{language} settings). For example, the
656 Obj-C++ front end depends on the C++ and ObjC front ends, so sets
657 @samp{lang_requires="objc c++"}.
658 @item subdir_requires
659 If defined, this variable lists (space-separated) front end directories
660 other than C that this front end requires to be present. For example,
661 the Objective-C++ front end uses source files from the C++ and
662 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
664 If defined, this variable lists (space-separated) targets in the top
665 level @file{Makefile} to build the runtime libraries for this
666 language, such as @code{target-libobjc}.
668 If defined, this variable lists (space-separated) top level
669 directories (parallel to @file{gcc}), apart from the runtime libraries,
670 that should not be configured if this front end is not built.
671 @item build_by_default
672 If defined to @samp{no}, this language front end is not built unless
673 enabled in a @option{--enable-languages} argument. Otherwise, front
674 ends are built by default, subject to any special logic in
675 @file{configure.ac} (as is present to disable the Ada front end if the
676 Ada compiler is not already installed).
678 If defined to @samp{yes}, this front end is built in stage1 of the
679 bootstrap. This is only relevant to front ends written in their own
682 If defined, a space-separated list of compiler executables that will
683 be run by the driver. The names here will each end
684 with @samp{\$(exeext)}.
686 If defined, a space-separated list of files that should be generated
687 by @file{configure} substituting values in them. This mechanism can
688 be used to create a file @file{@var{language}/Makefile} from
689 @file{@var{language}/Makefile.in}, but this is deprecated, building
690 everything from the single @file{gcc/Makefile} is preferred.
692 If defined, a space-separated list of files that should be scanned by
693 @file{gengtype.cc} to generate the garbage collection tables and routines for
694 this language. This excludes the files that are common to all front
695 ends. @xref{Type Information}.
699 @node Front End Makefile
700 @subsubsection The Front End @file{Make-lang.in} File
702 Each language subdirectory contains a @file{Make-lang.in} file. It contains
703 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
704 setting of @code{language} in @file{config-lang.in}) for the following
705 values of @code{@var{hook}}, and any other Makefile rules required to
706 build those targets (which may if necessary use other Makefiles
707 specified in @code{outputs} in @file{config-lang.in}, although this is
708 deprecated). It also adds any testsuite targets that can use the
709 standard rule in @file{gcc/Makefile.in} to the variable
716 FIXME: exactly what goes in each of these targets?
718 Build an @command{etags} @file{TAGS} file in the language subdirectory
721 Build info documentation for the front end, in the build directory.
722 This target is only called by @samp{make bootstrap} if a suitable
723 version of @command{makeinfo} is available, so does not need to check
724 for this, and should fail if an error occurs.
726 Build DVI documentation for the front end, in the build directory.
727 This should be done using @code{$(TEXI2DVI)}, with appropriate
728 @option{-I} arguments pointing to directories of included files.
730 Build PDF documentation for the front end, in the build directory.
731 This should be done using @code{$(TEXI2PDF)}, with appropriate
732 @option{-I} arguments pointing to directories of included files.
734 Build HTML documentation for the front end, in the build directory.
736 Build generated man pages for the front end from Texinfo manuals
737 (@pxref{Man Page Generation}), in the build directory. This target
738 is only called if the necessary tools are available, but should ignore
739 errors so as not to stop the build if errors occur; man pages are
740 optional and the tools involved may be installed in a broken way.
742 Install everything that is part of the front end, apart from the
743 compiler executables listed in @code{compilers} in
744 @file{config-lang.in}.
746 Install info documentation for the front end, if it is present in the
747 source directory. This target should have dependencies on info files
748 that should be installed.
750 Install man pages for the front end. This target should ignore
753 Install headers needed for plugins.
755 Copies its dependencies into the source directory. This generally should
756 be used for generated files such as Bison output files which are not
757 version-controlled, but should be included in any release tarballs. This
758 target will be executed during a bootstrap if
759 @samp{--enable-generated-files-in-srcdir} was specified as a
760 @file{configure} option.
763 Copies its dependencies into the source directory. These targets will be
764 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
765 was specified as a @file{configure} option.
767 Uninstall files installed by installing the compiler. This is
768 currently documented not to be supported, so the hook need not do
773 @itemx maintainer-clean
774 The language parts of the standard GNU
775 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
776 Users, standards, GNU Coding Standards}, for details of the standard
777 targets. For GCC, @code{maintainer-clean} should delete
778 all generated files in the source directory that are not version-controlled,
779 but should not delete anything that is.
782 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
783 to a list of host object files that are used by that language.
786 @subsection Anatomy of a Target Back End
788 A back end for a target architecture in GCC has the following parts:
792 A directory @file{@var{machine}} under @file{gcc/config}, containing a
793 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
794 , Machine Descriptions}), header files @file{@var{machine}.h} and
795 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
796 (@pxref{Target Macros, , Target Description Macros and Functions}),
797 possibly a target Makefile fragment @file{t-@var{machine}}
798 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
799 some other files. The names of these files may be changed from the
800 defaults given by explicit specifications in @file{config.gcc}.
802 If necessary, a file @file{@var{machine}-modes.def} in the
803 @file{@var{machine}} directory, containing additional machine modes to
804 represent condition codes. @xref{Condition Code}, for further details.
806 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
807 directory, containing a list of target-specific options. You can also
808 add other option files using the @code{extra_options} variable in
809 @file{config.gcc}. @xref{Options}.
811 Entries in @file{config.gcc} (@pxref{System Config, , The
812 @file{config.gcc} File}) for the systems with this target
815 Documentation in @file{gcc/doc/invoke.texi} for any command-line
816 options supported by this target (@pxref{Run-time Target, , Run-time
817 Target Specification}). This means both entries in the summary table
818 of options and details of the individual options.
820 Documentation in @file{gcc/doc/extend.texi} for any target-specific
821 attributes supported (@pxref{Target Attributes, , Defining
822 target-specific uses of @code{__attribute__}}), including where the
823 same attribute is already supported on some targets, which are
824 enumerated in the manual.
826 Documentation in @file{gcc/doc/extend.texi} for any target-specific
829 Documentation in @file{gcc/doc/extend.texi} of any target-specific
830 built-in functions supported.
832 Documentation in @file{gcc/doc/extend.texi} of any target-specific
833 format checking styles supported.
835 Documentation in @file{gcc/doc/md.texi} of any target-specific
836 constraint letters (@pxref{Machine Constraints, , Constraints for
837 Particular Machines}).
839 A note in @file{gcc/doc/contrib.texi} under the person or people who
840 contributed the target support.
842 Entries in @file{gcc/doc/install.texi} for all target triplets
843 supported with this target architecture, giving details of any special
844 notes about installation for this target, or saying that there are no
845 special notes if there are none.
847 Possibly other support outside the @file{gcc} directory for runtime
848 libraries. FIXME: reference docs for this. The @code{libstdc++} porting
849 manual needs to be installed as info for this to work, or to be a
850 chapter of this manual.
853 The @file{@var{machine}.h} header is included very early in GCC's
854 standard sequence of header files, while @file{@var{machine}-protos.h}
855 is included late in the sequence. Thus @file{@var{machine}-protos.h}
856 can include declarations referencing types that are not defined when
857 @file{@var{machine}.h} is included, specifically including those from
858 @file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not
859 be available in every context where @file{@var{machine}-protos.h} is
860 included, in this file you should guard declarations using these types
861 inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE}
862 conditional code segments.
864 If the backend uses shared data structures that require @code{GTY} markers
865 for garbage collection (@pxref{Type Information}), you must declare those
866 in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}.
867 Any definitions required for building libgcc must also go in
868 @file{@var{machine}.h}.
870 GCC uses the macro @code{IN_TARGET_CODE} to distinguish between
871 machine-specific @file{.c} and @file{.cc} files and
872 machine-independent @file{.c} and @file{.cc} files. Machine-specific
873 files should use the directive:
876 #define IN_TARGET_CODE 1
879 before including @code{config.h}.
881 If the back end is added to the official GCC source repository, the
882 following are also necessary:
886 An entry for the target architecture in @file{readings.html} on the
887 GCC web site, with any relevant links.
889 Details of the properties of the back end and target architecture in
890 @file{backends.html} on the GCC web site.
892 A news item about the contribution of support for that target
893 architecture, in @file{index.html} on the GCC web site.
895 Normally, one or more maintainers of that target listed in
896 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
897 but it would be unusual to add support for a target that does not have
898 a maintainer when support is added.
900 Target triplets covering all @file{config.gcc} stanzas for the target,
901 in the list in @file{contrib/config-list.mk}.
907 GCC contains several testsuites to help maintain compiler quality.
908 Most of the runtime libraries and language front ends in GCC have
909 testsuites. Currently only the C language testsuites are documented
910 here; FIXME: document the others.
913 * Test Idioms:: Idioms used in testsuite code.
914 * Test Directives:: Directives used within DejaGnu tests.
915 * Ada Tests:: The Ada language testsuites.
916 * C Tests:: The C language testsuites.
917 * LTO Testing:: Support for testing link-time optimizations.
918 * gcov Testing:: Support for testing gcov.
919 * profopt Testing:: Support for testing profile-directed optimizations.
920 * compat Testing:: Support for testing binary compatibility.
921 * Torture Tests:: Support for torture testing using multiple options.
922 * GIMPLE Tests:: Support for testing GIMPLE passes.
923 * RTL Tests:: Support for testing RTL passes.
927 @section Idioms Used in Testsuite Code
929 In general, C testcases have a trailing @file{-@var{n}.c}, starting
930 with @file{-1.c}, in case other testcases with similar names are added
931 later. If the test is a test of some well-defined feature, it should
932 have a name referring to that feature such as
933 @file{@var{feature}-1.c}. If it does not test a well-defined feature
934 but just happens to exercise a bug somewhere in the compiler, and a
935 bug report has been filed for this bug in the GCC bug database,
936 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
937 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
938 and previously more generally, test cases are named after the date on
939 which they were added. This allows people to tell at a glance whether
940 a test failure is because of a recently found bug that has not yet
941 been fixed, or whether it may be a regression, but does not give any
942 other information about the bug or where discussion of it may be
943 found. Some other language testsuites follow similar conventions.
945 In the @file{gcc.dg} testsuite, it is often necessary to test that an
946 error is indeed a hard error and not just a warning---for example,
947 where it is a constraint violation in the C standard, which must
948 become an error with @option{-pedantic-errors}. The following idiom,
949 where the first line shown is line @var{line} of the file and the line
950 that generates the error, is used for this:
953 /* @{ dg-bogus "warning" "warning in place of error" @} */
954 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
957 It may be necessary to check that an expression is an integer constant
958 expression and has a certain value. To check that @code{@var{E}} has
959 value @code{@var{V}}, an idiom similar to the following is used:
962 char x[((E) == (V) ? 1 : -1)];
965 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
966 assertions about the types of expressions. See, for example,
967 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
968 exact rules for the types of conditional expressions in the C
969 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
971 It is useful to be able to test that optimizations are being made
972 properly. This cannot be done in all cases, but it can be done where
973 the optimization will lead to code being optimized away (for example,
974 where flow analysis or alias analysis should show that certain code
975 cannot be called) or to functions not being called because they have
976 been expanded as built-in functions. Such tests go in
977 @file{gcc.c-torture/execute}. Where code should be optimized away, a
978 call to a nonexistent function such as @code{link_failure ()} may be
979 inserted; a definition
992 will also be needed so that linking still succeeds when the test is
993 run without optimization. When all calls to a built-in function
994 should have been optimized and no calls to the non-built-in version of
995 the function should remain, that function may be defined as
996 @code{static} to call @code{abort ()} (although redeclaring a function
997 as static may not work on all targets).
999 All testcases must be portable. Target-specific testcases must have
1000 appropriate code to avoid causing failures on unsupported systems;
1001 unfortunately, the mechanisms for this differ by directory.
1003 FIXME: discuss non-C testsuites here.
1005 @node Test Directives
1006 @section Directives used within DejaGnu tests
1009 * Directives:: Syntax and descriptions of test directives.
1010 * Selectors:: Selecting targets to which a test applies.
1011 * Effective-Target Keywords:: Keywords describing target attributes.
1012 * Add Options:: Features for @code{dg-add-options}
1013 * Require Support:: Variants of @code{dg-require-@var{support}}
1014 * Final Actions:: Commands for use in @code{dg-final}
1018 @subsection Syntax and Descriptions of test directives
1020 Test directives appear within comments in a test source file and begin
1021 with @code{dg-}. Some of these are defined within DejaGnu and others
1022 are local to the GCC testsuite.
1024 The order in which test directives appear in a test can be important:
1025 directives local to GCC sometimes override information used by the
1026 DejaGnu directives, which know nothing about the GCC directives, so the
1027 DejaGnu directives must precede GCC directives.
1029 Several test directives include selectors (@pxref{Selectors, , })
1030 which are usually preceded by the keyword @code{target} or @code{xfail}.
1032 @subsubsection Specify how to build the test
1035 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
1036 @var{do-what-keyword} specifies how the test is compiled and whether
1037 it is executed. It is one of:
1041 Compile with @option{-E} to run only the preprocessor.
1043 Compile with @option{-S} to produce an assembly code file.
1045 Compile with @option{-c} to produce a relocatable object file.
1047 Compile, assemble, and link to produce an executable file.
1049 Produce and run an executable file, which is expected to return
1053 The default is @code{compile}. That can be overridden for a set of
1054 tests by redefining @code{dg-do-what-default} within the @code{.exp}
1055 file for those tests.
1057 If the directive includes the optional @samp{@{ target @var{selector} @}}
1058 then the test is skipped unless the target system matches the
1061 If @var{do-what-keyword} is @code{run} and the directive includes
1062 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1063 then the test is expected to fail. The @code{xfail} clause is ignored
1064 for other values of @var{do-what-keyword}; those tests can use
1065 directive @code{dg-xfail-if}.
1068 @subsubsection Specify additional compiler options
1071 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1072 This DejaGnu directive provides a list of compiler options, to be used
1073 if the target system matches @var{selector}, that replace the default
1074 options used for this set of tests.
1076 @item @{ dg-add-options @var{feature} @dots{} @}
1077 Add any compiler options that are needed to access certain features.
1078 This directive does nothing on targets that enable the features by
1079 default, or that don't provide them at all. It must come after
1080 all @code{dg-options} directives.
1081 For supported values of @var{feature} see @ref{Add Options, ,}.
1083 @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
1084 This directive provides a list of compiler options, to be used
1085 if the target system matches @var{selector}, that are added to the default
1086 options used for this set of tests.
1089 @subsubsection Modify the test timeout value
1091 The normal timeout limit, in seconds, is found by searching the
1095 @item the value defined by an earlier @code{dg-timeout} directive in
1098 @item variable @var{tool_timeout} defined by the set of tests
1100 @item @var{gcc},@var{timeout} set in the target board
1106 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1107 Set the time limit for the compilation and for the execution of the test
1108 to the specified number of seconds.
1110 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1111 Multiply the normal time limit for compilation and execution of the test
1112 by the specified floating-point factor.
1115 @subsubsection Skip a test for some targets
1118 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1119 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1120 each element is a string of zero or more GCC options.
1121 Skip the test if all of the following conditions are met:
1123 @item the test system is included in @var{selector}
1125 @item for at least one of the option strings in @var{include-opts},
1126 every option from that string is in the set of options with which
1127 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1128 that matches any options; that is the default if @var{include-opts} is
1131 @item for each of the option strings in @var{exclude-opts}, at least one
1132 option from that string is not in the set of options with which the test
1133 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1134 that is the default if @var{exclude-opts} is not specified
1137 For example, to skip a test if option @code{-Os} is present:
1140 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
1143 To skip a test if both options @code{-O2} and @code{-g} are present:
1146 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
1149 To skip a test if either @code{-O2} or @code{-O3} is present:
1152 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
1155 To skip a test unless option @code{-Os} is present:
1158 /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
1161 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1162 but not if @code{-fpic} is also present:
1165 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1168 @item @{ dg-require-effective-target @var{keyword} [@{ target @var{selector} @}] @}
1169 Skip the test if the test target, including current multilib flags,
1170 is not covered by the effective-target keyword.
1171 If the directive includes the optional @samp{@{ @var{selector} @}}
1172 then the effective-target test is only performed if the target system
1173 matches the @var{selector}.
1174 This directive must appear after any @code{dg-do} directive in the test
1175 and before any @code{dg-additional-sources} directive.
1176 @xref{Effective-Target Keywords, , }.
1178 @item @{ dg-require-@var{support} args @}
1179 Skip the test if the target does not provide the required support.
1180 These directives must appear after any @code{dg-do} directive in the test
1181 and before any @code{dg-additional-sources} directive.
1182 They require at least one argument, which can be an empty string if the
1183 specific procedure does not examine the argument.
1184 @xref{Require Support, , }, for a complete list of these directives.
1187 @subsubsection Expect a test to fail for some targets
1190 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1191 Expect the test to fail if the conditions (which are the same as for
1192 @code{dg-skip-if}) are met. This does not affect the execute step.
1194 @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1195 Expect the execute step of a test to fail if the conditions (which are
1196 the same as for @code{dg-skip-if}) are met.
1199 @subsubsection Expect the compiler to crash
1202 @item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1203 Expect the compiler to crash with an internal compiler error and return
1204 a nonzero exit status if the conditions (which are the same as for
1205 @code{dg-skip-if}) are met. Used for tests that test bugs that have not been
1209 @subsubsection Expect the test executable to fail
1212 @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1213 Expect the test executable to return a nonzero exit status if the
1214 conditions (which are the same as for @code{dg-skip-if}) are met.
1217 @subsubsection Verify compiler messages
1218 Where @var{line} is an accepted argument for these commands, a value of @samp{0}
1219 can be used if there is no line associated with the message.
1222 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1223 This DejaGnu directive appears on a source line that is expected to get
1224 an error message, or else specifies the source line associated with the
1225 message. If there is no message for that line or if the text of that
1226 message is not matched by @var{regexp} then the check fails and
1227 @var{comment} is included in the @code{FAIL} message. The check does
1228 not look for the string @samp{error} unless it is part of @var{regexp}.
1230 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1231 This DejaGnu directive appears on a source line that is expected to get
1232 a warning message, or else specifies the source line associated with the
1233 message. If there is no message for that line or if the text of that
1234 message is not matched by @var{regexp} then the check fails and
1235 @var{comment} is included in the @code{FAIL} message. The check does
1236 not look for the string @samp{warning} unless it is part of @var{regexp}.
1238 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1239 The line is expected to get a message other than an error or warning.
1240 If there is no message for that line or if the text of that message is
1241 not matched by @var{regexp} then the check fails and @var{comment} is
1242 included in the @code{FAIL} message.
1244 @item @{ dg-note @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1245 The line is expected to get a @samp{note} message.
1246 If there is no message for that line or if the text of that message is
1247 not matched by @var{regexp} then the check fails and @var{comment} is
1248 included in the @code{FAIL} message.
1250 By default, any @emph{excess} @samp{note} messages are pruned, meaning
1251 their appearance doesn't trigger @emph{excess errors}.
1252 However, if @samp{dg-note} is used at least once in a testcase,
1253 they're not pruned and instead must @emph{all} be handled explicitly.
1254 Thus, if looking for just single instances of messages with
1255 @samp{note: } prefixes without caring for all of them, use
1256 @samp{dg-message "note: [@dots{}]"} instead of @samp{dg-note}, or use
1257 @samp{dg-note} together with @samp{dg-prune-output "note: "}.
1259 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1260 This DejaGnu directive appears on a source line that should not get a
1261 message matching @var{regexp}, or else specifies the source line
1262 associated with the bogus message. It is usually used with @samp{xfail}
1263 to indicate that the message is a known problem for a particular set of
1266 @item @{ dg-line @var{linenumvar} @}
1267 This DejaGnu directive sets the variable @var{linenumvar} to the line number of
1268 the source line. The variable @var{linenumvar} can then be used in subsequent
1269 @code{dg-error}, @code{dg-warning}, @code{dg-message}, @code{dg-note}
1271 directives. For example:
1274 int a; /* @{ dg-line first_def_a @} */
1275 float a; /* @{ dg-error "conflicting types of" @} */
1276 /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */
1279 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1280 This DejaGnu directive indicates that the test is expected to fail due
1281 to compiler messages that are not handled by @samp{dg-error},
1282 @samp{dg-warning}, @code{dg-message}, @samp{dg-note} or
1284 For this directive @samp{xfail}
1285 has the same effect as @samp{target}.
1287 @item @{ dg-prune-output @var{regexp} @}
1288 Prune messages matching @var{regexp} from the test output.
1291 @subsubsection Verify output of the test executable
1294 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1295 This DejaGnu directive compares @var{regexp} to the combined output
1296 that the test executable writes to @file{stdout} and @file{stderr}.
1299 @subsubsection Specify environment variables for a test
1302 @item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @}
1303 Specify that the environment variable @var{var_name} needs to be set
1304 to @var{var_value} before invoking the compiler on the test file.
1306 @item @{ dg-set-target-env-var @var{var_name} "@var{var_value}" @}
1307 Specify that the environment variable @var{var_name} needs to be set
1308 to @var{var_value} before execution of the program created by the test.
1311 @subsubsection Specify additional files for a test
1314 @item @{ dg-additional-files "@var{filelist}" @}
1315 Specify additional files, other than source files, that must be copied
1316 to the system where the compiler runs.
1318 @item @{ dg-additional-sources "@var{filelist}" @}
1319 Specify additional source files to appear in the compile line
1320 following the main test file.
1323 @subsubsection Add checks at the end of a test
1326 @item @{ dg-final @{ @var{local-directive} @} @}
1327 This DejaGnu directive is placed within a comment anywhere in the
1328 source file and is processed after the test has been compiled and run.
1329 Multiple @samp{dg-final} commands are processed in the order in which
1330 they appear in the source file. @xref{Final Actions, , }, for a list
1331 of directives that can be used within @code{dg-final}.
1335 @subsection Selecting targets to which a test applies
1337 Several test directives include @var{selector}s to limit the targets
1338 for which a test is run or to declare that a test is expected to fail
1339 on particular targets.
1343 @item one or more target triplets, possibly including wildcard characters;
1344 use @samp{*-*-*} to match any target
1345 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1346 @item a list of compiler options that should be included or excluded
1347 (as described in more detail below)
1348 @item a logical expression
1351 Depending on the context, the selector specifies whether a test is
1352 skipped and reported as unsupported or is expected to fail. A context
1353 that allows either @samp{target} or @samp{xfail} also allows
1354 @samp{@{ target @var{selector1} xfail @var{selector2} @}}
1355 to skip the test for targets that don't match @var{selector1} and the
1356 test to fail for targets that match @var{selector2}.
1358 A selector expression appears within curly braces and uses a single
1359 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
1360 operand is one of the following:
1364 another selector expression, in curly braces
1367 an effective-target keyword, such as @code{lp64}
1370 a single target triplet
1373 a list of target triplets within quotes or curly braces
1376 one of the following:
1379 @item @{ any-opts @var{opt1} @dots{} @var{optn} @}
1380 Each of @var{opt1} to @var{optn} is a space-separated list of option globs.
1381 The selector expression evaluates to true if, for one of these strings,
1382 every glob in the string matches an option that was passed to the compiler.
1386 @{ any-opts "-O3 -flto" "-O[2g]" @}
1389 is true if any of the following are true:
1393 @option{-O2} was passed to the compiler
1396 @option{-Og} was passed to the compiler
1399 both @option{-O3} and @option{-flto} were passed to the compiler
1402 This kind of selector can only be used within @code{dg-final} directives.
1403 Use @code{dg-skip-if}, @code{dg-xfail-if} or @code{dg-xfail-run-if} to
1404 skip whole tests based on options, or to mark them as expected to fail
1405 with certain options.
1407 @item @{ no-opts @var{opt1} @dots{} @var{optn} @}
1408 As for @code{any-opts} above, each of @var{opt1} to @var{optn} is a
1409 space-separated list of option globs. The selector expression
1410 evaluates to true if, for all of these strings, there is at least
1411 one glob that does not match an option that was passed to the compiler.
1412 It is shorthand for:
1415 @{ ! @{ any-opts @var{opt1} @dots{} @var{optn} @} @}
1421 @{ no-opts "-O3 -flto" "-O[2g]" @}
1424 is true if all of the following are true:
1428 @option{-O2} was not passed to the compiler
1431 @option{-Og} was not passed to the compiler
1434 at least one of @option{-O3} or @option{-flto} was not passed to the compiler
1437 Like @code{any-opts}, this kind of selector can only be used within
1438 @code{dg-final} directives.
1443 Here are some examples of full target selectors:
1446 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1447 @{ target @{ powerpc*-*-* && lp64 @} @}
1448 @{ xfail @{ lp64 || vect_no_align @} @}
1449 @{ xfail @{ aarch64*-*-* && @{ any-opts "-O2" @} @} @}
1452 @node Effective-Target Keywords
1453 @subsection Keywords describing target attributes
1455 Effective-target keywords identify sets of targets that support
1456 particular functionality. They are used to limit tests to be run only
1457 for particular targets, or to specify that particular sets of targets
1458 are expected to fail some tests.
1460 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1461 the GCC testsuite, with the exception of those that are documented as
1462 being local to a particular test directory.
1464 The @samp{effective target} takes into account all of the compiler options
1465 with which the test will be compiled, including the multilib options.
1466 By convention, keywords ending in @code{_nocache} can also include options
1467 specified for the particular test in an earlier @code{dg-options} or
1468 @code{dg-add-options} directive.
1470 @subsubsection Endianness
1474 Target uses big-endian memory order for multi-byte and multi-word data.
1477 Target uses little-endian memory order for multi-byte and multi-word data.
1480 @subsubsection Data type sizes
1484 Target has 32-bit @code{int}, @code{long}, and pointers.
1487 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1490 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1494 Target has 64-bit @code{double}.
1497 Target has @code{double} that is 64 bits or longer.
1500 Target has 128-bit @code{long double}.
1503 Target has @code{int} that is at 32 bits or longer.
1506 Target has @code{int} that is 16 bits or shorter.
1509 Target has 64-bit @code{long long}.
1512 Target has @code{int} and @code{long} with different sizes.
1515 Target has @code{short} and @code{int} with the same size.
1518 Target has pointers (@code{void *}) and @code{short} with the same size.
1521 Target has @code{int} and @code{float} with the same size.
1524 Target has pointers (@code{void *}) and @code{long} with the same size.
1527 Target supports @code{double} that is longer than @code{float}.
1529 @item large_long_double
1530 Target supports @code{long double} that is longer than @code{double}.
1533 Target has pointers that are 32 bits or longer.
1536 Target has a 20-bit or larger address space, so supports at least
1537 16-bit array and structure sizes.
1540 Target has a 24-bit or larger address space, so supports at least
1541 20-bit array and structure sizes.
1544 Target has a 32-bit or larger address space, so supports at least
1545 24-bit array and structure sizes.
1548 Target has @code{wchar_t} that is at least 4 bytes.
1551 Target has the @code{_Float@var{n}} type.
1554 Target has the @code{_Float@var{n}x} type.
1556 @item float@var{n}_runtime
1557 Target has the @code{_Float@var{n}} type, including runtime support
1558 for any options added with @code{dg-add-options}.
1560 @item float@var{n}x_runtime
1561 Target has the @code{_Float@var{n}x} type, including runtime support
1562 for any options added with @code{dg-add-options}.
1564 @item floatn_nx_runtime
1565 Target has runtime support for any options added with
1566 @code{dg-add-options} for any @code{_Float@var{n}} or
1567 @code{_Float@var{n}x} type.
1570 Target supports floating point infinite (@code{inf}) for type
1574 Target supports floating point infinite (@code{inf}) for type
1577 @subsubsection Fortran-specific attributes
1580 @item fortran_integer_16
1581 Target supports Fortran @code{integer} that is 16 bytes or longer.
1583 @item fortran_real_10
1584 Target supports Fortran @code{real} that is 10 bytes or longer.
1586 @item fortran_real_16
1587 Target supports Fortran @code{real} that is 16 bytes or longer.
1589 @item fortran_large_int
1590 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1592 @item fortran_large_real
1593 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1596 @subsubsection Vector-specific attributes
1599 @item vect_align_stack_vars
1600 The target's ABI allows stack variables to be aligned to the preferred
1604 Target supports both signed and unsigned averaging operations on vectors
1607 @item vect_mulhrs_hi
1608 Target supports both signed and unsigned multiply-high-with-round-and-scale
1609 operations on vectors of half-words.
1611 @item vect_sdiv_pow2_si
1612 Target supports signed division by constant power-of-2 operations
1613 on vectors of 4-byte integers.
1615 @item vect_condition
1616 Target supports vector conditional operations.
1618 @item vect_cond_mixed
1619 Target supports vector conditional operations where comparison operands
1620 have different type from the value operands.
1623 Target supports hardware vectors of @code{double}.
1625 @item vect_double_cond_arith
1626 Target supports conditional addition, subtraction, multiplication,
1627 division, minimum and maximum on vectors of @code{double}, via the
1628 @code{cond_} optabs.
1630 @item vect_element_align_preferred
1631 The target's preferred vector alignment is the same as the element
1635 Target supports hardware vectors of @code{float} when
1636 @option{-funsafe-math-optimizations} is in effect.
1638 @item vect_float_strict
1639 Target supports hardware vectors of @code{float} when
1640 @option{-funsafe-math-optimizations} is not in effect.
1641 This implies @code{vect_float}.
1644 Target supports hardware vectors of @code{int}.
1647 Target supports hardware vectors of @code{long}.
1649 @item vect_long_long
1650 Target supports hardware vectors of @code{long long}.
1652 @item vect_check_ptrs
1653 Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs}
1656 @item vect_fully_masked
1657 Target supports fully-masked (also known as fully-predicated) loops,
1658 so that vector loops can handle partial as well as full vectors.
1660 @item vect_masked_load
1661 Target supports vector masked loads.
1663 @item vect_masked_store
1664 Target supports vector masked stores.
1666 @item vect_gather_load_ifn
1667 Target supports vector gather loads using internal functions
1668 (rather than via built-in functions or emulation).
1670 @item vect_scatter_store
1671 Target supports vector scatter stores.
1673 @item vect_aligned_arrays
1674 Target aligns arrays to vector alignment boundary.
1676 @item vect_hw_misalign
1677 Target supports a vector misalign access.
1680 Target does not support a vector alignment mechanism.
1682 @item vect_peeling_profitable
1683 Target might require to peel loops for alignment purposes.
1685 @item vect_no_int_min_max
1686 Target does not support a vector min and max instruction on @code{int}.
1688 @item vect_no_int_add
1689 Target does not support a vector add instruction on @code{int}.
1691 @item vect_no_bitwise
1692 Target does not support vector bitwise instructions.
1695 Target supports comparison of @code{bool} vectors for at least one
1699 Target supports addition of @code{char} vectors for at least one
1702 @item vect_char_mult
1703 Target supports @code{vector char} multiplication.
1705 @item vect_short_mult
1706 Target supports @code{vector short} multiplication.
1709 Target supports @code{vector int} multiplication.
1711 @item vect_long_mult
1712 Target supports 64 bit @code{vector long} multiplication.
1714 @item vect_extract_even_odd
1715 Target supports vector even/odd element extraction.
1717 @item vect_extract_even_odd_wide
1718 Target supports vector even/odd element extraction of vectors with elements
1719 @code{SImode} or larger.
1721 @item vect_interleave
1722 Target supports vector interleaving.
1725 Target supports vector interleaving and extract even/odd.
1727 @item vect_strided_wide
1728 Target supports vector interleaving and extract even/odd for wide
1732 Target supports vector permutation.
1734 @item vect_perm_byte
1735 Target supports permutation of vectors with 8-bit elements.
1737 @item vect_perm_short
1738 Target supports permutation of vectors with 16-bit elements.
1740 @item vect_perm3_byte
1741 Target supports permutation of vectors with 8-bit elements, and for the
1742 default vector length it is possible to permute:
1744 @{ a0, a1, a2, b0, b1, b2, @dots{} @}
1748 @{ a0, a0, a0, b0, b0, b0, @dots{} @}
1749 @{ a1, a1, a1, b1, b1, b1, @dots{} @}
1750 @{ a2, a2, a2, b2, b2, b2, @dots{} @}
1752 using only two-vector permutes, regardless of how long the sequence is.
1754 @item vect_perm3_int
1755 Like @code{vect_perm3_byte}, but for 32-bit elements.
1757 @item vect_perm3_short
1758 Like @code{vect_perm3_byte}, but for 16-bit elements.
1761 Target supports a hardware vector shift operation.
1763 @item vect_unaligned_possible
1764 Target prefers vectors to have an alignment greater than element
1765 alignment, but also allows unaligned vector accesses in some
1768 @item vect_variable_length
1769 Target has variable-length vectors.
1772 Target supports vectors of 64 bits.
1775 Target supports vectors of 32 bits.
1777 @item vect_widen_sum_hi_to_si
1778 Target supports a vector widening summation of @code{short} operands
1779 into @code{int} results, or can promote (unpack) from @code{short}
1782 @item vect_widen_sum_qi_to_hi
1783 Target supports a vector widening summation of @code{char} operands
1784 into @code{short} results, or can promote (unpack) from @code{char}
1787 @item vect_widen_sum_qi_to_si
1788 Target supports a vector widening summation of @code{char} operands
1789 into @code{int} results.
1791 @item vect_widen_mult_qi_to_hi
1792 Target supports a vector widening multiplication of @code{char} operands
1793 into @code{short} results, or can promote (unpack) from @code{char} to
1794 @code{short} and perform non-widening multiplication of @code{short}.
1796 @item vect_widen_mult_hi_to_si
1797 Target supports a vector widening multiplication of @code{short} operands
1798 into @code{int} results, or can promote (unpack) from @code{short} to
1799 @code{int} and perform non-widening multiplication of @code{int}.
1801 @item vect_widen_mult_si_to_di_pattern
1802 Target supports a vector widening multiplication of @code{int} operands
1803 into @code{long} results.
1806 Target supports a vector dot-product of @code{signed char}.
1809 Target supports a vector dot-product of @code{unsigned char}.
1812 Target supports a vector dot-product where one operand of the multiply is
1813 @code{signed char} and the other of @code{unsigned char}.
1816 Target supports a vector dot-product of @code{signed short}.
1819 Target supports a vector dot-product of @code{unsigned short}.
1821 @item vect_pack_trunc
1822 Target supports a vector demotion (packing) of @code{short} to @code{char}
1823 and from @code{int} to @code{short} using modulo arithmetic.
1826 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1827 and from @code{char} to @code{int}.
1829 @item vect_intfloat_cvt
1830 Target supports conversion from @code{signed int} to @code{float}.
1832 @item vect_uintfloat_cvt
1833 Target supports conversion from @code{unsigned int} to @code{float}.
1835 @item vect_floatint_cvt
1836 Target supports conversion from @code{float} to @code{signed int}.
1838 @item vect_floatuint_cvt
1839 Target supports conversion from @code{float} to @code{unsigned int}.
1841 @item vect_intdouble_cvt
1842 Target supports conversion from @code{signed int} to @code{double}.
1844 @item vect_doubleint_cvt
1845 Target supports conversion from @code{double} to @code{signed int}.
1847 @item vect_max_reduc
1848 Target supports max reduction for vectors.
1850 @item vect_sizes_16B_8B
1851 Target supports 16- and 8-bytes vectors.
1853 @item vect_sizes_32B_16B
1854 Target supports 32- and 16-bytes vectors.
1856 @item vect_logical_reduc
1857 Target supports AND, IOR and XOR reduction on vectors.
1859 @item vect_fold_extract_last
1860 Target supports the @code{fold_extract_last} optab.
1862 @item vect_len_load_store
1863 Target supports the @code{len_load} and @code{len_store} optabs.
1865 @item vect_partial_vectors_usage_1
1866 Target supports loop vectorization with partial vectors and
1867 @code{vect-partial-vector-usage} is set to 1.
1869 @item vect_partial_vectors_usage_2
1870 Target supports loop vectorization with partial vectors and
1871 @code{vect-partial-vector-usage} is set to 2.
1873 @item vect_partial_vectors
1874 Target supports loop vectorization with partial vectors and
1875 @code{vect-partial-vector-usage} is nonzero.
1877 @item vect_slp_v2qi_store_align
1878 Target supports vectorization of 2-byte char stores with 2-byte aligned
1879 address at plain @option{-O2}.
1881 @item vect_slp_v4qi_store_align
1882 Target supports vectorization of 4-byte char stores with 4-byte aligned
1883 address at plain @option{-O2}.
1885 @item vect_slp_v4qi_store_unalign
1886 Target supports vectorization of 4-byte char stores with unaligned address
1887 at plain @option{-O2}.
1889 @item struct_4char_block_move
1890 Target supports block move for 8-byte aligned 4-byte size struct initialization.
1892 @item vect_slp_v4qi_store_unalign_1
1893 Target supports vectorization of 4-byte char stores with unaligned address
1894 or store them with constant pool at plain @option{-O2}.
1896 @item struct_8char_block_move
1897 Target supports block move for 8-byte aligned 8-byte size struct initialization.
1899 @item vect_slp_v8qi_store_unalign_1
1900 Target supports vectorization of 8-byte char stores with unaligned address
1901 or store them with constant pool at plain @option{-O2}.
1903 @item struct_16char_block_move
1904 Target supports block move for 8-byte aligned 16-byte size struct
1907 @item vect_slp_v16qi_store_unalign_1
1908 Target supports vectorization of 16-byte char stores with unaligned address
1909 or store them with constant pool at plain @option{-O2}.
1911 @item vect_slp_v2hi_store_align
1912 Target supports vectorization of 4-byte short stores with 4-byte aligned
1913 addressat plain @option{-O2}.
1915 @item vect_slp_v2hi_store_unalign
1916 Target supports vectorization of 4-byte short stores with unaligned address
1917 at plain @option{-O2}.
1919 @item vect_slp_v4hi_store_unalign
1920 Target supports vectorization of 8-byte short stores with unaligned address
1921 at plain @option{-O2}.
1923 @item vect_slp_v2si_store_align
1924 Target supports vectorization of 8-byte int stores with 8-byte aligned address
1925 at plain @option{-O2}.
1927 @item vect_slp_v4si_store_unalign
1928 Target supports vectorization of 16-byte int stores with unaligned address
1929 at plain @option{-O2}.
1932 @subsubsection Thread Local Storage attributes
1936 Target supports thread-local storage.
1939 Target supports native (rather than emulated) thread-local storage.
1942 Test system supports executing TLS executables.
1945 @subsubsection Decimal floating point attributes
1949 Targets supports compiling decimal floating point extension to C.
1952 Including the options used to compile this particular test, the
1953 target supports compiling decimal floating point extension to C.
1956 Test system can execute decimal floating point tests.
1959 Including the options used to compile this particular test, the
1960 test system can execute decimal floating point tests.
1963 Target generates decimal floating point instructions with current options.
1966 Target uses the BID format for decimal floating point.
1969 @subsubsection ARM-specific attributes
1973 ARM target generates 32-bit code.
1975 @item arm_little_endian
1976 ARM target that generates little-endian code.
1979 ARM target adheres to the ABI for the ARM Architecture.
1983 ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or
1984 equivalent options. Some multilibs may be incompatible with these
1988 @anchor{arm_fp_dp_ok}
1989 ARM target defines @code{__ARM_FP} with double-precision support using
1990 @code{-mfloat-abi=softfp} or equivalent options. Some multilibs may
1991 be incompatible with these options.
1994 ARM target adheres to the VFP and Advanced SIMD Register Arguments
1995 variant of the ABI for the ARM Architecture (as selected with
1996 @code{-mfloat-abi=hard}).
1999 ARM target uses emulated floating point operations.
2001 @item arm_hard_vfp_ok
2002 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
2003 Some multilibs may be incompatible with these options.
2006 ARM target supports @code{-mcpu=iwmmxt}.
2007 Some multilibs may be incompatible with this option.
2010 ARM target supports generating NEON instructions.
2012 @item arm_tune_string_ops_prefer_neon
2013 Test CPU tune supports inlining string operations with NEON instructions.
2016 Test system supports executing NEON instructions.
2019 Test system supports executing NEON v2 instructions.
2022 @anchor{arm_neon_ok}
2023 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
2024 options. Some multilibs may be incompatible with these options.
2026 @item arm_neon_ok_no_float_abi
2027 @anchor{arm_neon_ok_no_float_abi}
2028 ARM Target supports NEON with @code{-mfpu=neon}, but without any
2029 -mfloat-abi= option. Some multilibs may be incompatible with this
2033 @anchor{arm_neonv2_ok}
2034 ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible
2035 options. Some multilibs may be incompatible with these options.
2038 @anchor{arm_fp16_ok}
2039 Target supports options to generate VFP half-precision floating-point
2040 instructions. Some multilibs may be incompatible with these
2041 options. This test is valid for ARM only.
2044 Target supports executing VFP half-precision floating-point
2045 instructions. This test is valid for ARM only.
2047 @item arm_neon_fp16_ok
2048 @anchor{arm_neon_fp16_ok}
2049 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
2050 options, including @code{-mfp16-format=ieee} if necessary to obtain the
2051 @code{__fp16} type. Some multilibs may be incompatible with these options.
2053 @item arm_neon_fp16_hw
2054 Test system supports executing Neon half-precision float instructions.
2057 @item arm_fp16_alternative_ok
2058 ARM target supports the ARM FP16 alternative format. Some multilibs
2059 may be incompatible with the options needed.
2061 @item arm_fp16_none_ok
2062 ARM target supports specifying none as the ARM FP16 format.
2065 ARM target generates Thumb-1 code for @code{-mthumb}.
2068 ARM target generates Thumb-2 code for @code{-mthumb}.
2071 ARM target that is not using Thumb.
2074 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
2075 Some multilibs may be incompatible with these options.
2078 @anchor{arm_vfp3_ok}
2079 ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}.
2080 Some multilibs may be incompatible with these options.
2082 @item arm_arch_v8a_hard_ok
2083 @anchor{arm_arch_v8a_hard_ok}
2084 The compiler is targeting @code{arm*-*-*} and can compile and assemble code
2085 using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
2086 This is not enough to guarantee that linking works.
2088 @item arm_arch_v8a_hard_multilib
2089 The compiler is targeting @code{arm*-*-*} and can build programs using
2090 the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
2091 The target can also run the resulting binaries.
2094 ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}.
2095 Some multilibs may be incompatible with these options.
2097 @item arm_v8_neon_ok
2098 ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}.
2099 Some multilibs may be incompatible with these options.
2101 @item arm_v8_1a_neon_ok
2102 @anchor{arm_v8_1a_neon_ok}
2103 ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions.
2104 Some multilibs may be incompatible with these options.
2106 @item arm_v8_1a_neon_hw
2107 ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some
2108 multilibs may be incompatible with the options needed. Implies
2112 ARM target supports acquire-release instructions.
2114 @item arm_v8_2a_fp16_scalar_ok
2115 @anchor{arm_v8_2a_fp16_scalar_ok}
2116 ARM target supports options to generate instructions for ARMv8.2-A and
2117 scalar instructions from the FP16 extension. Some multilibs may be
2118 incompatible with these options.
2120 @item arm_v8_2a_fp16_scalar_hw
2121 ARM target supports executing instructions for ARMv8.2-A and scalar
2122 instructions from the FP16 extension. Some multilibs may be
2123 incompatible with these options. Implies arm_v8_2a_fp16_neon_ok.
2125 @item arm_v8_2a_fp16_neon_ok
2126 @anchor{arm_v8_2a_fp16_neon_ok}
2127 ARM target supports options to generate instructions from ARMv8.2-A with
2128 the FP16 extension. Some multilibs may be incompatible with these
2129 options. Implies arm_v8_2a_fp16_scalar_ok.
2131 @item arm_v8_2a_fp16_neon_hw
2132 ARM target supports executing instructions from ARMv8.2-A with the FP16
2133 extension. Some multilibs may be incompatible with these options.
2134 Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.
2136 @item arm_v8_2a_dotprod_neon_ok
2137 @anchor{arm_v8_2a_dotprod_neon_ok}
2138 ARM target supports options to generate instructions from ARMv8.2-A with
2139 the Dot Product extension. Some multilibs may be incompatible with these
2142 @item arm_v8_2a_dotprod_neon_hw
2143 ARM target supports executing instructions from ARMv8.2-A with the Dot
2144 Product extension. Some multilibs may be incompatible with these options.
2145 Implies arm_v8_2a_dotprod_neon_ok.
2147 @item arm_v8_2a_i8mm_neon_hw
2148 ARM target supports executing instructions from ARMv8.2-A with the 8-bit
2149 Matrix Multiply extension. Some multilibs may be incompatible with these
2150 options. Implies arm_v8_2a_i8mm_ok.
2152 @item arm_fp16fml_neon_ok
2153 @anchor{arm_fp16fml_neon_ok}
2154 ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS}
2155 half-precision floating-point instructions available from ARMv8.2-A and
2156 onwards. Some multilibs may be incompatible with these options.
2158 @item arm_v8_2a_bf16_neon_ok
2159 ARM target supports options to generate instructions from ARMv8.2-A with
2160 the BFloat16 extension (bf16). Some multilibs may be incompatible with these
2163 @item arm_v8_2a_i8mm_ok
2164 ARM target supports options to generate instructions from ARMv8.2-A with
2165 the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be
2166 incompatible with these options.
2168 @item arm_v8_1m_mve_ok
2169 ARM target supports options to generate instructions from ARMv8.1-M with
2170 the M-Profile Vector Extension (MVE). Some multilibs may be incompatible
2173 @item arm_v8_1m_mve_fp_ok
2174 ARM target supports options to generate instructions from ARMv8.1-M with
2175 the Half-precision floating-point instructions (HP), Floating-point Extension
2176 (FP) along with M-Profile Vector Extension (MVE). Some multilibs may be
2177 incompatible with these options.
2180 Test system supports executing MVE instructions.
2182 @item arm_v8m_main_cde
2183 ARM target supports options to generate instructions from ARMv8-M with
2184 the Custom Datapath Extension (CDE). Some multilibs may be incompatible
2187 @item arm_v8m_main_cde_fp
2188 ARM target supports options to generate instructions from ARMv8-M with
2189 the Custom Datapath Extension (CDE) and floating-point (VFP).
2190 Some multilibs may be incompatible with these options.
2192 @item arm_v8_1m_main_cde_mve
2193 ARM target supports options to generate instructions from ARMv8.1-M with
2194 the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE).
2195 Some multilibs may be incompatible with these options.
2197 @item arm_prefer_ldrd_strd
2198 ARM target prefers @code{LDRD} and @code{STRD} instructions over
2199 @code{LDM} and @code{STM} instructions.
2201 @item arm_thumb1_movt_ok
2202 ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW}
2203 and @code{MOVT} instructions available.
2205 @item arm_thumb1_cbz_ok
2206 ARM target generates Thumb-1 code for @code{-mthumb} with
2207 @code{CBZ} and @code{CBNZ} instructions available.
2209 @item arm_divmod_simode
2210 ARM target for which divmod transform is disabled, if it supports hardware
2214 ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse}
2218 Test system supports executing CMSE instructions.
2220 @item arm_coproc1_ok
2221 @anchor{arm_coproc1_ok}
2222 ARM target supports the following coprocessor instructions: @code{CDP},
2223 @code{LDC}, @code{STC}, @code{MCR} and @code{MRC}.
2225 @item arm_coproc2_ok
2226 @anchor{arm_coproc2_ok}
2227 ARM target supports all the coprocessor instructions also listed as supported
2228 in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2},
2229 @code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}.
2231 @item arm_coproc3_ok
2232 @anchor{arm_coproc3_ok}
2233 ARM target supports all the coprocessor instructions also listed as supported
2234 in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}.
2236 @item arm_coproc4_ok
2237 ARM target supports all the coprocessor instructions also listed as supported
2238 in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}.
2241 @anchor{arm_simd32_ok}
2242 ARM Target supports options suitable for accessing the SIMD32 intrinsics from
2244 Some multilibs may be incompatible with these options.
2248 ARM Target supports options suitable for accessing the saturation
2249 intrinsics from @code{arm_acle.h}.
2250 Some multilibs may be incompatible with these options.
2254 ARM Target supports options suitable for accessing the DSP intrinsics
2255 from @code{arm_acle.h}.
2256 Some multilibs may be incompatible with these options.
2259 @anchor{arm_softfp_ok}
2260 ARM target supports the @code{-mfloat-abi=softfp} option.
2263 @anchor{arm_hard_ok}
2264 ARM target supports the @code{-mfloat-abi=hard} option.
2268 ARM target supports generating MVE instructions.
2270 @item arm_v8_1_lob_ok
2271 @anchor{arm_v8_1_lob_ok}
2272 ARM Target supports executing the Armv8.1-M Mainline Low Overhead Loop
2273 instructions @code{DLS} and @code{LE}.
2274 Some multilibs may be incompatible with these options.
2276 @item arm_thumb2_no_arm_v8_1_lob
2277 ARM target where Thumb-2 is used without options but does not support
2278 executing the Armv8.1-M Mainline Low Overhead Loop instructions
2279 @code{DLS} and @code{LE}.
2281 @item arm_thumb2_ok_no_arm_v8_1_lob
2282 ARM target generates Thumb-2 code for @code{-mthumb} but does not
2283 support executing the Armv8.1-M Mainline Low Overhead Loop
2284 instructions @code{DLS} and @code{LE}.
2288 @subsubsection AArch64-specific attributes
2291 @item aarch64_asm_<ext>_ok
2292 AArch64 assembler supports the architecture extension @code{ext} via the
2293 @code{.arch_extension} pseudo-op.
2295 AArch64 target which generates instruction sequences for tiny memory model.
2297 AArch64 target which generates instruction sequences for small memory model.
2299 AArch64 target which generates instruction sequences for large memory model.
2300 @item aarch64_little_endian
2301 AArch64 target which generates instruction sequences for little endian.
2302 @item aarch64_big_endian
2303 AArch64 target which generates instruction sequences for big endian.
2304 @item aarch64_small_fpic
2305 Binutils installed on test system supports relocation types required by -fpic
2306 for AArch64 small memory model.
2307 @item aarch64_sve_hw
2308 AArch64 target that is able to generate and execute SVE code (regardless of
2309 whether it does so by default).
2310 @item aarch64_sve128_hw
2311 @itemx aarch64_sve256_hw
2312 @itemx aarch64_sve512_hw
2313 @itemx aarch64_sve1024_hw
2314 @itemx aarch64_sve2048_hw
2315 Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length.
2317 @item aarch64_fjcvtzs_hw
2318 AArch64 target that is able to generate and execute armv8.3-a FJCVTZS
2322 @subsubsection MIPS-specific attributes
2326 MIPS target supports 64-bit instructions.
2329 MIPS target does not produce MIPS16 code.
2331 @item mips16_attribute
2332 MIPS target can generate MIPS16 code.
2335 MIPS target is a Loongson-2E or -2F target using an ABI that supports
2336 the Loongson vector modes.
2339 MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA).
2341 @item mips_newabi_large_long_double
2342 MIPS target supports @code{long double} larger than @code{double}
2343 when using the new ABI.
2345 @item mpaired_single
2346 MIPS target supports @code{-mpaired-single}.
2349 @subsubsection MSP430-specific attributes
2353 MSP430 target has the small memory model enabled (@code{-msmall}).
2356 MSP430 target has the large memory model enabled (@code{-mlarge}).
2359 @subsubsection PowerPC-specific attributes
2364 PowerPC target supports executing hardware DFP instructions.
2367 PowerPC target supports executing VSX instructions (ISA 2.07).
2370 Test system supports executing 64-bit instructions.
2372 @item powerpc_altivec
2373 PowerPC target supports AltiVec.
2375 @item powerpc_altivec_ok
2376 PowerPC target supports @code{-maltivec}.
2378 @item powerpc_eabi_ok
2379 PowerPC target supports @code{-meabi}.
2382 PowerPC target supports @code{-mabi=elfv2}.
2385 PowerPC target supports floating-point registers.
2387 @item powerpc_hard_double
2388 PowerPC target supports hardware double-precision floating-point.
2390 @item powerpc_htm_ok
2391 PowerPC target supports @code{-mhtm}
2393 @item powerpc_p8vector_ok
2394 PowerPC target supports @code{-mpower8-vector}
2396 @item powerpc_popcntb_ok
2397 PowerPC target supports the @code{popcntb} instruction, indicating
2398 that this target supports @code{-mcpu=power5}.
2400 @item powerpc_ppu_ok
2401 PowerPC target supports @code{-mcpu=cell}.
2404 PowerPC target supports PowerPC SPE.
2406 @item powerpc_spe_nocache
2407 Including the options used to compile this particular test, the
2408 PowerPC target supports PowerPC SPE.
2411 PowerPC target supports PowerPC SPU.
2413 @item powerpc_vsx_ok
2414 PowerPC target supports @code{-mvsx}.
2416 @item powerpc_405_nocache
2417 Including the options used to compile this particular test, the
2418 PowerPC target supports PowerPC 405.
2421 PowerPC target supports executing reciprocal estimate instructions.
2424 PowerPC target supports executing AltiVec instructions.
2427 PowerPC target supports executing VSX instructions (ISA 2.06).
2430 PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu}
2431 setting is Power5 or later.
2434 PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu}
2435 setting is Power6 or later.
2438 PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu}
2439 setting is Power7 or later.
2442 PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu}
2443 setting is Power8 or later.
2446 PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu}
2447 setting is Power9 or later.
2450 @subsubsection RISC-V specific attributes
2455 Test system has an integer register width of 32 bits.
2458 Test system has an integer register width of 64 bits.
2462 @subsubsection Other hardware attributes
2464 @c Please keep this table sorted alphabetically.
2467 Target supports autoincrement/decrement addressing.
2470 Target supports compiling @code{avx} instructions.
2473 Target supports the execution of @code{avx} instructions.
2476 Target supports compiling @code{avx2} instructions.
2479 Target supports the execution of @code{avx2} instructions.
2482 Target supports the execution of @code{avxvnni} instructions.
2485 Target supports compiling @code{avx512f} instructions.
2487 @item avx512f_runtime
2488 Target supports the execution of @code{avx512f} instructions.
2490 @item avx512vp2intersect
2491 Target supports the execution of @code{avx512vp2intersect} instructions.
2494 Target supports the execution of @code{avxifma} instructions.
2497 Target supports the execution of @code{avxneconvert} instructions.
2500 Target supports the execution of @code{avxvnniint8} instructions.
2503 Target supports the execution of @code{amx-tile} instructions.
2506 Target supports the execution of @code{amx-int8} instructions.
2509 Target supports the execution of @code{amx-bf16} instructions.
2512 Target supports the execution of @code{amx-fp16} instructions.
2515 Test system can execute AltiVec and Cell PPU instructions.
2518 Target supports the execution of @code{cmpccxadd} instructions.
2521 Target uses a ColdFire FPU.
2524 Target supporting hardware divmod insn or divmod libcall.
2527 Target supporting hardware divmod insn or divmod libcall for SImode.
2530 Target supports FPU instructions.
2532 @item non_strict_align
2533 Target does not require strict alignment.
2536 The x86-64 target linker supports PIE with copy reloc.
2539 Target supports x86 @code{rdrand} instruction.
2542 Target has a square root instruction that the compiler can generate.
2545 Target supports compiling @code{sse} instructions.
2548 Target supports the execution of @code{sse} instructions.
2551 Target supports compiling @code{sse2} instructions.
2554 Target supports the execution of @code{sse2} instructions.
2556 @item sync_char_short
2557 Target supports atomic operations on @code{char} and @code{short}.
2560 Target supports atomic operations on @code{int} and @code{long}.
2563 Test environment appears to run executables on a simulator that
2564 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
2565 or @code{EM_SPARCV9} executables.
2567 @item vect_cmdline_needed
2568 Target requires a command line argument to enable a SIMD instruction set.
2571 Target supports the xorsign optab expansion.
2575 @subsubsection Environment attributes
2579 The language for the compiler under test is C.
2582 The language for the compiler under test is C++.
2585 Target provides a full C99 runtime.
2587 @item correct_iso_cpp_string_wchar_protos
2588 Target @code{string.h} and @code{wchar.h} headers provide C++ required
2589 overloads for @code{strchr} etc. functions.
2592 Target provides the D runtime.
2594 @item d_runtime_has_std_library
2595 Target provides the D standard library (Phobos).
2597 @item dummy_wcsftime
2598 Target uses a dummy @code{wcsftime} function that always returns zero.
2601 Target can truncate a file from a file descriptor, as used by
2602 @file{libgfortran/io/unix.c:fd_truncate}; i.e.@: @code{ftruncate} or
2606 Target provides @file{fenv.h} include file.
2608 @item fenv_exceptions
2609 Target supports @file{fenv.h} with all the standard IEEE exceptions
2610 and floating-point exceptions are raised by arithmetic operations.
2612 @item fenv_exceptions_dfp
2613 Target supports @file{fenv.h} with all the standard IEEE exceptions
2614 and floating-point exceptions are raised by arithmetic operations for
2615 decimal floating point.
2618 Target offers such file I/O library functions as @code{fopen},
2619 @code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time
2620 requirement for the presence of the functions in the library; even if
2621 they fail at runtime, the requirement is still regarded as satisfied.
2624 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
2625 Effectively, it is a target which supports no extra headers or libraries
2626 other than what is considered essential.
2629 Target supports @code{gettimeofday}.
2632 Target supports constructors with initialization priority arguments.
2634 @item inttypes_types
2635 Target has the basic signed and unsigned types in @code{inttypes.h}.
2636 This is for tests that GCC's notions of these types agree with those
2637 in the header, as some systems have only @code{inttypes.h}.
2640 Target might have errors of a few ULP in string to floating-point
2641 conversion functions and overflow is not always detected correctly by
2645 Target provides @code{mempcpy} function.
2648 Target supports @code{mmap}.
2651 Target supports Newlib.
2653 @item newlib_nano_io
2654 GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces
2655 the code size of Newlib formatted I/O functions.
2658 Target provides @code{pow10} function.
2661 Target can compile using @code{pthread.h} with no errors or warnings.
2664 Target has @code{pthread.h}.
2666 @item run_expensive_tests
2667 Expensive testcases (usually those that consume excessive amounts of CPU
2668 time) should be run on this target. This can be enabled by setting the
2669 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
2672 Test system runs executables on a simulator (i.e.@: slowly) rather than
2673 hardware (i.e.@: fast).
2676 Target has @code{signal.h}.
2679 Target supports the stabs debugging format.
2682 Target has the basic signed and unsigned C types in @code{stdint.h}.
2683 This will be obsolete when GCC ensures a working @code{stdint.h} for
2686 @item stdint_types_mbig_endian
2687 Target accepts the option @option{-mbig-endian} and @code{stdint.h}
2688 can be included without error when @option{-mbig-endian} is passed.
2691 Target provides @code{stpcpy} function.
2694 Target supports @code{sysconf}.
2697 Target supports trampolines.
2700 Target supports linking programs with 2+GiB of data.
2703 Target supports uClibc.
2706 Target does not use a status wrapper.
2708 @item vxworks_kernel
2709 Target is a VxWorks kernel.
2712 Target is a VxWorks RTP.
2715 Target supports wide characters.
2718 @subsubsection Other attributes
2721 @item R_flag_in_section
2722 Target supports the 'R' flag in .section directive in assembly inputs.
2724 @item automatic_stack_alignment
2725 Target supports automatic stack alignment.
2728 Target supports @option{-branch-cost=N}.
2731 Target uses @code{__cxa_atexit}.
2733 @item default_packed
2734 @anchor{default_packed}
2735 Target has packed layout of structure members by default.
2738 Target supports exceptions.
2740 @item exceptions_enabled
2741 Target supports exceptions and they are enabled in the current
2742 testing configuration.
2745 Target supports Graphite optimizations.
2748 Target supports fixed-point extension to C.
2751 Target supports OpenACC via @option{-fopenacc}.
2754 Target supports OpenMP via @option{-fopenmp}.
2757 Target supports @option{-fpic} and @option{-fPIC}.
2760 Target supports @option{-freorder-blocks-and-partition}.
2762 @item fstack_protector
2763 Target supports @option{-fstack-protector}.
2766 Target uses GNU @command{as}.
2769 Target supports @option{--gc-sections}.
2772 Target uses GNU @command{ld}.
2774 @item keeps_null_pointer_checks
2775 Target keeps null pointer checks, either due to the use of
2776 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
2779 Target is using an LLVM assembler and/or linker, instead of GNU Binutils.
2782 Target supports local register allocator (LRA).
2785 Compiler has been configured to support link-time optimization (LTO).
2787 @item lto_incremental
2788 Compiler and linker support link-time optimization relocatable linking
2789 with @option{-r} and @option{-flto} options.
2791 @item naked_functions
2792 Target supports the @code{naked} function attribute.
2794 @item named_sections
2795 Target supports named sections.
2797 @item natural_alignment_32
2798 Target uses natural alignment (aligned to type size) for types of
2801 @item target_natural_alignment_64
2802 Target uses natural alignment (aligned to type size) for types of
2805 @item no_alignment_constraints
2806 Target defines __BIGGEST_ALIGNMENT__=1. Hence target imposes
2807 no alignment constraints. This is similar, but not necessarily
2808 the same as @ref{default_packed}. Although @code{BIGGEST_FIELD_ALIGNMENT}
2809 defaults to @code{BIGGEST_ALIGNMENT} for most targets, it is possible
2810 for a target to set those two with different values and have different
2811 alignment constraints for aggregate and non-aggregate types.
2814 Target supports the @code{noinit} variable attribute.
2817 Target does not generate PIC by default.
2819 @item o_flag_in_section
2820 Target supports the 'o' flag in .section directive in assembly inputs.
2823 Target has been configured for OpenACC/OpenMP offloading on AMD GCN.
2826 Target supports the @code{persistent} variable attribute.
2829 Target generates PIE by default.
2831 @item pcc_bitfield_type_matters
2832 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
2834 @item pe_aligned_commons
2835 Target supports @option{-mpe-aligned-commons}.
2838 Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
2841 Target supports @option{-rdynamic}.
2843 @item scalar_all_fma
2844 Target supports all four fused multiply-add optabs for both @code{float}
2845 and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab},
2846 @code{fnma_optab} and @code{fnms_optab}.
2848 @item section_anchors
2849 Target supports section anchors.
2852 Target defaults to short enums.
2855 @anchor{stack_size_et}
2856 Target has limited stack size. The stack size limit can be obtained using the
2857 STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature
2861 Target supports @option{-static}.
2863 @item static_libgfortran
2864 Target supports statically linking @samp{libgfortran}.
2866 @item string_merging
2867 Target supports merging string constants at link time.
2870 Target supports compiling and assembling UCN.
2873 Including the options used to compile this particular test, the
2874 target supports compiling and assembling UCN.
2876 @item unaligned_stack
2877 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
2878 or equal to the required vector alignment.
2880 @item vector_alignment_reachable
2881 Vector alignment is reachable for types of 32 bits or less.
2883 @item vector_alignment_reachable_for_64bit
2884 Vector alignment is reachable for types of 64 bits or less.
2886 @item vma_equals_lma
2887 Target generates executable with VMA equal to LMA for .data section.
2889 @item wchar_t_char16_t_compatible
2890 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
2892 @item wchar_t_char32_t_compatible
2893 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
2896 Target uses comdat groups.
2898 @item indirect_calls
2899 Target supports indirect calls, i.e. calls where the target is not
2903 Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests.
2906 Optimizations are enabled (@code{__OPTIMIZE__}) per the current
2910 @subsubsection Local to tests in @code{gcc.target/i386}
2914 Target supports compiling @code{3dnow} instructions.
2917 Target supports compiling @code{aes} instructions.
2920 Target supports compiling @code{fma4} instructions.
2923 Target supports the @code{-mfentry} option that alters the
2924 position of profiling calls such that they precede the prologue.
2926 @item ms_hook_prologue
2927 Target supports attribute @code{ms_hook_prologue}.
2930 Target supports compiling @code{pclmul} instructions.
2933 Target supports compiling @code{sse3} instructions.
2936 Target supports compiling @code{sse4} instructions.
2939 Target supports compiling @code{sse4a} instructions.
2942 Target supports compiling @code{ssse3} instructions.
2945 Target supports compiling @code{vaes} instructions.
2948 Target supports compiling @code{vpclmul} instructions.
2951 Target supports compiling @code{xop} instructions.
2954 @subsubsection Local to tests in @code{gcc.test-framework}
2965 @subsection Features for @code{dg-add-options}
2967 The supported values of @var{feature} for directive @code{dg-add-options}
2972 @code{__ARM_FP} definition. Only ARM targets support this feature, and only then
2973 in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target
2977 @code{__ARM_FP} definition with double-precision support. Only ARM
2978 targets support this feature, and only then in certain modes; see the
2979 @ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}.
2982 NEON support. Only ARM targets support this feature, and only then
2983 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
2987 VFP half-precision floating point support. This does not select the
2988 FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or
2989 @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This
2990 feature is only supported by ARM targets and then only in certain
2991 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2995 @anchor{arm_fp16_ieee}
2996 ARM IEEE 754-2008 format VFP half-precision floating point support.
2997 This feature is only supported by ARM targets and then only in certain
2998 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
3001 @item arm_fp16_alternative
3002 @anchor{arm_fp16_alternative}
3003 ARM Alternative format VFP half-precision floating point support.
3004 This feature is only supported by ARM targets and then only in certain
3005 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
3009 NEON and half-precision floating point support. Only ARM targets
3010 support this feature, and only then in certain modes; see
3011 the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}.
3014 arm vfp3 floating point support; see
3015 the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}.
3017 @item arm_arch_v8a_hard
3018 Add options for ARMv8-A and the hard-float variant of the AAPCS,
3019 if this is supported by the compiler; see the
3020 @ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword.
3022 @item arm_v8_1a_neon
3023 Add options for ARMv8.1-A with Adv.SIMD support, if this is supported
3024 by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok}
3025 effective target keyword.
3027 @item arm_v8_2a_fp16_scalar
3028 Add options for ARMv8.2-A with scalar FP16 support, if this is
3029 supported by the target; see the
3030 @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective
3033 @item arm_v8_2a_fp16_neon
3034 Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is
3035 supported by the target; see the
3036 @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target
3039 @item arm_v8_2a_dotprod_neon
3040 Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is
3041 supported by the target; see the
3042 @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword.
3044 @item arm_fp16fml_neon
3045 Add options to enable generation of the @code{VFMAL} and @code{VFMSL}
3046 instructions, if this is supported by the target; see the
3047 @ref{arm_fp16fml_neon_ok} effective target keyword.
3050 Add options for ARM DSP intrinsics support, if this is supported by
3051 the target; see the @ref{arm_dsp_ok,,arm_dsp_ok effective target
3054 @item bind_pic_locally
3055 Add the target-specific flags needed to enable functions to bind
3056 locally when using pic/PIC passes in the testsuite.
3059 Add the target-specific flags needed to use the @code{_Float@var{n}} type.
3062 Add the target-specific flags needed to use the @code{_Float@var{n}x} type.
3065 Add the target-specific flags needed to enable full IEEE
3068 @item mips16_attribute
3069 @code{mips16} function attributes.
3070 Only MIPS targets support this feature, and only then in certain modes.
3073 @anchor{stack_size_ao}
3074 Add the flags needed to define macro STACK_SIZE and set it to the stack size
3075 limit associated with the @ref{stack_size_et,,@code{stack_size} effective
3079 Add the target-specific flags needed to enable hardware square root
3080 instructions, if any.
3083 Add the target-specific flags needed to use thread-local storage.
3086 @node Require Support
3087 @subsection Variants of @code{dg-require-@var{support}}
3089 A few of the @code{dg-require} directives take arguments.
3092 @item dg-require-iconv @var{codeset}
3093 Skip the test if the target does not support iconv. @var{codeset} is
3094 the codeset to convert to.
3096 @item dg-require-profiling @var{profopt}
3097 Skip the test if the target does not support profiling with option
3100 @item dg-require-stack-check @var{check}
3101 Skip the test if the target does not support the @code{-fstack-check}
3102 option. If @var{check} is @code{""}, support for @code{-fstack-check}
3103 is checked, for @code{-fstack-check=("@var{check}")} otherwise.
3105 @item dg-require-stack-size @var{size}
3106 Skip the test if the target does not support a stack size of @var{size}.
3108 @item dg-require-visibility @var{vis}
3109 Skip the test if the target does not support the @code{visibility} attribute.
3110 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
3111 checked, for @code{visibility("@var{vis}")} otherwise.
3114 The original @code{dg-require} directives were defined before there
3115 was support for effective-target keywords. The directives that do not
3116 take arguments could be replaced with effective-target keywords.
3119 @item dg-require-alias ""
3120 Skip the test if the target does not support the @samp{alias} attribute.
3122 @item dg-require-ascii-locale ""
3123 Skip the test if the host does not support an ASCII locale.
3125 @item dg-require-compat-dfp ""
3126 Skip this test unless both compilers in a @file{compat} testsuite
3127 support decimal floating point.
3129 @item dg-require-cxa-atexit ""
3130 Skip the test if the target does not support @code{__cxa_atexit}.
3131 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
3133 @item dg-require-dll ""
3134 Skip the test if the target does not support DLL attributes.
3136 @item dg-require-dot ""
3137 Skip the test if the host does not have @command{dot}.
3139 @item dg-require-fork ""
3140 Skip the test if the target does not support @code{fork}.
3142 @item dg-require-gc-sections ""
3143 Skip the test if the target's linker does not support the
3144 @code{--gc-sections} flags.
3145 This is equivalent to @code{dg-require-effective-target gc-sections}.
3147 @item dg-require-host-local ""
3148 Skip the test if the host is remote, rather than the same as the build
3149 system. Some tests are incompatible with DejaGnu's handling of remote
3150 hosts, which involves copying the source file to the host and compiling
3151 it with a relative path and "@code{-o a.out}".
3153 @item dg-require-mkfifo ""
3154 Skip the test if the target does not support @code{mkfifo}.
3156 @item dg-require-named-sections ""
3157 Skip the test is the target does not support named sections.
3158 This is equivalent to @code{dg-require-effective-target named_sections}.
3160 @item dg-require-weak ""
3161 Skip the test if the target does not support weak symbols.
3163 @item dg-require-weak-override ""
3164 Skip the test if the target does not support overriding weak symbols.
3168 @subsection Commands for use in @code{dg-final}
3170 The GCC testsuite defines the following directives to be used within
3173 @subsubsection Scan a particular file
3176 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
3177 Passes if @var{regexp} matches text in @var{filename}.
3178 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
3179 Passes if @var{regexp} does not match text in @var{filename}.
3180 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
3181 Passes if @var{regexp} matches in Fortran module @var{module}.
3182 @item dg-check-dot @var{filename}
3183 Passes if @var{filename} is a valid @file{.dot} file (by running
3184 @code{dot -Tpng} on it, and verifying the exit code is 0).
3185 @item scan-sarif-file @var{regexp} [@{ target/xfail @var{selector} @}]
3186 Passes if @var{regexp} matches text in the file generated by
3187 @option{-fdiagnostics-format=sarif-file}.
3188 @item scan-sarif-file-not @var{regexp} [@{ target/xfail @var{selector} @}]
3189 Passes if @var{regexp} does not match text in the file generated by
3190 @option{-fdiagnostics-format=sarif-file}.
3193 @subsubsection Scan the assembly output
3196 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
3197 Passes if @var{regex} matches text in the test's assembler output.
3199 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
3200 Passes if @var{regex} does not match text in the test's assembler output.
3202 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
3203 Passes if @var{regex} is matched exactly @var{num} times in the test's
3206 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
3207 Passes if @var{regex} matches text in the test's demangled assembler output.
3209 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
3210 Passes if @var{regex} does not match text in the test's demangled assembler
3213 @item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
3214 Passes if @var{functions} are all in @var{section}. The caller needs to
3215 allow for @code{USER_LABEL_PREFIX} and different section name conventions.
3217 @item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
3218 Passes if @var{functions} are all in @var{section}in @var{filename}.
3219 The same caveats as for @code{scan-assembler-symbol-section} apply.
3221 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
3222 Passes if @var{symbol} is defined as a hidden symbol in the test's
3225 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
3226 Passes if @var{symbol} is not defined as a hidden symbol in the test's
3229 @item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @}]]
3230 Looks through the source file for comments that give the expected assembly
3231 output for selected functions. Each line of expected output starts with the
3232 prefix string @var{prefix} and the expected output for a function as a whole
3233 is followed by a line that starts with the string @var{terminator}.
3234 Specifying an empty terminator is equivalent to specifying @samp{"*/"}.
3236 @var{options}, if specified, is a list of regular expressions, each of
3237 which matches a full command-line option. A non-empty list prevents
3238 the test from running unless all of the given options are present on the
3239 command line. This can help if a source file is compiled both with
3240 and without optimization, since it is rarely useful to check the full
3241 function body for unoptimized code.
3243 The first line of the expected output for a function @var{fn} has the form:
3246 @var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}]
3249 Subsequent lines of the expected output also start with @var{prefix}.
3250 In both cases, whitespace after @var{prefix} is not significant.
3252 The test discards assembly directives such as @code{.cfi_startproc}
3253 and local label definitions such as @code{.LFB0} from the compiler's
3254 assembly output. It then matches the result against the expected
3255 output for a function as a single regular expression. This means that
3256 later lines can use backslashes to refer back to @samp{(@dots{})}
3257 captures on earlier lines. For example:
3260 /* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */
3264 ** mov (z[0-9]+\.b), w0
3265 ** add z0\.b, p0/m, z0\.b, \1
3268 svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @}
3272 ** mov (z[0-9]+\.b), b0
3273 ** add z1\.b, p0/m, z1\.b, \1
3276 svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @}
3279 checks whether the implementations of @code{add_w0_s8_m} and
3280 @code{add_b0_s8_m} match the regular expressions given. The test only
3281 runs when @samp{-DCHECK_ASM} is passed on the command line.
3283 It is possible to create non-capturing multi-line regular expression
3284 groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the
3285 @samp{(}, @samp{|} and @samp{)} on separate lines (each still using
3286 @var{prefix}). For example:
3292 ** fcmge p0\.h, p0/z, z1\.h, z0\.h
3294 ** fcmle p0\.h, p0/z, z0\.h, z1\.h
3298 svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @}
3301 checks whether @code{cmple_f16_tied} is implemented by the
3302 @code{fcmge} instruction followed by @code{ret} or by the
3303 @code{fcmle} instruction followed by @code{ret}. The test is
3304 still a single regular rexpression.
3306 A line containing just:
3312 stands for zero or more unmatched lines; the whitespace after
3313 @var{prefix} is again not significant.
3317 @subsubsection Scan optimization dump files
3319 These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree},
3320 @code{offload-tree}, @code{rtl}, @code{offload-rtl}, @code{ipa}, and
3324 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3325 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
3327 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3328 Passes if @var{regex} does not match text in the dump file with suffix
3331 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
3332 Passes if @var{regex} is found exactly @var{num} times in the dump file
3333 with suffix @var{suffix}.
3335 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3336 Passes if @var{regex} matches demangled text in the dump file with
3337 suffix @var{suffix}.
3339 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3340 Passes if @var{regex} does not match demangled text in the dump file with
3341 suffix @var{suffix}.
3344 The @var{suffix} argument which describes the dump file to be scanned
3345 may contain a glob pattern that must expand to exactly one file
3346 name. This is useful if, e.g., different pass instances are executed
3347 depending on torture testing command-line flags, producing dump files
3348 whose names differ only in their pass instance number suffix. For
3349 example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for
3350 occurrences of the string ``code has been optimized'', use:
3352 /* @{ dg-options "-fdump-tree-mypass" @} */
3353 /* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */
3357 @subsubsection Check for output files
3360 @item output-exists [@{ target/xfail @var{selector} @}]
3361 Passes if compiler output file exists.
3363 @item output-exists-not [@{ target/xfail @var{selector} @}]
3364 Passes if compiler output file does not exist.
3366 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
3367 Passes if the pattern is present in the final executable.
3369 @item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}]
3370 Passes if the pattern is absent from the final executable.
3373 @subsubsection Checks for @command{gcov} tests
3376 @item run-gcov @var{sourcefile}
3377 Check line counts in @command{gcov} tests.
3379 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
3380 Check branch and/or call counts, in addition to line counts, in
3381 @command{gcov} tests.
3383 @item run-gcov-pytest @{ @var{sourcefile} @var{pytest_file} @}
3384 Check output of @command{gcov} intermediate format with a pytest
3388 @subsubsection Clean up generated test files
3390 Usually the test-framework removes files that were generated during
3391 testing. If a testcase, for example, uses any dumping mechanism to
3392 inspect a passes dump file, the testsuite recognized the dump option
3393 passed to the tool and schedules a final cleanup to remove these files.
3395 There are, however, following additional cleanup directives that can be
3396 used to annotate a testcase "manually".
3398 @item cleanup-coverage-files
3399 Removes coverage data files generated for this test.
3401 @item cleanup-modules "@var{list-of-extra-modules}"
3402 Removes Fortran module files generated for this test, excluding the
3403 module names listed in keep-modules.
3404 Cleaning up module files is usually done automatically by the testsuite
3405 by looking at the source files and removing the modules after the test
3416 ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
3417 ! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
3420 @item keep-modules "@var{list-of-modules-not-to-delete}"
3421 Whitespace separated list of module names that should not be deleted by
3423 If the list of modules is empty, all modules defined in this file are kept.
3425 module maybe_unneeded
3426 end module maybe_unneeded
3431 ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
3432 ! @{ dg-final @{ keep-modules "" @} @} ! keep all
3435 @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}"
3436 Whitespace separated list of suffixes that should not be deleted
3437 automatically in a testcase that uses @option{-save-temps}.
3439 // @{ dg-options "-save-temps -fpch-preprocess -I." @}
3440 int main() @{ return 0; @}
3441 // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file
3442 // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i
3443 // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o
3446 @item cleanup-profile-file
3447 Removes profiling files generated for this test.
3452 @section Ada Language Testsuites
3454 The Ada testsuite includes executable tests from the ACATS
3455 testsuite, publicly available at
3456 @uref{http://www.ada-auth.org/acats.html}.
3458 These tests are integrated in the GCC testsuite in the
3459 @file{ada/acats} directory, and
3460 enabled automatically when running @code{make check}, assuming
3461 the Ada language has been enabled when configuring GCC@.
3463 You can also run the Ada testsuite independently, using
3464 @code{make check-ada}, or run a subset of the tests by specifying which
3465 chapter to run, e.g.:
3468 $ make check-ada CHAPTERS="c3 c9"
3471 The tests are organized by directory, each directory corresponding to
3472 a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
3473 to chapter 9, which deals with tasking features of the language.
3475 The tests are run using two @command{sh} scripts: @file{run_acats} and
3476 @file{run_all.sh}. To run the tests using a simulator or a cross
3477 target, see the small
3478 customization section at the top of @file{run_all.sh}.
3480 These tests are run using the build tree: they can be run without doing
3481 a @code{make install}.
3484 @section C Language Testsuites
3486 GCC contains the following C language testsuites, in the
3487 @file{gcc/testsuite} directory:
3491 This contains tests of particular features of the C compiler, using the
3492 more modern @samp{dg} harness. Correctness tests for various compiler
3493 features should go here if possible.
3495 Magic comments determine whether the file
3496 is preprocessed, compiled, linked or run. In these tests, error and warning
3497 message texts are compared against expected texts or regular expressions
3498 given in comments. These tests are run with the options @samp{-ansi -pedantic}
3499 unless other options are given in the test. Except as noted below they
3500 are not run with multiple optimization options.
3502 This subdirectory contains tests for binary compatibility using
3503 @file{lib/compat.exp}, which in turn uses the language-independent support
3504 (@pxref{compat Testing, , Support for testing binary compatibility}).
3506 This subdirectory contains tests of the preprocessor.
3508 This subdirectory contains tests for debug formats. Tests in this
3509 subdirectory are run for each debug format that the compiler supports.
3511 This subdirectory contains tests of the @option{-Wformat} format
3512 checking. Tests in this directory are run with and without
3514 @item gcc.dg/noncompile
3515 This subdirectory contains tests of code that should not compile and
3516 does not need any special compilation options. They are run with
3517 multiple optimization options, since sometimes invalid code crashes
3518 the compiler with optimization.
3519 @item gcc.dg/special
3520 FIXME: describe this.
3523 This contains particular code fragments which have historically broken easily.
3524 These tests are run with multiple optimization options, so tests for features
3525 which only break at some optimization levels belong here. This also contains
3526 tests to check that certain optimizations occur. It might be worthwhile to
3527 separate the correctness tests cleanly from the code quality tests, but
3528 it hasn't been done yet.
3530 @item gcc.c-torture/compat
3531 FIXME: describe this.
3533 This directory should probably not be used for new tests.
3534 @item gcc.c-torture/compile
3535 This testsuite contains test cases that should compile, but do not
3536 need to link or run. These test cases are compiled with several
3537 different combinations of optimization options. All warnings are
3538 disabled for these test cases, so this directory is not suitable if
3539 you wish to test for the presence or absence of compiler warnings.
3540 While special options can be set, and tests disabled on specific
3541 platforms, by the use of @file{.x} files, mostly these test cases
3542 should not contain platform dependencies. FIXME: discuss how defines
3543 such as @code{STACK_SIZE} are used.
3544 @item gcc.c-torture/execute
3545 This testsuite contains test cases that should compile, link and run;
3546 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
3547 @item gcc.c-torture/execute/ieee
3548 This contains tests which are specific to IEEE floating point.
3549 @item gcc.c-torture/unsorted
3550 FIXME: describe this.
3552 This directory should probably not be used for new tests.
3553 @item gcc.misc-tests
3554 This directory contains C tests that require special handling. Some
3555 of these tests have individual expect files, and others share
3556 special-purpose expect files:
3559 @item @code{bprob*.c}
3560 Test @option{-fbranch-probabilities} using
3561 @file{gcc.misc-tests/bprob.exp}, which
3562 in turn uses the generic, language-independent framework
3563 (@pxref{profopt Testing, , Support for testing profile-directed
3566 @item @code{gcov*.c}
3567 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
3568 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
3570 @item @code{i386-pf-*.c}
3571 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
3574 @item gcc.test-framework
3577 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
3582 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
3583 test cases and magic comments more.
3586 @section Support for testing link-time optimizations
3588 Tests for link-time optimizations usually require multiple source files
3589 that are compiled separately, perhaps with different sets of options.
3590 There are several special-purpose test directives used for these tests.
3593 @item @{ dg-lto-do @var{do-what-keyword} @}
3594 @var{do-what-keyword} specifies how the test is compiled and whether
3595 it is executed. It is one of:
3599 Compile with @option{-c} to produce a relocatable object file.
3601 Compile, assemble, and link to produce an executable file.
3603 Produce and run an executable file, which is expected to return
3607 The default is @code{assemble}. That can be overridden for a set of
3608 tests by redefining @code{dg-do-what-default} within the @code{.exp}
3609 file for those tests.
3611 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
3612 @samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
3613 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
3615 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
3616 This directive provides a list of one or more sets of compiler options
3617 to override @var{LTO_OPTIONS}. Each test will be compiled and run with
3618 each of these sets of options.
3620 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
3621 This directive adds @var{options} to the linker options used.
3623 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
3624 This directive removes @var{options} from the set of linker options used.
3628 @section Support for testing @command{gcov}
3630 Language-independent support for testing @command{gcov}, and for checking
3631 that branch profiling produces expected values, is provided by the
3632 expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
3633 in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
3634 @command{gcov} test contains the following DejaGnu commands within comments:
3637 @{ dg-options "--coverage" @}
3638 @{ dg-do run @{ target native @} @}
3639 @{ dg-final @{ run-gcov sourcefile @} @}
3642 Checks of @command{gcov} output can include line counts, branch percentages,
3643 and call return percentages. All of these checks are requested via
3644 commands that appear in comments in the test's source file.
3645 Commands to check line counts are processed by default.
3646 Commands to check branch percentages and call return percentages are
3647 processed if the @command{run-gcov} command has arguments @code{branches}
3648 or @code{calls}, respectively. For example, the following specifies
3649 checking both, as well as passing @option{-b} to @command{gcov}:
3652 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
3655 A line count command appears within a comment on the source line
3656 that is expected to get the specified count and has the form
3657 @code{count(@var{cnt})}. A test should only check line counts for
3658 lines that will get the same count for any architecture.
3660 Commands to check branch percentages (@code{branch}) and call
3661 return percentages (@code{returns}) are very similar to each other.
3662 A beginning command appears on or before the first of a range of
3663 lines that will report the percentage, and the ending command
3664 follows that range of lines. The beginning command can include a
3665 list of percentages, all of which are expected to be found within
3666 the range. A range is terminated by the next command of the same
3667 kind. A command @code{branch(end)} or @code{returns(end)} marks
3668 the end of a range without starting a new one. For example:
3671 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
3672 /* @r{branch(end)} */
3676 For a call return percentage, the value specified is the
3677 percentage of calls reported to return. For a branch percentage,
3678 the value is either the expected percentage or 100 minus that
3679 value, since the direction of a branch can differ depending on the
3680 target or the optimization level.
3682 Not all branches and calls need to be checked. A test should not
3683 check for branches that might be optimized away or replaced with
3684 predicated instructions. Don't check for calls inserted by the
3685 compiler or ones that might be inlined or optimized away.
3687 A single test can check for combinations of line counts, branch
3688 percentages, and call return percentages. The command to check a
3689 line count must appear on the line that will report that count, but
3690 commands to check branch percentages and call return percentages can
3691 bracket the lines that report them.
3693 @node profopt Testing
3694 @section Support for testing profile-directed optimizations
3696 The file @file{profopt.exp} provides language-independent support for
3697 checking correct execution of a test built with profile-directed
3698 optimization. This testing requires that a test program be built and
3699 executed twice. The first time it is compiled to generate profile
3700 data, and the second time it is compiled to use the data that was
3701 generated during the first execution. The second execution is to
3702 verify that the test produces the expected results.
3704 To check that the optimization actually generated better code, a
3705 test can be built and run a third time with normal optimizations to
3706 verify that the performance is better with the profile-directed
3707 optimizations. @file{profopt.exp} has the beginnings of this kind
3710 @file{profopt.exp} provides generic support for profile-directed
3711 optimizations. Each set of tests that uses it provides information
3712 about a specific optimization:
3716 tool being tested, e.g., @command{gcc}
3718 @item profile_option
3719 options used to generate profile data
3721 @item feedback_option
3722 options used to optimize using that profile data
3725 suffix of profile data files
3727 @item PROFOPT_OPTIONS
3728 list of options with which to run each test, similar to the lists for
3731 @item @{ dg-final-generate @{ @var{local-directive} @} @}
3732 This directive is similar to @code{dg-final}, but the
3733 @var{local-directive} is run after the generation of profile data.
3735 @item @{ dg-final-use @{ @var{local-directive} @} @}
3736 The @var{local-directive} is run after the profile data have been
3740 @node compat Testing
3741 @section Support for testing binary compatibility
3743 The file @file{compat.exp} provides language-independent support for
3744 binary compatibility testing. It supports testing interoperability of
3745 two compilers that follow the same ABI, or of multiple sets of
3746 compiler options that should not affect binary compatibility. It is
3747 intended to be used for testsuites that complement ABI testsuites.
3749 A test supported by this framework has three parts, each in a
3750 separate source file: a main program and two pieces that interact
3751 with each other to split up the functionality being tested.
3754 @item @var{testname}_main.@var{suffix}
3755 Contains the main program, which calls a function in file
3756 @file{@var{testname}_x.@var{suffix}}.
3758 @item @var{testname}_x.@var{suffix}
3759 Contains at least one call to a function in
3760 @file{@var{testname}_y.@var{suffix}}.
3762 @item @var{testname}_y.@var{suffix}
3763 Shares data with, or gets arguments from,
3764 @file{@var{testname}_x.@var{suffix}}.
3767 Within each test, the main program and one functional piece are
3768 compiled by the GCC under test. The other piece can be compiled by
3769 an alternate compiler. If no alternate compiler is specified,
3770 then all three source files are all compiled by the GCC under test.
3771 You can specify pairs of sets of compiler options. The first element
3772 of such a pair specifies options used with the GCC under test, and the
3773 second element of the pair specifies options used with the alternate
3774 compiler. Each test is compiled with each pair of options.
3776 @file{compat.exp} defines default pairs of compiler options.
3777 These can be overridden by defining the environment variable
3778 @env{COMPAT_OPTIONS} as:
3781 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
3782 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
3785 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
3786 used by the compiler under test and @var{alti} used by the alternate
3787 compiler. For example, with
3788 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
3789 the test is first built with @option{-g -O0} by the compiler under
3790 test and with @option{-O3} by the alternate compiler. The test is
3791 built a second time using @option{-fpic} by the compiler under test
3792 and @option{-fPIC -O2} by the alternate compiler.
3794 An alternate compiler is specified by defining an environment
3795 variable to be the full pathname of an installed compiler; for C
3796 define @env{ALT_CC_UNDER_TEST}, and for C++ define
3797 @env{ALT_CXX_UNDER_TEST}. These will be written to the
3798 @file{site.exp} file used by DejaGnu. The default is to build each
3799 test with the compiler under test using the first of each pair of
3800 compiler options from @env{COMPAT_OPTIONS}. When
3801 @env{ALT_CC_UNDER_TEST} or
3802 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
3803 the compiler under test but with combinations of the options from
3804 @env{COMPAT_OPTIONS}.
3806 To run only the C++ compatibility suite using the compiler under test
3807 and another version of GCC using specific compiler options, do the
3808 following from @file{@var{objdir}/gcc}:
3813 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
3814 COMPAT_OPTIONS="@var{lists as shown above}" \
3816 RUNTESTFLAGS="compat.exp"
3819 A test that fails when the source files are compiled with different
3820 compilers, but passes when the files are compiled with the same
3821 compiler, demonstrates incompatibility of the generated code or
3822 runtime support. A test that fails for the alternate compiler but
3823 passes for the compiler under test probably tests for a bug that was
3824 fixed in the compiler under test but is present in the alternate
3827 The binary compatibility tests support a small number of test framework
3828 commands that appear within comments in a test file.
3832 These commands can be used in @file{@var{testname}_main.@var{suffix}}
3833 to skip the test if specific support is not available on the target.
3836 The specified options are used for compiling this particular source
3837 file, appended to the options from @env{COMPAT_OPTIONS}. When this
3838 command appears in @file{@var{testname}_main.@var{suffix}} the options
3839 are also used to link the test program.
3842 This command can be used in a secondary source file to specify that
3843 compilation is expected to fail for particular options on particular
3848 @section Support for torture testing using multiple options
3850 Throughout the compiler testsuite there are several directories whose
3851 tests are run multiple times, each with a different set of options.
3852 These are known as torture tests.
3853 @file{lib/torture-options.exp} defines procedures to
3858 Initialize use of torture lists.
3859 @item set-torture-options
3860 Set lists of torture options to use for tests with and without loops.
3861 Optionally combine a set of torture options with a set of other
3862 options, as is done with Objective-C runtime options.
3863 @item torture-finish
3864 Finalize use of torture lists.
3867 The @file{.exp} file for a set of tests that use torture options must
3868 include calls to these three procedures if:
3871 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
3873 @item It calls @var{$@{tool@}}@code{-torture} or
3874 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
3875 @code{fortran}, or @code{objc}.
3877 @item It calls @code{dg-pch}.
3880 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
3881 to call the torture procedures if the tests should use the list in
3882 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
3884 Most uses of torture options can override the default lists by defining
3885 @var{TORTURE_OPTIONS} or add to the default list by defining
3886 @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
3887 file or add them to the @file{site.exp} file; for example
3890 set ADDITIONAL_TORTURE_OPTIONS [list \
3891 @{ -O2 -ftree-loop-linear @} \
3892 @{ -O2 -fpeel-loops @} ]
3896 @section Support for testing GIMPLE passes
3898 As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
3899 that the function body will be GIMPLE, rather than C. The compiler requires
3900 the option @option{-fgimple} to enable this functionality. For example:
3903 /* @{ dg-do compile @} */
3904 /* @{ dg-options "-O -fgimple" @} */
3906 void __GIMPLE (startwith ("dse2")) foo ()
3924 a_1 = __PHI (bb_3: a_2, bb_4: a_3);
3931 The @code{startwith} argument indicates at which pass to begin.
3933 Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple})
3934 to make tree dumps more closely follow the format accepted by the GIMPLE
3937 Example DejaGnu tests of GIMPLE can be seen in the source tree at
3938 @file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
3940 The @code{__GIMPLE} parser is integrated with the C tokenizer and
3941 preprocessor, so it should be possible to use macros to build out
3945 @section Support for testing RTL passes
3947 As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
3948 function body will be RTL, rather than C. For example:
3951 double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
3954 [...snip; various directives go in here...]
3955 ) ;; function "test"
3959 The @code{startwith} argument indicates at which pass to begin.
3961 The parser expects the RTL body to be in the format emitted by this
3966 print_rtx_function (FILE *outfile, function *fn, bool compact);
3969 when "compact" is true. So you can capture RTL in the correct format
3970 from the debugger using:
3973 (gdb) print_rtx_function (stderr, cfun, true);
3976 and copy and paste the output into the body of the C function.
3978 Example DejaGnu tests of RTL can be seen in the source tree under
3979 @file{gcc/testsuite/gcc.dg/rtl}.
3981 The @code{__RTL} parser is not integrated with the C tokenizer or
3982 preprocessor, and works simply by reading the relevant lines within
3983 the braces. In particular, the RTL body must be on separate lines from
3984 the enclosing braces, and the preprocessor is not usable within it.