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