Debian Codegraph @

gcc/doc/sourcebuild.texi

raw
1 @c Copyright (C) 2002-2023 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
4
5 @node Source Tree
6 @chapter Source Tree Structure and Build System
7
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.
12
13 @menu
14 * Configure Terms:: Configuration terminology and history.
15 * Top Level:: The top level source directory.
16 * gcc Directory:: The @file{gcc} subdirectory.
17 @end menu
18
19 @include configterms.texi
20
21 @node Top Level
22 @section Top Level Source Directory
23
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:
28
29 @table @file
30 @item c++tools
31 Contains the sources for the g++-mapper-server, a tool used with
32 C++ modules.
33
34 @item config
35 Autoconf macros and Makefile fragments used throughout the tree.
36
37 @item contrib
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.
41
42 @item fixincludes
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}.
48
49 @item gcc
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.
54
55 @item gnattools
56 Support tools for GNAT.
57
58 @item gotools
59 Support tools for Go.
60
61 @item include
62 Headers for the @code{libiberty} library.
63
64 @item intl
65 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
66 include it in @code{libc}.
67
68 @item libada
69 The Ada runtime library.
70
71 @item libatomic
72 The runtime support library for atomic operations (e.g.@: for @code{__sync}
73 and @code{__atomic}).
74
75 @item libbacktrace
76 A library that allows GCC to produce backtraces when it crashes.
77
78 @item libcc1
79 A library that allows GDB to make use of the compiler.
80
81 @item libcody
82 A compiler dynamism library to allow communication between compilers and
83 build systems, for purposes such as C++ modules.
84
85 @item libcpp
86 The C preprocessor library.
87
88 @item libdecnumber
89 The Decimal Float support library.
90
91 @item libffi
92 The @code{libffi} library, used as part of the Go runtime library.
93
94 @item libgcc
95 The GCC runtime library.
96
97 @item libgfortran
98 The Fortran runtime library.
99
100 @item libgm2
101 The Modula-2 runtime library.
102
103 @item libgo
104 The Go runtime library. The bulk of this library is mirrored from the
105 @uref{https://github.com/@/golang/go, master Go repository}.
106
107 @item libgomp
108 The GNU Offloading and Multi Processing Runtime Library.
109
110 @item libiberty
111 The @code{libiberty} library, used for portability and for some
112 generally useful data structures and algorithms. @xref{Top, ,
113 Introduction, libiberty, @sc{gnu} libiberty}, for more information
114 about this library.
115
116 @item libitm
117 The runtime support library for transactional memory.
118
119 @item libobjc
120 The Objective-C and Objective-C++ runtime library.
121
122 @item libphobos
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}.
125
126 @item libquadmath
127 The runtime support library for quad-precision math operations.
128
129 @item libsanitizer
130 Libraries for various sanitizers. The bulk of this directory is mirrored
131 from the @uref{https://github.com/google/sanitizers, Google sanitizers
132 repositories}.
133
134 @item libssp
135 The Stack protector runtime library.
136
137 @item libstdc++-v3
138 The C++ runtime library.
139
140 @item libvtv
141 The vtable verification library.
142
143 @item lto-plugin
144 Plugin used by the linker if link-time optimizations are enabled.
145
146 @item maintainer-scripts
147 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
148
149 @item zlib
150 The @code{zlib} compression library, used for compressing and
151 uncompressing GCC's intermediate language in LTO object files.
152 @end table
153
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.
158
159 @node gcc Directory
160 @section The @file{gcc} Subdirectory
161
162 The @file{gcc} directory contains many files that are part of the C
163 sources of GCC, other files used as part of the configuration and
164 build process, and subdirectories including documentation and a
165 testsuite. The files that are sources of GCC are documented in a
166 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
167
168 @menu
169 * Subdirectories:: Subdirectories of @file{gcc}.
170 * Configuration:: The configuration process, and the files it uses.
171 * Build:: The build system in the @file{gcc} directory.
172 * Makefile:: Targets in @file{gcc/Makefile}.
173 * Library Files:: Library source files and headers under @file{gcc/}.
174 * Headers:: Headers installed by GCC.
175 * Documentation:: Building documentation in GCC.
176 * Front End:: Anatomy of a language front end.
177 * Back End:: Anatomy of a target back end.
178 @end menu
179
180 @node Subdirectories
181 @subsection Subdirectories of @file{gcc}
182
183 The @file{gcc} directory contains the following subdirectories:
184
185 @table @file
186 @item @var{language}
187 Subdirectories for various languages. Directories containing a file
188 @file{config-lang.in} are language subdirectories. The contents of
189 the subdirectories @file{c} (for C), @file{cp} (for C++), @file{m2}
190 (for Modula-2),
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
196 directories.
197
198 @item common
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}.
203
204 @item config
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.
208
209 @item doc
210 Texinfo documentation for GCC, together with automatically generated
211 man pages and support for converting the installation manual to
212 HTML@. @xref{Documentation}.
213
214 @item ginclude
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
218 installed.
219
220 @item po
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.
228
229 @item testsuite
230 The GCC testsuites (except for those for runtime libraries).
231 @xref{Testsuites}.
232 @end table
233
234 @node Configuration
235 @subsection Configuration in the @file{gcc} Directory
236
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
242 timestamp.
243
244 @menu
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}.
249 @end menu
250
251 @node Config Fragments
252 @subsubsection Scripts Used by @file{configure}
253
254 @file{configure} uses some other scripts to help in its work:
255
256 @itemize @bullet
257 @item The standard GNU @file{config.sub} and @file{config.guess}
258 files, kept in the top level directory, are used.
259
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.
269
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.
274
275 @item A helper script @file{configure.frag} is used as part of
276 creating the output of @file{configure}.
277 @end itemize
278
279 @node System Config
280 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
281
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.
285
286 The @file{config.host} file contains specific rules for particular systems
287 which GCC will run on. This is rarely needed.
288
289 The @file{config.gcc} file contains specific rules for particular systems
290 which GCC will generate code for. This is usually needed.
291
292 Each file has a list of the shell variables it sets, with descriptions, at the
293 top of the file.
294
295 FIXME: document the contents of these files, and what variables should
296 be set to control build, host and target configuration.
297
298 @include configfiles.texi
299
300 @node Build
301 @subsection Build System in the @file{gcc} Directory
302
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}).
307
308 @include makefile.texi
309
310 @node Library Files
311 @subsection Library Source Files and Headers under the @file{gcc} Directory
312
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.
319
320 @node Headers
321 @subsection Headers Installed by GCC
322
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.)
330
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}.
337
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.
343
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.
347
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.
359
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}.
362
363 @node Documentation
364 @subsection Building Documentation
365
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.
374
375 @menu
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.
379 @end menu
380
381 @node Texinfo Manuals
382 @subsubsection Texinfo Manuals
383
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}:
389
390 @table @file
391 @item fdl.texi
392 The GNU Free Documentation License.
393 @item funding.texi
394 The section ``Funding Free Software''.
395 @item gcc-common.texi
396 Common definitions for manuals.
397 @item gpl_v3.texi
398 The GNU General Public License.
399 @item texinfo.tex
400 A copy of @file{texinfo.tex} known to work with the GCC manuals.
401 @end table
402
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.
412
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.
429
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}.
433
434 @node Man Page Generation
435 @subsubsection Man Page Generation
436
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
443 Texinfo manuals.)
444
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.
451
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:
459
460 @table @code
461 @item @@gcctabopt
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
465 wanted.
466 @item @@gccoptlist
467 Use for summary lists of options in manuals.
468 @end table
469
470 FIXME: describe the @file{texi2pod.pl} input language and magic
471 comments in more detail.
472
473 @node Miscellaneous Docs
474 @subsubsection Miscellaneous Documentation
475
476 In addition to the formal documentation that is installed by GCC,
477 there are several other text files in the @file{gcc} subdirectory
478 with miscellaneous documentation:
479
480 @table @file
481 @item ABOUT-GCC-NLS
482 Notes on GCC's Native Language Support. FIXME: this should be part of
483 this manual rather than a separate file.
484 @item ABOUT-NLS
485 Notes on the Free Translation Project.
486 @item COPYING
487 @itemx COPYING3
488 The GNU General Public License, Versions 2 and 3.
489 @item COPYING.LIB
490 @itemx COPYING3.LIB
491 The GNU Lesser General Public License, Versions 2.1 and 3.
492 @item *ChangeLog*
493 @itemx */ChangeLog*
494 Change log files for various parts of GCC@.
495 @item LANGUAGES
496 Details of a few changes to the GCC front-end interface. FIXME: the
497 information in this file should be part of general documentation of
498 the front-end interface in this manual.
499 @item ONEWS
500 Information about new features in old versions of GCC@. (For recent
501 versions, the information is on the GCC web site.)
502 @item README.Portability
503 Information about portability issues when writing code in GCC@. FIXME:
504 why isn't this part of this manual or of the GCC Coding Conventions?
505 @end table
506
507 FIXME: document such files in subdirectories, at least @file{config},
508 @file{c}, @file{cp}, @file{objc}, @file{testsuite}.
509
510 @node Front End
511 @subsection Anatomy of a Language Front End
512
513 A front end for a language in GCC has the following parts:
514
515 @itemize @bullet
516 @item
517 A directory @file{@var{language}} under @file{gcc} containing source
518 files for that front end. @xref{Front End Directory, , The Front End
519 @file{@var{language}} Directory}, for details.
520 @item
521 A mention of the language in the list of supported languages in
522 @file{gcc/doc/install.texi}.
523 @item
524 A mention of the name under which the language's runtime library is
525 recognized by @option{--enable-shared=@var{package}} in the
526 documentation of that option in @file{gcc/doc/install.texi}.
527 @item
528 A mention of any special prerequisites for building the front end in
529 the documentation of prerequisites in @file{gcc/doc/install.texi}.
530 @item
531 Details of contributors to that front end in
532 @file{gcc/doc/contrib.texi}. If the details are in that front end's
533 own manual then there should be a link to that manual's list in
534 @file{contrib.texi}.
535 @item
536 Information about support for that language in
537 @file{gcc/doc/frontends.texi}.
538 @item
539 Information about standards for that language, and the front end's
540 support for them, in @file{gcc/doc/standards.texi}. This may be a
541 link to such information in the front end's own manual.
542 @item
543 Details of source file suffixes for that language and @option{-x
544 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
545 @item
546 Entries in @code{default_compilers} in @file{gcc.cc} for source file
547 suffixes for that language.
548 @item
549 Preferably testsuites, which may be under @file{gcc/testsuite} or
550 runtime library directories. FIXME: document somewhere how to write
551 testsuite harnesses.
552 @item
553 Probably a runtime library for the language, outside the @file{gcc}
554 directory. FIXME: document this further.
555 @item
556 Details of the directories of any runtime libraries in
557 @file{gcc/doc/sourcebuild.texi}.
558 @item
559 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
560 to check just the compiler or the compiler and runtime library for the
561 language.
562 @end itemize
563
564 If the front end is added to the official GCC source repository, the
565 following are also necessary:
566
567 @itemize @bullet
568 @item
569 At least one Bugzilla component for bugs in that front end and runtime
570 libraries. This category needs to be added to the Bugzilla database.
571 @item
572 Normally, one or more maintainers of that front end listed in
573 @file{MAINTAINERS}.
574 @item
575 Mentions on the GCC web site in @file{index.html} and
576 @file{frontends.html}, with any relevant links on
577 @file{readings.html}. (Front ends that are not an official part of
578 GCC may also be listed on @file{frontends.html}, with relevant links.)
579 @item
580 A news item on @file{index.html}, and possibly an announcement on the
581 @email{gcc-announce@@gcc.gnu.org} mailing list.
582 @item
583 The front end's manuals should be mentioned in
584 @file{maintainer-scripts/update_web_docs_git} (@pxref{Texinfo Manuals})
585 and the online manuals should be linked to from
586 @file{onlinedocs/index.html}.
587 @item
588 Any old releases or CVS repositories of the front end, before its
589 inclusion in GCC, should be made available on the GCC web site at
590 @uref{https://gcc.gnu.org/pub/gcc/old-releases/}.
591 @item
592 The release and snapshot script @file{maintainer-scripts/gcc_release}
593 should be updated to generate appropriate tarballs for this front end.
594 @item
595 If this front end includes its own version files that include the
596 current date, @file{maintainer-scripts/update_version} should be
597 updated accordingly.
598 @end itemize
599
600 @menu
601 * Front End Directory:: The front end @file{@var{language}} directory.
602 * Front End Config:: The front end @file{config-lang.in} file.
603 * Front End Makefile:: The front end @file{Make-lang.in} file.
604 @end menu
605
606 @node Front End Directory
607 @subsubsection The Front End @file{@var{language}} Directory
608
609 A front end @file{@var{language}} directory contains the source files
610 of that front end (but not of any runtime libraries, which should be
611 outside the @file{gcc} directory). This includes documentation, and
612 possibly some subsidiary programs built alongside the front end.
613 Certain files are special and other parts of the compiler depend on
614 their names:
615
616 @table @file
617 @item config-lang.in
618 This file is required in all language subdirectories. @xref{Front End
619 Config, , The Front End @file{config-lang.in} File}, for details of
620 its contents
621 @item Make-lang.in
622 This file is required in all language subdirectories. @xref{Front End
623 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
624 contents.
625 @item lang.opt
626 This file registers the set of switches that the front end accepts on
627 the command line, and their @option{--help} text. @xref{Options}.
628 @item lang-specs.h
629 This file provides entries for @code{default_compilers} in
630 @file{gcc.cc} which override the default of giving an error that a
631 compiler for that language is not installed.
632 @item @var{language}-tree.def
633 This file, which need not exist, defines any language-specific tree
634 codes.
635 @end table
636
637 @node Front End Config
638 @subsubsection The Front End @file{config-lang.in} File
639
640 Each language subdirectory contains a @file{config-lang.in} file.
641 This file is a shell script that may define some variables describing
642 the language:
643
644 @table @code
645 @item language
646 This definition must be present, and gives the name of the language
647 for some purposes such as arguments to @option{--enable-languages}.
648 @item lang_requires
649 If defined, this variable lists (space-separated) language front ends
650 other than C that this front end requires to be enabled (with the
651 names given being their @code{language} settings). For example, the
652 Obj-C++ front end depends on the C++ and ObjC front ends, so sets
653 @samp{lang_requires="objc c++"}.
654 @item subdir_requires
655 If defined, this variable lists (space-separated) front end directories
656 other than C that this front end requires to be present. For example,
657 the Objective-C++ front end uses source files from the C++ and
658 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
659 @item target_libs
660 If defined, this variable lists (space-separated) targets in the top
661 level @file{Makefile} to build the runtime libraries for this
662 language, such as @code{target-libobjc}.
663 @item lang_dirs
664 If defined, this variable lists (space-separated) top level
665 directories (parallel to @file{gcc}), apart from the runtime libraries,
666 that should not be configured if this front end is not built.
667 @item build_by_default
668 If defined to @samp{no}, this language front end is not built unless
669 enabled in a @option{--enable-languages} argument. Otherwise, front
670 ends are built by default, subject to any special logic in
671 @file{configure.ac} (as is present to disable the Ada front end if the
672 Ada compiler is not already installed).
673 @item boot_language
674 If defined to @samp{yes}, this front end is built in stage1 of the
675 bootstrap. This is only relevant to front ends written in their own
676 languages.
677 @item compilers
678 If defined, a space-separated list of compiler executables that will
679 be run by the driver. The names here will each end
680 with @samp{\$(exeext)}.
681 @item outputs
682 If defined, a space-separated list of files that should be generated
683 by @file{configure} substituting values in them. This mechanism can
684 be used to create a file @file{@var{language}/Makefile} from
685 @file{@var{language}/Makefile.in}, but this is deprecated, building
686 everything from the single @file{gcc/Makefile} is preferred.
687 @item gtfiles
688 If defined, a space-separated list of files that should be scanned by
689 @file{gengtype.cc} to generate the garbage collection tables and routines for
690 this language. This excludes the files that are common to all front
691 ends. @xref{Type Information}.
692
693 @end table
694
695 @node Front End Makefile
696 @subsubsection The Front End @file{Make-lang.in} File
697
698 Each language subdirectory contains a @file{Make-lang.in} file. It contains
699 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
700 setting of @code{language} in @file{config-lang.in}) for the following
701 values of @code{@var{hook}}, and any other Makefile rules required to
702 build those targets (which may if necessary use other Makefiles
703 specified in @code{outputs} in @file{config-lang.in}, although this is
704 deprecated). It also adds any testsuite targets that can use the
705 standard rule in @file{gcc/Makefile.in} to the variable
706 @code{lang_checks}.
707
708 @table @code
709 @item all.cross
710 @itemx start.encap
711 @itemx rest.encap
712 FIXME: exactly what goes in each of these targets?
713 @item tags
714 Build an @command{etags} @file{TAGS} file in the language subdirectory
715 in the source tree.
716 @item info
717 Build info documentation for the front end, in the build directory.
718 This target is only called by @samp{make bootstrap} if a suitable
719 version of @command{makeinfo} is available, so does not need to check
720 for this, and should fail if an error occurs.
721 @item dvi
722 Build DVI documentation for the front end, in the build directory.
723 This should be done using @code{$(TEXI2DVI)}, with appropriate
724 @option{-I} arguments pointing to directories of included files.
725 @item pdf
726 Build PDF documentation for the front end, in the build directory.
727 This should be done using @code{$(TEXI2PDF)}, with appropriate
728 @option{-I} arguments pointing to directories of included files.
729 @item html
730 Build HTML documentation for the front end, in the build directory.
731 @item man
732 Build generated man pages for the front end from Texinfo manuals
733 (@pxref{Man Page Generation}), in the build directory. This target
734 is only called if the necessary tools are available, but should ignore
735 errors so as not to stop the build if errors occur; man pages are
736 optional and the tools involved may be installed in a broken way.
737 @item install-common
738 Install everything that is part of the front end, apart from the
739 compiler executables listed in @code{compilers} in
740 @file{config-lang.in}.
741 @item install-info
742 Install info documentation for the front end, if it is present in the
743 source directory. This target should have dependencies on info files
744 that should be installed.
745 @item install-man
746 Install man pages for the front end. This target should ignore
747 errors.
748 @item install-plugin
749 Install headers needed for plugins.
750 @item srcextra
751 Copies its dependencies into the source directory. This generally should
752 be used for generated files such as Bison output files which are not
753 version-controlled, but should be included in any release tarballs. This
754 target will be executed during a bootstrap if
755 @samp{--enable-generated-files-in-srcdir} was specified as a
756 @file{configure} option.
757 @item srcinfo
758 @itemx srcman
759 Copies its dependencies into the source directory. These targets will be
760 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
761 was specified as a @file{configure} option.
762 @item uninstall
763 Uninstall files installed by installing the compiler. This is
764 currently documented not to be supported, so the hook need not do
765 anything.
766 @item mostlyclean
767 @itemx clean
768 @itemx distclean
769 @itemx maintainer-clean
770 The language parts of the standard GNU
771 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
772 Users, standards, GNU Coding Standards}, for details of the standard
773 targets. For GCC, @code{maintainer-clean} should delete
774 all generated files in the source directory that are not version-controlled,
775 but should not delete anything that is.
776 @end table
777
778 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
779 to a list of host object files that are used by that language.
780
781 @node Back End
782 @subsection Anatomy of a Target Back End
783
784 A back end for a target architecture in GCC has the following parts:
785
786 @itemize @bullet
787 @item
788 A directory @file{@var{machine}} under @file{gcc/config}, containing a
789 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
790 , Machine Descriptions}), header files @file{@var{machine}.h} and
791 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
792 (@pxref{Target Macros, , Target Description Macros and Functions}),
793 possibly a target Makefile fragment @file{t-@var{machine}}
794 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
795 some other files. The names of these files may be changed from the
796 defaults given by explicit specifications in @file{config.gcc}.
797 @item
798 If necessary, a file @file{@var{machine}-modes.def} in the
799 @file{@var{machine}} directory, containing additional machine modes to
800 represent condition codes. @xref{Condition Code}, for further details.
801 @item
802 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
803 directory, containing a list of target-specific options. You can also
804 add other option files using the @code{extra_options} variable in
805 @file{config.gcc}. @xref{Options}.
806 @item
807 Entries in @file{config.gcc} (@pxref{System Config, , The
808 @file{config.gcc} File}) for the systems with this target
809 architecture.
810 @item
811 Documentation in @file{gcc/doc/invoke.texi} for any command-line
812 options supported by this target (@pxref{Run-time Target, , Run-time
813 Target Specification}). This means both entries in the summary table
814 of options and details of the individual options.
815 @item
816 Documentation in @file{gcc/doc/extend.texi} for any target-specific
817 attributes supported (@pxref{Target Attributes, , Defining
818 target-specific uses of @code{__attribute__}}), including where the
819 same attribute is already supported on some targets, which are
820 enumerated in the manual.
821 @item
822 Documentation in @file{gcc/doc/extend.texi} for any target-specific
823 pragmas supported.
824 @item
825 Documentation in @file{gcc/doc/extend.texi} of any target-specific
826 built-in functions supported.
827 @item
828 Documentation in @file{gcc/doc/extend.texi} of any target-specific
829 format checking styles supported.
830 @item
831 Documentation in @file{gcc/doc/md.texi} of any target-specific
832 constraint letters (@pxref{Machine Constraints, , Constraints for
833 Particular Machines}).
834 @item
835 A note in @file{gcc/doc/contrib.texi} under the person or people who
836 contributed the target support.
837 @item
838 Entries in @file{gcc/doc/install.texi} for all target triplets
839 supported with this target architecture, giving details of any special
840 notes about installation for this target, or saying that there are no
841 special notes if there are none.
842 @item
843 Possibly other support outside the @file{gcc} directory for runtime
844 libraries. FIXME: reference docs for this. The @code{libstdc++} porting
845 manual needs to be installed as info for this to work, or to be a
846 chapter of this manual.
847 @end itemize
848
849 The @file{@var{machine}.h} header is included very early in GCC's
850 standard sequence of header files, while @file{@var{machine}-protos.h}
851 is included late in the sequence. Thus @file{@var{machine}-protos.h}
852 can include declarations referencing types that are not defined when
853 @file{@var{machine}.h} is included, specifically including those from
854 @file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not
855 be available in every context where @file{@var{machine}-protos.h} is
856 included, in this file you should guard declarations using these types
857 inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE}
858 conditional code segments.
859
860 If the backend uses shared data structures that require @code{GTY} markers
861 for garbage collection (@pxref{Type Information}), you must declare those
862 in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}.
863 Any definitions required for building libgcc must also go in
864 @file{@var{machine}.h}.
865
866 GCC uses the macro @code{IN_TARGET_CODE} to distinguish between
867 machine-specific @file{.c} and @file{.cc} files and
868 machine-independent @file{.c} and @file{.cc} files. Machine-specific
869 files should use the directive:
870
871 @example
872 #define IN_TARGET_CODE 1
873 @end example
874
875 before including @code{config.h}.
876
877 If the back end is added to the official GCC source repository, the
878 following are also necessary:
879
880 @itemize @bullet
881 @item
882 An entry for the target architecture in @file{readings.html} on the
883 GCC web site, with any relevant links.
884 @item
885 Details of the properties of the back end and target architecture in
886 @file{backends.html} on the GCC web site.
887 @item
888 A news item about the contribution of support for that target
889 architecture, in @file{index.html} on the GCC web site.
890 @item
891 Normally, one or more maintainers of that target listed in
892 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
893 but it would be unusual to add support for a target that does not have
894 a maintainer when support is added.
895 @item
896 Target triplets covering all @file{config.gcc} stanzas for the target,
897 in the list in @file{contrib/config-list.mk}.
898 @end itemize
899
900 @node Testsuites
901 @chapter Testsuites
902
903 GCC contains several testsuites to help maintain compiler quality.
904 Most of the runtime libraries and language front ends in GCC have
905 testsuites. Currently only the C language testsuites are documented
906 here; FIXME: document the others.
907
908 @menu
909 * Test Idioms:: Idioms used in testsuite code.
910 * Test Directives:: Directives used within DejaGnu tests.
911 * Ada Tests:: The Ada language testsuites.
912 * C Tests:: The C language testsuites.
913 * LTO Testing:: Support for testing link-time optimizations.
914 * gcov Testing:: Support for testing gcov.
915 * profopt Testing:: Support for testing profile-directed optimizations.
916 * compat Testing:: Support for testing binary compatibility.
917 * Torture Tests:: Support for torture testing using multiple options.
918 * GIMPLE Tests:: Support for testing GIMPLE passes.
919 * RTL Tests:: Support for testing RTL passes.
920 @end menu
921
922 @node Test Idioms
923 @section Idioms Used in Testsuite Code
924
925 In general, C testcases have a trailing @file{-@var{n}.c}, starting
926 with @file{-1.c}, in case other testcases with similar names are added
927 later. If the test is a test of some well-defined feature, it should
928 have a name referring to that feature such as
929 @file{@var{feature}-1.c}. If it does not test a well-defined feature
930 but just happens to exercise a bug somewhere in the compiler, and a
931 bug report has been filed for this bug in the GCC bug database,
932 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
933 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
934 and previously more generally, test cases are named after the date on
935 which they were added. This allows people to tell at a glance whether
936 a test failure is because of a recently found bug that has not yet
937 been fixed, or whether it may be a regression, but does not give any
938 other information about the bug or where discussion of it may be
939 found. Some other language testsuites follow similar conventions.
940
941 In the @file{gcc.dg} testsuite, it is often necessary to test that an
942 error is indeed a hard error and not just a warning---for example,
943 where it is a constraint violation in the C standard, which must
944 become an error with @option{-pedantic-errors}. The following idiom,
945 where the first line shown is line @var{line} of the file and the line
946 that generates the error, is used for this:
947
948 @smallexample
949 /* @{ dg-bogus "warning" "warning in place of error" @} */
950 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
951 @end smallexample
952
953 It may be necessary to check that an expression is an integer constant
954 expression and has a certain value. To check that @code{@var{E}} has
955 value @code{@var{V}}, an idiom similar to the following is used:
956
957 @smallexample
958 char x[((E) == (V) ? 1 : -1)];
959 @end smallexample
960
961 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
962 assertions about the types of expressions. See, for example,
963 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
964 exact rules for the types of conditional expressions in the C
965 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
966
967 It is useful to be able to test that optimizations are being made
968 properly. This cannot be done in all cases, but it can be done where
969 the optimization will lead to code being optimized away (for example,
970 where flow analysis or alias analysis should show that certain code
971 cannot be called) or to functions not being called because they have
972 been expanded as built-in functions. Such tests go in
973 @file{gcc.c-torture/execute}. Where code should be optimized away, a
974 call to a nonexistent function such as @code{link_failure ()} may be
975 inserted; a definition
976
977 @smallexample
978 #ifndef __OPTIMIZE__
979 void
980 link_failure (void)
981 @{
982 abort ();
983 @}
984 #endif
985 @end smallexample
986
987 @noindent
988 will also be needed so that linking still succeeds when the test is
989 run without optimization. When all calls to a built-in function
990 should have been optimized and no calls to the non-built-in version of
991 the function should remain, that function may be defined as
992 @code{static} to call @code{abort ()} (although redeclaring a function
993 as static may not work on all targets).
994
995 All testcases must be portable. Target-specific testcases must have
996 appropriate code to avoid causing failures on unsupported systems;
997 unfortunately, the mechanisms for this differ by directory.
998
999 FIXME: discuss non-C testsuites here.
1000
1001 @node Test Directives
1002 @section Directives used within DejaGnu tests
1003
1004 @menu
1005 * Directives:: Syntax and descriptions of test directives.
1006 * Selectors:: Selecting targets to which a test applies.
1007 * Effective-Target Keywords:: Keywords describing target attributes.
1008 * Add Options:: Features for @code{dg-add-options}
1009 * Require Support:: Variants of @code{dg-require-@var{support}}
1010 * Final Actions:: Commands for use in @code{dg-final}
1011 @end menu
1012
1013 @node Directives
1014 @subsection Syntax and Descriptions of test directives
1015
1016 Test directives appear within comments in a test source file and begin
1017 with @code{dg-}. Some of these are defined within DejaGnu and others
1018 are local to the GCC testsuite.
1019
1020 The order in which test directives appear in a test can be important:
1021 directives local to GCC sometimes override information used by the
1022 DejaGnu directives, which know nothing about the GCC directives, so the
1023 DejaGnu directives must precede GCC directives.
1024
1025 Several test directives include selectors (@pxref{Selectors, , })
1026 which are usually preceded by the keyword @code{target} or @code{xfail}.
1027
1028 @subsubsection Specify how to build the test
1029
1030 @table @code
1031 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
1032 @var{do-what-keyword} specifies how the test is compiled and whether
1033 it is executed. It is one of:
1034
1035 @table @code
1036 @item preprocess
1037 Compile with @option{-E} to run only the preprocessor.
1038 @item compile
1039 Compile with @option{-S} to produce an assembly code file.
1040 @item assemble
1041 Compile with @option{-c} to produce a relocatable object file.
1042 @item link
1043 Compile, assemble, and link to produce an executable file.
1044 @item run
1045 Produce and run an executable file, which is expected to return
1046 an exit code of 0.
1047 @end table
1048
1049 The default is @code{compile}. That can be overridden for a set of
1050 tests by redefining @code{dg-do-what-default} within the @code{.exp}
1051 file for those tests.
1052
1053 If the directive includes the optional @samp{@{ target @var{selector} @}}
1054 then the test is skipped unless the target system matches the
1055 @var{selector}.
1056
1057 If @var{do-what-keyword} is @code{run} and the directive includes
1058 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1059 then the test is expected to fail. The @code{xfail} clause is ignored
1060 for other values of @var{do-what-keyword}; those tests can use
1061 directive @code{dg-xfail-if}.
1062 @end table
1063
1064 @subsubsection Specify additional compiler options
1065
1066 @table @code
1067 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1068 This DejaGnu directive provides a list of compiler options, to be used
1069 if the target system matches @var{selector}, that replace the default
1070 options used for this set of tests.
1071
1072 @item @{ dg-add-options @var{feature} @dots{} @}
1073 Add any compiler options that are needed to access certain features.
1074 This directive does nothing on targets that enable the features by
1075 default, or that don't provide them at all. It must come after
1076 all @code{dg-options} directives.
1077 For supported values of @var{feature} see @ref{Add Options, ,}.
1078
1079 @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
1080 This directive provides a list of compiler options, to be used
1081 if the target system matches @var{selector}, that are added to the default
1082 options used for this set of tests.
1083 @end table
1084
1085 @subsubsection Modify the test timeout value
1086
1087 The normal timeout limit, in seconds, is found by searching the
1088 following in order:
1089
1090 @itemize @bullet
1091 @item the value defined by an earlier @code{dg-timeout} directive in
1092 the test
1093
1094 @item variable @var{tool_timeout} defined by the set of tests
1095
1096 @item @var{gcc},@var{timeout} set in the target board
1097
1098 @item 300
1099 @end itemize
1100
1101 @table @code
1102 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1103 Set the time limit for the compilation and for the execution of the test
1104 to the specified number of seconds.
1105
1106 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1107 Multiply the normal time limit for compilation and execution of the test
1108 by the specified floating-point factor.
1109 @end table
1110
1111 @subsubsection Skip a test for some targets
1112
1113 @table @code
1114 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1115 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1116 each element is a string of zero or more GCC options.
1117 Skip the test if all of the following conditions are met:
1118 @itemize @bullet
1119 @item the test system is included in @var{selector}
1120
1121 @item for at least one of the option strings in @var{include-opts},
1122 every option from that string is in the set of options with which
1123 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1124 that matches any options; that is the default if @var{include-opts} is
1125 not specified
1126
1127 @item for each of the option strings in @var{exclude-opts}, at least one
1128 option from that string is not in the set of options with which the test
1129 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1130 that is the default if @var{exclude-opts} is not specified
1131 @end itemize
1132
1133 For example, to skip a test if option @code{-Os} is present:
1134
1135 @smallexample
1136 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
1137 @end smallexample
1138
1139 To skip a test if both options @code{-O2} and @code{-g} are present:
1140
1141 @smallexample
1142 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
1143 @end smallexample
1144
1145 To skip a test if either @code{-O2} or @code{-O3} is present:
1146
1147 @smallexample
1148 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
1149 @end smallexample
1150
1151 To skip a test unless option @code{-Os} is present:
1152
1153 @smallexample
1154 /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
1155 @end smallexample
1156
1157 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1158 but not if @code{-fpic} is also present:
1159
1160 @smallexample
1161 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1162 @end smallexample
1163
1164 @item @{ dg-require-effective-target @var{keyword} [@{ target @var{selector} @}] @}
1165 Skip the test if the test target, including current multilib flags,
1166 is not covered by the effective-target keyword.
1167 If the directive includes the optional @samp{@{ @var{selector} @}}
1168 then the effective-target test is only performed if the target system
1169 matches the @var{selector}.
1170 This directive must appear after any @code{dg-do} directive in the test
1171 and before any @code{dg-additional-sources} directive.
1172 @xref{Effective-Target Keywords, , }.
1173
1174 @item @{ dg-require-@var{support} args @}
1175 Skip the test if the target does not provide the required support.
1176 These directives must appear after any @code{dg-do} directive in the test
1177 and before any @code{dg-additional-sources} directive.
1178 They require at least one argument, which can be an empty string if the
1179 specific procedure does not examine the argument.
1180 @xref{Require Support, , }, for a complete list of these directives.
1181 @end table
1182
1183 @subsubsection Expect a test to fail for some targets
1184
1185 @table @code
1186 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1187 Expect the test to fail if the conditions (which are the same as for
1188 @code{dg-skip-if}) are met. This does not affect the execute step.
1189
1190 @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1191 Expect the execute step of a test to fail if the conditions (which are
1192 the same as for @code{dg-skip-if}) are met.
1193 @end table
1194
1195 @subsubsection Expect the compiler to crash
1196
1197 @table @code
1198 @item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1199 Expect the compiler to crash with an internal compiler error and return
1200 a nonzero exit status if the conditions (which are the same as for
1201 @code{dg-skip-if}) are met. Used for tests that test bugs that have not been
1202 fixed yet.
1203 @end table
1204
1205 @subsubsection Expect the test executable to fail
1206
1207 @table @code
1208 @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1209 Expect the test executable to return a nonzero exit status if the
1210 conditions (which are the same as for @code{dg-skip-if}) are met.
1211 @end table
1212
1213 @subsubsection Verify compiler messages
1214 Where @var{line} is an accepted argument for these commands, a value of @samp{0}
1215 can be used if there is no line associated with the message.
1216
1217 @table @code
1218 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1219 This DejaGnu directive appears on a source line that is expected to get
1220 an error message, or else specifies the source line associated with the
1221 message. If there is no message for that line or if the text of that
1222 message is not matched by @var{regexp} then the check fails and
1223 @var{comment} is included in the @code{FAIL} message. The check does
1224 not look for the string @samp{error} unless it is part of @var{regexp}.
1225
1226 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1227 This DejaGnu directive appears on a source line that is expected to get
1228 a warning message, or else specifies the source line associated with the
1229 message. If there is no message for that line or if the text of that
1230 message is not matched by @var{regexp} then the check fails and
1231 @var{comment} is included in the @code{FAIL} message. The check does
1232 not look for the string @samp{warning} unless it is part of @var{regexp}.
1233
1234 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1235 The line is expected to get a message other than an error or warning.
1236 If there is no message for that line or if the text of that message is
1237 not matched by @var{regexp} then the check fails and @var{comment} is
1238 included in the @code{FAIL} message.
1239
1240 @item @{ dg-note @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1241 The line is expected to get a @samp{note} message.
1242 If there is no message for that line or if the text of that message is
1243 not matched by @var{regexp} then the check fails and @var{comment} is
1244 included in the @code{FAIL} message.
1245
1246 By default, any @emph{excess} @samp{note} messages are pruned, meaning
1247 their appearance doesn't trigger @emph{excess errors}.
1248 However, if @samp{dg-note} is used at least once in a testcase,
1249 they're not pruned and instead must @emph{all} be handled explicitly.
1250 Thus, if looking for just single instances of messages with
1251 @samp{note: } prefixes without caring for all of them, use
1252 @samp{dg-message "note: [@dots{}]"} instead of @samp{dg-note}, or use
1253 @samp{dg-note} together with @samp{dg-prune-output "note: "}.
1254
1255 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1256 This DejaGnu directive appears on a source line that should not get a
1257 message matching @var{regexp}, or else specifies the source line
1258 associated with the bogus message. It is usually used with @samp{xfail}
1259 to indicate that the message is a known problem for a particular set of
1260 targets.
1261
1262 @item @{ dg-line @var{linenumvar} @}
1263 This DejaGnu directive sets the variable @var{linenumvar} to the line number of
1264 the source line. The variable @var{linenumvar} can then be used in subsequent
1265 @code{dg-error}, @code{dg-warning}, @code{dg-message}, @code{dg-note}
1266 and @code{dg-bogus}
1267 directives. For example:
1268
1269 @smallexample
1270 int a; /* @{ dg-line first_def_a @} */
1271 float a; /* @{ dg-error "conflicting types of" @} */
1272 /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */
1273 @end smallexample
1274
1275 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1276 This DejaGnu directive indicates that the test is expected to fail due
1277 to compiler messages that are not handled by @samp{dg-error},
1278 @samp{dg-warning}, @code{dg-message}, @samp{dg-note} or
1279 @samp{dg-bogus}.
1280 For this directive @samp{xfail}
1281 has the same effect as @samp{target}.
1282
1283 @item @{ dg-prune-output @var{regexp} @}
1284 Prune messages matching @var{regexp} from the test output.
1285 @end table
1286
1287 @subsubsection Verify output of the test executable
1288
1289 @table @code
1290 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1291 This DejaGnu directive compares @var{regexp} to the combined output
1292 that the test executable writes to @file{stdout} and @file{stderr}.
1293 @end table
1294
1295 @subsubsection Specify environment variables for a test
1296
1297 @table @code
1298 @item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @}
1299 Specify that the environment variable @var{var_name} needs to be set
1300 to @var{var_value} before invoking the compiler on the test file.
1301
1302 @item @{ dg-set-target-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 execution of the program created by the test.
1305 @end table
1306
1307 @subsubsection Specify additional files for a test
1308
1309 @table @code
1310 @item @{ dg-additional-files "@var{filelist}" @}
1311 Specify additional files, other than source files, that must be copied
1312 to the system where the compiler runs.
1313
1314 @item @{ dg-additional-sources "@var{filelist}" @}
1315 Specify additional source files to appear in the compile line
1316 following the main test file.
1317 @end table
1318
1319 @subsubsection Add checks at the end of a test
1320
1321 @table @code
1322 @item @{ dg-final @{ @var{local-directive} @} @}
1323 This DejaGnu directive is placed within a comment anywhere in the
1324 source file and is processed after the test has been compiled and run.
1325 Multiple @samp{dg-final} commands are processed in the order in which
1326 they appear in the source file. @xref{Final Actions, , }, for a list
1327 of directives that can be used within @code{dg-final}.
1328 @end table
1329
1330 @node Selectors
1331 @subsection Selecting targets to which a test applies
1332
1333 Several test directives include @var{selector}s to limit the targets
1334 for which a test is run or to declare that a test is expected to fail
1335 on particular targets.
1336
1337 A selector is:
1338 @itemize @bullet
1339 @item one or more target triplets, possibly including wildcard characters;
1340 use @samp{*-*-*} to match any target
1341 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1342 @item a list of compiler options that should be included or excluded
1343 (as described in more detail below)
1344 @item a logical expression
1345 @end itemize
1346
1347 Depending on the context, the selector specifies whether a test is
1348 skipped and reported as unsupported or is expected to fail. A context
1349 that allows either @samp{target} or @samp{xfail} also allows
1350 @samp{@{ target @var{selector1} xfail @var{selector2} @}}
1351 to skip the test for targets that don't match @var{selector1} and the
1352 test to fail for targets that match @var{selector2}.
1353
1354 A selector expression appears within curly braces and uses a single
1355 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
1356 operand is one of the following:
1357
1358 @itemize @bullet
1359 @item
1360 another selector expression, in curly braces
1361
1362 @item
1363 an effective-target keyword, such as @code{lp64}
1364
1365 @item
1366 a single target triplet
1367
1368 @item
1369 a list of target triplets within quotes or curly braces
1370
1371 @item
1372 one of the following:
1373
1374 @table @samp
1375 @item @{ any-opts @var{opt1} @dots{} @var{optn} @}
1376 Each of @var{opt1} to @var{optn} is a space-separated list of option globs.
1377 The selector expression evaluates to true if, for one of these strings,
1378 every glob in the string matches an option that was passed to the compiler.
1379 For example:
1380
1381 @smallexample
1382 @{ any-opts "-O3 -flto" "-O[2g]" @}
1383 @end smallexample
1384
1385 is true if any of the following are true:
1386
1387 @itemize @bullet
1388 @item
1389 @option{-O2} was passed to the compiler
1390
1391 @item
1392 @option{-Og} was passed to the compiler
1393
1394 @item
1395 both @option{-O3} and @option{-flto} were passed to the compiler
1396 @end itemize
1397
1398 This kind of selector can only be used within @code{dg-final} directives.
1399 Use @code{dg-skip-if}, @code{dg-xfail-if} or @code{dg-xfail-run-if} to
1400 skip whole tests based on options, or to mark them as expected to fail
1401 with certain options.
1402
1403 @item @{ no-opts @var{opt1} @dots{} @var{optn} @}
1404 As for @code{any-opts} above, each of @var{opt1} to @var{optn} is a
1405 space-separated list of option globs. The selector expression
1406 evaluates to true if, for all of these strings, there is at least
1407 one glob that does not match an option that was passed to the compiler.
1408 It is shorthand for:
1409
1410 @smallexample
1411 @{ ! @{ any-opts @var{opt1} @dots{} @var{optn} @} @}
1412 @end smallexample
1413
1414 For example:
1415
1416 @smallexample
1417 @{ no-opts "-O3 -flto" "-O[2g]" @}
1418 @end smallexample
1419
1420 is true if all of the following are true:
1421
1422 @itemize @bullet
1423 @item
1424 @option{-O2} was not passed to the compiler
1425
1426 @item
1427 @option{-Og} was not passed to the compiler
1428
1429 @item
1430 at least one of @option{-O3} or @option{-flto} was not passed to the compiler
1431 @end itemize
1432
1433 Like @code{any-opts}, this kind of selector can only be used within
1434 @code{dg-final} directives.
1435
1436 @end table
1437 @end itemize
1438
1439 Here are some examples of full target selectors:
1440
1441 @smallexample
1442 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1443 @{ target @{ powerpc*-*-* && lp64 @} @}
1444 @{ xfail @{ lp64 || vect_no_align @} @}
1445 @{ xfail @{ aarch64*-*-* && @{ any-opts "-O2" @} @} @}
1446 @end smallexample
1447
1448 @node Effective-Target Keywords
1449 @subsection Keywords describing target attributes
1450
1451 Effective-target keywords identify sets of targets that support
1452 particular functionality. They are used to limit tests to be run only
1453 for particular targets, or to specify that particular sets of targets
1454 are expected to fail some tests.
1455
1456 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1457 the GCC testsuite, with the exception of those that are documented as
1458 being local to a particular test directory.
1459
1460 The @samp{effective target} takes into account all of the compiler options
1461 with which the test will be compiled, including the multilib options.
1462 By convention, keywords ending in @code{_nocache} can also include options
1463 specified for the particular test in an earlier @code{dg-options} or
1464 @code{dg-add-options} directive.
1465
1466 @subsubsection Endianness
1467
1468 @table @code
1469 @item be
1470 Target uses big-endian memory order for multi-byte and multi-word data.
1471
1472 @item le
1473 Target uses little-endian memory order for multi-byte and multi-word data.
1474 @end table
1475
1476 @subsubsection Data type sizes
1477
1478 @table @code
1479 @item ilp32
1480 Target has 32-bit @code{int}, @code{long}, and pointers.
1481
1482 @item lp64
1483 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1484
1485 @item llp64
1486 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1487 and pointers.
1488
1489 @item double64
1490 Target has 64-bit @code{double}.
1491
1492 @item double64plus
1493 Target has @code{double} that is 64 bits or longer.
1494
1495 @item longdouble128
1496 Target has 128-bit @code{long double}.
1497
1498 @item int32plus
1499 Target has @code{int} that is at 32 bits or longer.
1500
1501 @item int16
1502 Target has @code{int} that is 16 bits or shorter.
1503
1504 @item longlong64
1505 Target has 64-bit @code{long long}.
1506
1507 @item long_neq_int
1508 Target has @code{int} and @code{long} with different sizes.
1509
1510 @item short_eq_int
1511 Target has @code{short} and @code{int} with the same size.
1512
1513 @item ptr_eq_short
1514 Target has pointers (@code{void *}) and @code{short} with the same size.
1515
1516 @item int_eq_float
1517 Target has @code{int} and @code{float} with the same size.
1518
1519 @item ptr_eq_long
1520 Target has pointers (@code{void *}) and @code{long} with the same size.
1521
1522 @item large_double
1523 Target supports @code{double} that is longer than @code{float}.
1524
1525 @item large_long_double
1526 Target supports @code{long double} that is longer than @code{double}.
1527
1528 @item ptr32plus
1529 Target has pointers that are 32 bits or longer.
1530
1531 @item size20plus
1532 Target has a 20-bit or larger address space, so supports at least
1533 16-bit array and structure sizes.
1534
1535 @item size24plus
1536 Target has a 24-bit or larger address space, so supports at least
1537 20-bit array and structure sizes.
1538
1539 @item size32plus
1540 Target has a 32-bit or larger address space, so supports at least
1541 24-bit array and structure sizes.
1542
1543 @item 4byte_wchar_t
1544 Target has @code{wchar_t} that is at least 4 bytes.
1545
1546 @item float@var{n}
1547 Target has the @code{_Float@var{n}} type.
1548
1549 @item float@var{n}x
1550 Target has the @code{_Float@var{n}x} type.
1551
1552 @item float@var{n}_runtime
1553 Target has the @code{_Float@var{n}} type, including runtime support
1554 for any options added with @code{dg-add-options}.
1555
1556 @item float@var{n}x_runtime
1557 Target has the @code{_Float@var{n}x} type, including runtime support
1558 for any options added with @code{dg-add-options}.
1559
1560 @item floatn_nx_runtime
1561 Target has runtime support for any options added with
1562 @code{dg-add-options} for any @code{_Float@var{n}} or
1563 @code{_Float@var{n}x} type.
1564
1565 @item inf
1566 Target supports floating point infinite (@code{inf}) for type
1567 @code{double}.
1568
1569 @item inff
1570 Target supports floating point infinite (@code{inf}) for type
1571 @code{float}.
1572 @end table
1573 @subsubsection Fortran-specific attributes
1574
1575 @table @code
1576 @item fortran_integer_16
1577 Target supports Fortran @code{integer} that is 16 bytes or longer.
1578
1579 @item fortran_real_10
1580 Target supports Fortran @code{real} that is 10 bytes or longer.
1581
1582 @item fortran_real_16
1583 Target supports Fortran @code{real} that is 16 bytes or longer.
1584
1585 @item fortran_large_int
1586 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1587
1588 @item fortran_large_real
1589 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1590 @end table
1591
1592 @subsubsection Vector-specific attributes
1593
1594 @table @code
1595 @item vect_align_stack_vars
1596 The target's ABI allows stack variables to be aligned to the preferred
1597 vector alignment.
1598
1599 @item vect_avg_qi
1600 Target supports both signed and unsigned averaging operations on vectors
1601 of bytes.
1602
1603 @item vect_mulhrs_hi
1604 Target supports both signed and unsigned multiply-high-with-round-and-scale
1605 operations on vectors of half-words.
1606
1607 @item vect_sdiv_pow2_si
1608 Target supports signed division by constant power-of-2 operations
1609 on vectors of 4-byte integers.
1610
1611 @item vect_condition
1612 Target supports vector conditional operations.
1613
1614 @item vect_cond_mixed
1615 Target supports vector conditional operations where comparison operands
1616 have different type from the value operands.
1617
1618 @item vect_double
1619 Target supports hardware vectors of @code{double}.
1620
1621 @item vect_double_cond_arith
1622 Target supports conditional addition, subtraction, multiplication,
1623 division, minimum and maximum on vectors of @code{double}, via the
1624 @code{cond_} optabs.
1625
1626 @item vect_element_align_preferred
1627 The target's preferred vector alignment is the same as the element
1628 alignment.
1629
1630 @item vect_float
1631 Target supports hardware vectors of @code{float} when
1632 @option{-funsafe-math-optimizations} is in effect.
1633
1634 @item vect_float_strict
1635 Target supports hardware vectors of @code{float} when
1636 @option{-funsafe-math-optimizations} is not in effect.
1637 This implies @code{vect_float}.
1638
1639 @item vect_int
1640 Target supports hardware vectors of @code{int}.
1641
1642 @item vect_long
1643 Target supports hardware vectors of @code{long}.
1644
1645 @item vect_long_long
1646 Target supports hardware vectors of @code{long long}.
1647
1648 @item vect_check_ptrs
1649 Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs}
1650 optabs on vectors.
1651
1652 @item vect_fully_masked
1653 Target supports fully-masked (also known as fully-predicated) loops,
1654 so that vector loops can handle partial as well as full vectors.
1655
1656 @item vect_masked_load
1657 Target supports vector masked loads.
1658
1659 @item vect_masked_store
1660 Target supports vector masked stores.
1661
1662 @item vect_gather_load_ifn
1663 Target supports vector gather loads using internal functions
1664 (rather than via built-in functions or emulation).
1665
1666 @item vect_scatter_store
1667 Target supports vector scatter stores.
1668
1669 @item vect_aligned_arrays
1670 Target aligns arrays to vector alignment boundary.
1671
1672 @item vect_hw_misalign
1673 Target supports a vector misalign access.
1674
1675 @item vect_no_align
1676 Target does not support a vector alignment mechanism.
1677
1678 @item vect_peeling_profitable
1679 Target might require to peel loops for alignment purposes.
1680
1681 @item vect_no_int_min_max
1682 Target does not support a vector min and max instruction on @code{int}.
1683
1684 @item vect_no_int_add
1685 Target does not support a vector add instruction on @code{int}.
1686
1687 @item vect_no_bitwise
1688 Target does not support vector bitwise instructions.
1689
1690 @item vect_bool_cmp
1691 Target supports comparison of @code{bool} vectors for at least one
1692 vector length.
1693
1694 @item vect_char_add
1695 Target supports addition of @code{char} vectors for at least one
1696 vector length.
1697
1698 @item vect_char_mult
1699 Target supports @code{vector char} multiplication.
1700
1701 @item vect_short_mult
1702 Target supports @code{vector short} multiplication.
1703
1704 @item vect_int_mult
1705 Target supports @code{vector int} multiplication.
1706
1707 @item vect_long_mult
1708 Target supports 64 bit @code{vector long} multiplication.
1709
1710 @item vect_extract_even_odd
1711 Target supports vector even/odd element extraction.
1712
1713 @item vect_extract_even_odd_wide
1714 Target supports vector even/odd element extraction of vectors with elements
1715 @code{SImode} or larger.
1716
1717 @item vect_interleave
1718 Target supports vector interleaving.
1719
1720 @item vect_strided
1721 Target supports vector interleaving and extract even/odd.
1722
1723 @item vect_strided_wide
1724 Target supports vector interleaving and extract even/odd for wide
1725 element types.
1726
1727 @item vect_perm
1728 Target supports vector permutation.
1729
1730 @item vect_perm_byte
1731 Target supports permutation of vectors with 8-bit elements.
1732
1733 @item vect_perm_short
1734 Target supports permutation of vectors with 16-bit elements.
1735
1736 @item vect_perm3_byte
1737 Target supports permutation of vectors with 8-bit elements, and for the
1738 default vector length it is possible to permute:
1739 @example
1740 @{ a0, a1, a2, b0, b1, b2, @dots{} @}
1741 @end example
1742 to:
1743 @example
1744 @{ a0, a0, a0, b0, b0, b0, @dots{} @}
1745 @{ a1, a1, a1, b1, b1, b1, @dots{} @}
1746 @{ a2, a2, a2, b2, b2, b2, @dots{} @}
1747 @end example
1748 using only two-vector permutes, regardless of how long the sequence is.
1749
1750 @item vect_perm3_int
1751 Like @code{vect_perm3_byte}, but for 32-bit elements.
1752
1753 @item vect_perm3_short
1754 Like @code{vect_perm3_byte}, but for 16-bit elements.
1755
1756 @item vect_shift
1757 Target supports a hardware vector shift operation.
1758
1759 @item vect_unaligned_possible
1760 Target prefers vectors to have an alignment greater than element
1761 alignment, but also allows unaligned vector accesses in some
1762 circumstances.
1763
1764 @item vect_variable_length
1765 Target has variable-length vectors.
1766
1767 @item vect64
1768 Target supports vectors of 64 bits.
1769
1770 @item vect32
1771 Target supports vectors of 32 bits.
1772
1773 @item vect_widen_sum_hi_to_si
1774 Target supports a vector widening summation of @code{short} operands
1775 into @code{int} results, or can promote (unpack) from @code{short}
1776 to @code{int}.
1777
1778 @item vect_widen_sum_qi_to_hi
1779 Target supports a vector widening summation of @code{char} operands
1780 into @code{short} results, or can promote (unpack) from @code{char}
1781 to @code{short}.
1782
1783 @item vect_widen_sum_qi_to_si
1784 Target supports a vector widening summation of @code{char} operands
1785 into @code{int} results.
1786
1787 @item vect_widen_mult_qi_to_hi
1788 Target supports a vector widening multiplication of @code{char} operands
1789 into @code{short} results, or can promote (unpack) from @code{char} to
1790 @code{short} and perform non-widening multiplication of @code{short}.
1791
1792 @item vect_widen_mult_hi_to_si
1793 Target supports a vector widening multiplication of @code{short} operands
1794 into @code{int} results, or can promote (unpack) from @code{short} to
1795 @code{int} and perform non-widening multiplication of @code{int}.
1796
1797 @item vect_widen_mult_si_to_di_pattern
1798 Target supports a vector widening multiplication of @code{int} operands
1799 into @code{long} results.
1800
1801 @item vect_sdot_qi
1802 Target supports a vector dot-product of @code{signed char}.
1803
1804 @item vect_udot_qi
1805 Target supports a vector dot-product of @code{unsigned char}.
1806
1807 @item vect_usdot_qi
1808 Target supports a vector dot-product where one operand of the multiply is
1809 @code{signed char} and the other of @code{unsigned char}.
1810
1811 @item vect_sdot_hi
1812 Target supports a vector dot-product of @code{signed short}.
1813
1814 @item vect_udot_hi
1815 Target supports a vector dot-product of @code{unsigned short}.
1816
1817 @item vect_pack_trunc
1818 Target supports a vector demotion (packing) of @code{short} to @code{char}
1819 and from @code{int} to @code{short} using modulo arithmetic.
1820
1821 @item vect_unpack
1822 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1823 and from @code{char} to @code{int}.
1824
1825 @item vect_intfloat_cvt
1826 Target supports conversion from @code{signed int} to @code{float}.
1827
1828 @item vect_uintfloat_cvt
1829 Target supports conversion from @code{unsigned int} to @code{float}.
1830
1831 @item vect_floatint_cvt
1832 Target supports conversion from @code{float} to @code{signed int}.
1833
1834 @item vect_floatuint_cvt
1835 Target supports conversion from @code{float} to @code{unsigned int}.
1836
1837 @item vect_intdouble_cvt
1838 Target supports conversion from @code{signed int} to @code{double}.
1839
1840 @item vect_doubleint_cvt
1841 Target supports conversion from @code{double} to @code{signed int}.
1842
1843 @item vect_max_reduc
1844 Target supports max reduction for vectors.
1845
1846 @item vect_sizes_16B_8B
1847 Target supports 16- and 8-bytes vectors.
1848
1849 @item vect_sizes_32B_16B
1850 Target supports 32- and 16-bytes vectors.
1851
1852 @item vect_logical_reduc
1853 Target supports AND, IOR and XOR reduction on vectors.
1854
1855 @item vect_fold_extract_last
1856 Target supports the @code{fold_extract_last} optab.
1857
1858 @item vect_len_load_store
1859 Target supports the @code{len_load} and @code{len_store} optabs.
1860
1861 @item vect_partial_vectors_usage_1
1862 Target supports loop vectorization with partial vectors and
1863 @code{vect-partial-vector-usage} is set to 1.
1864
1865 @item vect_partial_vectors_usage_2
1866 Target supports loop vectorization with partial vectors and
1867 @code{vect-partial-vector-usage} is set to 2.
1868
1869 @item vect_partial_vectors
1870 Target supports loop vectorization with partial vectors and
1871 @code{vect-partial-vector-usage} is nonzero.
1872
1873 @item vect_slp_v2qi_store_align
1874 Target supports vectorization of 2-byte char stores with 2-byte aligned
1875 address at plain @option{-O2}.
1876
1877 @item vect_slp_v4qi_store_align
1878 Target supports vectorization of 4-byte char stores with 4-byte aligned
1879 address at plain @option{-O2}.
1880
1881 @item vect_slp_v4qi_store_unalign
1882 Target supports vectorization of 4-byte char stores with unaligned address
1883 at plain @option{-O2}.
1884
1885 @item struct_4char_block_move
1886 Target supports block move for 8-byte aligned 4-byte size struct initialization.
1887
1888 @item vect_slp_v4qi_store_unalign_1
1889 Target supports vectorization of 4-byte char stores with unaligned address
1890 or store them with constant pool at plain @option{-O2}.
1891
1892 @item struct_8char_block_move
1893 Target supports block move for 8-byte aligned 8-byte size struct initialization.
1894
1895 @item vect_slp_v8qi_store_unalign_1
1896 Target supports vectorization of 8-byte char stores with unaligned address
1897 or store them with constant pool at plain @option{-O2}.
1898
1899 @item struct_16char_block_move
1900 Target supports block move for 8-byte aligned 16-byte size struct
1901 initialization.
1902
1903 @item vect_slp_v16qi_store_unalign_1
1904 Target supports vectorization of 16-byte char stores with unaligned address
1905 or store them with constant pool at plain @option{-O2}.
1906
1907 @item vect_slp_v2hi_store_align
1908 Target supports vectorization of 4-byte short stores with 4-byte aligned
1909 addressat plain @option{-O2}.
1910
1911 @item vect_slp_v2hi_store_unalign
1912 Target supports vectorization of 4-byte short stores with unaligned address
1913 at plain @option{-O2}.
1914
1915 @item vect_slp_v4hi_store_unalign
1916 Target supports vectorization of 8-byte short stores with unaligned address
1917 at plain @option{-O2}.
1918
1919 @item vect_slp_v2si_store_align
1920 Target supports vectorization of 8-byte int stores with 8-byte aligned address
1921 at plain @option{-O2}.
1922
1923 @item vect_slp_v4si_store_unalign
1924 Target supports vectorization of 16-byte int stores with unaligned address
1925 at plain @option{-O2}.
1926 @end table
1927
1928 @subsubsection Thread Local Storage attributes
1929
1930 @table @code
1931 @item tls
1932 Target supports thread-local storage.
1933
1934 @item tls_native
1935 Target supports native (rather than emulated) thread-local storage.
1936
1937 @item tls_runtime
1938 Test system supports executing TLS executables.
1939 @end table
1940
1941 @subsubsection Decimal floating point attributes
1942
1943 @table @code
1944 @item dfp
1945 Targets supports compiling decimal floating point extension to C.
1946
1947 @item dfp_nocache
1948 Including the options used to compile this particular test, the
1949 target supports compiling decimal floating point extension to C.
1950
1951 @item dfprt
1952 Test system can execute decimal floating point tests.
1953
1954 @item dfprt_nocache
1955 Including the options used to compile this particular test, the
1956 test system can execute decimal floating point tests.
1957
1958 @item hard_dfp
1959 Target generates decimal floating point instructions with current options.
1960
1961 @item dfp_bid
1962 Target uses the BID format for decimal floating point.
1963 @end table
1964
1965 @subsubsection ARM-specific attributes
1966
1967 @table @code
1968 @item arm32
1969 ARM target generates 32-bit code.
1970
1971 @item arm_little_endian
1972 ARM target that generates little-endian code.
1973
1974 @item arm_eabi
1975 ARM target adheres to the ABI for the ARM Architecture.
1976
1977 @item arm_fp_ok
1978 @anchor{arm_fp_ok}
1979 ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or
1980 equivalent options. Some multilibs may be incompatible with these
1981 options.
1982
1983 @item arm_fp_dp_ok
1984 @anchor{arm_fp_dp_ok}
1985 ARM target defines @code{__ARM_FP} with double-precision support using
1986 @code{-mfloat-abi=softfp} or equivalent options. Some multilibs may
1987 be incompatible with these options.
1988
1989 @item arm_hf_eabi
1990 ARM target adheres to the VFP and Advanced SIMD Register Arguments
1991 variant of the ABI for the ARM Architecture (as selected with
1992 @code{-mfloat-abi=hard}).
1993
1994 @item arm_softfloat
1995 ARM target uses emulated floating point operations.
1996
1997 @item arm_hard_vfp_ok
1998 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
1999 Some multilibs may be incompatible with these options.
2000
2001 @item arm_iwmmxt_ok
2002 ARM target supports @code{-mcpu=iwmmxt}.
2003 Some multilibs may be incompatible with this option.
2004
2005 @item arm_neon
2006 ARM target supports generating NEON instructions.
2007
2008 @item arm_tune_string_ops_prefer_neon
2009 Test CPU tune supports inlining string operations with NEON instructions.
2010
2011 @item arm_neon_hw
2012 Test system supports executing NEON instructions.
2013
2014 @item arm_neonv2_hw
2015 Test system supports executing NEON v2 instructions.
2016
2017 @item arm_neon_ok
2018 @anchor{arm_neon_ok}
2019 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
2020 options. Some multilibs may be incompatible with these options.
2021
2022 @item arm_neon_ok_no_float_abi
2023 @anchor{arm_neon_ok_no_float_abi}
2024 ARM Target supports NEON with @code{-mfpu=neon}, but without any
2025 -mfloat-abi= option. Some multilibs may be incompatible with this
2026 option.
2027
2028 @item arm_neonv2_ok
2029 @anchor{arm_neonv2_ok}
2030 ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible
2031 options. Some multilibs may be incompatible with these options.
2032
2033 @item arm_fp16_ok
2034 @anchor{arm_fp16_ok}
2035 Target supports options to generate VFP half-precision floating-point
2036 instructions. Some multilibs may be incompatible with these
2037 options. This test is valid for ARM only.
2038
2039 @item arm_fp16_hw
2040 Target supports executing VFP half-precision floating-point
2041 instructions. This test is valid for ARM only.
2042
2043 @item arm_neon_fp16_ok
2044 @anchor{arm_neon_fp16_ok}
2045 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
2046 options, including @code{-mfp16-format=ieee} if necessary to obtain the
2047 @code{__fp16} type. Some multilibs may be incompatible with these options.
2048
2049 @item arm_neon_fp16_hw
2050 Test system supports executing Neon half-precision float instructions.
2051 (Implies previous.)
2052
2053 @item arm_fp16_alternative_ok
2054 ARM target supports the ARM FP16 alternative format. Some multilibs
2055 may be incompatible with the options needed.
2056
2057 @item arm_fp16_none_ok
2058 ARM target supports specifying none as the ARM FP16 format.
2059
2060 @item arm_thumb1_ok
2061 ARM target generates Thumb-1 code for @code{-mthumb}.
2062
2063 @item arm_thumb2_ok
2064 ARM target generates Thumb-2 code for @code{-mthumb}.
2065
2066 @item arm_nothumb
2067 ARM target that is not using Thumb.
2068
2069 @item arm_vfp_ok
2070 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
2071 Some multilibs may be incompatible with these options.
2072
2073 @item arm_vfp3_ok
2074 @anchor{arm_vfp3_ok}
2075 ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}.
2076 Some multilibs may be incompatible with these options.
2077
2078 @item arm_arch_v8a_hard_ok
2079 @anchor{arm_arch_v8a_hard_ok}
2080 The compiler is targeting @code{arm*-*-*} and can compile and assemble code
2081 using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
2082 This is not enough to guarantee that linking works.
2083
2084 @item arm_arch_v8a_hard_multilib
2085 The compiler is targeting @code{arm*-*-*} and can build programs using
2086 the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}.
2087 The target can also run the resulting binaries.
2088
2089 @item arm_v8_vfp_ok
2090 ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}.
2091 Some multilibs may be incompatible with these options.
2092
2093 @item arm_v8_neon_ok
2094 ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}.
2095 Some multilibs may be incompatible with these options.
2096
2097 @item arm_v8_1a_neon_ok
2098 @anchor{arm_v8_1a_neon_ok}
2099 ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions.
2100 Some multilibs may be incompatible with these options.
2101
2102 @item arm_v8_1a_neon_hw
2103 ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some
2104 multilibs may be incompatible with the options needed. Implies
2105 arm_v8_1a_neon_ok.
2106
2107 @item arm_acq_rel
2108 ARM target supports acquire-release instructions.
2109
2110 @item arm_v8_2a_fp16_scalar_ok
2111 @anchor{arm_v8_2a_fp16_scalar_ok}
2112 ARM target supports options to generate instructions for ARMv8.2-A and
2113 scalar instructions from the FP16 extension. Some multilibs may be
2114 incompatible with these options.
2115
2116 @item arm_v8_2a_fp16_scalar_hw
2117 ARM target supports executing instructions for ARMv8.2-A and scalar
2118 instructions from the FP16 extension. Some multilibs may be
2119 incompatible with these options. Implies arm_v8_2a_fp16_neon_ok.
2120
2121 @item arm_v8_2a_fp16_neon_ok
2122 @anchor{arm_v8_2a_fp16_neon_ok}
2123 ARM target supports options to generate instructions from ARMv8.2-A with
2124 the FP16 extension. Some multilibs may be incompatible with these
2125 options. Implies arm_v8_2a_fp16_scalar_ok.
2126
2127 @item arm_v8_2a_fp16_neon_hw
2128 ARM target supports executing instructions from ARMv8.2-A with the FP16
2129 extension. Some multilibs may be incompatible with these options.
2130 Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.
2131
2132 @item arm_v8_2a_dotprod_neon_ok
2133 @anchor{arm_v8_2a_dotprod_neon_ok}
2134 ARM target supports options to generate instructions from ARMv8.2-A with
2135 the Dot Product extension. Some multilibs may be incompatible with these
2136 options.
2137
2138 @item arm_v8_2a_dotprod_neon_hw
2139 ARM target supports executing instructions from ARMv8.2-A with the Dot
2140 Product extension. Some multilibs may be incompatible with these options.
2141 Implies arm_v8_2a_dotprod_neon_ok.
2142
2143 @item arm_v8_2a_i8mm_neon_hw
2144 ARM target supports executing instructions from ARMv8.2-A with the 8-bit
2145 Matrix Multiply extension. Some multilibs may be incompatible with these
2146 options. Implies arm_v8_2a_i8mm_ok.
2147
2148 @item arm_fp16fml_neon_ok
2149 @anchor{arm_fp16fml_neon_ok}
2150 ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS}
2151 half-precision floating-point instructions available from ARMv8.2-A and
2152 onwards. Some multilibs may be incompatible with these options.
2153
2154 @item arm_v8_2a_bf16_neon_ok
2155 ARM target supports options to generate instructions from ARMv8.2-A with
2156 the BFloat16 extension (bf16). Some multilibs may be incompatible with these
2157 options.
2158
2159 @item arm_v8_2a_i8mm_ok
2160 ARM target supports options to generate instructions from ARMv8.2-A with
2161 the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be
2162 incompatible with these options.
2163
2164 @item arm_v8_1m_mve_ok
2165 ARM target supports options to generate instructions from ARMv8.1-M with
2166 the M-Profile Vector Extension (MVE). Some multilibs may be incompatible
2167 with these options.
2168
2169 @item arm_v8_1m_mve_fp_ok
2170 ARM target supports options to generate instructions from ARMv8.1-M with
2171 the Half-precision floating-point instructions (HP), Floating-point Extension
2172 (FP) along with M-Profile Vector Extension (MVE). Some multilibs may be
2173 incompatible with these options.
2174
2175 @item arm_mve_hw
2176 Test system supports executing MVE instructions.
2177
2178 @item arm_v8m_main_cde
2179 ARM target supports options to generate instructions from ARMv8-M with
2180 the Custom Datapath Extension (CDE). Some multilibs may be incompatible
2181 with these options.
2182
2183 @item arm_v8m_main_cde_fp
2184 ARM target supports options to generate instructions from ARMv8-M with
2185 the Custom Datapath Extension (CDE) and floating-point (VFP).
2186 Some multilibs may be incompatible with these options.
2187
2188 @item arm_v8_1m_main_cde_mve
2189 ARM target supports options to generate instructions from ARMv8.1-M with
2190 the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE).
2191 Some multilibs may be incompatible with these options.
2192
2193 @item arm_pacbti_hw
2194 Test system supports executing Pointer Authentication and Branch Target
2195 Identification instructions.
2196
2197 @item arm_prefer_ldrd_strd
2198 ARM target prefers @code{LDRD} and @code{STRD} instructions over
2199 @code{LDM} and @code{STM} instructions.
2200
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.
2204
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.
2208
2209 @item arm_divmod_simode
2210 ARM target for which divmod transform is disabled, if it supports hardware
2211 div instruction.
2212
2213 @item arm_cmse_ok
2214 ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse}
2215 option.
2216
2217 @item arm_cmse_hw
2218 Test system supports executing CMSE instructions.
2219
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}.
2224
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}.
2230
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}.
2235
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}.
2239
2240 @item arm_simd32_ok
2241 @anchor{arm_simd32_ok}
2242 ARM Target supports options suitable for accessing the SIMD32 intrinsics from
2243 @code{arm_acle.h}.
2244 Some multilibs may be incompatible with these options.
2245
2246 @item arm_sat_ok
2247 @anchor{arm_sat_ok}
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.
2251
2252 @item arm_dsp_ok
2253 @anchor{arm_dsp_ok}
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.
2257
2258 @item arm_softfp_ok
2259 @anchor{arm_softfp_ok}
2260 ARM target supports the @code{-mfloat-abi=softfp} option.
2261
2262 @item arm_hard_ok
2263 @anchor{arm_hard_ok}
2264 ARM target supports the @code{-mfloat-abi=hard} option.
2265
2266 @item arm_mve
2267 @anchor{arm_mve}
2268 ARM target supports generating MVE instructions.
2269
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.
2275
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}.
2280
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}.
2285
2286 @item mbranch_protection_ok
2287 ARM target supporting @code{-mbranch-protection=standard}.
2288
2289 @item arm_pacbti_hw
2290 Test system supports for executing non nop pacbti instructions.
2291
2292 @end table
2293
2294 @subsubsection AArch64-specific attributes
2295
2296 @table @code
2297 @item aarch64_asm_<ext>_ok
2298 AArch64 assembler supports the architecture extension @code{ext} via the
2299 @code{.arch_extension} pseudo-op.
2300 @item aarch64_tiny
2301 AArch64 target which generates instruction sequences for tiny memory model.
2302 @item aarch64_small
2303 AArch64 target which generates instruction sequences for small memory model.
2304 @item aarch64_large
2305 AArch64 target which generates instruction sequences for large memory model.
2306 @item aarch64_little_endian
2307 AArch64 target which generates instruction sequences for little endian.
2308 @item aarch64_big_endian
2309 AArch64 target which generates instruction sequences for big endian.
2310 @item aarch64_small_fpic
2311 Binutils installed on test system supports relocation types required by -fpic
2312 for AArch64 small memory model.
2313 @item aarch64_sve_hw
2314 AArch64 target that is able to generate and execute SVE code (regardless of
2315 whether it does so by default).
2316 @item aarch64_sve128_hw
2317 @itemx aarch64_sve256_hw
2318 @itemx aarch64_sve512_hw
2319 @itemx aarch64_sve1024_hw
2320 @itemx aarch64_sve2048_hw
2321 Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length.
2322
2323 @item aarch64_fjcvtzs_hw
2324 AArch64 target that is able to generate and execute armv8.3-a FJCVTZS
2325 instruction.
2326 @end table
2327
2328 @subsubsection MIPS-specific attributes
2329
2330 @table @code
2331 @item mips64
2332 MIPS target supports 64-bit instructions.
2333
2334 @item nomips16
2335 MIPS target does not produce MIPS16 code.
2336
2337 @item mips16_attribute
2338 MIPS target can generate MIPS16 code.
2339
2340 @item mips_loongson
2341 MIPS target is a Loongson-2E or -2F target using an ABI that supports
2342 the Loongson vector modes.
2343
2344 @item mips_msa
2345 MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA).
2346
2347 @item mips_newabi_large_long_double
2348 MIPS target supports @code{long double} larger than @code{double}
2349 when using the new ABI.
2350
2351 @item mpaired_single
2352 MIPS target supports @code{-mpaired-single}.
2353 @end table
2354
2355 @subsubsection MSP430-specific attributes
2356
2357 @table @code
2358 @item msp430_small
2359 MSP430 target has the small memory model enabled (@code{-msmall}).
2360
2361 @item msp430_large
2362 MSP430 target has the large memory model enabled (@code{-mlarge}).
2363 @end table
2364
2365 @subsubsection PowerPC-specific attributes
2366
2367 @table @code
2368
2369 @item dfp_hw
2370 PowerPC target supports executing hardware DFP instructions.
2371
2372 @item p8vector_hw
2373 PowerPC target supports executing VSX instructions (ISA 2.07).
2374
2375 @item powerpc64
2376 Test system supports executing 64-bit instructions.
2377
2378 @item powerpc_altivec
2379 PowerPC target supports AltiVec.
2380
2381 @item powerpc_altivec_ok
2382 PowerPC target supports @code{-maltivec}.
2383
2384 @item powerpc_eabi_ok
2385 PowerPC target supports @code{-meabi}.
2386
2387 @item powerpc_elfv2
2388 PowerPC target supports @code{-mabi=elfv2}.
2389
2390 @item powerpc_fprs
2391 PowerPC target supports floating-point registers.
2392
2393 @item powerpc_hard_double
2394 PowerPC target supports hardware double-precision floating-point.
2395
2396 @item powerpc_htm_ok
2397 PowerPC target supports @code{-mhtm}
2398
2399 @item powerpc_p8vector_ok
2400 PowerPC target supports @code{-mpower8-vector}
2401
2402 @item powerpc_popcntb_ok
2403 PowerPC target supports the @code{popcntb} instruction, indicating
2404 that this target supports @code{-mcpu=power5}.
2405
2406 @item powerpc_ppu_ok
2407 PowerPC target supports @code{-mcpu=cell}.
2408
2409 @item powerpc_spe
2410 PowerPC target supports PowerPC SPE.
2411
2412 @item powerpc_spe_nocache
2413 Including the options used to compile this particular test, the
2414 PowerPC target supports PowerPC SPE.
2415
2416 @item powerpc_spu
2417 PowerPC target supports PowerPC SPU.
2418
2419 @item powerpc_vsx_ok
2420 PowerPC target supports @code{-mvsx}.
2421
2422 @item powerpc_405_nocache
2423 Including the options used to compile this particular test, the
2424 PowerPC target supports PowerPC 405.
2425
2426 @item ppc_recip_hw
2427 PowerPC target supports executing reciprocal estimate instructions.
2428
2429 @item vmx_hw
2430 PowerPC target supports executing AltiVec instructions.
2431
2432 @item vsx_hw
2433 PowerPC target supports executing VSX instructions (ISA 2.06).
2434
2435 @item has_arch_pwr5
2436 PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu}
2437 setting is Power5 or later.
2438
2439 @item has_arch_pwr6
2440 PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu}
2441 setting is Power6 or later.
2442
2443 @item has_arch_pwr7
2444 PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu}
2445 setting is Power7 or later.
2446
2447 @item has_arch_pwr8
2448 PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu}
2449 setting is Power8 or later.
2450
2451 @item has_arch_pwr9
2452 PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu}
2453 setting is Power9 or later.
2454 @end table
2455
2456 @subsubsection RISC-V specific attributes
2457
2458 @table @code
2459
2460 @item rv32
2461 Test system has an integer register width of 32 bits.
2462
2463 @item rv64
2464 Test system has an integer register width of 64 bits.
2465
2466 @end table
2467
2468 @subsubsection Other hardware attributes
2469
2470 @c Please keep this table sorted alphabetically.
2471 @table @code
2472 @item autoincdec
2473 Target supports autoincrement/decrement addressing.
2474
2475 @item avx
2476 Target supports compiling @code{avx} instructions.
2477
2478 @item avx_runtime
2479 Target supports the execution of @code{avx} instructions.
2480
2481 @item avx2
2482 Target supports compiling @code{avx2} instructions.
2483
2484 @item avx2_runtime
2485 Target supports the execution of @code{avx2} instructions.
2486
2487 @item avxvnni
2488 Target supports the execution of @code{avxvnni} instructions.
2489
2490 @item avx512f
2491 Target supports compiling @code{avx512f} instructions.
2492
2493 @item avx512f_runtime
2494 Target supports the execution of @code{avx512f} instructions.
2495
2496 @item avx512vp2intersect
2497 Target supports the execution of @code{avx512vp2intersect} instructions.
2498
2499 @item avxifma
2500 Target supports the execution of @code{avxifma} instructions.
2501
2502 @item avxneconvert
2503 Target supports the execution of @code{avxneconvert} instructions.
2504
2505 @item avxvnniint8
2506 Target supports the execution of @code{avxvnniint8} instructions.
2507
2508 @item amx_tile
2509 Target supports the execution of @code{amx-tile} instructions.
2510
2511 @item amx_int8
2512 Target supports the execution of @code{amx-int8} instructions.
2513
2514 @item amx_bf16
2515 Target supports the execution of @code{amx-bf16} instructions.
2516
2517 @item amx_complex
2518 Target supports the execution of @code{amx-complex} instructions.
2519
2520 @item amx_fp16
2521 Target supports the execution of @code{amx-fp16} instructions.
2522
2523 @item cell_hw
2524 Test system can execute AltiVec and Cell PPU instructions.
2525
2526 @item clz
2527 Target supports a clz optab on int.
2528
2529 @item clzl
2530 Target supports a clz optab on long.
2531
2532 @item clzll
2533 Target supports a clz optab on long long.
2534
2535 @item ctz
2536 Target supports a ctz optab on int.
2537
2538 @item ctzl
2539 Target supports a ctz optab on long.
2540
2541 @item ctzll
2542 Target supports a ctz optab on long long.
2543
2544 @item cmpccxadd
2545 Target supports the execution of @code{cmpccxadd} instructions.
2546
2547 @item coldfire_fpu
2548 Target uses a ColdFire FPU.
2549
2550 @item divmod
2551 Target supporting hardware divmod insn or divmod libcall.
2552
2553 @item divmod_simode
2554 Target supporting hardware divmod insn or divmod libcall for SImode.
2555
2556 @item hard_float
2557 Target supports FPU instructions.
2558
2559 @item non_strict_align
2560 Target does not require strict alignment.
2561
2562 @item pie_copyreloc
2563 The x86-64 target linker supports PIE with copy reloc.
2564
2565 @item popcount
2566 Target supports a popcount optab on int.
2567
2568 @item popcountl
2569 Target supports a popcount optab on long.
2570
2571 @item popcountll
2572 Target supports a popcount optab on long long.
2573
2574 @item prefetchi
2575 Target supports the execution of @code{prefetchi} instructions.
2576
2577 @item raoint
2578 Target supports the execution of @code{raoint} instructions.
2579
2580 @item rdrand
2581 Target supports x86 @code{rdrand} instruction.
2582
2583 @item sqrt_insn
2584 Target has a square root instruction that the compiler can generate.
2585
2586 @item sse
2587 Target supports compiling @code{sse} instructions.
2588
2589 @item sse_runtime
2590 Target supports the execution of @code{sse} instructions.
2591
2592 @item sse2
2593 Target supports compiling @code{sse2} instructions.
2594
2595 @item sse2_runtime
2596 Target supports the execution of @code{sse2} instructions.
2597
2598 @item sync_char_short
2599 Target supports atomic operations on @code{char} and @code{short}.
2600
2601 @item sync_int_long
2602 Target supports atomic operations on @code{int} and @code{long}.
2603
2604 @item ultrasparc_hw
2605 Test environment appears to run executables on a simulator that
2606 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
2607 or @code{EM_SPARCV9} executables.
2608
2609 @item vect_cmdline_needed
2610 Target requires a command line argument to enable a SIMD instruction set.
2611
2612 @item xorsign
2613 Target supports the xorsign optab expansion.
2614
2615 @end table
2616
2617 @subsubsection Environment attributes
2618
2619 @table @code
2620 @item c
2621 The language for the compiler under test is C.
2622
2623 @item c++
2624 The language for the compiler under test is C++.
2625
2626 @item c99_runtime
2627 Target provides a full C99 runtime.
2628
2629 @item correct_iso_cpp_string_wchar_protos
2630 Target @code{string.h} and @code{wchar.h} headers provide C++ required
2631 overloads for @code{strchr} etc. functions.
2632
2633 @item d_runtime
2634 Target provides the D runtime.
2635
2636 @item d_runtime_has_std_library
2637 Target provides the D standard library (Phobos).
2638
2639 @item dummy_wcsftime
2640 Target uses a dummy @code{wcsftime} function that always returns zero.
2641
2642 @item fd_truncate
2643 Target can truncate a file from a file descriptor, as used by
2644 @file{libgfortran/io/unix.c:fd_truncate}; i.e.@: @code{ftruncate} or
2645 @code{chsize}.
2646
2647 @item fenv
2648 Target provides @file{fenv.h} include file.
2649
2650 @item fenv_exceptions
2651 Target supports @file{fenv.h} with all the standard IEEE exceptions
2652 and floating-point exceptions are raised by arithmetic operations.
2653
2654 @item fenv_exceptions_dfp
2655 Target supports @file{fenv.h} with all the standard IEEE exceptions
2656 and floating-point exceptions are raised by arithmetic operations for
2657 decimal floating point.
2658
2659 @item fileio
2660 Target offers such file I/O library functions as @code{fopen},
2661 @code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time
2662 requirement for the presence of the functions in the library; even if
2663 they fail at runtime, the requirement is still regarded as satisfied.
2664
2665 @item freestanding
2666 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
2667 Effectively, it is a target which supports no extra headers or libraries
2668 other than what is considered essential.
2669
2670 @item gettimeofday
2671 Target supports @code{gettimeofday}.
2672
2673 @item init_priority
2674 Target supports constructors with initialization priority arguments.
2675
2676 @item inttypes_types
2677 Target has the basic signed and unsigned types in @code{inttypes.h}.
2678 This is for tests that GCC's notions of these types agree with those
2679 in the header, as some systems have only @code{inttypes.h}.
2680
2681 @item lax_strtofp
2682 Target might have errors of a few ULP in string to floating-point
2683 conversion functions and overflow is not always detected correctly by
2684 those functions.
2685
2686 @item mempcpy
2687 Target provides @code{mempcpy} function.
2688
2689 @item mmap
2690 Target supports @code{mmap}.
2691
2692 @item newlib
2693 Target supports Newlib.
2694
2695 @item newlib_nano_io
2696 GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces
2697 the code size of Newlib formatted I/O functions.
2698
2699 @item posix_memalign
2700 Target supports @code{posix_memalign}.
2701
2702 @item pow10
2703 Target provides @code{pow10} function.
2704
2705 @item pthread
2706 Target can compile using @code{pthread.h} with no errors or warnings.
2707
2708 @item pthread_h
2709 Target has @code{pthread.h}.
2710
2711 @item sockets
2712 Target can compile using @code{sys/socket.h} with no errors or warnings.
2713
2714 @item run_expensive_tests
2715 Expensive testcases (usually those that consume excessive amounts of CPU
2716 time) should be run on this target. This can be enabled by setting the
2717 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
2718
2719 @item simulator
2720 Test system runs executables on a simulator (i.e.@: slowly) rather than
2721 hardware (i.e.@: fast).
2722
2723 @item signal
2724 Target has @code{signal.h}.
2725
2726 @item stabs
2727 Target supports the stabs debugging format.
2728
2729 @item stdint_types
2730 Target has the basic signed and unsigned C types in @code{stdint.h}.
2731 This will be obsolete when GCC ensures a working @code{stdint.h} for
2732 all targets.
2733
2734 @item stdint_types_mbig_endian
2735 Target accepts the option @option{-mbig-endian} and @code{stdint.h}
2736 can be included without error when @option{-mbig-endian} is passed.
2737
2738 @item stpcpy
2739 Target provides @code{stpcpy} function.
2740
2741 @item sysconf
2742 Target supports @code{sysconf}.
2743
2744 @item trampolines
2745 Target supports trampolines.
2746
2747 @item two_plus_gigs
2748 Target supports linking programs with 2+GiB of data.
2749
2750 @item uclibc
2751 Target supports uClibc.
2752
2753 @item unwrapped
2754 Target does not use a status wrapper.
2755
2756 @item vxworks_kernel
2757 Target is a VxWorks kernel.
2758
2759 @item vxworks_rtp
2760 Target is a VxWorks RTP.
2761
2762 @item wchar
2763 Target supports wide characters.
2764
2765 @item weak_undefined
2766 Target supports weak undefined symbols
2767 @end table
2768
2769 @subsubsection Other attributes
2770
2771 @table @code
2772 @item R_flag_in_section
2773 Target supports the 'R' flag in .section directive in assembly inputs.
2774
2775 @item automatic_stack_alignment
2776 Target supports automatic stack alignment.
2777
2778 @item branch_cost
2779 Target supports @option{-branch-cost=N}.
2780
2781 @item const_volatile_readonly_section
2782 Target places const volatile variables in readonly sections.
2783
2784 @item cxa_atexit
2785 Target uses @code{__cxa_atexit}.
2786
2787 @item default_packed
2788 @anchor{default_packed}
2789 Target has packed layout of structure members by default.
2790
2791 @item exceptions
2792 Target supports exceptions.
2793
2794 @item exceptions_enabled
2795 Target supports exceptions and they are enabled in the current
2796 testing configuration.
2797
2798 @item fgraphite
2799 Target supports Graphite optimizations.
2800
2801 @item fixed_point
2802 Target supports fixed-point extension to C.
2803
2804 @item fopenacc
2805 Target supports OpenACC via @option{-fopenacc}.
2806
2807 @item fopenmp
2808 Target supports OpenMP via @option{-fopenmp}.
2809
2810 @item fpic
2811 Target supports @option{-fpic} and @option{-fPIC}.
2812
2813 @item freorder
2814 Target supports @option{-freorder-blocks-and-partition}.
2815
2816 @item fstack_protector
2817 Target supports @option{-fstack-protector}.
2818
2819 @item gas
2820 Target uses GNU @command{as}.
2821
2822 @item gc_sections
2823 Target supports @option{--gc-sections}.
2824
2825 @item gld
2826 Target uses GNU @command{ld}.
2827
2828 @item keeps_null_pointer_checks
2829 Target keeps null pointer checks, either due to the use of
2830 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
2831
2832 @item llvm_binutils
2833 Target is using an LLVM assembler and/or linker, instead of GNU Binutils.
2834
2835 @item lra
2836 Target supports local register allocator (LRA).
2837
2838 @item lto
2839 Compiler has been configured to support link-time optimization (LTO).
2840
2841 @item lto_incremental
2842 Compiler and linker support link-time optimization relocatable linking
2843 with @option{-r} and @option{-flto} options.
2844
2845 @item naked_functions
2846 Target supports the @code{naked} function attribute.
2847
2848 @item named_sections
2849 Target supports named sections.
2850
2851 @item natural_alignment_32
2852 Target uses natural alignment (aligned to type size) for types of
2853 32 bits or less.
2854
2855 @item tail_call
2856 Target supports tail-call optimizations.
2857
2858 @item target_natural_alignment_64
2859 Target uses natural alignment (aligned to type size) for types of
2860 64 bits or less.
2861
2862 @item no_alignment_constraints
2863 Target defines __BIGGEST_ALIGNMENT__=1. Hence target imposes
2864 no alignment constraints. This is similar, but not necessarily
2865 the same as @ref{default_packed}. Although @code{BIGGEST_FIELD_ALIGNMENT}
2866 defaults to @code{BIGGEST_ALIGNMENT} for most targets, it is possible
2867 for a target to set those two with different values and have different
2868 alignment constraints for aggregate and non-aggregate types.
2869
2870 @item noinit
2871 Target supports the @code{noinit} variable attribute.
2872
2873 @item nonpic
2874 Target does not generate PIC by default.
2875
2876 @item o_flag_in_section
2877 Target supports the 'o' flag in .section directive in assembly inputs.
2878
2879 @item offload_gcn
2880 Target has been configured for OpenACC/OpenMP offloading on AMD GCN.
2881
2882 @item persistent
2883 Target supports the @code{persistent} variable attribute.
2884
2885 @item pie_enabled
2886 Target generates PIE by default.
2887
2888 @item pcc_bitfield_type_matters
2889 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
2890
2891 @item pe_aligned_commons
2892 Target supports @option{-mpe-aligned-commons}.
2893
2894 @item pie
2895 Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
2896
2897 @item rdynamic
2898 Target supports @option{-rdynamic}.
2899
2900 @item scalar_all_fma
2901 Target supports all four fused multiply-add optabs for both @code{float}
2902 and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab},
2903 @code{fnma_optab} and @code{fnms_optab}.
2904
2905 @item section_anchors
2906 Target supports section anchors.
2907
2908 @item short_enums
2909 Target defaults to short enums.
2910
2911 @item stack_size
2912 @anchor{stack_size_et}
2913 Target has limited stack size. The stack size limit can be obtained using the
2914 STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature
2915 @code{stack_size}}.
2916
2917 @item static
2918 Target supports @option{-static}.
2919
2920 @item static_libgfortran
2921 Target supports statically linking @samp{libgfortran}.
2922
2923 @item string_merging
2924 Target supports merging string constants at link time.
2925
2926 @item ucn
2927 Target supports compiling and assembling UCN.
2928
2929 @item ucn_nocache
2930 Including the options used to compile this particular test, the
2931 target supports compiling and assembling UCN.
2932
2933 @item unaligned_stack
2934 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
2935 or equal to the required vector alignment.
2936
2937 @item vector_alignment_reachable
2938 Vector alignment is reachable for types of 32 bits or less.
2939
2940 @item vector_alignment_reachable_for_64bit
2941 Vector alignment is reachable for types of 64 bits or less.
2942
2943 @item vma_equals_lma
2944 Target generates executable with VMA equal to LMA for .data section.
2945
2946 @item wchar_t_char16_t_compatible
2947 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
2948
2949 @item wchar_t_char32_t_compatible
2950 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
2951
2952 @item comdat_group
2953 Target uses comdat groups.
2954
2955 @item indirect_calls
2956 Target supports indirect calls, i.e. calls where the target is not
2957 constant.
2958
2959 @item lgccjit
2960 Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests.
2961
2962 @item __OPTIMIZE__
2963 Optimizations are enabled (@code{__OPTIMIZE__}) per the current
2964 compiler flags.
2965 @end table
2966
2967 @subsubsection Local to tests in @code{gcc.target/i386}
2968
2969 @table @code
2970 @item 3dnow
2971 Target supports compiling @code{3dnow} instructions.
2972
2973 @item aes
2974 Target supports compiling @code{aes} instructions.
2975
2976 @item fma4
2977 Target supports compiling @code{fma4} instructions.
2978
2979 @item mfentry
2980 Target supports the @code{-mfentry} option that alters the
2981 position of profiling calls such that they precede the prologue.
2982
2983 @item ms_hook_prologue
2984 Target supports attribute @code{ms_hook_prologue}.
2985
2986 @item pclmul
2987 Target supports compiling @code{pclmul} instructions.
2988
2989 @item sse3
2990 Target supports compiling @code{sse3} instructions.
2991
2992 @item sse4
2993 Target supports compiling @code{sse4} instructions.
2994
2995 @item sse4a
2996 Target supports compiling @code{sse4a} instructions.
2997
2998 @item ssse3
2999 Target supports compiling @code{ssse3} instructions.
3000
3001 @item vaes
3002 Target supports compiling @code{vaes} instructions.
3003
3004 @item vpclmul
3005 Target supports compiling @code{vpclmul} instructions.
3006
3007 @item xop
3008 Target supports compiling @code{xop} instructions.
3009 @end table
3010
3011 @subsubsection Local to tests in @code{gcc.test-framework}
3012
3013 @table @code
3014 @item no
3015 Always returns 0.
3016
3017 @item yes
3018 Always returns 1.
3019 @end table
3020
3021 @node Add Options
3022 @subsection Features for @code{dg-add-options}
3023
3024 The supported values of @var{feature} for directive @code{dg-add-options}
3025 are:
3026
3027 @table @code
3028 @item arm_fp
3029 @code{__ARM_FP} definition. Only ARM targets support this feature, and only then
3030 in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target
3031 keyword}.
3032
3033 @item arm_fp_dp
3034 @code{__ARM_FP} definition with double-precision support. Only ARM
3035 targets support this feature, and only then in certain modes; see the
3036 @ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}.
3037
3038 @item arm_neon
3039 NEON support. Only ARM targets support this feature, and only then
3040 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
3041 keyword}.
3042
3043 @item arm_fp16
3044 VFP half-precision floating point support. This does not select the
3045 FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or
3046 @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This
3047 feature is only supported by ARM targets and then only in certain
3048 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
3049 keyword}.
3050
3051 @item arm_fp16_ieee
3052 @anchor{arm_fp16_ieee}
3053 ARM IEEE 754-2008 format VFP half-precision floating point support.
3054 This feature is only supported by ARM targets and then only in certain
3055 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
3056 keyword}.
3057
3058 @item arm_fp16_alternative
3059 @anchor{arm_fp16_alternative}
3060 ARM Alternative format VFP half-precision floating point support.
3061 This feature is only supported by ARM targets and then only in certain
3062 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
3063 keyword}.
3064
3065 @item arm_neon_fp16
3066 NEON and half-precision floating point support. Only ARM targets
3067 support this feature, and only then in certain modes; see
3068 the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}.
3069
3070 @item arm_vfp3
3071 arm vfp3 floating point support; see
3072 the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}.
3073
3074 @item arm_arch_v8a_hard
3075 Add options for ARMv8-A and the hard-float variant of the AAPCS,
3076 if this is supported by the compiler; see the
3077 @ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword.
3078
3079 @item arm_v8_1a_neon
3080 Add options for ARMv8.1-A with Adv.SIMD support, if this is supported
3081 by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok}
3082 effective target keyword.
3083
3084 @item arm_v8_2a_fp16_scalar
3085 Add options for ARMv8.2-A with scalar FP16 support, if this is
3086 supported by the target; see the
3087 @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective
3088 target keyword.
3089
3090 @item arm_v8_2a_fp16_neon
3091 Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is
3092 supported by the target; see the
3093 @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target
3094 keyword.
3095
3096 @item arm_v8_2a_dotprod_neon
3097 Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is
3098 supported by the target; see the
3099 @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword.
3100
3101 @item arm_fp16fml_neon
3102 Add options to enable generation of the @code{VFMAL} and @code{VFMSL}
3103 instructions, if this is supported by the target; see the
3104 @ref{arm_fp16fml_neon_ok} effective target keyword.
3105
3106 @item arm_dsp
3107 Add options for ARM DSP intrinsics support, if this is supported by
3108 the target; see the @ref{arm_dsp_ok,,arm_dsp_ok effective target
3109 keyword}.
3110
3111 @item bind_pic_locally
3112 Add the target-specific flags needed to enable functions to bind
3113 locally when using pic/PIC passes in the testsuite.
3114
3115 @item float@var{n}
3116 Add the target-specific flags needed to use the @code{_Float@var{n}} type.
3117
3118 @item float@var{n}x
3119 Add the target-specific flags needed to use the @code{_Float@var{n}x} type.
3120
3121 @item ieee
3122 Add the target-specific flags needed to enable full IEEE
3123 compliance mode.
3124
3125 @item mips16_attribute
3126 @code{mips16} function attributes.
3127 Only MIPS targets support this feature, and only then in certain modes.
3128
3129 @item stack_size
3130 @anchor{stack_size_ao}
3131 Add the flags needed to define macro STACK_SIZE and set it to the stack size
3132 limit associated with the @ref{stack_size_et,,@code{stack_size} effective
3133 target}.
3134
3135 @item sqrt_insn
3136 Add the target-specific flags needed to enable hardware square root
3137 instructions, if any.
3138
3139 @item tls
3140 Add the target-specific flags needed to use thread-local storage.
3141
3142 @item weak_undefined
3143 Add the flags needed to enable support for weak undefined symbols.
3144 @end table
3145
3146 @node Require Support
3147 @subsection Variants of @code{dg-require-@var{support}}
3148
3149 A few of the @code{dg-require} directives take arguments.
3150
3151 @table @code
3152 @item dg-require-iconv @var{codeset}
3153 Skip the test if the target does not support iconv. @var{codeset} is
3154 the codeset to convert to.
3155
3156 @item dg-require-profiling @var{profopt}
3157 Skip the test if the target does not support profiling with option
3158 @var{profopt}.
3159
3160 @item dg-require-stack-check @var{check}
3161 Skip the test if the target does not support the @code{-fstack-check}
3162 option. If @var{check} is @code{""}, support for @code{-fstack-check}
3163 is checked, for @code{-fstack-check=("@var{check}")} otherwise.
3164
3165 @item dg-require-stack-size @var{size}
3166 Skip the test if the target does not support a stack size of @var{size}.
3167
3168 @item dg-require-visibility @var{vis}
3169 Skip the test if the target does not support the @code{visibility} attribute.
3170 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
3171 checked, for @code{visibility("@var{vis}")} otherwise.
3172 @end table
3173
3174 The original @code{dg-require} directives were defined before there
3175 was support for effective-target keywords. The directives that do not
3176 take arguments could be replaced with effective-target keywords.
3177
3178 @table @code
3179 @item dg-require-alias ""
3180 Skip the test if the target does not support the @samp{alias} attribute.
3181
3182 @item dg-require-ascii-locale ""
3183 Skip the test if the host does not support an ASCII locale.
3184
3185 @item dg-require-compat-dfp ""
3186 Skip this test unless both compilers in a @file{compat} testsuite
3187 support decimal floating point.
3188
3189 @item dg-require-cxa-atexit ""
3190 Skip the test if the target does not support @code{__cxa_atexit}.
3191 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
3192
3193 @item dg-require-dll ""
3194 Skip the test if the target does not support DLL attributes.
3195
3196 @item dg-require-dot ""
3197 Skip the test if the host does not have @command{dot}.
3198
3199 @item dg-require-fork ""
3200 Skip the test if the target does not support @code{fork}.
3201
3202 @item dg-require-gc-sections ""
3203 Skip the test if the target's linker does not support the
3204 @code{--gc-sections} flags.
3205 This is equivalent to @code{dg-require-effective-target gc-sections}.
3206
3207 @item dg-require-host-local ""
3208 Skip the test if the host is remote, rather than the same as the build
3209 system. Some tests are incompatible with DejaGnu's handling of remote
3210 hosts, which involves copying the source file to the host and compiling
3211 it with a relative path and "@code{-o a.out}".
3212
3213 @item dg-require-mkfifo ""
3214 Skip the test if the target does not support @code{mkfifo}.
3215
3216 @item dg-require-named-sections ""
3217 Skip the test is the target does not support named sections.
3218 This is equivalent to @code{dg-require-effective-target named_sections}.
3219
3220 @item dg-require-weak ""
3221 Skip the test if the target does not support weak symbols.
3222
3223 @item dg-require-weak-override ""
3224 Skip the test if the target does not support overriding weak symbols.
3225 @end table
3226
3227 @node Final Actions
3228 @subsection Commands for use in @code{dg-final}
3229
3230 The GCC testsuite defines the following directives to be used within
3231 @code{dg-final}.
3232
3233 @subsubsection Scan a particular file
3234
3235 @table @code
3236 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
3237 Passes if @var{regexp} matches text in @var{filename}.
3238 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
3239 Passes if @var{regexp} does not match text in @var{filename}.
3240 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
3241 Passes if @var{regexp} matches in Fortran module @var{module}.
3242 @item dg-check-dot @var{filename}
3243 Passes if @var{filename} is a valid @file{.dot} file (by running
3244 @code{dot -Tpng} on it, and verifying the exit code is 0).
3245 @item scan-sarif-file @var{regexp} [@{ target/xfail @var{selector} @}]
3246 Passes if @var{regexp} matches text in the file generated by
3247 @option{-fdiagnostics-format=sarif-file}.
3248 @item scan-sarif-file-not @var{regexp} [@{ target/xfail @var{selector} @}]
3249 Passes if @var{regexp} does not match text in the file generated by
3250 @option{-fdiagnostics-format=sarif-file}.
3251 @end table
3252
3253 @subsubsection Scan the assembly output
3254
3255 @table @code
3256 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
3257 Passes if @var{regex} matches text in the test's assembler output.
3258
3259 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
3260 Passes if @var{regex} does not match text in the test's assembler output.
3261
3262 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
3263 Passes if @var{regex} is matched exactly @var{num} times in the test's
3264 assembler output.
3265
3266 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
3267 Passes if @var{regex} matches text in the test's demangled assembler output.
3268
3269 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
3270 Passes if @var{regex} does not match text in the test's demangled assembler
3271 output.
3272
3273 @item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
3274 Passes if @var{functions} are all in @var{section}. The caller needs to
3275 allow for @code{USER_LABEL_PREFIX} and different section name conventions.
3276
3277 @item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}]
3278 Passes if @var{functions} are all in @var{section}in @var{filename}.
3279 The same caveats as for @code{scan-assembler-symbol-section} apply.
3280
3281 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
3282 Passes if @var{symbol} is defined as a hidden symbol in the test's
3283 assembly output.
3284
3285 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
3286 Passes if @var{symbol} is not defined as a hidden symbol in the test's
3287 assembly output.
3288
3289 @item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @}]]
3290 Looks through the source file for comments that give the expected assembly
3291 output for selected functions. Each line of expected output starts with the
3292 prefix string @var{prefix} and the expected output for a function as a whole
3293 is followed by a line that starts with the string @var{terminator}.
3294 Specifying an empty terminator is equivalent to specifying @samp{"*/"}.
3295
3296 @var{options}, if specified, is a list of regular expressions, each of
3297 which matches a full command-line option. A non-empty list prevents
3298 the test from running unless all of the given options are present on the
3299 command line. This can help if a source file is compiled both with
3300 and without optimization, since it is rarely useful to check the full
3301 function body for unoptimized code.
3302
3303 The first line of the expected output for a function @var{fn} has the form:
3304
3305 @smallexample
3306 @var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}]
3307 @end smallexample
3308
3309 Subsequent lines of the expected output also start with @var{prefix}.
3310 In both cases, whitespace after @var{prefix} is not significant.
3311
3312 The test discards assembly directives such as @code{.cfi_startproc}
3313 and local label definitions such as @code{.LFB0} from the compiler's
3314 assembly output. It then matches the result against the expected
3315 output for a function as a single regular expression. This means that
3316 later lines can use backslashes to refer back to @samp{(@dots{})}
3317 captures on earlier lines. For example:
3318
3319 @smallexample
3320 /* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */
3321 @dots{}
3322 /*
3323 ** add_w0_s8_m:
3324 ** mov (z[0-9]+\.b), w0
3325 ** add z0\.b, p0/m, z0\.b, \1
3326 ** ret
3327 */
3328 svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @}
3329 @dots{}
3330 /*
3331 ** add_b0_s8_m:
3332 ** mov (z[0-9]+\.b), b0
3333 ** add z1\.b, p0/m, z1\.b, \1
3334 ** ret
3335 */
3336 svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @}
3337 @end smallexample
3338
3339 checks whether the implementations of @code{add_w0_s8_m} and
3340 @code{add_b0_s8_m} match the regular expressions given. The test only
3341 runs when @samp{-DCHECK_ASM} is passed on the command line.
3342
3343 It is possible to create non-capturing multi-line regular expression
3344 groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the
3345 @samp{(}, @samp{|} and @samp{)} on separate lines (each still using
3346 @var{prefix}). For example:
3347
3348 @smallexample
3349 /*
3350 ** cmple_f16_tied:
3351 ** (
3352 ** fcmge p0\.h, p0/z, z1\.h, z0\.h
3353 ** |
3354 ** fcmle p0\.h, p0/z, z0\.h, z1\.h
3355 ** )
3356 ** ret
3357 */
3358 svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @}
3359 @end smallexample
3360
3361 checks whether @code{cmple_f16_tied} is implemented by the
3362 @code{fcmge} instruction followed by @code{ret} or by the
3363 @code{fcmle} instruction followed by @code{ret}. The test is
3364 still a single regular rexpression.
3365
3366 A line containing just:
3367
3368 @smallexample
3369 @var{prefix} ...
3370 @end smallexample
3371
3372 stands for zero or more unmatched lines; the whitespace after
3373 @var{prefix} is again not significant.
3374
3375 @end table
3376
3377 @subsubsection Scan optimization dump files
3378
3379 These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree},
3380 @code{offload-tree}, @code{rtl}, @code{offload-rtl}, @code{ipa}, and
3381 @code{wpa-ipa}.
3382
3383 @table @code
3384 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3385 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
3386
3387 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3388 Passes if @var{regex} does not match text in the dump file with suffix
3389 @var{suffix}.
3390
3391 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
3392 Passes if @var{regex} is found exactly @var{num} times in the dump file
3393 with suffix @var{suffix}.
3394
3395 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3396 Passes if @var{regex} matches demangled text in the dump file with
3397 suffix @var{suffix}.
3398
3399 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
3400 Passes if @var{regex} does not match demangled text in the dump file with
3401 suffix @var{suffix}.
3402 @end table
3403
3404 The @var{suffix} argument which describes the dump file to be scanned
3405 may contain a glob pattern that must expand to exactly one file
3406 name. This is useful if, e.g., different pass instances are executed
3407 depending on torture testing command-line flags, producing dump files
3408 whose names differ only in their pass instance number suffix. For
3409 example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for
3410 occurrences of the string ``code has been optimized'', use:
3411 @smallexample
3412 /* @{ dg-options "-fdump-tree-mypass" @} */
3413 /* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */
3414 @end smallexample
3415
3416
3417 @subsubsection Check for output files
3418
3419 @table @code
3420 @item output-exists [@{ target/xfail @var{selector} @}]
3421 Passes if compiler output file exists.
3422
3423 @item output-exists-not [@{ target/xfail @var{selector} @}]
3424 Passes if compiler output file does not exist.
3425
3426 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
3427 Passes if the pattern is present in the final executable.
3428
3429 @item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}]
3430 Passes if the pattern is absent from the final executable.
3431 @end table
3432
3433 @subsubsection Checks for @command{gcov} tests
3434
3435 @table @code
3436 @item run-gcov @var{sourcefile}
3437 Check line counts in @command{gcov} tests.
3438
3439 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
3440 Check branch and/or call counts, in addition to line counts, in
3441 @command{gcov} tests.
3442
3443 @item run-gcov-pytest @{ @var{sourcefile} @var{pytest_file} @}
3444 Check output of @command{gcov} intermediate format with a pytest
3445 script.
3446 @end table
3447
3448 @subsubsection Clean up generated test files
3449
3450 Usually the test-framework removes files that were generated during
3451 testing. If a testcase, for example, uses any dumping mechanism to
3452 inspect a passes dump file, the testsuite recognized the dump option
3453 passed to the tool and schedules a final cleanup to remove these files.
3454
3455 There are, however, following additional cleanup directives that can be
3456 used to annotate a testcase "manually".
3457 @table @code
3458 @item cleanup-coverage-files
3459 Removes coverage data files generated for this test.
3460
3461 @item cleanup-modules "@var{list-of-extra-modules}"
3462 Removes Fortran module files generated for this test, excluding the
3463 module names listed in keep-modules.
3464 Cleaning up module files is usually done automatically by the testsuite
3465 by looking at the source files and removing the modules after the test
3466 has been executed.
3467 @smallexample
3468 module MoD1
3469 end module MoD1
3470 module Mod2
3471 end module Mod2
3472 module moD3
3473 end module moD3
3474 module mod4
3475 end module mod4
3476 ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
3477 ! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
3478 @end smallexample
3479
3480 @item keep-modules "@var{list-of-modules-not-to-delete}"
3481 Whitespace separated list of module names that should not be deleted by
3482 cleanup-modules.
3483 If the list of modules is empty, all modules defined in this file are kept.
3484 @smallexample
3485 module maybe_unneeded
3486 end module maybe_unneeded
3487 module keep1
3488 end module keep1
3489 module keep2
3490 end module keep2
3491 ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
3492 ! @{ dg-final @{ keep-modules "" @} @} ! keep all
3493 @end smallexample
3494
3495 @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}"
3496 Whitespace separated list of suffixes that should not be deleted
3497 automatically in a testcase that uses @option{-save-temps}.
3498 @smallexample
3499 // @{ dg-options "-save-temps -fpch-preprocess -I." @}
3500 int main() @{ return 0; @}
3501 // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file
3502 // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i
3503 // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o
3504 @end smallexample
3505
3506 @item cleanup-profile-file
3507 Removes profiling files generated for this test.
3508
3509 @end table
3510
3511 @node Ada Tests
3512 @section Ada Language Testsuites
3513
3514 The Ada testsuite includes executable tests from the ACATS
3515 testsuite, publicly available at
3516 @uref{http://www.ada-auth.org/acats.html}.
3517
3518 These tests are integrated in the GCC testsuite in the
3519 @file{ada/acats} directory, and
3520 enabled automatically when running @code{make check}, assuming
3521 the Ada language has been enabled when configuring GCC@.
3522
3523 You can also run the Ada testsuite independently, using
3524 @code{make check-ada}, or run a subset of the tests by specifying which
3525 chapter to run, e.g.:
3526
3527 @smallexample
3528 $ make check-ada CHAPTERS="c3 c9"
3529 @end smallexample
3530
3531 The tests are organized by directory, each directory corresponding to
3532 a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
3533 to chapter 9, which deals with tasking features of the language.
3534
3535 The tests are run using two @command{sh} scripts: @file{run_acats} and
3536 @file{run_all.sh}. To run the tests using a simulator or a cross
3537 target, see the small
3538 customization section at the top of @file{run_all.sh}.
3539
3540 These tests are run using the build tree: they can be run without doing
3541 a @code{make install}.
3542
3543 @node C Tests
3544 @section C Language Testsuites
3545
3546 GCC contains the following C language testsuites, in the
3547 @file{gcc/testsuite} directory:
3548
3549 @table @file
3550 @item gcc.dg
3551 This contains tests of particular features of the C compiler, using the
3552 more modern @samp{dg} harness. Correctness tests for various compiler
3553 features should go here if possible.
3554
3555 Magic comments determine whether the file
3556 is preprocessed, compiled, linked or run. In these tests, error and warning
3557 message texts are compared against expected texts or regular expressions
3558 given in comments. These tests are run with the options @samp{-ansi -pedantic}
3559 unless other options are given in the test. Except as noted below they
3560 are not run with multiple optimization options.
3561 @item gcc.dg/compat
3562 This subdirectory contains tests for binary compatibility using
3563 @file{lib/compat.exp}, which in turn uses the language-independent support
3564 (@pxref{compat Testing, , Support for testing binary compatibility}).
3565 @item gcc.dg/cpp
3566 This subdirectory contains tests of the preprocessor.
3567 @item gcc.dg/debug
3568 This subdirectory contains tests for debug formats. Tests in this
3569 subdirectory are run for each debug format that the compiler supports.
3570 @item gcc.dg/format
3571 This subdirectory contains tests of the @option{-Wformat} format
3572 checking. Tests in this directory are run with and without
3573 @option{-DWIDE}.
3574 @item gcc.dg/noncompile
3575 This subdirectory contains tests of code that should not compile and
3576 does not need any special compilation options. They are run with
3577 multiple optimization options, since sometimes invalid code crashes
3578 the compiler with optimization.
3579 @item gcc.dg/special
3580 FIXME: describe this.
3581
3582 @item gcc.c-torture
3583 This contains particular code fragments which have historically broken easily.
3584 These tests are run with multiple optimization options, so tests for features
3585 which only break at some optimization levels belong here. This also contains
3586 tests to check that certain optimizations occur. It might be worthwhile to
3587 separate the correctness tests cleanly from the code quality tests, but
3588 it hasn't been done yet.
3589
3590 @item gcc.c-torture/compat
3591 FIXME: describe this.
3592
3593 This directory should probably not be used for new tests.
3594 @item gcc.c-torture/compile
3595 This testsuite contains test cases that should compile, but do not
3596 need to link or run. These test cases are compiled with several
3597 different combinations of optimization options. All warnings are
3598 disabled for these test cases, so this directory is not suitable if
3599 you wish to test for the presence or absence of compiler warnings.
3600 While special options can be set, and tests disabled on specific
3601 platforms, by the use of @file{.x} files, mostly these test cases
3602 should not contain platform dependencies. FIXME: discuss how defines
3603 such as @code{STACK_SIZE} are used.
3604 @item gcc.c-torture/execute
3605 This testsuite contains test cases that should compile, link and run;
3606 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
3607 @item gcc.c-torture/execute/ieee
3608 This contains tests which are specific to IEEE floating point.
3609 @item gcc.c-torture/unsorted
3610 FIXME: describe this.
3611
3612 This directory should probably not be used for new tests.
3613 @item gcc.misc-tests
3614 This directory contains C tests that require special handling. Some
3615 of these tests have individual expect files, and others share
3616 special-purpose expect files:
3617
3618 @table @file
3619 @item @code{bprob*.c}
3620 Test @option{-fbranch-probabilities} using
3621 @file{gcc.misc-tests/bprob.exp}, which
3622 in turn uses the generic, language-independent framework
3623 (@pxref{profopt Testing, , Support for testing profile-directed
3624 optimizations}).
3625
3626 @item @code{gcov*.c}
3627 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
3628 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
3629
3630 @item @code{i386-pf-*.c}
3631 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
3632 @end table
3633
3634 @item gcc.test-framework
3635 @table @file
3636 @item @code{dg-*.c}
3637 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
3638 @end table
3639
3640 @end table
3641
3642 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
3643 test cases and magic comments more.
3644
3645 @node LTO Testing
3646 @section Support for testing link-time optimizations
3647
3648 Tests for link-time optimizations usually require multiple source files
3649 that are compiled separately, perhaps with different sets of options.
3650 There are several special-purpose test directives used for these tests.
3651
3652 @table @code
3653 @item @{ dg-lto-do @var{do-what-keyword} @}
3654 @var{do-what-keyword} specifies how the test is compiled and whether
3655 it is executed. It is one of:
3656
3657 @table @code
3658 @item assemble
3659 Compile with @option{-c} to produce a relocatable object file.
3660 @item link
3661 Compile, assemble, and link to produce an executable file.
3662 @item run
3663 Produce and run an executable file, which is expected to return
3664 an exit code of 0.
3665 @end table
3666
3667 The default is @code{assemble}. That can be overridden for a set of
3668 tests by redefining @code{dg-do-what-default} within the @code{.exp}
3669 file for those tests.
3670
3671 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
3672 @samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
3673 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
3674
3675 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
3676 This directive provides a list of one or more sets of compiler options
3677 to override @var{LTO_OPTIONS}. Each test will be compiled and run with
3678 each of these sets of options.
3679
3680 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
3681 This directive adds @var{options} to the linker options used.
3682
3683 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
3684 This directive removes @var{options} from the set of linker options used.
3685 @end table
3686
3687 @node gcov Testing
3688 @section Support for testing @command{gcov}
3689
3690 Language-independent support for testing @command{gcov}, and for checking
3691 that branch profiling produces expected values, is provided by the
3692 expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
3693 in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
3694 @command{gcov} test contains the following DejaGnu commands within comments:
3695
3696 @smallexample
3697 @{ dg-options "--coverage" @}
3698 @{ dg-do run @{ target native @} @}
3699 @{ dg-final @{ run-gcov sourcefile @} @}
3700 @end smallexample
3701
3702 Checks of @command{gcov} output can include line counts, branch percentages,
3703 and call return percentages. All of these checks are requested via
3704 commands that appear in comments in the test's source file.
3705 Commands to check line counts are processed by default.
3706 Commands to check branch percentages and call return percentages are
3707 processed if the @command{run-gcov} command has arguments @code{branches}
3708 or @code{calls}, respectively. For example, the following specifies
3709 checking both, as well as passing @option{-b} to @command{gcov}:
3710
3711 @smallexample
3712 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
3713 @end smallexample
3714
3715 A line count command appears within a comment on the source line
3716 that is expected to get the specified count and has the form
3717 @code{count(@var{cnt})}. A test should only check line counts for
3718 lines that will get the same count for any architecture.
3719
3720 Commands to check branch percentages (@code{branch}) and call
3721 return percentages (@code{returns}) are very similar to each other.
3722 A beginning command appears on or before the first of a range of
3723 lines that will report the percentage, and the ending command
3724 follows that range of lines. The beginning command can include a
3725 list of percentages, all of which are expected to be found within
3726 the range. A range is terminated by the next command of the same
3727 kind. A command @code{branch(end)} or @code{returns(end)} marks
3728 the end of a range without starting a new one. For example:
3729
3730 @smallexample
3731 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
3732 /* @r{branch(end)} */
3733 foo (i, j);
3734 @end smallexample
3735
3736 For a call return percentage, the value specified is the
3737 percentage of calls reported to return. For a branch percentage,
3738 the value is either the expected percentage or 100 minus that
3739 value, since the direction of a branch can differ depending on the
3740 target or the optimization level.
3741
3742 Not all branches and calls need to be checked. A test should not
3743 check for branches that might be optimized away or replaced with
3744 predicated instructions. Don't check for calls inserted by the
3745 compiler or ones that might be inlined or optimized away.
3746
3747 A single test can check for combinations of line counts, branch
3748 percentages, and call return percentages. The command to check a
3749 line count must appear on the line that will report that count, but
3750 commands to check branch percentages and call return percentages can
3751 bracket the lines that report them.
3752
3753 @node profopt Testing
3754 @section Support for testing profile-directed optimizations
3755
3756 The file @file{profopt.exp} provides language-independent support for
3757 checking correct execution of a test built with profile-directed
3758 optimization. This testing requires that a test program be built and
3759 executed twice. The first time it is compiled to generate profile
3760 data, and the second time it is compiled to use the data that was
3761 generated during the first execution. The second execution is to
3762 verify that the test produces the expected results.
3763
3764 To check that the optimization actually generated better code, a
3765 test can be built and run a third time with normal optimizations to
3766 verify that the performance is better with the profile-directed
3767 optimizations. @file{profopt.exp} has the beginnings of this kind
3768 of support.
3769
3770 @file{profopt.exp} provides generic support for profile-directed
3771 optimizations. Each set of tests that uses it provides information
3772 about a specific optimization:
3773
3774 @table @code
3775 @item tool
3776 tool being tested, e.g., @command{gcc}
3777
3778 @item profile_option
3779 options used to generate profile data
3780
3781 @item feedback_option
3782 options used to optimize using that profile data
3783
3784 @item prof_ext
3785 suffix of profile data files
3786
3787 @item PROFOPT_OPTIONS
3788 list of options with which to run each test, similar to the lists for
3789 torture tests
3790
3791 @item @{ dg-final-generate @{ @var{local-directive} @} @}
3792 This directive is similar to @code{dg-final}, but the
3793 @var{local-directive} is run after the generation of profile data.
3794
3795 @item @{ dg-final-use @{ @var{local-directive} @} @}
3796 The @var{local-directive} is run after the profile data have been
3797 used.
3798 @end table
3799
3800 @node compat Testing
3801 @section Support for testing binary compatibility
3802
3803 The file @file{compat.exp} provides language-independent support for
3804 binary compatibility testing. It supports testing interoperability of
3805 two compilers that follow the same ABI, or of multiple sets of
3806 compiler options that should not affect binary compatibility. It is
3807 intended to be used for testsuites that complement ABI testsuites.
3808
3809 A test supported by this framework has three parts, each in a
3810 separate source file: a main program and two pieces that interact
3811 with each other to split up the functionality being tested.
3812
3813 @table @file
3814 @item @var{testname}_main.@var{suffix}
3815 Contains the main program, which calls a function in file
3816 @file{@var{testname}_x.@var{suffix}}.
3817
3818 @item @var{testname}_x.@var{suffix}
3819 Contains at least one call to a function in
3820 @file{@var{testname}_y.@var{suffix}}.
3821
3822 @item @var{testname}_y.@var{suffix}
3823 Shares data with, or gets arguments from,
3824 @file{@var{testname}_x.@var{suffix}}.
3825 @end table
3826
3827 Within each test, the main program and one functional piece are
3828 compiled by the GCC under test. The other piece can be compiled by
3829 an alternate compiler. If no alternate compiler is specified,
3830 then all three source files are all compiled by the GCC under test.
3831 You can specify pairs of sets of compiler options. The first element
3832 of such a pair specifies options used with the GCC under test, and the
3833 second element of the pair specifies options used with the alternate
3834 compiler. Each test is compiled with each pair of options.
3835
3836 @file{compat.exp} defines default pairs of compiler options.
3837 These can be overridden by defining the environment variable
3838 @env{COMPAT_OPTIONS} as:
3839
3840 @smallexample
3841 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
3842 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
3843 @end smallexample
3844
3845 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
3846 used by the compiler under test and @var{alti} used by the alternate
3847 compiler. For example, with
3848 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
3849 the test is first built with @option{-g -O0} by the compiler under
3850 test and with @option{-O3} by the alternate compiler. The test is
3851 built a second time using @option{-fpic} by the compiler under test
3852 and @option{-fPIC -O2} by the alternate compiler.
3853
3854 An alternate compiler is specified by defining an environment
3855 variable to be the full pathname of an installed compiler; for C
3856 define @env{ALT_CC_UNDER_TEST}, and for C++ define
3857 @env{ALT_CXX_UNDER_TEST}. These will be written to the
3858 @file{site.exp} file used by DejaGnu. The default is to build each
3859 test with the compiler under test using the first of each pair of
3860 compiler options from @env{COMPAT_OPTIONS}. When
3861 @env{ALT_CC_UNDER_TEST} or
3862 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
3863 the compiler under test but with combinations of the options from
3864 @env{COMPAT_OPTIONS}.
3865
3866 To run only the C++ compatibility suite using the compiler under test
3867 and another version of GCC using specific compiler options, do the
3868 following from @file{@var{objdir}/gcc}:
3869
3870 @smallexample
3871 rm site.exp
3872 make -k \
3873 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
3874 COMPAT_OPTIONS="@var{lists as shown above}" \
3875 check-c++ \
3876 RUNTESTFLAGS="compat.exp"
3877 @end smallexample
3878
3879 A test that fails when the source files are compiled with different
3880 compilers, but passes when the files are compiled with the same
3881 compiler, demonstrates incompatibility of the generated code or
3882 runtime support. A test that fails for the alternate compiler but
3883 passes for the compiler under test probably tests for a bug that was
3884 fixed in the compiler under test but is present in the alternate
3885 compiler.
3886
3887 The binary compatibility tests support a small number of test framework
3888 commands that appear within comments in a test file.
3889
3890 @table @code
3891 @item dg-require-*
3892 These commands can be used in @file{@var{testname}_main.@var{suffix}}
3893 to skip the test if specific support is not available on the target.
3894
3895 @item dg-options
3896 The specified options are used for compiling this particular source
3897 file, appended to the options from @env{COMPAT_OPTIONS}. When this
3898 command appears in @file{@var{testname}_main.@var{suffix}} the options
3899 are also used to link the test program.
3900
3901 @item dg-xfail-if
3902 This command can be used in a secondary source file to specify that
3903 compilation is expected to fail for particular options on particular
3904 targets.
3905 @end table
3906
3907 @node Torture Tests
3908 @section Support for torture testing using multiple options
3909
3910 Throughout the compiler testsuite there are several directories whose
3911 tests are run multiple times, each with a different set of options.
3912 These are known as torture tests.
3913 @file{lib/torture-options.exp} defines procedures to
3914 set up these lists:
3915
3916 @table @code
3917 @item torture-init
3918 Initialize use of torture lists.
3919 @item set-torture-options
3920 Set lists of torture options to use for tests with and without loops.
3921 Optionally combine a set of torture options with a set of other
3922 options, as is done with Objective-C runtime options.
3923 @item torture-finish
3924 Finalize use of torture lists.
3925 @end table
3926
3927 The @file{.exp} file for a set of tests that use torture options must
3928 include calls to these three procedures if:
3929
3930 @itemize @bullet
3931 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
3932
3933 @item It calls @var{$@{tool@}}@code{-torture} or
3934 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
3935 @code{fortran}, or @code{objc}.
3936
3937 @item It calls @code{dg-pch}.
3938 @end itemize
3939
3940 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
3941 to call the torture procedures if the tests should use the list in
3942 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
3943
3944 Most uses of torture options can override the default lists by defining
3945 @var{TORTURE_OPTIONS} or add to the default list by defining
3946 @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
3947 file or add them to the @file{site.exp} file; for example
3948
3949 @smallexample
3950 set ADDITIONAL_TORTURE_OPTIONS [list \
3951 @{ -O2 -ftree-loop-linear @} \
3952 @{ -O2 -fpeel-loops @} ]
3953 @end smallexample
3954
3955 @node GIMPLE Tests
3956 @section Support for testing GIMPLE passes
3957
3958 As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
3959 that the function body will be GIMPLE, rather than C. The compiler requires
3960 the option @option{-fgimple} to enable this functionality. For example:
3961
3962 @smallexample
3963 /* @{ dg-do compile @} */
3964 /* @{ dg-options "-O -fgimple" @} */
3965
3966 void __GIMPLE (startwith ("dse2")) foo ()
3967 @{
3968 int a;
3969
3970 bb_2:
3971 if (a > 4)
3972 goto bb_3;
3973 else
3974 goto bb_4;
3975
3976 bb_3:
3977 a_2 = 10;
3978 goto bb_5;
3979
3980 bb_4:
3981 a_3 = 20;
3982
3983 bb_5:
3984 a_1 = __PHI (bb_3: a_2, bb_4: a_3);
3985 a_4 = a_1 + 4;
3986
3987 return;
3988 @}
3989 @end smallexample
3990
3991 The @code{startwith} argument indicates at which pass to begin.
3992
3993 Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple})
3994 to make tree dumps more closely follow the format accepted by the GIMPLE
3995 parser.
3996
3997 Example DejaGnu tests of GIMPLE can be seen in the source tree at
3998 @file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
3999
4000 The @code{__GIMPLE} parser is integrated with the C tokenizer and
4001 preprocessor, so it should be possible to use macros to build out
4002 test coverage.
4003
4004 @node RTL Tests
4005 @section Support for testing RTL passes
4006
4007 As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
4008 function body will be RTL, rather than C. For example:
4009
4010 @smallexample
4011 double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
4012 @{
4013 (function "test"
4014 [...snip; various directives go in here...]
4015 ) ;; function "test"
4016 @}
4017 @end smallexample
4018
4019 The @code{startwith} argument indicates at which pass to begin.
4020
4021 The parser expects the RTL body to be in the format emitted by this
4022 dumping function:
4023
4024 @smallexample
4025 DEBUG_FUNCTION void
4026 print_rtx_function (FILE *outfile, function *fn, bool compact);
4027 @end smallexample
4028
4029 when "compact" is true. So you can capture RTL in the correct format
4030 from the debugger using:
4031
4032 @smallexample
4033 (gdb) print_rtx_function (stderr, cfun, true);
4034 @end smallexample
4035
4036 and copy and paste the output into the body of the C function.
4037
4038 Example DejaGnu tests of RTL can be seen in the source tree under
4039 @file{gcc/testsuite/gcc.dg/rtl}.
4040
4041 The @code{__RTL} parser is not integrated with the C tokenizer or
4042 preprocessor, and works simply by reading the relevant lines within
4043 the braces. In particular, the RTL body must be on separate lines from
4044 the enclosing braces, and the preprocessor is not usable within it.