Debian Codegraph @

gcc/doc/sourcebuild.texi

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