1 @c Copyright (C) 2002-2017 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Source Tree Structure and Build System
8 This chapter describes the structure of the GCC source tree, and how
9 GCC is built. The user documentation for building and installing GCC
10 is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
11 which it is presumed that you are familiar.
14 * Configure Terms:: Configuration terminology and history.
15 * Top Level:: The top level source directory.
16 * gcc Directory:: The @file{gcc} subdirectory.
19 @include configterms.texi
22 @section Top Level Source Directory
24 The top level source directory in a GCC distribution contains several
25 files and directories that are shared with other software
26 distributions such as that of GNU Binutils. It also contains several
27 subdirectories that contain parts of GCC and its runtime libraries:
31 The Boehm conservative garbage collector, optionally used as part of
32 the ObjC runtime library when configured with @option{--enable-objc-gc}.
35 Autoconf macros and Makefile fragments used throughout the tree.
38 Contributed scripts that may be found useful in conjunction with GCC@.
39 One of these, @file{contrib/texi2pod.pl}, is used to generate man
40 pages from Texinfo manuals as part of the GCC build process.
43 The support for fixing system headers to work with GCC@. See
44 @file{fixincludes/README} for more information. The headers fixed by
45 this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
46 Along with those headers, @file{README-fixinc} is also installed, as
47 @file{@var{libsubdir}/include-fixed/README}.
50 The main sources of GCC itself (except for runtime libraries),
51 including optimizers, support for different target architectures,
52 language front ends, and testsuites. @xref{gcc Directory, , The
53 @file{gcc} Subdirectory}, for details.
56 Support tools for GNAT.
59 Headers for the @code{libiberty} library.
62 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
63 include it in @code{libc}.
66 The Ada runtime library.
69 The runtime support library for atomic operations (e.g. for @code{__sync}
73 The C preprocessor library.
76 The Decimal Float support library.
79 The @code{libffi} library, used as part of the Go runtime library.
82 The GCC runtime library.
85 The Fortran runtime library.
88 The Go runtime library. The bulk of this library is mirrored from the
89 @uref{https://github.com/@/golang/go, master Go repository}.
92 The GNU Offloading and Multi Processing Runtime Library.
95 The @code{libiberty} library, used for portability and for some
96 generally useful data structures and algorithms. @xref{Top, ,
97 Introduction, libiberty, @sc{gnu} libiberty}, for more information
101 The runtime support library for transactional memory.
104 The Objective-C and Objective-C++ runtime library.
107 The runtime support library for quad-precision math operations.
110 The Stack protector runtime library.
113 The C++ runtime library.
116 Plugin used by the linker if link-time optimizations are enabled.
118 @item maintainer-scripts
119 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
122 The @code{zlib} compression library, used for compressing and
123 uncompressing GCC's intermediate language in LTO object files.
126 The build system in the top level directory, including how recursion
127 into subdirectories works and how building runtime libraries for
128 multilibs is handled, is documented in a separate manual, included
129 with GNU Binutils. @xref{Top, , GNU configure and build system,
130 configure, The GNU configure and build system}, for details.
133 @section The @file{gcc} Subdirectory
135 The @file{gcc} directory contains many files that are part of the C
136 sources of GCC, other files used as part of the configuration and
137 build process, and subdirectories including documentation and a
138 testsuite. The files that are sources of GCC are documented in a
139 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
142 * Subdirectories:: Subdirectories of @file{gcc}.
143 * Configuration:: The configuration process, and the files it uses.
144 * Build:: The build system in the @file{gcc} directory.
145 * Makefile:: Targets in @file{gcc/Makefile}.
146 * Library Files:: Library source files and headers under @file{gcc/}.
147 * Headers:: Headers installed by GCC.
148 * Documentation:: Building documentation in GCC.
149 * Front End:: Anatomy of a language front end.
150 * Back End:: Anatomy of a target back end.
154 @subsection Subdirectories of @file{gcc}
156 The @file{gcc} directory contains the following subdirectories:
160 Subdirectories for various languages. Directories containing a file
161 @file{config-lang.in} are language subdirectories. The contents of
162 the subdirectories @file{c} (for C), @file{cp} (for C++),
163 @file{objc} (for Objective-C), @file{objcp} (for Objective-C++),
164 and @file{lto} (for LTO) are documented in this
165 manual (@pxref{Passes, , Passes and Files of the Compiler});
166 those for other languages are not. @xref{Front End, ,
167 Anatomy of a Language Front End}, for details of the files in these
171 Source files shared between the compiler drivers (such as
172 @command{gcc}) and the compilers proper (such as @file{cc1}). If an
173 architecture defines target hooks shared between those places, it also
174 has a subdirectory in @file{common/config}. @xref{Target Structure}.
177 Configuration files for supported architectures and operating
178 systems. @xref{Back End, , Anatomy of a Target Back End}, for
179 details of the files in this directory.
182 Texinfo documentation for GCC, together with automatically generated
183 man pages and support for converting the installation manual to
184 HTML@. @xref{Documentation}.
187 System headers installed by GCC, mainly those required by the C
188 standard of freestanding implementations. @xref{Headers, , Headers
189 Installed by GCC}, for details of when these and other headers are
193 Message catalogs with translations of messages produced by GCC into
194 various languages, @file{@var{language}.po}. This directory also
195 contains @file{gcc.pot}, the template for these message catalogues,
196 @file{exgettext}, a wrapper around @command{gettext} to extract the
197 messages from the GCC sources and create @file{gcc.pot}, which is run
198 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
199 which messages should not be extracted.
202 The GCC testsuites (except for those for runtime libraries).
207 @subsection Configuration in the @file{gcc} Directory
209 The @file{gcc} directory is configured with an Autoconf-generated
210 script @file{configure}. The @file{configure} script is generated
211 from @file{configure.ac} and @file{aclocal.m4}. From the files
212 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
213 file @file{config.in}. The file @file{cstamp-h.in} is used as a
217 * Config Fragments:: Scripts used by @file{configure}.
218 * System Config:: The @file{config.build}, @file{config.host}, and
219 @file{config.gcc} files.
220 * Configuration Files:: Files created by running @file{configure}.
223 @node Config Fragments
224 @subsubsection Scripts Used by @file{configure}
226 @file{configure} uses some other scripts to help in its work:
229 @item The standard GNU @file{config.sub} and @file{config.guess}
230 files, kept in the top level directory, are used.
232 @item The file @file{config.gcc} is used to handle configuration
233 specific to the particular target machine. The file
234 @file{config.build} is used to handle configuration specific to the
235 particular build machine. The file @file{config.host} is used to handle
236 configuration specific to the particular host machine. (In general,
237 these should only be used for features that cannot reasonably be tested in
238 Autoconf feature tests.)
239 @xref{System Config, , The @file{config.build}; @file{config.host};
240 and @file{config.gcc} Files}, for details of the contents of these files.
242 @item Each language subdirectory has a file
243 @file{@var{language}/config-lang.in} that is used for
244 front-end-specific configuration. @xref{Front End Config, , The Front
245 End @file{config-lang.in} File}, for details of this file.
247 @item A helper script @file{configure.frag} is used as part of
248 creating the output of @file{configure}.
252 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
254 The @file{config.build} file contains specific rules for particular systems
255 which GCC is built on. This should be used as rarely as possible, as the
256 behavior of the build system can always be detected by autoconf.
258 The @file{config.host} file contains specific rules for particular systems
259 which GCC will run on. This is rarely needed.
261 The @file{config.gcc} file contains specific rules for particular systems
262 which GCC will generate code for. This is usually needed.
264 Each file has a list of the shell variables it sets, with descriptions, at the
267 FIXME: document the contents of these files, and what variables should
268 be set to control build, host and target configuration.
270 @include configfiles.texi
273 @subsection Build System in the @file{gcc} Directory
275 FIXME: describe the build system, including what is built in what
276 stages. Also list the various source files that are used in the build
277 process but aren't source files of GCC itself and so aren't documented
278 below (@pxref{Passes}).
280 @include makefile.texi
283 @subsection Library Source Files and Headers under the @file{gcc} Directory
285 FIXME: list here, with explanation, all the C source files and headers
286 under the @file{gcc} directory that aren't built into the GCC
287 executable but rather are part of runtime libraries and object files,
288 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
289 Headers Installed by GCC}, for more information about the
290 @file{ginclude} directory.
293 @subsection Headers Installed by GCC
295 In general, GCC expects the system C library to provide most of the
296 headers to be used with it. However, GCC will fix those headers if
297 necessary to make them work with GCC, and will install some headers
298 required of freestanding implementations. These headers are installed
299 in @file{@var{libsubdir}/include}. Headers for non-C runtime
300 libraries are also installed by GCC; these are not documented here.
301 (FIXME: document them somewhere.)
303 Several of the headers GCC installs are in the @file{ginclude}
304 directory. These headers, @file{iso646.h},
305 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
306 are installed in @file{@var{libsubdir}/include},
307 unless the target Makefile fragment (@pxref{Target Fragment})
308 overrides this by setting @code{USER_H}.
310 In addition to these headers and those generated by fixing system
311 headers to work with GCC, some other headers may also be installed in
312 @file{@var{libsubdir}/include}. @file{config.gcc} may set
313 @code{extra_headers}; this specifies additional headers under
314 @file{config} to be installed on some systems.
316 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
317 This is done to cope with command-line options that change the
318 representation of floating point numbers.
320 GCC also installs its own version of @code{<limits.h>}; this is generated
321 from @file{glimits.h}, together with @file{limitx.h} and
322 @file{limity.h} if the system also has its own version of
323 @code{<limits.h>}. (GCC provides its own header because it is
324 required of ISO C freestanding implementations, but needs to include
325 the system header from its own header as well because other standards
326 such as POSIX specify additional values to be defined in
327 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
328 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
329 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
330 needs fixing, @file{syslimits.h} is the fixed copy.
332 GCC can also install @code{<tgmath.h>}. It will do this when
333 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
336 @subsection Building Documentation
338 The main GCC documentation is in the form of manuals in Texinfo
339 format. These are installed in Info format; DVI versions may be
340 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
341 HTML versions by @samp{make html}. In addition, some man pages are
342 generated from the Texinfo manuals, there are some other text files
343 with miscellaneous documentation, and runtime libraries have their own
344 documentation outside the @file{gcc} directory. FIXME: document the
345 documentation for runtime libraries somewhere.
348 * Texinfo Manuals:: GCC manuals in Texinfo format.
349 * Man Page Generation:: Generating man pages from Texinfo manuals.
350 * Miscellaneous Docs:: Miscellaneous text files with documentation.
353 @node Texinfo Manuals
354 @subsubsection Texinfo Manuals
356 The manuals for GCC as a whole, and the C and C++ front ends, are in
357 files @file{doc/*.texi}. Other front ends have their own manuals in
358 files @file{@var{language}/*.texi}. Common files
359 @file{doc/include/*.texi} are provided which may be included in
360 multiple manuals; the following files are in @file{doc/include}:
364 The GNU Free Documentation License.
366 The section ``Funding Free Software''.
367 @item gcc-common.texi
368 Common definitions for manuals.
370 The GNU General Public License.
372 A copy of @file{texinfo.tex} known to work with the GCC manuals.
375 DVI-formatted manuals are generated by @samp{make dvi}, which uses
376 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
377 PDF-formatted manuals are generated by @samp{make pdf}, which uses
378 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
379 formatted manuals are generated by @samp{make html}. Info
380 manuals are generated by @samp{make info} (which is run as part of
381 a bootstrap); this generates the manuals in the source directory,
382 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
383 and they are included in release distributions.
385 Manuals are also provided on the GCC web site, in both HTML and
386 PostScript forms. This is done via the script
387 @file{maintainer-scripts/update_web_docs_svn}. Each manual to be
388 provided online must be listed in the definition of @code{MANUALS} in
389 that file; a file @file{@var{name}.texi} must only appear once in the
390 source tree, and the output manual must have the same name as the
391 source file. (However, other Texinfo files, included in manuals but
392 not themselves the root files of manuals, may have names that appear
393 more than once in the source tree.) The manual file
394 @file{@var{name}.texi} should only include other files in its own
395 directory or in @file{doc/include}. HTML manuals will be generated by
396 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
397 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
398 All Texinfo files that are parts of manuals must
399 be version-controlled, even if they are generated files, for the
400 generation of online manuals to work.
402 The installation manual, @file{doc/install.texi}, is also provided on
403 the GCC web site. The HTML version is generated by the script
404 @file{doc/install.texi2html}.
406 @node Man Page Generation
407 @subsubsection Man Page Generation
409 Because of user demand, in addition to full Texinfo manuals, man pages
410 are provided which contain extracts from those manuals. These man
411 pages are generated from the Texinfo manuals using
412 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
413 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
414 to @file{gcc.1}, but all the other man pages are generated from
417 Because many systems may not have the necessary tools installed to
418 generate the man pages, they are only generated if the
419 @file{configure} script detects that recent enough tools are
420 installed, and the Makefiles allow generating man pages to fail
421 without aborting the build. Man pages are also included in release
422 distributions. They are generated in the source directory.
424 Magic comments in Texinfo files starting @samp{@@c man} control what
425 parts of a Texinfo file go into a man page. Only a subset of Texinfo
426 is supported by @file{texi2pod.pl}, and it may be necessary to add
427 support for more Texinfo features to this script when generating new
428 man pages. To improve the man page output, some special Texinfo
429 macros are provided in @file{doc/include/gcc-common.texi} which
430 @file{texi2pod.pl} understands:
434 Use in the form @samp{@@table @@gcctabopt} for tables of options,
435 where for printed output the effect of @samp{@@code} is better than
436 that of @samp{@@option} but for man page output a different effect is
439 Use for summary lists of options in manuals.
441 Use at the end of each line inside @samp{@@gccoptlist}. This is
442 necessary to avoid problems with differences in how the
443 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
446 FIXME: describe the @file{texi2pod.pl} input language and magic
447 comments in more detail.
449 @node Miscellaneous Docs
450 @subsubsection Miscellaneous Documentation
452 In addition to the formal documentation that is installed by GCC,
453 there are several other text files in the @file{gcc} subdirectory
454 with miscellaneous documentation:
458 Notes on GCC's Native Language Support. FIXME: this should be part of
459 this manual rather than a separate file.
461 Notes on the Free Translation Project.
464 The GNU General Public License, Versions 2 and 3.
467 The GNU Lesser General Public License, Versions 2.1 and 3.
470 Change log files for various parts of GCC@.
472 Details of a few changes to the GCC front-end interface. FIXME: the
473 information in this file should be part of general documentation of
474 the front-end interface in this manual.
476 Information about new features in old versions of GCC@. (For recent
477 versions, the information is on the GCC web site.)
478 @item README.Portability
479 Information about portability issues when writing code in GCC@. FIXME:
480 why isn't this part of this manual or of the GCC Coding Conventions?
483 FIXME: document such files in subdirectories, at least @file{config},
484 @file{c}, @file{cp}, @file{objc}, @file{testsuite}.
487 @subsection Anatomy of a Language Front End
489 A front end for a language in GCC has the following parts:
493 A directory @file{@var{language}} under @file{gcc} containing source
494 files for that front end. @xref{Front End Directory, , The Front End
495 @file{@var{language}} Directory}, for details.
497 A mention of the language in the list of supported languages in
498 @file{gcc/doc/install.texi}.
500 A mention of the name under which the language's runtime library is
501 recognized by @option{--enable-shared=@var{package}} in the
502 documentation of that option in @file{gcc/doc/install.texi}.
504 A mention of any special prerequisites for building the front end in
505 the documentation of prerequisites in @file{gcc/doc/install.texi}.
507 Details of contributors to that front end in
508 @file{gcc/doc/contrib.texi}. If the details are in that front end's
509 own manual then there should be a link to that manual's list in
512 Information about support for that language in
513 @file{gcc/doc/frontends.texi}.
515 Information about standards for that language, and the front end's
516 support for them, in @file{gcc/doc/standards.texi}. This may be a
517 link to such information in the front end's own manual.
519 Details of source file suffixes for that language and @option{-x
520 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
522 Entries in @code{default_compilers} in @file{gcc.c} for source file
523 suffixes for that language.
525 Preferably testsuites, which may be under @file{gcc/testsuite} or
526 runtime library directories. FIXME: document somewhere how to write
529 Probably a runtime library for the language, outside the @file{gcc}
530 directory. FIXME: document this further.
532 Details of the directories of any runtime libraries in
533 @file{gcc/doc/sourcebuild.texi}.
535 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
536 to check just the compiler or the compiler and runtime library for the
540 If the front end is added to the official GCC source repository, the
541 following are also necessary:
545 At least one Bugzilla component for bugs in that front end and runtime
546 libraries. This category needs to be added to the Bugzilla database.
548 Normally, one or more maintainers of that front end listed in
551 Mentions on the GCC web site in @file{index.html} and
552 @file{frontends.html}, with any relevant links on
553 @file{readings.html}. (Front ends that are not an official part of
554 GCC may also be listed on @file{frontends.html}, with relevant links.)
556 A news item on @file{index.html}, and possibly an announcement on the
557 @email{gcc-announce@@gcc.gnu.org} mailing list.
559 The front end's manuals should be mentioned in
560 @file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals})
561 and the online manuals should be linked to from
562 @file{onlinedocs/index.html}.
564 Any old releases or CVS repositories of the front end, before its
565 inclusion in GCC, should be made available on the GCC FTP site
566 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
568 The release and snapshot script @file{maintainer-scripts/gcc_release}
569 should be updated to generate appropriate tarballs for this front end.
571 If this front end includes its own version files that include the
572 current date, @file{maintainer-scripts/update_version} should be
577 * Front End Directory:: The front end @file{@var{language}} directory.
578 * Front End Config:: The front end @file{config-lang.in} file.
579 * Front End Makefile:: The front end @file{Make-lang.in} file.
582 @node Front End Directory
583 @subsubsection The Front End @file{@var{language}} Directory
585 A front end @file{@var{language}} directory contains the source files
586 of that front end (but not of any runtime libraries, which should be
587 outside the @file{gcc} directory). This includes documentation, and
588 possibly some subsidiary programs built alongside the front end.
589 Certain files are special and other parts of the compiler depend on
594 This file is required in all language subdirectories. @xref{Front End
595 Config, , The Front End @file{config-lang.in} File}, for details of
598 This file is required in all language subdirectories. @xref{Front End
599 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
602 This file registers the set of switches that the front end accepts on
603 the command line, and their @option{--help} text. @xref{Options}.
605 This file provides entries for @code{default_compilers} in
606 @file{gcc.c} which override the default of giving an error that a
607 compiler for that language is not installed.
608 @item @var{language}-tree.def
609 This file, which need not exist, defines any language-specific tree
613 @node Front End Config
614 @subsubsection The Front End @file{config-lang.in} File
616 Each language subdirectory contains a @file{config-lang.in} file.
617 This file is a shell script that may define some variables describing
622 This definition must be present, and gives the name of the language
623 for some purposes such as arguments to @option{--enable-languages}.
625 If defined, this variable lists (space-separated) language front ends
626 other than C that this front end requires to be enabled (with the
627 names given being their @code{language} settings). For example, the
628 Obj-C++ front end depends on the C++ and ObjC front ends, so sets
629 @samp{lang_requires="objc c++"}.
630 @item subdir_requires
631 If defined, this variable lists (space-separated) front end directories
632 other than C that this front end requires to be present. For example,
633 the Objective-C++ front end uses source files from the C++ and
634 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
636 If defined, this variable lists (space-separated) targets in the top
637 level @file{Makefile} to build the runtime libraries for this
638 language, such as @code{target-libobjc}.
640 If defined, this variable lists (space-separated) top level
641 directories (parallel to @file{gcc}), apart from the runtime libraries,
642 that should not be configured if this front end is not built.
643 @item build_by_default
644 If defined to @samp{no}, this language front end is not built unless
645 enabled in a @option{--enable-languages} argument. Otherwise, front
646 ends are built by default, subject to any special logic in
647 @file{configure.ac} (as is present to disable the Ada front end if the
648 Ada compiler is not already installed).
650 If defined to @samp{yes}, this front end is built in stage1 of the
651 bootstrap. This is only relevant to front ends written in their own
654 If defined, a space-separated list of compiler executables that will
655 be run by the driver. The names here will each end
656 with @samp{\$(exeext)}.
658 If defined, a space-separated list of files that should be generated
659 by @file{configure} substituting values in them. This mechanism can
660 be used to create a file @file{@var{language}/Makefile} from
661 @file{@var{language}/Makefile.in}, but this is deprecated, building
662 everything from the single @file{gcc/Makefile} is preferred.
664 If defined, a space-separated list of files that should be scanned by
665 @file{gengtype.c} to generate the garbage collection tables and routines for
666 this language. This excludes the files that are common to all front
667 ends. @xref{Type Information}.
671 @node Front End Makefile
672 @subsubsection The Front End @file{Make-lang.in} File
674 Each language subdirectory contains a @file{Make-lang.in} file. It contains
675 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
676 setting of @code{language} in @file{config-lang.in}) for the following
677 values of @code{@var{hook}}, and any other Makefile rules required to
678 build those targets (which may if necessary use other Makefiles
679 specified in @code{outputs} in @file{config-lang.in}, although this is
680 deprecated). It also adds any testsuite targets that can use the
681 standard rule in @file{gcc/Makefile.in} to the variable
688 FIXME: exactly what goes in each of these targets?
690 Build an @command{etags} @file{TAGS} file in the language subdirectory
693 Build info documentation for the front end, in the build directory.
694 This target is only called by @samp{make bootstrap} if a suitable
695 version of @command{makeinfo} is available, so does not need to check
696 for this, and should fail if an error occurs.
698 Build DVI documentation for the front end, in the build directory.
699 This should be done using @code{$(TEXI2DVI)}, with appropriate
700 @option{-I} arguments pointing to directories of included files.
702 Build PDF documentation for the front end, in the build directory.
703 This should be done using @code{$(TEXI2PDF)}, with appropriate
704 @option{-I} arguments pointing to directories of included files.
706 Build HTML documentation for the front end, in the build directory.
708 Build generated man pages for the front end from Texinfo manuals
709 (@pxref{Man Page Generation}), in the build directory. This target
710 is only called if the necessary tools are available, but should ignore
711 errors so as not to stop the build if errors occur; man pages are
712 optional and the tools involved may be installed in a broken way.
714 Install everything that is part of the front end, apart from the
715 compiler executables listed in @code{compilers} in
716 @file{config-lang.in}.
718 Install info documentation for the front end, if it is present in the
719 source directory. This target should have dependencies on info files
720 that should be installed.
722 Install man pages for the front end. This target should ignore
725 Install headers needed for plugins.
727 Copies its dependencies into the source directory. This generally should
728 be used for generated files such as Bison output files which are not
729 version-controlled, but should be included in any release tarballs. This
730 target will be executed during a bootstrap if
731 @samp{--enable-generated-files-in-srcdir} was specified as a
732 @file{configure} option.
735 Copies its dependencies into the source directory. These targets will be
736 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
737 was specified as a @file{configure} option.
739 Uninstall files installed by installing the compiler. This is
740 currently documented not to be supported, so the hook need not do
745 @itemx maintainer-clean
746 The language parts of the standard GNU
747 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
748 Users, standards, GNU Coding Standards}, for details of the standard
749 targets. For GCC, @code{maintainer-clean} should delete
750 all generated files in the source directory that are not version-controlled,
751 but should not delete anything that is.
754 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
755 to a list of host object files that are used by that language.
758 @subsection Anatomy of a Target Back End
760 A back end for a target architecture in GCC has the following parts:
764 A directory @file{@var{machine}} under @file{gcc/config}, containing a
765 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
766 , Machine Descriptions}), header files @file{@var{machine}.h} and
767 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
768 (@pxref{Target Macros, , Target Description Macros and Functions}),
769 possibly a target Makefile fragment @file{t-@var{machine}}
770 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
771 some other files. The names of these files may be changed from the
772 defaults given by explicit specifications in @file{config.gcc}.
774 If necessary, a file @file{@var{machine}-modes.def} in the
775 @file{@var{machine}} directory, containing additional machine modes to
776 represent condition codes. @xref{Condition Code}, for further details.
778 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
779 directory, containing a list of target-specific options. You can also
780 add other option files using the @code{extra_options} variable in
781 @file{config.gcc}. @xref{Options}.
783 Entries in @file{config.gcc} (@pxref{System Config, , The
784 @file{config.gcc} File}) for the systems with this target
787 Documentation in @file{gcc/doc/invoke.texi} for any command-line
788 options supported by this target (@pxref{Run-time Target, , Run-time
789 Target Specification}). This means both entries in the summary table
790 of options and details of the individual options.
792 Documentation in @file{gcc/doc/extend.texi} for any target-specific
793 attributes supported (@pxref{Target Attributes, , Defining
794 target-specific uses of @code{__attribute__}}), including where the
795 same attribute is already supported on some targets, which are
796 enumerated in the manual.
798 Documentation in @file{gcc/doc/extend.texi} for any target-specific
801 Documentation in @file{gcc/doc/extend.texi} of any target-specific
802 built-in functions supported.
804 Documentation in @file{gcc/doc/extend.texi} of any target-specific
805 format checking styles supported.
807 Documentation in @file{gcc/doc/md.texi} of any target-specific
808 constraint letters (@pxref{Machine Constraints, , Constraints for
809 Particular Machines}).
811 A note in @file{gcc/doc/contrib.texi} under the person or people who
812 contributed the target support.
814 Entries in @file{gcc/doc/install.texi} for all target triplets
815 supported with this target architecture, giving details of any special
816 notes about installation for this target, or saying that there are no
817 special notes if there are none.
819 Possibly other support outside the @file{gcc} directory for runtime
820 libraries. FIXME: reference docs for this. The @code{libstdc++} porting
821 manual needs to be installed as info for this to work, or to be a
822 chapter of this manual.
825 If the back end is added to the official GCC source repository, the
826 following are also necessary:
830 An entry for the target architecture in @file{readings.html} on the
831 GCC web site, with any relevant links.
833 Details of the properties of the back end and target architecture in
834 @file{backends.html} on the GCC web site.
836 A news item about the contribution of support for that target
837 architecture, in @file{index.html} on the GCC web site.
839 Normally, one or more maintainers of that target listed in
840 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
841 but it would be unusual to add support for a target that does not have
842 a maintainer when support is added.
844 Target triplets covering all @file{config.gcc} stanzas for the target,
845 in the list in @file{contrib/config-list.mk}.
851 GCC contains several testsuites to help maintain compiler quality.
852 Most of the runtime libraries and language front ends in GCC have
853 testsuites. Currently only the C language testsuites are documented
854 here; FIXME: document the others.
857 * Test Idioms:: Idioms used in testsuite code.
858 * Test Directives:: Directives used within DejaGnu tests.
859 * Ada Tests:: The Ada language testsuites.
860 * C Tests:: The C language testsuites.
861 * LTO Testing:: Support for testing link-time optimizations.
862 * gcov Testing:: Support for testing gcov.
863 * profopt Testing:: Support for testing profile-directed optimizations.
864 * compat Testing:: Support for testing binary compatibility.
865 * Torture Tests:: Support for torture testing using multiple options.
866 * GIMPLE Tests:: Support for testing GIMPLE passes.
867 * RTL Tests:: Support for testing RTL passes.
871 @section Idioms Used in Testsuite Code
873 In general, C testcases have a trailing @file{-@var{n}.c}, starting
874 with @file{-1.c}, in case other testcases with similar names are added
875 later. If the test is a test of some well-defined feature, it should
876 have a name referring to that feature such as
877 @file{@var{feature}-1.c}. If it does not test a well-defined feature
878 but just happens to exercise a bug somewhere in the compiler, and a
879 bug report has been filed for this bug in the GCC bug database,
880 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
881 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
882 and previously more generally, test cases are named after the date on
883 which they were added. This allows people to tell at a glance whether
884 a test failure is because of a recently found bug that has not yet
885 been fixed, or whether it may be a regression, but does not give any
886 other information about the bug or where discussion of it may be
887 found. Some other language testsuites follow similar conventions.
889 In the @file{gcc.dg} testsuite, it is often necessary to test that an
890 error is indeed a hard error and not just a warning---for example,
891 where it is a constraint violation in the C standard, which must
892 become an error with @option{-pedantic-errors}. The following idiom,
893 where the first line shown is line @var{line} of the file and the line
894 that generates the error, is used for this:
897 /* @{ dg-bogus "warning" "warning in place of error" @} */
898 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
901 It may be necessary to check that an expression is an integer constant
902 expression and has a certain value. To check that @code{@var{E}} has
903 value @code{@var{V}}, an idiom similar to the following is used:
906 char x[((E) == (V) ? 1 : -1)];
909 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
910 assertions about the types of expressions. See, for example,
911 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
912 exact rules for the types of conditional expressions in the C
913 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
915 It is useful to be able to test that optimizations are being made
916 properly. This cannot be done in all cases, but it can be done where
917 the optimization will lead to code being optimized away (for example,
918 where flow analysis or alias analysis should show that certain code
919 cannot be called) or to functions not being called because they have
920 been expanded as built-in functions. Such tests go in
921 @file{gcc.c-torture/execute}. Where code should be optimized away, a
922 call to a nonexistent function such as @code{link_failure ()} may be
923 inserted; a definition
936 will also be needed so that linking still succeeds when the test is
937 run without optimization. When all calls to a built-in function
938 should have been optimized and no calls to the non-built-in version of
939 the function should remain, that function may be defined as
940 @code{static} to call @code{abort ()} (although redeclaring a function
941 as static may not work on all targets).
943 All testcases must be portable. Target-specific testcases must have
944 appropriate code to avoid causing failures on unsupported systems;
945 unfortunately, the mechanisms for this differ by directory.
947 FIXME: discuss non-C testsuites here.
949 @node Test Directives
950 @section Directives used within DejaGnu tests
953 * Directives:: Syntax and descriptions of test directives.
954 * Selectors:: Selecting targets to which a test applies.
955 * Effective-Target Keywords:: Keywords describing target attributes.
956 * Add Options:: Features for @code{dg-add-options}
957 * Require Support:: Variants of @code{dg-require-@var{support}}
958 * Final Actions:: Commands for use in @code{dg-final}
962 @subsection Syntax and Descriptions of test directives
964 Test directives appear within comments in a test source file and begin
965 with @code{dg-}. Some of these are defined within DejaGnu and others
966 are local to the GCC testsuite.
968 The order in which test directives appear in a test can be important:
969 directives local to GCC sometimes override information used by the
970 DejaGnu directives, which know nothing about the GCC directives, so the
971 DejaGnu directives must precede GCC directives.
973 Several test directives include selectors (@pxref{Selectors, , })
974 which are usually preceded by the keyword @code{target} or @code{xfail}.
976 @subsubsection Specify how to build the test
979 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
980 @var{do-what-keyword} specifies how the test is compiled and whether
981 it is executed. It is one of:
985 Compile with @option{-E} to run only the preprocessor.
987 Compile with @option{-S} to produce an assembly code file.
989 Compile with @option{-c} to produce a relocatable object file.
991 Compile, assemble, and link to produce an executable file.
993 Produce and run an executable file, which is expected to return
997 The default is @code{compile}. That can be overridden for a set of
998 tests by redefining @code{dg-do-what-default} within the @code{.exp}
999 file for those tests.
1001 If the directive includes the optional @samp{@{ target @var{selector} @}}
1002 then the test is skipped unless the target system matches the
1005 If @var{do-what-keyword} is @code{run} and the directive includes
1006 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1007 then the test is expected to fail. The @code{xfail} clause is ignored
1008 for other values of @var{do-what-keyword}; those tests can use
1009 directive @code{dg-xfail-if}.
1012 @subsubsection Specify additional compiler options
1015 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1016 This DejaGnu directive provides a list of compiler options, to be used
1017 if the target system matches @var{selector}, that replace the default
1018 options used for this set of tests.
1020 @item @{ dg-add-options @var{feature} @dots{} @}
1021 Add any compiler options that are needed to access certain features.
1022 This directive does nothing on targets that enable the features by
1023 default, or that don't provide them at all. It must come after
1024 all @code{dg-options} directives.
1025 For supported values of @var{feature} see @ref{Add Options, ,}.
1027 @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
1028 This directive provides a list of compiler options, to be used
1029 if the target system matches @var{selector}, that are added to the default
1030 options used for this set of tests.
1033 @subsubsection Modify the test timeout value
1035 The normal timeout limit, in seconds, is found by searching the
1039 @item the value defined by an earlier @code{dg-timeout} directive in
1042 @item variable @var{tool_timeout} defined by the set of tests
1044 @item @var{gcc},@var{timeout} set in the target board
1050 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1051 Set the time limit for the compilation and for the execution of the test
1052 to the specified number of seconds.
1054 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1055 Multiply the normal time limit for compilation and execution of the test
1056 by the specified floating-point factor.
1059 @subsubsection Skip a test for some targets
1062 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1063 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1064 each element is a string of zero or more GCC options.
1065 Skip the test if all of the following conditions are met:
1067 @item the test system is included in @var{selector}
1069 @item for at least one of the option strings in @var{include-opts},
1070 every option from that string is in the set of options with which
1071 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1072 that matches any options; that is the default if @var{include-opts} is
1075 @item for each of the option strings in @var{exclude-opts}, at least one
1076 option from that string is not in the set of options with which the test
1077 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1078 that is the default if @var{exclude-opts} is not specified
1081 For example, to skip a test if option @code{-Os} is present:
1084 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
1087 To skip a test if both options @code{-O2} and @code{-g} are present:
1090 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
1093 To skip a test if either @code{-O2} or @code{-O3} is present:
1096 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
1099 To skip a test unless option @code{-Os} is present:
1102 /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
1105 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1106 but not if @code{-fpic} is also present:
1109 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1112 @item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @}
1113 Skip the test if the test target, including current multilib flags,
1114 is not covered by the effective-target keyword.
1115 If the directive includes the optional @samp{@{ @var{selector} @}}
1116 then the effective-target test is only performed if the target system
1117 matches the @var{selector}.
1118 This directive must appear after any @code{dg-do} directive in the test
1119 and before any @code{dg-additional-sources} directive.
1120 @xref{Effective-Target Keywords, , }.
1122 @item @{ dg-require-@var{support} args @}
1123 Skip the test if the target does not provide the required support.
1124 These directives must appear after any @code{dg-do} directive in the test
1125 and before any @code{dg-additional-sources} directive.
1126 They require at least one argument, which can be an empty string if the
1127 specific procedure does not examine the argument.
1128 @xref{Require Support, , }, for a complete list of these directives.
1131 @subsubsection Expect a test to fail for some targets
1134 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1135 Expect the test to fail if the conditions (which are the same as for
1136 @code{dg-skip-if}) are met. This does not affect the execute step.
1138 @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1139 Expect the execute step of a test to fail if the conditions (which are
1140 the same as for @code{dg-skip-if}) are met.
1143 @subsubsection Expect the test executable to fail
1146 @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1147 Expect the test executable to return a nonzero exit status if the
1148 conditions (which are the same as for @code{dg-skip-if}) are met.
1151 @subsubsection Verify compiler messages
1154 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1155 This DejaGnu directive appears on a source line that is expected to get
1156 an error message, or else specifies the source line associated with the
1157 message. If there is no message for that line or if the text of that
1158 message is not matched by @var{regexp} then the check fails and
1159 @var{comment} is included in the @code{FAIL} message. The check does
1160 not look for the string @samp{error} unless it is part of @var{regexp}.
1162 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1163 This DejaGnu directive appears on a source line that is expected to get
1164 a warning message, or else specifies the source line associated with the
1165 message. If there is no message for that line or if the text of that
1166 message is not matched by @var{regexp} then the check fails and
1167 @var{comment} is included in the @code{FAIL} message. The check does
1168 not look for the string @samp{warning} unless it is part of @var{regexp}.
1170 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1171 The line is expected to get a message other than an error or warning.
1172 If there is no message for that line or if the text of that message is
1173 not matched by @var{regexp} then the check fails and @var{comment} is
1174 included in the @code{FAIL} message.
1176 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @}
1177 This DejaGnu directive appears on a source line that should not get a
1178 message matching @var{regexp}, or else specifies the source line
1179 associated with the bogus message. It is usually used with @samp{xfail}
1180 to indicate that the message is a known problem for a particular set of
1183 @item @{ dg-line @var{linenumvar} @}
1184 This DejaGnu directive sets the variable @var{linenumvar} to the line number of
1185 the source line. The variable @var{linenumvar} can then be used in subsequent
1186 @code{dg-error}, @code{dg-warning}, @code{dg-message} and @code{dg-bogus}
1187 directives. For example:
1190 int a; /* @{ dg-line first_def_a @} */
1191 float a; /* @{ dg-error "conflicting types of" @} */
1192 /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */
1195 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1196 This DejaGnu directive indicates that the test is expected to fail due
1197 to compiler messages that are not handled by @samp{dg-error},
1198 @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail}
1199 has the same effect as @samp{target}.
1201 @item @{ dg-prune-output @var{regexp} @}
1202 Prune messages matching @var{regexp} from the test output.
1205 @subsubsection Verify output of the test executable
1208 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1209 This DejaGnu directive compares @var{regexp} to the combined output
1210 that the test executable writes to @file{stdout} and @file{stderr}.
1213 @subsubsection Specify additional files for a test
1216 @item @{ dg-additional-files "@var{filelist}" @}
1217 Specify additional files, other than source files, that must be copied
1218 to the system where the compiler runs.
1220 @item @{ dg-additional-sources "@var{filelist}" @}
1221 Specify additional source files to appear in the compile line
1222 following the main test file.
1225 @subsubsection Add checks at the end of a test
1228 @item @{ dg-final @{ @var{local-directive} @} @}
1229 This DejaGnu directive is placed within a comment anywhere in the
1230 source file and is processed after the test has been compiled and run.
1231 Multiple @samp{dg-final} commands are processed in the order in which
1232 they appear in the source file. @xref{Final Actions, , }, for a list
1233 of directives that can be used within @code{dg-final}.
1237 @subsection Selecting targets to which a test applies
1239 Several test directives include @var{selector}s to limit the targets
1240 for which a test is run or to declare that a test is expected to fail
1241 on particular targets.
1245 @item one or more target triplets, possibly including wildcard characters;
1246 use @samp{*-*-*} to match any target
1247 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1248 @item a logical expression
1251 Depending on the context, the selector specifies whether a test is
1252 skipped and reported as unsupported or is expected to fail. A context
1253 that allows either @samp{target} or @samp{xfail} also allows
1254 @samp{@{ target @var{selector1} xfail @var{selector2} @}}
1255 to skip the test for targets that don't match @var{selector1} and the
1256 test to fail for targets that match @var{selector2}.
1258 A selector expression appears within curly braces and uses a single
1259 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
1260 operand is another selector expression, an effective-target keyword,
1261 a single target triplet, or a list of target triplets within quotes or
1262 curly braces. For example:
1265 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1266 @{ target @{ powerpc*-*-* && lp64 @} @}
1267 @{ xfail @{ lp64 || vect_no_align @} @}
1270 @node Effective-Target Keywords
1271 @subsection Keywords describing target attributes
1273 Effective-target keywords identify sets of targets that support
1274 particular functionality. They are used to limit tests to be run only
1275 for particular targets, or to specify that particular sets of targets
1276 are expected to fail some tests.
1278 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1279 the GCC testsuite, with the exception of those that are documented as
1280 being local to a particular test directory.
1282 The @samp{effective target} takes into account all of the compiler options
1283 with which the test will be compiled, including the multilib options.
1284 By convention, keywords ending in @code{_nocache} can also include options
1285 specified for the particular test in an earlier @code{dg-options} or
1286 @code{dg-add-options} directive.
1288 @subsubsection Data type sizes
1292 Target has 32-bit @code{int}, @code{long}, and pointers.
1295 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1298 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1302 Target has 64-bit @code{double}.
1305 Target has @code{double} that is 64 bits or longer.
1308 Target has 128-bit @code{long double}.
1311 Target has @code{int} that is at 32 bits or longer.
1314 Target has @code{int} that is 16 bits or shorter.
1317 Target has @code{int} and @code{long} with different sizes.
1320 Target supports @code{double} that is longer than @code{float}.
1322 @item large_long_double
1323 Target supports @code{long double} that is longer than @code{double}.
1326 Target has pointers that are 32 bits or longer.
1329 Target supports array and structure sizes that are 32 bits or longer.
1332 Target has @code{wchar_t} that is at least 4 bytes.
1335 Target has the @code{_Float@var{n}} type.
1338 Target has the @code{_Float@var{n}x} type.
1340 @item float@var{n}_runtime
1341 Target has the @code{_Float@var{n}} type, including runtime support
1342 for any options added with @code{dg-add-options}.
1344 @item float@var{n}x_runtime
1345 Target has the @code{_Float@var{n}x} type, including runtime support
1346 for any options added with @code{dg-add-options}.
1348 @item floatn_nx_runtime
1349 Target has runtime support for any options added with
1350 @code{dg-add-options} for any @code{_Float@var{n}} or
1351 @code{_Float@var{n}x} type.
1354 @subsubsection Fortran-specific attributes
1357 @item fortran_integer_16
1358 Target supports Fortran @code{integer} that is 16 bytes or longer.
1360 @item fortran_real_10
1361 Target supports Fortran @code{real} that is 10 bytes or longer.
1363 @item fortran_real_16
1364 Target supports Fortran @code{real} that is 16 bytes or longer.
1366 @item fortran_large_int
1367 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1369 @item fortran_large_real
1370 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1373 @subsubsection Vector-specific attributes
1376 @item vect_condition
1377 Target supports vector conditional operations.
1379 @item vect_cond_mixed
1380 Target supports vector conditional operations where comparison operands
1381 have different type from the value operands.
1384 Target supports hardware vectors of @code{double}.
1386 @item vect_element_align_preferred
1387 The target's preferred vector alignment is the same as the element
1391 Target supports hardware vectors of @code{float}.
1394 Target supports hardware vectors of @code{int}.
1397 Target supports hardware vectors of @code{long}.
1399 @item vect_long_long
1400 Target supports hardware vectors of @code{long long}.
1402 @item vect_aligned_arrays
1403 Target aligns arrays to vector alignment boundary.
1405 @item vect_hw_misalign
1406 Target supports a vector misalign access.
1409 Target does not support a vector alignment mechanism.
1411 @item vect_peeling_profitable
1412 Target might require to peel loops for alignment purposes.
1414 @item vect_no_int_min_max
1415 Target does not support a vector min and max instruction on @code{int}.
1417 @item vect_no_int_add
1418 Target does not support a vector add instruction on @code{int}.
1420 @item vect_no_bitwise
1421 Target does not support vector bitwise instructions.
1423 @item vect_char_mult
1424 Target supports @code{vector char} multiplication.
1426 @item vect_short_mult
1427 Target supports @code{vector short} multiplication.
1430 Target supports @code{vector int} multiplication.
1432 @item vect_long_mult
1433 Target supports 64 bit @code{vector long} multiplication.
1435 @item vect_extract_even_odd
1436 Target supports vector even/odd element extraction.
1438 @item vect_extract_even_odd_wide
1439 Target supports vector even/odd element extraction of vectors with elements
1440 @code{SImode} or larger.
1442 @item vect_interleave
1443 Target supports vector interleaving.
1446 Target supports vector interleaving and extract even/odd.
1448 @item vect_strided_wide
1449 Target supports vector interleaving and extract even/odd for wide
1453 Target supports vector permutation.
1455 @item vect_perm_byte
1456 Target supports permutation of vectors with 8-bit elements.
1458 @item vect_perm_short
1459 Target supports permutation of vectors with 16-bit elements.
1461 @item vect_perm3_byte
1462 Target supports permutation of vectors with 8-bit elements, and for the
1463 default vector length it is possible to permute:
1465 @{ a0, a1, a2, b0, b1, b2, @dots{} @}
1469 @{ a0, a0, a0, b0, b0, b0, @dots{} @}
1470 @{ a1, a1, a1, b1, b1, b1, @dots{} @}
1471 @{ a2, a2, a2, b2, b2, b2, @dots{} @}
1473 using only two-vector permutes, regardless of how long the sequence is.
1475 @item vect_perm3_int
1476 Like @code{vect_perm3_byte}, but for 32-bit elements.
1478 @item vect_perm3_short
1479 Like @code{vect_perm3_byte}, but for 16-bit elements.
1482 Target supports a hardware vector shift operation.
1484 @item vect_unaligned_possible
1485 Target prefers vectors to have an alignment greater than element
1486 alignment, but also allows unaligned vector accesses in some
1489 @item vect_widen_sum_hi_to_si
1490 Target supports a vector widening summation of @code{short} operands
1491 into @code{int} results, or can promote (unpack) from @code{short}
1494 @item vect_widen_sum_qi_to_hi
1495 Target supports a vector widening summation of @code{char} operands
1496 into @code{short} results, or can promote (unpack) from @code{char}
1499 @item vect_widen_sum_qi_to_si
1500 Target supports a vector widening summation of @code{char} operands
1501 into @code{int} results.
1503 @item vect_widen_mult_qi_to_hi
1504 Target supports a vector widening multiplication of @code{char} operands
1505 into @code{short} results, or can promote (unpack) from @code{char} to
1506 @code{short} and perform non-widening multiplication of @code{short}.
1508 @item vect_widen_mult_hi_to_si
1509 Target supports a vector widening multiplication of @code{short} operands
1510 into @code{int} results, or can promote (unpack) from @code{short} to
1511 @code{int} and perform non-widening multiplication of @code{int}.
1513 @item vect_widen_mult_si_to_di_pattern
1514 Target supports a vector widening multiplication of @code{int} operands
1515 into @code{long} results.
1518 Target supports a vector dot-product of @code{signed char}.
1521 Target supports a vector dot-product of @code{unsigned char}.
1524 Target supports a vector dot-product of @code{signed short}.
1527 Target supports a vector dot-product of @code{unsigned short}.
1529 @item vect_pack_trunc
1530 Target supports a vector demotion (packing) of @code{short} to @code{char}
1531 and from @code{int} to @code{short} using modulo arithmetic.
1534 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1535 and from @code{char} to @code{int}.
1537 @item vect_intfloat_cvt
1538 Target supports conversion from @code{signed int} to @code{float}.
1540 @item vect_uintfloat_cvt
1541 Target supports conversion from @code{unsigned int} to @code{float}.
1543 @item vect_floatint_cvt
1544 Target supports conversion from @code{float} to @code{signed int}.
1546 @item vect_floatuint_cvt
1547 Target supports conversion from @code{float} to @code{unsigned int}.
1549 @item vect_intdouble_cvt
1550 Target supports conversion from @code{signed int} to @code{double}.
1552 @item vect_doubleint_cvt
1553 Target supports conversion from @code{double} to @code{signed int}.
1555 @item vect_max_reduc
1556 Target supports max reduction for vectors.
1558 @item vect_sizes_16B_8B
1559 Target supports 16- and 8-bytes vectors.
1561 @item vect_sizes_32B_16B
1562 Target supports 32- and 16-bytes vectors.
1565 @subsubsection Thread Local Storage attributes
1569 Target supports thread-local storage.
1572 Target supports native (rather than emulated) thread-local storage.
1575 Test system supports executing TLS executables.
1578 @subsubsection Decimal floating point attributes
1582 Targets supports compiling decimal floating point extension to C.
1585 Including the options used to compile this particular test, the
1586 target supports compiling decimal floating point extension to C.
1589 Test system can execute decimal floating point tests.
1592 Including the options used to compile this particular test, the
1593 test system can execute decimal floating point tests.
1596 Target generates decimal floating point instructions with current options.
1599 @subsubsection ARM-specific attributes
1603 ARM target generates 32-bit code.
1606 ARM target adheres to the ABI for the ARM Architecture.
1610 ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or
1611 equivalent options. Some multilibs may be incompatible with these
1615 ARM target adheres to the VFP and Advanced SIMD Register Arguments
1616 variant of the ABI for the ARM Architecture (as selected with
1617 @code{-mfloat-abi=hard}).
1619 @item arm_hard_vfp_ok
1620 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
1621 Some multilibs may be incompatible with these options.
1624 ARM target supports @code{-mcpu=iwmmxt}.
1625 Some multilibs may be incompatible with this option.
1628 ARM target supports generating NEON instructions.
1630 @item arm_tune_string_ops_prefer_neon
1631 Test CPU tune supports inlining string operations with NEON instructions.
1634 Test system supports executing NEON instructions.
1637 Test system supports executing NEON v2 instructions.
1640 @anchor{arm_neon_ok}
1641 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
1642 options. Some multilibs may be incompatible with these options.
1644 @item arm_neon_ok_no_float_abi
1645 @anchor{arm_neon_ok_no_float_abi}
1646 ARM Target supports NEON with @code{-mfpu=neon}, but without any
1647 -mfloat-abi= option. Some multilibs may be incompatible with this
1651 @anchor{arm_neonv2_ok}
1652 ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible
1653 options. Some multilibs may be incompatible with these options.
1656 @anchor{arm_fp16_ok}
1657 Target supports options to generate VFP half-precision floating-point
1658 instructions. Some multilibs may be incompatible with these
1659 options. This test is valid for ARM only.
1662 Target supports executing VFP half-precision floating-point
1663 instructions. This test is valid for ARM only.
1665 @item arm_neon_fp16_ok
1666 @anchor{arm_neon_fp16_ok}
1667 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
1668 options, including @code{-mfp16-format=ieee} if necessary to obtain the
1669 @code{__fp16} type. Some multilibs may be incompatible with these options.
1671 @item arm_neon_fp16_hw
1672 Test system supports executing Neon half-precision float instructions.
1675 @item arm_fp16_alternative_ok
1676 ARM target supports the ARM FP16 alternative format. Some multilibs
1677 may be incompatible with the options needed.
1679 @item arm_fp16_none_ok
1680 ARM target supports specifying none as the ARM FP16 format.
1683 ARM target generates Thumb-1 code for @code{-mthumb}.
1686 ARM target generates Thumb-2 code for @code{-mthumb}.
1689 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
1690 Some multilibs may be incompatible with these options.
1693 @anchor{arm_vfp3_ok}
1694 ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}.
1695 Some multilibs may be incompatible with these options.
1698 ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}.
1699 Some multilibs may be incompatible with these options.
1701 @item arm_v8_neon_ok
1702 ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}.
1703 Some multilibs may be incompatible with these options.
1705 @item arm_v8_1a_neon_ok
1706 @anchor{arm_v8_1a_neon_ok}
1707 ARM target supports options to generate ARMv8.1 Adv.SIMD instructions.
1708 Some multilibs may be incompatible with these options.
1710 @item arm_v8_1a_neon_hw
1711 ARM target supports executing ARMv8.1 Adv.SIMD instructions. Some
1712 multilibs may be incompatible with the options needed. Implies
1716 ARM target supports acquire-release instructions.
1718 @item arm_v8_2a_fp16_scalar_ok
1719 @anchor{arm_v8_2a_fp16_scalar_ok}
1720 ARM target supports options to generate instructions for ARMv8.2 and
1721 scalar instructions from the FP16 extension. Some multilibs may be
1722 incompatible with these options.
1724 @item arm_v8_2a_fp16_scalar_hw
1725 ARM target supports executing instructions for ARMv8.2 and scalar
1726 instructions from the FP16 extension. Some multilibs may be
1727 incompatible with these options. Implies arm_v8_2a_fp16_neon_ok.
1729 @item arm_v8_2a_fp16_neon_ok
1730 @anchor{arm_v8_2a_fp16_neon_ok}
1731 ARM target supports options to generate instructions from ARMv8.2 with
1732 the FP16 extension. Some multilibs may be incompatible with these
1733 options. Implies arm_v8_2a_fp16_scalar_ok.
1735 @item arm_v8_2a_fp16_neon_hw
1736 ARM target supports executing instructions from ARMv8.2 with the FP16
1737 extension. Some multilibs may be incompatible with these options.
1738 Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw.
1740 @item arm_v8_2a_dotprod_neon_ok
1741 @anchor{arm_v8_2a_dotprod_neon_ok}
1742 ARM target supports options to generate instructions from ARMv8.2 with
1743 the Dot Product extension. Some multilibs may be incompatible with these
1746 @item arm_v8_2a_dotprod_neon_hw
1747 ARM target supports executing instructions from ARMv8.2 with the Dot
1748 Product extension. Some multilibs may be incompatible with these options.
1749 Implies arm_v8_2a_dotprod_neon_ok.
1751 @item arm_prefer_ldrd_strd
1752 ARM target prefers @code{LDRD} and @code{STRD} instructions over
1753 @code{LDM} and @code{STM} instructions.
1755 @item arm_thumb1_movt_ok
1756 ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW}
1757 and @code{MOVT} instructions available.
1759 @item arm_thumb1_cbz_ok
1760 ARM target generates Thumb-1 code for @code{-mthumb} with
1761 @code{CBZ} and @code{CBNZ} instructions available.
1763 @item arm_divmod_simode
1764 ARM target for which divmod transform is disabled, if it supports hardware
1768 ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse}
1771 @item arm_coproc1_ok
1772 @anchor{arm_coproc1_ok}
1773 ARM target supports the following coprocessor instructions: @code{CDP},
1774 @code{LDC}, @code{STC}, @code{MCR} and @code{MRC}.
1776 @item arm_coproc2_ok
1777 @anchor{arm_coproc2_ok}
1778 ARM target supports all the coprocessor instructions also listed as supported
1779 in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2},
1780 @code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}.
1782 @item arm_coproc3_ok
1783 @anchor{arm_coproc3_ok}
1784 ARM target supports all the coprocessor instructions also listed as supported
1785 in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}.
1787 @item arm_coproc4_ok
1788 ARM target supports all the coprocessor instructions also listed as supported
1789 in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}.
1792 @subsubsection AArch64-specific attributes
1795 @item aarch64_asm_<ext>_ok
1796 AArch64 assembler supports the architecture extension @code{ext} via the
1797 @code{.arch_extension} pseudo-op.
1799 AArch64 target which generates instruction sequences for tiny memory model.
1801 AArch64 target which generates instruction sequences for small memory model.
1803 AArch64 target which generates instruction sequences for large memory model.
1804 @item aarch64_little_endian
1805 AArch64 target which generates instruction sequences for little endian.
1806 @item aarch64_big_endian
1807 AArch64 target which generates instruction sequences for big endian.
1808 @item aarch64_small_fpic
1809 Binutils installed on test system supports relocation types required by -fpic
1810 for AArch64 small memory model.
1814 @subsubsection MIPS-specific attributes
1818 MIPS target supports 64-bit instructions.
1821 MIPS target does not produce MIPS16 code.
1823 @item mips16_attribute
1824 MIPS target can generate MIPS16 code.
1827 MIPS target is a Loongson-2E or -2F target using an ABI that supports
1828 the Loongson vector modes.
1831 MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA).
1833 @item mips_newabi_large_long_double
1834 MIPS target supports @code{long double} larger than @code{double}
1835 when using the new ABI.
1837 @item mpaired_single
1838 MIPS target supports @code{-mpaired-single}.
1841 @subsubsection PowerPC-specific attributes
1846 PowerPC target supports executing hardware DFP instructions.
1849 PowerPC target supports executing VSX instructions (ISA 2.07).
1852 Test system supports executing 64-bit instructions.
1854 @item powerpc_altivec
1855 PowerPC target supports AltiVec.
1857 @item powerpc_altivec_ok
1858 PowerPC target supports @code{-maltivec}.
1860 @item powerpc_eabi_ok
1861 PowerPC target supports @code{-meabi}.
1864 PowerPC target supports @code{-mabi=elfv2}.
1867 PowerPC target supports floating-point registers.
1869 @item powerpc_hard_double
1870 PowerPC target supports hardware double-precision floating-point.
1872 @item powerpc_htm_ok
1873 PowerPC target supports @code{-mhtm}
1875 @item powerpc_p8vector_ok
1876 PowerPC target supports @code{-mpower8-vector}
1878 @item powerpc_popcntb_ok
1879 PowerPC target supports the @code{popcntb} instruction, indicating
1880 that this target supports @code{-mcpu=power5}.
1882 @item powerpc_ppu_ok
1883 PowerPC target supports @code{-mcpu=cell}.
1886 PowerPC target supports PowerPC SPE.
1888 @item powerpc_spe_nocache
1889 Including the options used to compile this particular test, the
1890 PowerPC target supports PowerPC SPE.
1893 PowerPC target supports PowerPC SPU.
1895 @item powerpc_vsx_ok
1896 PowerPC target supports @code{-mvsx}.
1898 @item powerpc_405_nocache
1899 Including the options used to compile this particular test, the
1900 PowerPC target supports PowerPC 405.
1903 PowerPC target supports executing reciprocal estimate instructions.
1905 @item spu_auto_overlay
1906 SPU target has toolchain that supports automatic overlay generation.
1909 PowerPC target supports executing AltiVec instructions.
1912 PowerPC target supports executing VSX instructions (ISA 2.06).
1915 @subsubsection Other hardware attributes
1917 @c Please keep this table sorted alphabetically.
1920 Target supports autoincrement/decrement addressing.
1923 Target supports compiling @code{avx} instructions.
1926 Target supports the execution of @code{avx} instructions.
1929 Target supports compiling @code{avx2} instructions.
1932 Target supports the execution of @code{avx2} instructions.
1935 Target supports compiling @code{avx512f} instructions.
1937 @item avx512f_runtime
1938 Target supports the execution of @code{avx512f} instructions.
1941 Test system can execute AltiVec and Cell PPU instructions.
1944 Target uses a ColdFire FPU.
1947 Target supporting hardware divmod insn or divmod libcall.
1950 Target supporting hardware divmod insn or divmod libcall for SImode.
1953 Target supports FPU instructions.
1955 @item non_strict_align
1956 Target does not require strict alignment.
1959 The x86-64 target linker supports PIE with copy reloc.
1962 Target supports x86 @code{rdrand} instruction.
1965 Target has a square root instruction that the compiler can generate.
1968 Target supports compiling @code{sse} instructions.
1971 Target supports the execution of @code{sse} instructions.
1974 Target supports compiling @code{sse2} instructions.
1977 Target supports the execution of @code{sse2} instructions.
1979 @item sync_char_short
1980 Target supports atomic operations on @code{char} and @code{short}.
1983 Target supports atomic operations on @code{int} and @code{long}.
1986 Test environment appears to run executables on a simulator that
1987 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
1988 or @code{EM_SPARCV9} executables.
1990 @item vect_cmdline_needed
1991 Target requires a command line argument to enable a SIMD instruction set.
1994 Target supports the xorsign optab expansion.
1998 @subsubsection Environment attributes
2002 The language for the compiler under test is C.
2005 The language for the compiler under test is C++.
2008 Target provides a full C99 runtime.
2010 @item correct_iso_cpp_string_wchar_protos
2011 Target @code{string.h} and @code{wchar.h} headers provide C++ required
2012 overloads for @code{strchr} etc. functions.
2014 @item dummy_wcsftime
2015 Target uses a dummy @code{wcsftime} function that always returns zero.
2018 Target can truncate a file from a file descriptor, as used by
2019 @file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or
2023 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
2024 Effectively, it is a target which supports no extra headers or libraries
2025 other than what is considered essential.
2028 Target supports @code{gettimeofday}.
2031 Target supports constructors with initialization priority arguments.
2033 @item inttypes_types
2034 Target has the basic signed and unsigned types in @code{inttypes.h}.
2035 This is for tests that GCC's notions of these types agree with those
2036 in the header, as some systems have only @code{inttypes.h}.
2039 Target might have errors of a few ULP in string to floating-point
2040 conversion functions and overflow is not always detected correctly by
2044 Target provides @code{mempcpy} function.
2047 Target supports @code{mmap}.
2050 Target supports Newlib.
2053 Target provides @code{pow10} function.
2056 Target can compile using @code{pthread.h} with no errors or warnings.
2059 Target has @code{pthread.h}.
2061 @item run_expensive_tests
2062 Expensive testcases (usually those that consume excessive amounts of CPU
2063 time) should be run on this target. This can be enabled by setting the
2064 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
2067 Test system runs executables on a simulator (i.e. slowly) rather than
2068 hardware (i.e. fast).
2071 Target has @code{signal.h}.
2074 Target supports the stabs debugging format.
2077 Target has the basic signed and unsigned C types in @code{stdint.h}.
2078 This will be obsolete when GCC ensures a working @code{stdint.h} for
2082 Target provides @code{stpcpy} function.
2085 Target supports trampolines.
2088 Target supports uClibc.
2091 Target does not use a status wrapper.
2093 @item vxworks_kernel
2094 Target is a VxWorks kernel.
2097 Target is a VxWorks RTP.
2100 Target supports wide characters.
2103 @subsubsection Other attributes
2106 @item automatic_stack_alignment
2107 Target supports automatic stack alignment.
2109 @item cilkplus_runtime
2110 Target supports the Cilk Plus runtime library.
2113 Target uses @code{__cxa_atexit}.
2115 @item default_packed
2116 Target has packed layout of structure members by default.
2119 Target supports Graphite optimizations.
2122 Target supports fixed-point extension to C.
2125 Target supports OpenACC via @option{-fopenacc}.
2128 Target supports OpenMP via @option{-fopenmp}.
2131 Target supports @option{-fpic} and @option{-fPIC}.
2134 Target supports @option{-freorder-blocks-and-partition}.
2136 @item fstack_protector
2137 Target supports @option{-fstack-protector}.
2140 Target uses GNU @command{as}.
2143 Target supports @option{--gc-sections}.
2146 Target uses GNU @command{ld}.
2148 @item keeps_null_pointer_checks
2149 Target keeps null pointer checks, either due to the use of
2150 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
2153 Compiler has been configured to support link-time optimization (LTO).
2155 @item naked_functions
2156 Target supports the @code{naked} function attribute.
2158 @item named_sections
2159 Target supports named sections.
2161 @item natural_alignment_32
2162 Target uses natural alignment (aligned to type size) for types of
2165 @item target_natural_alignment_64
2166 Target uses natural alignment (aligned to type size) for types of
2170 Target does not generate PIC by default.
2173 Target generates PIE by default.
2175 @item pcc_bitfield_type_matters
2176 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
2178 @item pe_aligned_commons
2179 Target supports @option{-mpe-aligned-commons}.
2182 Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
2185 Target supports @option{-rdynamic}.
2187 @item section_anchors
2188 Target supports section anchors.
2191 Target defaults to short enums.
2194 @anchor{stack_size_et}
2195 Target has limited stack size. The stack size limit can be obtained using the
2196 STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature
2200 Target supports @option{-static}.
2202 @item static_libgfortran
2203 Target supports statically linking @samp{libgfortran}.
2205 @item string_merging
2206 Target supports merging string constants at link time.
2209 Target supports compiling and assembling UCN.
2212 Including the options used to compile this particular test, the
2213 target supports compiling and assembling UCN.
2215 @item unaligned_stack
2216 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
2217 or equal to the required vector alignment.
2219 @item vector_alignment_reachable
2220 Vector alignment is reachable for types of 32 bits or less.
2222 @item vector_alignment_reachable_for_64bit
2223 Vector alignment is reachable for types of 64 bits or less.
2225 @item wchar_t_char16_t_compatible
2226 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
2228 @item wchar_t_char32_t_compatible
2229 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
2232 Target uses comdat groups.
2235 @subsubsection Local to tests in @code{gcc.target/i386}
2239 Target supports compiling @code{3dnow} instructions.
2242 Target supports compiling @code{aes} instructions.
2245 Target supports compiling @code{fma4} instructions.
2247 @item ms_hook_prologue
2248 Target supports attribute @code{ms_hook_prologue}.
2251 Target supports compiling @code{pclmul} instructions.
2254 Target supports compiling @code{sse3} instructions.
2257 Target supports compiling @code{sse4} instructions.
2260 Target supports compiling @code{sse4a} instructions.
2263 Target supports compiling @code{ssse3} instructions.
2266 Target supports compiling @code{vaes} instructions.
2269 Target supports compiling @code{vpclmul} instructions.
2272 Target supports compiling @code{xop} instructions.
2275 @subsubsection Local to tests in @code{gcc.target/spu/ea}
2279 Target @code{__ea} library functions are available.
2282 @subsubsection Local to tests in @code{gcc.test-framework}
2293 @subsection Features for @code{dg-add-options}
2295 The supported values of @var{feature} for directive @code{dg-add-options}
2300 @code{__ARM_FP} definition. Only ARM targets support this feature, and only then
2301 in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target
2305 NEON support. Only ARM targets support this feature, and only then
2306 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
2310 VFP half-precision floating point support. This does not select the
2311 FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or
2312 @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This
2313 feature is only supported by ARM targets and then only in certain
2314 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2318 @anchor{arm_fp16_ieee}
2319 ARM IEEE 754-2008 format VFP half-precision floating point support.
2320 This feature is only supported by ARM targets and then only in certain
2321 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2324 @item arm_fp16_alternative
2325 @anchor{arm_fp16_alternative}
2326 ARM Alternative format VFP half-precision floating point support.
2327 This feature is only supported by ARM targets and then only in certain
2328 modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target
2332 NEON and half-precision floating point support. Only ARM targets
2333 support this feature, and only then in certain modes; see
2334 the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}.
2337 arm vfp3 floating point support; see
2338 the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}.
2340 @item arm_v8_1a_neon
2341 Add options for ARMv8.1 with Adv.SIMD support, if this is supported
2342 by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok}
2343 effective target keyword.
2345 @item arm_v8_2a_fp16_scalar
2346 Add options for ARMv8.2 with scalar FP16 support, if this is
2347 supported by the target; see the
2348 @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective
2351 @item arm_v8_2a_fp16_neon
2352 Add options for ARMv8.2 with Adv.SIMD FP16 support, if this is
2353 supported by the target; see the
2354 @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target
2357 @item arm_v8_2a_dotprod_neon
2358 Add options for ARMv8.2 with Adv.SIMD Dot Product support, if this is
2359 supported by the target; see the
2360 @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword.
2362 @item bind_pic_locally
2363 Add the target-specific flags needed to enable functions to bind
2364 locally when using pic/PIC passes in the testsuite.
2367 Add the target-specific flags needed to access the C99 runtime.
2370 Add the target-specific flags needed to use the @code{_Float@var{n}} type.
2373 Add the target-specific flags needed to use the @code{_Float@var{n}x} type.
2376 Add the target-specific flags needed to enable full IEEE
2379 @item mips16_attribute
2380 @code{mips16} function attributes.
2381 Only MIPS targets support this feature, and only then in certain modes.
2384 @anchor{stack_size_ao}
2385 Add the flags needed to define macro STACK_SIZE and set it to the stack size
2386 limit associated with the @ref{stack_size_et,,@code{stack_size} effective
2390 Add the target-specific flags needed to use thread-local storage.
2393 @node Require Support
2394 @subsection Variants of @code{dg-require-@var{support}}
2396 A few of the @code{dg-require} directives take arguments.
2399 @item dg-require-iconv @var{codeset}
2400 Skip the test if the target does not support iconv. @var{codeset} is
2401 the codeset to convert to.
2403 @item dg-require-profiling @var{profopt}
2404 Skip the test if the target does not support profiling with option
2407 @item dg-require-stack-check @var{check}
2408 Skip the test if the target does not support the @code{-fstack-check}
2409 option. If @var{check} is @code{""}, support for @code{-fstack-check}
2410 is checked, for @code{-fstack-check=("@var{check}")} otherwise.
2412 @item dg-require-stack-size @var{size}
2413 Skip the test if the target does not support a stack size of @var{size}.
2415 @item dg-require-visibility @var{vis}
2416 Skip the test if the target does not support the @code{visibility} attribute.
2417 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
2418 checked, for @code{visibility("@var{vis}")} otherwise.
2421 The original @code{dg-require} directives were defined before there
2422 was support for effective-target keywords. The directives that do not
2423 take arguments could be replaced with effective-target keywords.
2426 @item dg-require-alias ""
2427 Skip the test if the target does not support the @samp{alias} attribute.
2429 @item dg-require-ascii-locale ""
2430 Skip the test if the host does not support an ASCII locale.
2432 @item dg-require-compat-dfp ""
2433 Skip this test unless both compilers in a @file{compat} testsuite
2434 support decimal floating point.
2436 @item dg-require-cxa-atexit ""
2437 Skip the test if the target does not support @code{__cxa_atexit}.
2438 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
2440 @item dg-require-dll ""
2441 Skip the test if the target does not support DLL attributes.
2443 @item dg-require-fork ""
2444 Skip the test if the target does not support @code{fork}.
2446 @item dg-require-gc-sections ""
2447 Skip the test if the target's linker does not support the
2448 @code{--gc-sections} flags.
2449 This is equivalent to @code{dg-require-effective-target gc-sections}.
2451 @item dg-require-host-local ""
2452 Skip the test if the host is remote, rather than the same as the build
2453 system. Some tests are incompatible with DejaGnu's handling of remote
2454 hosts, which involves copying the source file to the host and compiling
2455 it with a relative path and "@code{-o a.out}".
2457 @item dg-require-mkfifo ""
2458 Skip the test if the target does not support @code{mkfifo}.
2460 @item dg-require-named-sections ""
2461 Skip the test is the target does not support named sections.
2462 This is equivalent to @code{dg-require-effective-target named_sections}.
2464 @item dg-require-weak ""
2465 Skip the test if the target does not support weak symbols.
2467 @item dg-require-weak-override ""
2468 Skip the test if the target does not support overriding weak symbols.
2472 @subsection Commands for use in @code{dg-final}
2474 The GCC testsuite defines the following directives to be used within
2477 @subsubsection Scan a particular file
2480 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2481 Passes if @var{regexp} matches text in @var{filename}.
2482 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2483 Passes if @var{regexp} does not match text in @var{filename}.
2484 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
2485 Passes if @var{regexp} matches in Fortran module @var{module}.
2488 @subsubsection Scan the assembly output
2491 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
2492 Passes if @var{regex} matches text in the test's assembler output.
2494 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
2495 Passes if @var{regex} does not match text in the test's assembler output.
2497 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
2498 Passes if @var{regex} is matched exactly @var{num} times in the test's
2501 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
2502 Passes if @var{regex} matches text in the test's demangled assembler output.
2504 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
2505 Passes if @var{regex} does not match text in the test's demangled assembler
2508 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2509 Passes if @var{symbol} is defined as a hidden symbol in the test's
2512 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2513 Passes if @var{symbol} is not defined as a hidden symbol in the test's
2517 @subsubsection Scan optimization dump files
2519 These commands are available for @var{kind} of @code{tree}, @code{rtl},
2523 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2524 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
2526 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2527 Passes if @var{regex} does not match text in the dump file with suffix
2530 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
2531 Passes if @var{regex} is found exactly @var{num} times in the dump file
2532 with suffix @var{suffix}.
2534 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2535 Passes if @var{regex} matches demangled text in the dump file with
2536 suffix @var{suffix}.
2538 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2539 Passes if @var{regex} does not match demangled text in the dump file with
2540 suffix @var{suffix}.
2543 @subsubsection Verify that an output files exists or not
2546 @item output-exists [@{ target/xfail @var{selector} @}]
2547 Passes if compiler output file exists.
2549 @item output-exists-not [@{ target/xfail @var{selector} @}]
2550 Passes if compiler output file does not exist.
2553 @subsubsection Check for LTO tests
2556 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
2557 Passes if the pattern is present in the final executable.
2560 @subsubsection Checks for @command{gcov} tests
2563 @item run-gcov @var{sourcefile}
2564 Check line counts in @command{gcov} tests.
2566 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
2567 Check branch and/or call counts, in addition to line counts, in
2568 @command{gcov} tests.
2571 @subsubsection Clean up generated test files
2573 Usually the test-framework removes files that were generated during
2574 testing. If a testcase, for example, uses any dumping mechanism to
2575 inspect a passes dump file, the testsuite recognized the dump option
2576 passed to the tool and schedules a final cleanup to remove these files.
2578 There are, however, following additional cleanup directives that can be
2579 used to annotate a testcase "manually".
2581 @item cleanup-coverage-files
2582 Removes coverage data files generated for this test.
2584 @item cleanup-modules "@var{list-of-extra-modules}"
2585 Removes Fortran module files generated for this test, excluding the
2586 module names listed in keep-modules.
2587 Cleaning up module files is usually done automatically by the testsuite
2588 by looking at the source files and removing the modules after the test
2599 ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
2600 ! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
2603 @item keep-modules "@var{list-of-modules-not-to-delete}"
2604 Whitespace separated list of module names that should not be deleted by
2606 If the list of modules is empty, all modules defined in this file are kept.
2608 module maybe_unneeded
2609 end module maybe_unneeded
2614 ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
2615 ! @{ dg-final @{ keep-modules "" @} @} ! keep all
2618 @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}"
2619 Whitespace separated list of suffixes that should not be deleted
2620 automatically in a testcase that uses @option{-save-temps}.
2622 // @{ dg-options "-save-temps -fpch-preprocess -I." @}
2623 int main() @{ return 0; @}
2624 // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file
2625 // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i
2626 // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o
2629 @item cleanup-profile-file
2630 Removes profiling files generated for this test.
2632 @item cleanup-repo-files
2633 Removes files generated for this test for @option{-frepo}.
2638 @section Ada Language Testsuites
2640 The Ada testsuite includes executable tests from the ACATS
2641 testsuite, publicly available at
2642 @uref{http://www.ada-auth.org/acats.html}.
2644 These tests are integrated in the GCC testsuite in the
2645 @file{ada/acats} directory, and
2646 enabled automatically when running @code{make check}, assuming
2647 the Ada language has been enabled when configuring GCC@.
2649 You can also run the Ada testsuite independently, using
2650 @code{make check-ada}, or run a subset of the tests by specifying which
2651 chapter to run, e.g.:
2654 $ make check-ada CHAPTERS="c3 c9"
2657 The tests are organized by directory, each directory corresponding to
2658 a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
2659 to chapter 9, which deals with tasking features of the language.
2661 The tests are run using two @command{sh} scripts: @file{run_acats} and
2662 @file{run_all.sh}. To run the tests using a simulator or a cross
2663 target, see the small
2664 customization section at the top of @file{run_all.sh}.
2666 These tests are run using the build tree: they can be run without doing
2667 a @code{make install}.
2670 @section C Language Testsuites
2672 GCC contains the following C language testsuites, in the
2673 @file{gcc/testsuite} directory:
2677 This contains tests of particular features of the C compiler, using the
2678 more modern @samp{dg} harness. Correctness tests for various compiler
2679 features should go here if possible.
2681 Magic comments determine whether the file
2682 is preprocessed, compiled, linked or run. In these tests, error and warning
2683 message texts are compared against expected texts or regular expressions
2684 given in comments. These tests are run with the options @samp{-ansi -pedantic}
2685 unless other options are given in the test. Except as noted below they
2686 are not run with multiple optimization options.
2688 This subdirectory contains tests for binary compatibility using
2689 @file{lib/compat.exp}, which in turn uses the language-independent support
2690 (@pxref{compat Testing, , Support for testing binary compatibility}).
2692 This subdirectory contains tests of the preprocessor.
2694 This subdirectory contains tests for debug formats. Tests in this
2695 subdirectory are run for each debug format that the compiler supports.
2697 This subdirectory contains tests of the @option{-Wformat} format
2698 checking. Tests in this directory are run with and without
2700 @item gcc.dg/noncompile
2701 This subdirectory contains tests of code that should not compile and
2702 does not need any special compilation options. They are run with
2703 multiple optimization options, since sometimes invalid code crashes
2704 the compiler with optimization.
2705 @item gcc.dg/special
2706 FIXME: describe this.
2709 This contains particular code fragments which have historically broken easily.
2710 These tests are run with multiple optimization options, so tests for features
2711 which only break at some optimization levels belong here. This also contains
2712 tests to check that certain optimizations occur. It might be worthwhile to
2713 separate the correctness tests cleanly from the code quality tests, but
2714 it hasn't been done yet.
2716 @item gcc.c-torture/compat
2717 FIXME: describe this.
2719 This directory should probably not be used for new tests.
2720 @item gcc.c-torture/compile
2721 This testsuite contains test cases that should compile, but do not
2722 need to link or run. These test cases are compiled with several
2723 different combinations of optimization options. All warnings are
2724 disabled for these test cases, so this directory is not suitable if
2725 you wish to test for the presence or absence of compiler warnings.
2726 While special options can be set, and tests disabled on specific
2727 platforms, by the use of @file{.x} files, mostly these test cases
2728 should not contain platform dependencies. FIXME: discuss how defines
2729 such as @code{STACK_SIZE} are used.
2730 @item gcc.c-torture/execute
2731 This testsuite contains test cases that should compile, link and run;
2732 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
2733 @item gcc.c-torture/execute/ieee
2734 This contains tests which are specific to IEEE floating point.
2735 @item gcc.c-torture/unsorted
2736 FIXME: describe this.
2738 This directory should probably not be used for new tests.
2739 @item gcc.misc-tests
2740 This directory contains C tests that require special handling. Some
2741 of these tests have individual expect files, and others share
2742 special-purpose expect files:
2745 @item @code{bprob*.c}
2746 Test @option{-fbranch-probabilities} using
2747 @file{gcc.misc-tests/bprob.exp}, which
2748 in turn uses the generic, language-independent framework
2749 (@pxref{profopt Testing, , Support for testing profile-directed
2752 @item @code{gcov*.c}
2753 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
2754 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
2756 @item @code{i386-pf-*.c}
2757 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
2760 @item gcc.test-framework
2763 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
2768 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
2769 test cases and magic comments more.
2772 @section Support for testing link-time optimizations
2774 Tests for link-time optimizations usually require multiple source files
2775 that are compiled separately, perhaps with different sets of options.
2776 There are several special-purpose test directives used for these tests.
2779 @item @{ dg-lto-do @var{do-what-keyword} @}
2780 @var{do-what-keyword} specifies how the test is compiled and whether
2781 it is executed. It is one of:
2785 Compile with @option{-c} to produce a relocatable object file.
2787 Compile, assemble, and link to produce an executable file.
2789 Produce and run an executable file, which is expected to return
2793 The default is @code{assemble}. That can be overridden for a set of
2794 tests by redefining @code{dg-do-what-default} within the @code{.exp}
2795 file for those tests.
2797 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
2798 @samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
2799 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
2801 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
2802 This directive provides a list of one or more sets of compiler options
2803 to override @var{LTO_OPTIONS}. Each test will be compiled and run with
2804 each of these sets of options.
2806 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
2807 This directive adds @var{options} to the linker options used.
2809 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
2810 This directive removes @var{options} from the set of linker options used.
2814 @section Support for testing @command{gcov}
2816 Language-independent support for testing @command{gcov}, and for checking
2817 that branch profiling produces expected values, is provided by the
2818 expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
2819 in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
2820 @command{gcov} test contains the following DejaGnu commands within comments:
2823 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
2824 @{ dg-do run @{ target native @} @}
2825 @{ dg-final @{ run-gcov sourcefile @} @}
2828 Checks of @command{gcov} output can include line counts, branch percentages,
2829 and call return percentages. All of these checks are requested via
2830 commands that appear in comments in the test's source file.
2831 Commands to check line counts are processed by default.
2832 Commands to check branch percentages and call return percentages are
2833 processed if the @command{run-gcov} command has arguments @code{branches}
2834 or @code{calls}, respectively. For example, the following specifies
2835 checking both, as well as passing @option{-b} to @command{gcov}:
2838 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
2841 A line count command appears within a comment on the source line
2842 that is expected to get the specified count and has the form
2843 @code{count(@var{cnt})}. A test should only check line counts for
2844 lines that will get the same count for any architecture.
2846 Commands to check branch percentages (@code{branch}) and call
2847 return percentages (@code{returns}) are very similar to each other.
2848 A beginning command appears on or before the first of a range of
2849 lines that will report the percentage, and the ending command
2850 follows that range of lines. The beginning command can include a
2851 list of percentages, all of which are expected to be found within
2852 the range. A range is terminated by the next command of the same
2853 kind. A command @code{branch(end)} or @code{returns(end)} marks
2854 the end of a range without starting a new one. For example:
2857 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
2858 /* @r{branch(end)} */
2862 For a call return percentage, the value specified is the
2863 percentage of calls reported to return. For a branch percentage,
2864 the value is either the expected percentage or 100 minus that
2865 value, since the direction of a branch can differ depending on the
2866 target or the optimization level.
2868 Not all branches and calls need to be checked. A test should not
2869 check for branches that might be optimized away or replaced with
2870 predicated instructions. Don't check for calls inserted by the
2871 compiler or ones that might be inlined or optimized away.
2873 A single test can check for combinations of line counts, branch
2874 percentages, and call return percentages. The command to check a
2875 line count must appear on the line that will report that count, but
2876 commands to check branch percentages and call return percentages can
2877 bracket the lines that report them.
2879 @node profopt Testing
2880 @section Support for testing profile-directed optimizations
2882 The file @file{profopt.exp} provides language-independent support for
2883 checking correct execution of a test built with profile-directed
2884 optimization. This testing requires that a test program be built and
2885 executed twice. The first time it is compiled to generate profile
2886 data, and the second time it is compiled to use the data that was
2887 generated during the first execution. The second execution is to
2888 verify that the test produces the expected results.
2890 To check that the optimization actually generated better code, a
2891 test can be built and run a third time with normal optimizations to
2892 verify that the performance is better with the profile-directed
2893 optimizations. @file{profopt.exp} has the beginnings of this kind
2896 @file{profopt.exp} provides generic support for profile-directed
2897 optimizations. Each set of tests that uses it provides information
2898 about a specific optimization:
2902 tool being tested, e.g., @command{gcc}
2904 @item profile_option
2905 options used to generate profile data
2907 @item feedback_option
2908 options used to optimize using that profile data
2911 suffix of profile data files
2913 @item PROFOPT_OPTIONS
2914 list of options with which to run each test, similar to the lists for
2917 @item @{ dg-final-generate @{ @var{local-directive} @} @}
2918 This directive is similar to @code{dg-final}, but the
2919 @var{local-directive} is run after the generation of profile data.
2921 @item @{ dg-final-use @{ @var{local-directive} @} @}
2922 The @var{local-directive} is run after the profile data have been
2926 @node compat Testing
2927 @section Support for testing binary compatibility
2929 The file @file{compat.exp} provides language-independent support for
2930 binary compatibility testing. It supports testing interoperability of
2931 two compilers that follow the same ABI, or of multiple sets of
2932 compiler options that should not affect binary compatibility. It is
2933 intended to be used for testsuites that complement ABI testsuites.
2935 A test supported by this framework has three parts, each in a
2936 separate source file: a main program and two pieces that interact
2937 with each other to split up the functionality being tested.
2940 @item @var{testname}_main.@var{suffix}
2941 Contains the main program, which calls a function in file
2942 @file{@var{testname}_x.@var{suffix}}.
2944 @item @var{testname}_x.@var{suffix}
2945 Contains at least one call to a function in
2946 @file{@var{testname}_y.@var{suffix}}.
2948 @item @var{testname}_y.@var{suffix}
2949 Shares data with, or gets arguments from,
2950 @file{@var{testname}_x.@var{suffix}}.
2953 Within each test, the main program and one functional piece are
2954 compiled by the GCC under test. The other piece can be compiled by
2955 an alternate compiler. If no alternate compiler is specified,
2956 then all three source files are all compiled by the GCC under test.
2957 You can specify pairs of sets of compiler options. The first element
2958 of such a pair specifies options used with the GCC under test, and the
2959 second element of the pair specifies options used with the alternate
2960 compiler. Each test is compiled with each pair of options.
2962 @file{compat.exp} defines default pairs of compiler options.
2963 These can be overridden by defining the environment variable
2964 @env{COMPAT_OPTIONS} as:
2967 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
2968 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
2971 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
2972 used by the compiler under test and @var{alti} used by the alternate
2973 compiler. For example, with
2974 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
2975 the test is first built with @option{-g -O0} by the compiler under
2976 test and with @option{-O3} by the alternate compiler. The test is
2977 built a second time using @option{-fpic} by the compiler under test
2978 and @option{-fPIC -O2} by the alternate compiler.
2980 An alternate compiler is specified by defining an environment
2981 variable to be the full pathname of an installed compiler; for C
2982 define @env{ALT_CC_UNDER_TEST}, and for C++ define
2983 @env{ALT_CXX_UNDER_TEST}. These will be written to the
2984 @file{site.exp} file used by DejaGnu. The default is to build each
2985 test with the compiler under test using the first of each pair of
2986 compiler options from @env{COMPAT_OPTIONS}. When
2987 @env{ALT_CC_UNDER_TEST} or
2988 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
2989 the compiler under test but with combinations of the options from
2990 @env{COMPAT_OPTIONS}.
2992 To run only the C++ compatibility suite using the compiler under test
2993 and another version of GCC using specific compiler options, do the
2994 following from @file{@var{objdir}/gcc}:
2999 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
3000 COMPAT_OPTIONS="@var{lists as shown above}" \
3002 RUNTESTFLAGS="compat.exp"
3005 A test that fails when the source files are compiled with different
3006 compilers, but passes when the files are compiled with the same
3007 compiler, demonstrates incompatibility of the generated code or
3008 runtime support. A test that fails for the alternate compiler but
3009 passes for the compiler under test probably tests for a bug that was
3010 fixed in the compiler under test but is present in the alternate
3013 The binary compatibility tests support a small number of test framework
3014 commands that appear within comments in a test file.
3018 These commands can be used in @file{@var{testname}_main.@var{suffix}}
3019 to skip the test if specific support is not available on the target.
3022 The specified options are used for compiling this particular source
3023 file, appended to the options from @env{COMPAT_OPTIONS}. When this
3024 command appears in @file{@var{testname}_main.@var{suffix}} the options
3025 are also used to link the test program.
3028 This command can be used in a secondary source file to specify that
3029 compilation is expected to fail for particular options on particular
3034 @section Support for torture testing using multiple options
3036 Throughout the compiler testsuite there are several directories whose
3037 tests are run multiple times, each with a different set of options.
3038 These are known as torture tests.
3039 @file{lib/torture-options.exp} defines procedures to
3044 Initialize use of torture lists.
3045 @item set-torture-options
3046 Set lists of torture options to use for tests with and without loops.
3047 Optionally combine a set of torture options with a set of other
3048 options, as is done with Objective-C runtime options.
3049 @item torture-finish
3050 Finalize use of torture lists.
3053 The @file{.exp} file for a set of tests that use torture options must
3054 include calls to these three procedures if:
3057 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
3059 @item It calls @var{$@{tool@}}@code{-torture} or
3060 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
3061 @code{fortran}, or @code{objc}.
3063 @item It calls @code{dg-pch}.
3066 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
3067 to call the torture procedures if the tests should use the list in
3068 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
3070 Most uses of torture options can override the default lists by defining
3071 @var{TORTURE_OPTIONS} or add to the default list by defining
3072 @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
3073 file or add them to the @file{site.exp} file; for example
3076 set ADDITIONAL_TORTURE_OPTIONS [list \
3077 @{ -O2 -ftree-loop-linear @} \
3078 @{ -O2 -fpeel-loops @} ]
3082 @section Support for testing GIMPLE passes
3084 As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate
3085 that the function body will be GIMPLE, rather than C. The compiler requires
3086 the option @option{-fgimple} to enable this functionality. For example:
3089 /* @{ dg-do compile @} */
3090 /* @{ dg-options "-O -fgimple" @} */
3092 void __GIMPLE (startwith ("dse2")) foo ()
3110 a_1 = __PHI (bb_3: a_2, bb_4: a_3);
3117 The @code{startwith} argument indicates at which pass to begin.
3119 Use the dump modifier @code{-gimple} (e.g. @option{-fdump-tree-all-gimple})
3120 to make tree dumps more closely follow the format accepted by the GIMPLE
3123 Example DejaGnu tests of GIMPLE can be seen in the source tree at
3124 @file{gcc/testsuite/gcc.dg/gimplefe-*.c}.
3126 The @code{__GIMPLE} parser is integrated with the C tokenizer and
3127 preprocessor, so it should be possible to use macros to build out
3131 @section Support for testing RTL passes
3133 As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the
3134 function body will be RTL, rather than C. For example:
3137 double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b)
3140 [...snip; various directives go in here...]
3141 ) ;; function "test"
3145 The @code{startwith} argument indicates at which pass to begin.
3147 The parser expects the RTL body to be in the format emitted by this
3152 print_rtx_function (FILE *outfile, function *fn, bool compact);
3155 when "compact" is true. So you can capture RTL in the correct format
3156 from the debugger using:
3159 (gdb) print_rtx_function (stderr, cfun, true);
3162 and copy and paste the output into the body of the C function.
3164 Example DejaGnu tests of RTL can be seen in the source tree under
3165 @file{gcc/testsuite/gcc.dg/rtl}.
3167 The @code{__RTL} parser is not integrated with the C tokenizer or
3168 preprocessor, and works simply by reading the relevant lines within
3169 the braces. In particular, the RTL body must be on separate lines from
3170 the enclosing braces, and the preprocessor is not usable within it.