1@c Copyright (C) 2002-2015 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, used as part of the Java 32runtime library. 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 Java 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{http://code.google.com/@/p/@/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 libjava 104The Java runtime library. 105 106@item libobjc 107The Objective-C and Objective-C++ runtime library. 108 109@item libquadmath 110The runtime support library for quad-precision math operations. 111 112@item libssp 113The Stack protector runtime library. 114 115@item libstdc++-v3 116The C++ runtime library. 117 118@item lto-plugin 119Plugin used by the linker if link-time optimizations are enabled. 120 121@item maintainer-scripts 122Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. 123 124@item zlib 125The @code{zlib} compression library, used by the Java front end, as 126part of the Java runtime library, and for compressing and uncompressing 127GCC'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_svn}. 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_svn} (@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 FTP site 570@uref{ftp://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 632Java front end depends on the C++ front end, so sets 633@samp{lang_requires=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 829If the back end is added to the official GCC source repository, the 830following are also necessary: 831 832@itemize @bullet 833@item 834An entry for the target architecture in @file{readings.html} on the 835GCC web site, with any relevant links. 836@item 837Details of the properties of the back end and target architecture in 838@file{backends.html} on the GCC web site. 839@item 840A news item about the contribution of support for that target 841architecture, in @file{index.html} on the GCC web site. 842@item 843Normally, one or more maintainers of that target listed in 844@file{MAINTAINERS}. Some existing architectures may be unmaintained, 845but it would be unusual to add support for a target that does not have 846a maintainer when support is added. 847@item 848Target triplets covering all @file{config.gcc} stanzas for the target, 849in the list in @file{contrib/config-list.mk}. 850@end itemize 851 852@node Testsuites 853@chapter Testsuites 854 855GCC contains several testsuites to help maintain compiler quality. 856Most of the runtime libraries and language front ends in GCC have 857testsuites. Currently only the C language testsuites are documented 858here; FIXME: document the others. 859 860@menu 861* Test Idioms:: Idioms used in testsuite code. 862* Test Directives:: Directives used within DejaGnu tests. 863* Ada Tests:: The Ada language testsuites. 864* C Tests:: The C language testsuites. 865* libgcj Tests:: The Java library testsuites. 866* LTO Testing:: Support for testing link-time optimizations. 867* gcov Testing:: Support for testing gcov. 868* profopt Testing:: Support for testing profile-directed optimizations. 869* compat Testing:: Support for testing binary compatibility. 870* Torture Tests:: Support for torture testing using multiple options. 871@end menu 872 873@node Test Idioms 874@section Idioms Used in Testsuite Code 875 876In general, C testcases have a trailing @file{-@var{n}.c}, starting 877with @file{-1.c}, in case other testcases with similar names are added 878later. If the test is a test of some well-defined feature, it should 879have a name referring to that feature such as 880@file{@var{feature}-1.c}. If it does not test a well-defined feature 881but just happens to exercise a bug somewhere in the compiler, and a 882bug report has been filed for this bug in the GCC bug database, 883@file{pr@var{bug-number}-1.c} is the appropriate form of name. 884Otherwise (for miscellaneous bugs not filed in the GCC bug database), 885and previously more generally, test cases are named after the date on 886which they were added. This allows people to tell at a glance whether 887a test failure is because of a recently found bug that has not yet 888been fixed, or whether it may be a regression, but does not give any 889other information about the bug or where discussion of it may be 890found. Some other language testsuites follow similar conventions. 891 892In the @file{gcc.dg} testsuite, it is often necessary to test that an 893error is indeed a hard error and not just a warning---for example, 894where it is a constraint violation in the C standard, which must 895become an error with @option{-pedantic-errors}. The following idiom, 896where the first line shown is line @var{line} of the file and the line 897that generates the error, is used for this: 898 899@smallexample 900/* @{ dg-bogus "warning" "warning in place of error" @} */ 901/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ 902@end smallexample 903 904It may be necessary to check that an expression is an integer constant 905expression and has a certain value. To check that @code{@var{E}} has 906value @code{@var{V}}, an idiom similar to the following is used: 907 908@smallexample 909char x[((E) == (V) ? 1 : -1)]; 910@end smallexample 911 912In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make 913assertions about the types of expressions. See, for example, 914@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the 915exact rules for the types of conditional expressions in the C 916standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. 917 918It is useful to be able to test that optimizations are being made 919properly. This cannot be done in all cases, but it can be done where 920the optimization will lead to code being optimized away (for example, 921where flow analysis or alias analysis should show that certain code 922cannot be called) or to functions not being called because they have 923been expanded as built-in functions. Such tests go in 924@file{gcc.c-torture/execute}. Where code should be optimized away, a 925call to a nonexistent function such as @code{link_failure ()} may be 926inserted; a definition 927 928@smallexample 929#ifndef __OPTIMIZE__ 930void 931link_failure (void) 932@{ 933 abort (); 934@} 935#endif 936@end smallexample 937 938@noindent 939will also be needed so that linking still succeeds when the test is 940run without optimization. When all calls to a built-in function 941should have been optimized and no calls to the non-built-in version of 942the function should remain, that function may be defined as 943@code{static} to call @code{abort ()} (although redeclaring a function 944as static may not work on all targets). 945 946All testcases must be portable. Target-specific testcases must have 947appropriate code to avoid causing failures on unsupported systems; 948unfortunately, the mechanisms for this differ by directory. 949 950FIXME: discuss non-C testsuites here. 951 952@node Test Directives 953@section Directives used within DejaGnu tests 954 955@menu 956* Directives:: Syntax and descriptions of test directives. 957* Selectors:: Selecting targets to which a test applies. 958* Effective-Target Keywords:: Keywords describing target attributes. 959* Add Options:: Features for @code{dg-add-options} 960* Require Support:: Variants of @code{dg-require-@var{support}} 961* Final Actions:: Commands for use in @code{dg-final} 962@end menu 963 964@node Directives 965@subsection Syntax and Descriptions of test directives 966 967Test directives appear within comments in a test source file and begin 968with @code{dg-}. Some of these are defined within DejaGnu and others 969are local to the GCC testsuite. 970 971The order in which test directives appear in a test can be important: 972directives local to GCC sometimes override information used by the 973DejaGnu directives, which know nothing about the GCC directives, so the 974DejaGnu directives must precede GCC directives. 975 976Several test directives include selectors (@pxref{Selectors, , }) 977which are usually preceded by the keyword @code{target} or @code{xfail}. 978 979@subsubsection Specify how to build the test 980 981@table @code 982@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} 983@var{do-what-keyword} specifies how the test is compiled and whether 984it is executed. It is one of: 985 986@table @code 987@item preprocess 988Compile with @option{-E} to run only the preprocessor. 989@item compile 990Compile with @option{-S} to produce an assembly code file. 991@item assemble 992Compile with @option{-c} to produce a relocatable object file. 993@item link 994Compile, assemble, and link to produce an executable file. 995@item run 996Produce and run an executable file, which is expected to return 997an exit code of 0. 998@end table 999 1000The default is @code{compile}. That can be overridden for a set of 1001tests by redefining @code{dg-do-what-default} within the @code{.exp} 1002file for those tests. 1003 1004If the directive includes the optional @samp{@{ target @var{selector} @}} 1005then the test is skipped unless the target system matches the 1006@var{selector}. 1007 1008If @var{do-what-keyword} is @code{run} and the directive includes 1009the optional @samp{@{ xfail @var{selector} @}} and the selector is met 1010then the test is expected to fail. The @code{xfail} clause is ignored 1011for other values of @var{do-what-keyword}; those tests can use 1012directive @code{dg-xfail-if}. 1013@end table 1014 1015@subsubsection Specify additional compiler options 1016 1017@table @code 1018@item @{ dg-options @var{options} [@{ target @var{selector} @}] @} 1019This DejaGnu directive provides a list of compiler options, to be used 1020if the target system matches @var{selector}, that replace the default 1021options used for this set of tests. 1022 1023@item @{ dg-add-options @var{feature} @dots{} @} 1024Add any compiler options that are needed to access certain features. 1025This directive does nothing on targets that enable the features by 1026default, or that don't provide them at all. It must come after 1027all @code{dg-options} directives. 1028For supported values of @var{feature} see @ref{Add Options, ,}. 1029 1030@item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @} 1031This directive provides a list of compiler options, to be used 1032if the target system matches @var{selector}, that are added to the default 1033options used for this set of tests. 1034@end table 1035 1036@subsubsection Modify the test timeout value 1037 1038The normal timeout limit, in seconds, is found by searching the 1039following in order: 1040 1041@itemize @bullet 1042@item the value defined by an earlier @code{dg-timeout} directive in 1043the test 1044 1045@item variable @var{tool_timeout} defined by the set of tests 1046 1047@item @var{gcc},@var{timeout} set in the target board 1048 1049@item 300 1050@end itemize 1051 1052@table @code 1053@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @} 1054Set the time limit for the compilation and for the execution of the test 1055to the specified number of seconds. 1056 1057@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @} 1058Multiply the normal time limit for compilation and execution of the test 1059by the specified floating-point factor. 1060@end table 1061 1062@subsubsection Skip a test for some targets 1063 1064@table @code 1065@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1066Arguments @var{include-opts} and @var{exclude-opts} are lists in which 1067each element is a string of zero or more GCC options. 1068Skip the test if all of the following conditions are met: 1069@itemize @bullet 1070@item the test system is included in @var{selector} 1071 1072@item for at least one of the option strings in @var{include-opts}, 1073every option from that string is in the set of options with which 1074the test would be compiled; use @samp{"*"} for an @var{include-opts} list 1075that matches any options; that is the default if @var{include-opts} is 1076not specified 1077 1078@item for each of the option strings in @var{exclude-opts}, at least one 1079option from that string is not in the set of options with which the test 1080would be compiled; use @samp{""} for an empty @var{exclude-opts} list; 1081that is the default if @var{exclude-opts} is not specified 1082@end itemize 1083 1084For example, to skip a test if option @code{-Os} is present: 1085 1086@smallexample 1087/* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */ 1088@end smallexample 1089 1090To skip a test if both options @code{-O2} and @code{-g} are present: 1091 1092@smallexample 1093/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */ 1094@end smallexample 1095 1096To skip a test if either @code{-O2} or @code{-O3} is present: 1097 1098@smallexample 1099/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */ 1100@end smallexample 1101 1102To skip a test unless option @code{-Os} is present: 1103 1104@smallexample 1105/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */ 1106@end smallexample 1107 1108To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g} 1109but not if @code{-fpic} is also present: 1110 1111@smallexample 1112/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */ 1113@end smallexample 1114 1115@item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @} 1116Skip the test if the test target, including current multilib flags, 1117is not covered by the effective-target keyword. 1118If the directive includes the optional @samp{@{ @var{selector} @}} 1119then the effective-target test is only performed if the target system 1120matches the @var{selector}. 1121This directive must appear after any @code{dg-do} directive in the test 1122and before any @code{dg-additional-sources} directive. 1123@xref{Effective-Target Keywords, , }. 1124 1125@item @{ dg-require-@var{support} args @} 1126Skip the test if the target does not provide the required support. 1127These directives must appear after any @code{dg-do} directive in the test 1128and before any @code{dg-additional-sources} directive. 1129They require at least one argument, which can be an empty string if the 1130specific procedure does not examine the argument. 1131@xref{Require Support, , }, for a complete list of these directives. 1132@end table 1133 1134@subsubsection Expect a test to fail for some targets 1135 1136@table @code 1137@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1138Expect the test to fail if the conditions (which are the same as for 1139@code{dg-skip-if}) are met. This does not affect the execute step. 1140 1141@item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1142Expect the execute step of a test to fail if the conditions (which are 1143the same as for @code{dg-skip-if}) are met. 1144@end table 1145 1146@subsubsection Expect the test executable to fail 1147 1148@table @code 1149@item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} 1150Expect the test executable to return a nonzero exit status if the 1151conditions (which are the same as for @code{dg-skip-if}) are met. 1152@end table 1153 1154@subsubsection Verify compiler messages 1155 1156@table @code 1157@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1158This DejaGnu directive appears on a source line that is expected to get 1159an error message, or else specifies the source line associated with the 1160message. If there is no message for that line or if the text of that 1161message is not matched by @var{regexp} then the check fails and 1162@var{comment} is included in the @code{FAIL} message. The check does 1163not look for the string @samp{error} unless it is part of @var{regexp}. 1164 1165@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1166This DejaGnu directive appears on a source line that is expected to get 1167a warning message, or else specifies the source line associated with the 1168message. If there is no message for that line or if the text of that 1169message is not matched by @var{regexp} then the check fails and 1170@var{comment} is included in the @code{FAIL} message. The check does 1171not look for the string @samp{warning} unless it is part of @var{regexp}. 1172 1173@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1174The line is expected to get a message other than an error or warning. 1175If there is no message for that line or if the text of that message is 1176not matched by @var{regexp} then the check fails and @var{comment} is 1177included in the @code{FAIL} message. 1178 1179@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1180This DejaGnu directive appears on a source line that should not get a 1181message matching @var{regexp}, or else specifies the source line 1182associated with the bogus message. It is usually used with @samp{xfail} 1183to indicate that the message is a known problem for a particular set of 1184targets. 1185 1186@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} 1187This DejaGnu directive indicates that the test is expected to fail due 1188to compiler messages that are not handled by @samp{dg-error}, 1189@samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail} 1190has the same effect as @samp{target}. 1191 1192@item @{ dg-prune-output @var{regexp} @} 1193Prune messages matching @var{regexp} from the test output. 1194@end table 1195 1196@subsubsection Verify output of the test executable 1197 1198@table @code 1199@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} 1200This DejaGnu directive compares @var{regexp} to the combined output 1201that the test executable writes to @file{stdout} and @file{stderr}. 1202@end table 1203 1204@subsubsection Specify additional files for a test 1205 1206@table @code 1207@item @{ dg-additional-files "@var{filelist}" @} 1208Specify additional files, other than source files, that must be copied 1209to the system where the compiler runs. 1210 1211@item @{ dg-additional-sources "@var{filelist}" @} 1212Specify additional source files to appear in the compile line 1213following the main test file. 1214@end table 1215 1216@subsubsection Add checks at the end of a test 1217 1218@table @code 1219@item @{ dg-final @{ @var{local-directive} @} @} 1220This DejaGnu directive is placed within a comment anywhere in the 1221source file and is processed after the test has been compiled and run. 1222Multiple @samp{dg-final} commands are processed in the order in which 1223they appear in the source file. @xref{Final Actions, , }, for a list 1224of directives that can be used within @code{dg-final}. 1225@end table 1226 1227@node Selectors 1228@subsection Selecting targets to which a test applies 1229 1230Several test directives include @var{selector}s to limit the targets 1231for which a test is run or to declare that a test is expected to fail 1232on particular targets. 1233 1234A selector is: 1235@itemize @bullet 1236@item one or more target triplets, possibly including wildcard characters; 1237use @samp{*-*-*} to match any target 1238@item a single effective-target keyword (@pxref{Effective-Target Keywords}) 1239@item a logical expression 1240@end itemize 1241 1242Depending on the context, the selector specifies whether a test is 1243skipped and reported as unsupported or is expected to fail. A context 1244that allows either @samp{target} or @samp{xfail} also allows 1245@samp{@{ target @var{selector1} xfail @var{selector2} @}} 1246to skip the test for targets that don't match @var{selector1} and the 1247test to fail for targets that match @var{selector2}. 1248 1249A selector expression appears within curly braces and uses a single 1250logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An 1251operand is another selector expression, an effective-target keyword, 1252a single target triplet, or a list of target triplets within quotes or 1253curly braces. For example: 1254 1255@smallexample 1256@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} 1257@{ target @{ powerpc*-*-* && lp64 @} @} 1258@{ xfail @{ lp64 || vect_no_align @} @} 1259@end smallexample 1260 1261@node Effective-Target Keywords 1262@subsection Keywords describing target attributes 1263 1264Effective-target keywords identify sets of targets that support 1265particular functionality. They are used to limit tests to be run only 1266for particular targets, or to specify that particular sets of targets 1267are expected to fail some tests. 1268 1269Effective-target keywords are defined in @file{lib/target-supports.exp} in 1270the GCC testsuite, with the exception of those that are documented as 1271being local to a particular test directory. 1272 1273The @samp{effective target} takes into account all of the compiler options 1274with which the test will be compiled, including the multilib options. 1275By convention, keywords ending in @code{_nocache} can also include options 1276specified for the particular test in an earlier @code{dg-options} or 1277@code{dg-add-options} directive. 1278 1279@subsubsection Data type sizes 1280 1281@table @code 1282@item ilp32 1283Target has 32-bit @code{int}, @code{long}, and pointers. 1284 1285@item lp64 1286Target has 32-bit @code{int}, 64-bit @code{long} and pointers. 1287 1288@item llp64 1289Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long} 1290and pointers. 1291 1292@item double64 1293Target has 64-bit @code{double}. 1294 1295@item double64plus 1296Target has @code{double} that is 64 bits or longer. 1297 1298@item longdouble128 1299Target has 128-bit @code{long double}. 1300 1301@item int32plus 1302Target has @code{int} that is at 32 bits or longer. 1303 1304@item int16 1305Target has @code{int} that is 16 bits or shorter. 1306 1307@item long_neq_int 1308Target has @code{int} and @code{long} with different sizes. 1309 1310@item large_double 1311Target supports @code{double} that is longer than @code{float}. 1312 1313@item large_long_double 1314Target supports @code{long double} that is longer than @code{double}. 1315 1316@item ptr32plus 1317Target has pointers that are 32 bits or longer. 1318 1319@item size32plus 1320Target supports array and structure sizes that are 32 bits or longer. 1321 1322@item 4byte_wchar_t 1323Target has @code{wchar_t} that is at least 4 bytes. 1324@end table 1325 1326@subsubsection Fortran-specific attributes 1327 1328@table @code 1329@item fortran_integer_16 1330Target supports Fortran @code{integer} that is 16 bytes or longer. 1331 1332@item fortran_large_int 1333Target supports Fortran @code{integer} kinds larger than @code{integer(8)}. 1334 1335@item fortran_large_real 1336Target supports Fortran @code{real} kinds larger than @code{real(8)}. 1337@end table 1338 1339@subsubsection Vector-specific attributes 1340 1341@table @code 1342@item vect_condition 1343Target supports vector conditional operations. 1344 1345@item vect_double 1346Target supports hardware vectors of @code{double}. 1347 1348@item vect_float 1349Target supports hardware vectors of @code{float}. 1350 1351@item vect_int 1352Target supports hardware vectors of @code{int}. 1353 1354@item vect_long 1355Target supports hardware vectors of @code{long}. 1356 1357@item vect_long_long 1358Target supports hardware vectors of @code{long long}. 1359 1360@item vect_aligned_arrays 1361Target aligns arrays to vector alignment boundary. 1362 1363@item vect_hw_misalign 1364Target supports a vector misalign access. 1365 1366@item vect_no_align 1367Target does not support a vector alignment mechanism. 1368 1369@item vect_no_int_max 1370Target does not support a vector max instruction on @code{int}. 1371 1372@item vect_no_int_add 1373Target does not support a vector add instruction on @code{int}. 1374 1375@item vect_no_bitwise 1376Target does not support vector bitwise instructions. 1377 1378@item vect_char_mult 1379Target supports @code{vector char} multiplication. 1380 1381@item vect_short_mult 1382Target supports @code{vector short} multiplication. 1383 1384@item vect_int_mult 1385Target supports @code{vector int} multiplication. 1386 1387@item vect_extract_even_odd 1388Target supports vector even/odd element extraction. 1389 1390@item vect_extract_even_odd_wide 1391Target supports vector even/odd element extraction of vectors with elements 1392@code{SImode} or larger. 1393 1394@item vect_interleave 1395Target supports vector interleaving. 1396 1397@item vect_strided 1398Target supports vector interleaving and extract even/odd. 1399 1400@item vect_strided_wide 1401Target supports vector interleaving and extract even/odd for wide 1402element types. 1403 1404@item vect_perm 1405Target supports vector permutation. 1406 1407@item vect_shift 1408Target supports a hardware vector shift operation. 1409 1410@item vect_widen_sum_hi_to_si 1411Target supports a vector widening summation of @code{short} operands 1412into @code{int} results, or can promote (unpack) from @code{short} 1413to @code{int}. 1414 1415@item vect_widen_sum_qi_to_hi 1416Target supports a vector widening summation of @code{char} operands 1417into @code{short} results, or can promote (unpack) from @code{char} 1418to @code{short}. 1419 1420@item vect_widen_sum_qi_to_si 1421Target supports a vector widening summation of @code{char} operands 1422into @code{int} results. 1423 1424@item vect_widen_mult_qi_to_hi 1425Target supports a vector widening multiplication of @code{char} operands 1426into @code{short} results, or can promote (unpack) from @code{char} to 1427@code{short} and perform non-widening multiplication of @code{short}. 1428 1429@item vect_widen_mult_hi_to_si 1430Target supports a vector widening multiplication of @code{short} operands 1431into @code{int} results, or can promote (unpack) from @code{short} to 1432@code{int} and perform non-widening multiplication of @code{int}. 1433 1434@item vect_widen_mult_si_to_di_pattern 1435Target supports a vector widening multiplication of @code{int} operands 1436into @code{long} results. 1437 1438@item vect_sdot_qi 1439Target supports a vector dot-product of @code{signed char}. 1440 1441@item vect_udot_qi 1442Target supports a vector dot-product of @code{unsigned char}. 1443 1444@item vect_sdot_hi 1445Target supports a vector dot-product of @code{signed short}. 1446 1447@item vect_udot_hi 1448Target supports a vector dot-product of @code{unsigned short}. 1449 1450@item vect_pack_trunc 1451Target supports a vector demotion (packing) of @code{short} to @code{char} 1452and from @code{int} to @code{short} using modulo arithmetic. 1453 1454@item vect_unpack 1455Target supports a vector promotion (unpacking) of @code{char} to @code{short} 1456and from @code{char} to @code{int}. 1457 1458@item vect_intfloat_cvt 1459Target supports conversion from @code{signed int} to @code{float}. 1460 1461@item vect_uintfloat_cvt 1462Target supports conversion from @code{unsigned int} to @code{float}. 1463 1464@item vect_floatint_cvt 1465Target supports conversion from @code{float} to @code{signed int}. 1466 1467@item vect_floatuint_cvt 1468Target supports conversion from @code{float} to @code{unsigned int}. 1469@end table 1470 1471@subsubsection Thread Local Storage attributes 1472 1473@table @code 1474@item tls 1475Target supports thread-local storage. 1476 1477@item tls_native 1478Target supports native (rather than emulated) thread-local storage. 1479 1480@item tls_runtime 1481Test system supports executing TLS executables. 1482@end table 1483 1484@subsubsection Decimal floating point attributes 1485 1486@table @code 1487@item dfp 1488Targets supports compiling decimal floating point extension to C. 1489 1490@item dfp_nocache 1491Including the options used to compile this particular test, the 1492target supports compiling decimal floating point extension to C. 1493 1494@item dfprt 1495Test system can execute decimal floating point tests. 1496 1497@item dfprt_nocache 1498Including the options used to compile this particular test, the 1499test system can execute decimal floating point tests. 1500 1501@item hard_dfp 1502Target generates decimal floating point instructions with current options. 1503@end table 1504 1505@subsubsection ARM-specific attributes 1506 1507@table @code 1508@item arm32 1509ARM target generates 32-bit code. 1510 1511@item arm_eabi 1512ARM target adheres to the ABI for the ARM Architecture. 1513 1514@item arm_hf_eabi 1515ARM target adheres to the VFP and Advanced SIMD Register Arguments 1516variant of the ABI for the ARM Architecture (as selected with 1517@code{-mfloat-abi=hard}). 1518 1519@item arm_hard_vfp_ok 1520ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. 1521Some multilibs may be incompatible with these options. 1522 1523@item arm_iwmmxt_ok 1524ARM target supports @code{-mcpu=iwmmxt}. 1525Some multilibs may be incompatible with this option. 1526 1527@item arm_neon 1528ARM target supports generating NEON instructions. 1529 1530@item arm_tune_string_ops_prefer_neon 1531Test CPU tune supports inlining string operations with NEON instructions. 1532 1533@item arm_neon_hw 1534Test system supports executing NEON instructions. 1535 1536@item arm_neonv2_hw 1537Test system supports executing NEON v2 instructions. 1538 1539@item arm_neon_ok 1540@anchor{arm_neon_ok} 1541ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible 1542options. Some multilibs may be incompatible with these options. 1543 1544@item arm_neonv2_ok 1545@anchor{arm_neonv2_ok} 1546ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible 1547options. Some multilibs may be incompatible with these options. 1548 1549@item arm_neon_fp16_ok 1550@anchor{arm_neon_fp16_ok} 1551ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible 1552options. Some multilibs may be incompatible with these options. 1553 1554@item arm_thumb1_ok 1555ARM target generates Thumb-1 code for @code{-mthumb}. 1556 1557@item arm_thumb2_ok 1558ARM target generates Thumb-2 code for @code{-mthumb}. 1559 1560@item arm_vfp_ok 1561ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. 1562Some multilibs may be incompatible with these options. 1563 1564@item arm_vfp3_ok 1565@anchor{arm_vfp3_ok} 1566ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}. 1567Some multilibs may be incompatible with these options. 1568 1569@item arm_v8_vfp_ok 1570ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}. 1571Some multilibs may be incompatible with these options. 1572 1573@item arm_v8_neon_ok 1574ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}. 1575Some multilibs may be incompatible with these options. 1576 1577@item arm_prefer_ldrd_strd 1578ARM target prefers @code{LDRD} and @code{STRD} instructions over 1579@code{LDM} and @code{STM} instructions. 1580 1581@end table 1582 1583@subsubsection MIPS-specific attributes 1584 1585@table @code 1586@item mips64 1587MIPS target supports 64-bit instructions. 1588 1589@item nomips16 1590MIPS target does not produce MIPS16 code. 1591 1592@item mips16_attribute 1593MIPS target can generate MIPS16 code. 1594 1595@item mips_loongson 1596MIPS target is a Loongson-2E or -2F target using an ABI that supports 1597the Loongson vector modes. 1598 1599@item mips_newabi_large_long_double 1600MIPS target supports @code{long double} larger than @code{double} 1601when using the new ABI. 1602 1603@item mpaired_single 1604MIPS target supports @code{-mpaired-single}. 1605@end table 1606 1607@subsubsection PowerPC-specific attributes 1608 1609@table @code 1610 1611@item dfp_hw 1612PowerPC target supports executing hardware DFP instructions. 1613 1614@item p8vector_hw 1615PowerPC target supports executing VSX instructions (ISA 2.07). 1616 1617@item powerpc64 1618Test system supports executing 64-bit instructions. 1619 1620@item powerpc_altivec 1621PowerPC target supports AltiVec. 1622 1623@item powerpc_altivec_ok 1624PowerPC target supports @code{-maltivec}. 1625 1626@item powerpc_eabi_ok 1627PowerPC target supports @code{-meabi}. 1628 1629@item powerpc_elfv2 1630PowerPC target supports @code{-mabi=elfv2}. 1631 1632@item powerpc_fprs 1633PowerPC target supports floating-point registers. 1634 1635@item powerpc_hard_double 1636PowerPC target supports hardware double-precision floating-point. 1637 1638@item powerpc_htm_ok 1639PowerPC target supports @code{-mhtm} 1640 1641@item powerpc_p8vector_ok 1642PowerPC target supports @code{-mpower8-vector} 1643 1644@item powerpc_ppu_ok 1645PowerPC target supports @code{-mcpu=cell}. 1646 1647@item powerpc_spe 1648PowerPC target supports PowerPC SPE. 1649 1650@item powerpc_spe_nocache 1651Including the options used to compile this particular test, the 1652PowerPC target supports PowerPC SPE. 1653 1654@item powerpc_spu 1655PowerPC target supports PowerPC SPU. 1656 1657@item powerpc_vsx_ok 1658PowerPC target supports @code{-mvsx}. 1659 1660@item powerpc_405_nocache 1661Including the options used to compile this particular test, the 1662PowerPC target supports PowerPC 405. 1663 1664@item ppc_recip_hw 1665PowerPC target supports executing reciprocal estimate instructions. 1666 1667@item spu_auto_overlay 1668SPU target has toolchain that supports automatic overlay generation. 1669 1670@item vmx_hw 1671PowerPC target supports executing AltiVec instructions. 1672 1673@item vsx_hw 1674PowerPC target supports executing VSX instructions (ISA 2.06). 1675@end table 1676 1677@subsubsection Other hardware attributes 1678 1679@table @code 1680@item avx 1681Target supports compiling @code{avx} instructions. 1682 1683@item avx_runtime 1684Target supports the execution of @code{avx} instructions. 1685 1686@item cell_hw 1687Test system can execute AltiVec and Cell PPU instructions. 1688 1689@item coldfire_fpu 1690Target uses a ColdFire FPU. 1691 1692@item hard_float 1693Target supports FPU instructions. 1694 1695@item non_strict_align 1696Target does not require strict alignment. 1697 1698@item sse 1699Target supports compiling @code{sse} instructions. 1700 1701@item sse_runtime 1702Target supports the execution of @code{sse} instructions. 1703 1704@item sse2 1705Target supports compiling @code{sse2} instructions. 1706 1707@item sse2_runtime 1708Target supports the execution of @code{sse2} instructions. 1709 1710@item sync_char_short 1711Target supports atomic operations on @code{char} and @code{short}. 1712 1713@item sync_int_long 1714Target supports atomic operations on @code{int} and @code{long}. 1715 1716@item ultrasparc_hw 1717Test environment appears to run executables on a simulator that 1718accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS} 1719or @code{EM_SPARCV9} executables. 1720 1721@item vect_cmdline_needed 1722Target requires a command line argument to enable a SIMD instruction set. 1723 1724@item pie_copyreloc 1725The x86-64 target linker supports PIE with copy reloc. 1726@end table 1727 1728@subsubsection Environment attributes 1729 1730@table @code 1731@item c 1732The language for the compiler under test is C. 1733 1734@item c++ 1735The language for the compiler under test is C++. 1736 1737@item c99_runtime 1738Target provides a full C99 runtime. 1739 1740@item correct_iso_cpp_string_wchar_protos 1741Target @code{string.h} and @code{wchar.h} headers provide C++ required 1742overloads for @code{strchr} etc. functions. 1743 1744@item dummy_wcsftime 1745Target uses a dummy @code{wcsftime} function that always returns zero. 1746 1747@item fd_truncate 1748Target can truncate a file from a file descriptor, as used by 1749@file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or 1750@code{chsize}. 1751 1752@item freestanding 1753Target is @samp{freestanding} as defined in section 4 of the C99 standard. 1754Effectively, it is a target which supports no extra headers or libraries 1755other than what is considered essential. 1756 1757@item init_priority 1758Target supports constructors with initialization priority arguments. 1759 1760@item inttypes_types 1761Target has the basic signed and unsigned types in @code{inttypes.h}. 1762This is for tests that GCC's notions of these types agree with those 1763in the header, as some systems have only @code{inttypes.h}. 1764 1765@item lax_strtofp 1766Target might have errors of a few ULP in string to floating-point 1767conversion functions and overflow is not always detected correctly by 1768those functions. 1769 1770@item mempcpy 1771Target provides @code{mempcpy} function. 1772 1773@item mmap 1774Target supports @code{mmap}. 1775 1776@item newlib 1777Target supports Newlib. 1778 1779@item pow10 1780Target provides @code{pow10} function. 1781 1782@item pthread 1783Target can compile using @code{pthread.h} with no errors or warnings. 1784 1785@item pthread_h 1786Target has @code{pthread.h}. 1787 1788@item run_expensive_tests 1789Expensive testcases (usually those that consume excessive amounts of CPU 1790time) should be run on this target. This can be enabled by setting the 1791@env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string. 1792 1793@item simulator 1794Test system runs executables on a simulator (i.e. slowly) rather than 1795hardware (i.e. fast). 1796 1797@item stabs 1798Target supports the stabs debugging format. 1799 1800@item stdint_types 1801Target has the basic signed and unsigned C types in @code{stdint.h}. 1802This will be obsolete when GCC ensures a working @code{stdint.h} for 1803all targets. 1804 1805@item stpcpy 1806Target provides @code{stpcpy} function. 1807 1808@item trampolines 1809Target supports trampolines. 1810 1811@item uclibc 1812Target supports uClibc. 1813 1814@item unwrapped 1815Target does not use a status wrapper. 1816 1817@item vxworks_kernel 1818Target is a VxWorks kernel. 1819 1820@item vxworks_rtp 1821Target is a VxWorks RTP. 1822 1823@item wchar 1824Target supports wide characters. 1825@end table 1826 1827@subsubsection Other attributes 1828 1829@table @code 1830@item automatic_stack_alignment 1831Target supports automatic stack alignment. 1832 1833@item cxa_atexit 1834Target uses @code{__cxa_atexit}. 1835 1836@item default_packed 1837Target has packed layout of structure members by default. 1838 1839@item fgraphite 1840Target supports Graphite optimizations. 1841 1842@item fixed_point 1843Target supports fixed-point extension to C. 1844 1845@item fopenacc 1846Target supports OpenACC via @option{-fopenacc}. 1847 1848@item fopenmp 1849Target supports OpenMP via @option{-fopenmp}. 1850 1851@item fpic 1852Target supports @option{-fpic} and @option{-fPIC}. 1853 1854@item freorder 1855Target supports @option{-freorder-blocks-and-partition}. 1856 1857@item fstack_protector 1858Target supports @option{-fstack-protector}. 1859 1860@item gas 1861Target uses GNU @command{as}. 1862 1863@item gc_sections 1864Target supports @option{--gc-sections}. 1865 1866@item gld 1867Target uses GNU @command{ld}. 1868 1869@item keeps_null_pointer_checks 1870Target keeps null pointer checks, either due to the use of 1871@option{-fno-delete-null-pointer-checks} or hardwired into the target. 1872 1873@item lto 1874Compiler has been configured to support link-time optimization (LTO). 1875 1876@item naked_functions 1877Target supports the @code{naked} function attribute. 1878 1879@item named_sections 1880Target supports named sections. 1881 1882@item natural_alignment_32 1883Target uses natural alignment (aligned to type size) for types of 188432 bits or less. 1885 1886@item target_natural_alignment_64 1887Target uses natural alignment (aligned to type size) for types of 188864 bits or less. 1889 1890@item nonpic 1891Target does not generate PIC by default. 1892 1893@item pie_enabled 1894Target generates PIE by default. 1895 1896@item pcc_bitfield_type_matters 1897Target defines @code{PCC_BITFIELD_TYPE_MATTERS}. 1898 1899@item pe_aligned_commons 1900Target supports @option{-mpe-aligned-commons}. 1901 1902@item pie 1903Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}. 1904 1905@item section_anchors 1906Target supports section anchors. 1907 1908@item short_enums 1909Target defaults to short enums. 1910 1911@item static 1912Target supports @option{-static}. 1913 1914@item static_libgfortran 1915Target supports statically linking @samp{libgfortran}. 1916 1917@item string_merging 1918Target supports merging string constants at link time. 1919 1920@item ucn 1921Target supports compiling and assembling UCN. 1922 1923@item ucn_nocache 1924Including the options used to compile this particular test, the 1925target supports compiling and assembling UCN. 1926 1927@item unaligned_stack 1928Target does not guarantee that its @code{STACK_BOUNDARY} is greater than 1929or equal to the required vector alignment. 1930 1931@item vector_alignment_reachable 1932Vector alignment is reachable for types of 32 bits or less. 1933 1934@item vector_alignment_reachable_for_64bit 1935Vector alignment is reachable for types of 64 bits or less. 1936 1937@item wchar_t_char16_t_compatible 1938Target supports @code{wchar_t} that is compatible with @code{char16_t}. 1939 1940@item wchar_t_char32_t_compatible 1941Target supports @code{wchar_t} that is compatible with @code{char32_t}. 1942 1943@item comdat_group 1944Target uses comdat groups. 1945@end table 1946 1947@subsubsection Local to tests in @code{gcc.target/i386} 1948 1949@table @code 1950@item 3dnow 1951Target supports compiling @code{3dnow} instructions. 1952 1953@item aes 1954Target supports compiling @code{aes} instructions. 1955 1956@item fma4 1957Target supports compiling @code{fma4} instructions. 1958 1959@item ms_hook_prologue 1960Target supports attribute @code{ms_hook_prologue}. 1961 1962@item pclmul 1963Target supports compiling @code{pclmul} instructions. 1964 1965@item sse3 1966Target supports compiling @code{sse3} instructions. 1967 1968@item sse4 1969Target supports compiling @code{sse4} instructions. 1970 1971@item sse4a 1972Target supports compiling @code{sse4a} instructions. 1973 1974@item ssse3 1975Target supports compiling @code{ssse3} instructions. 1976 1977@item vaes 1978Target supports compiling @code{vaes} instructions. 1979 1980@item vpclmul 1981Target supports compiling @code{vpclmul} instructions. 1982 1983@item xop 1984Target supports compiling @code{xop} instructions. 1985@end table 1986 1987@subsubsection Local to tests in @code{gcc.target/spu/ea} 1988 1989@table @code 1990@item ealib 1991Target @code{__ea} library functions are available. 1992@end table 1993 1994@subsubsection Local to tests in @code{gcc.test-framework} 1995 1996@table @code 1997@item no 1998Always returns 0. 1999 2000@item yes 2001Always returns 1. 2002@end table 2003 2004@node Add Options 2005@subsection Features for @code{dg-add-options} 2006 2007The supported values of @var{feature} for directive @code{dg-add-options} 2008are: 2009 2010@table @code 2011@item arm_neon 2012NEON support. Only ARM targets support this feature, and only then 2013in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target 2014keyword}. 2015 2016@item arm_neon_fp16 2017NEON and half-precision floating point support. Only ARM targets 2018support this feature, and only then in certain modes; see 2019the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}. 2020 2021@item arm_vfp3 2022arm vfp3 floating point support; see 2023the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}. 2024 2025@item bind_pic_locally 2026Add the target-specific flags needed to enable functions to bind 2027locally when using pic/PIC passes in the testsuite. 2028 2029@item c99_runtime 2030Add the target-specific flags needed to access the C99 runtime. 2031 2032@item ieee 2033Add the target-specific flags needed to enable full IEEE 2034compliance mode. 2035 2036@item mips16_attribute 2037@code{mips16} function attributes. 2038Only MIPS targets support this feature, and only then in certain modes. 2039 2040@item tls 2041Add the target-specific flags needed to use thread-local storage. 2042@end table 2043 2044@node Require Support 2045@subsection Variants of @code{dg-require-@var{support}} 2046 2047A few of the @code{dg-require} directives take arguments. 2048 2049@table @code 2050@item dg-require-iconv @var{codeset} 2051Skip the test if the target does not support iconv. @var{codeset} is 2052the codeset to convert to. 2053 2054@item dg-require-profiling @var{profopt} 2055Skip the test if the target does not support profiling with option 2056@var{profopt}. 2057 2058@item dg-require-visibility @var{vis} 2059Skip the test if the target does not support the @code{visibility} attribute. 2060If @var{vis} is @code{""}, support for @code{visibility("hidden")} is 2061checked, for @code{visibility("@var{vis}")} otherwise. 2062@end table 2063 2064The original @code{dg-require} directives were defined before there 2065was support for effective-target keywords. The directives that do not 2066take arguments could be replaced with effective-target keywords. 2067 2068@table @code 2069@item dg-require-alias "" 2070Skip the test if the target does not support the @samp{alias} attribute. 2071 2072@item dg-require-ascii-locale "" 2073Skip the test if the host does not support an ASCII locale. 2074 2075@item dg-require-compat-dfp "" 2076Skip this test unless both compilers in a @file{compat} testsuite 2077support decimal floating point. 2078 2079@item dg-require-cxa-atexit "" 2080Skip the test if the target does not support @code{__cxa_atexit}. 2081This is equivalent to @code{dg-require-effective-target cxa_atexit}. 2082 2083@item dg-require-dll "" 2084Skip the test if the target does not support DLL attributes. 2085 2086@item dg-require-fork "" 2087Skip the test if the target does not support @code{fork}. 2088 2089@item dg-require-gc-sections "" 2090Skip the test if the target's linker does not support the 2091@code{--gc-sections} flags. 2092This is equivalent to @code{dg-require-effective-target gc-sections}. 2093 2094@item dg-require-host-local "" 2095Skip the test if the host is remote, rather than the same as the build 2096system. Some tests are incompatible with DejaGnu's handling of remote 2097hosts, which involves copying the source file to the host and compiling 2098it with a relative path and "@code{-o a.out}". 2099 2100@item dg-require-mkfifo "" 2101Skip the test if the target does not support @code{mkfifo}. 2102 2103@item dg-require-named-sections "" 2104Skip the test is the target does not support named sections. 2105This is equivalent to @code{dg-require-effective-target named_sections}. 2106 2107@item dg-require-weak "" 2108Skip the test if the target does not support weak symbols. 2109 2110@item dg-require-weak-override "" 2111Skip the test if the target does not support overriding weak symbols. 2112@end table 2113 2114@node Final Actions 2115@subsection Commands for use in @code{dg-final} 2116 2117The GCC testsuite defines the following directives to be used within 2118@code{dg-final}. 2119 2120@subsubsection Scan a particular file 2121 2122@table @code 2123@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 2124Passes if @var{regexp} matches text in @var{filename}. 2125@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 2126Passes if @var{regexp} does not match text in @var{filename}. 2127@item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}] 2128Passes if @var{regexp} matches in Fortran module @var{module}. 2129@end table 2130 2131@subsubsection Scan the assembly output 2132 2133@table @code 2134@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] 2135Passes if @var{regex} matches text in the test's assembler output. 2136 2137@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] 2138Passes if @var{regex} does not match text in the test's assembler output. 2139 2140@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] 2141Passes if @var{regex} is matched exactly @var{num} times in the test's 2142assembler output. 2143 2144@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] 2145Passes if @var{regex} matches text in the test's demangled assembler output. 2146 2147@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] 2148Passes if @var{regex} does not match text in the test's demangled assembler 2149output. 2150 2151@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 2152Passes if @var{symbol} is defined as a hidden symbol in the test's 2153assembly output. 2154 2155@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 2156Passes if @var{symbol} is not defined as a hidden symbol in the test's 2157assembly output. 2158@end table 2159 2160@subsubsection Scan optimization dump files 2161 2162These commands are available for @var{kind} of @code{tree}, @code{rtl}, 2163and @code{ipa}. 2164 2165@table @code 2166@item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2167Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. 2168 2169@item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2170Passes if @var{regex} does not match text in the dump file with suffix 2171@var{suffix}. 2172 2173@item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] 2174Passes if @var{regex} is found exactly @var{num} times in the dump file 2175with suffix @var{suffix}. 2176 2177@item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2178Passes if @var{regex} matches demangled text in the dump file with 2179suffix @var{suffix}. 2180 2181@item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2182Passes if @var{regex} does not match demangled text in the dump file with 2183suffix @var{suffix}. 2184@end table 2185 2186@subsubsection Verify that an output files exists or not 2187 2188@table @code 2189@item output-exists [@{ target/xfail @var{selector} @}] 2190Passes if compiler output file exists. 2191 2192@item output-exists-not [@{ target/xfail @var{selector} @}] 2193Passes if compiler output file does not exist. 2194@end table 2195 2196@subsubsection Check for LTO tests 2197 2198@table @code 2199@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] 2200Passes if the pattern is present in the final executable. 2201@end table 2202 2203@subsubsection Checks for @command{gcov} tests 2204 2205@table @code 2206@item run-gcov @var{sourcefile} 2207Check line counts in @command{gcov} tests. 2208 2209@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} 2210Check branch and/or call counts, in addition to line counts, in 2211@command{gcov} tests. 2212@end table 2213 2214@subsubsection Clean up generated test files 2215 2216@table @code 2217@item cleanup-coverage-files 2218Removes coverage data files generated for this test. 2219 2220@item cleanup-ipa-dump @var{suffix} 2221Removes IPA dump files generated for this test. 2222 2223@item cleanup-modules "@var{list-of-extra-modules}" 2224Removes Fortran module files generated for this test, excluding the 2225module names listed in keep-modules. 2226Cleaning up module files is usually done automatically by the testsuite 2227by looking at the source files and removing the modules after the test 2228has been executed. 2229@smallexample 2230module MoD1 2231end module MoD1 2232module Mod2 2233end module Mod2 2234module moD3 2235end module moD3 2236module mod4 2237end module mod4 2238! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant 2239! @{ dg-final @{ keep-modules "mod3 mod4" @} @} 2240@end smallexample 2241 2242@item keep-modules "@var{list-of-modules-not-to-delete}" 2243Whitespace separated list of module names that should not be deleted by 2244cleanup-modules. 2245If the list of modules is empty, all modules defined in this file are kept. 2246@smallexample 2247module maybe_unneeded 2248end module maybe_unneeded 2249module keep1 2250end module keep1 2251module keep2 2252end module keep2 2253! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two 2254! @{ dg-final @{ keep-modules "" @} @} ! keep all 2255@end smallexample 2256 2257@item cleanup-profile-file 2258Removes profiling files generated for this test. 2259 2260@item cleanup-repo-files 2261Removes files generated for this test for @option{-frepo}. 2262 2263@item cleanup-rtl-dump @var{suffix} 2264Removes RTL dump files generated for this test. 2265 2266@item cleanup-saved-temps 2267Removes files for the current test which were kept for @option{-save-temps}. 2268 2269@item cleanup-tree-dump @var{suffix} 2270Removes tree dump files matching @var{suffix} which were generated for 2271this test. 2272@end table 2273 2274@node Ada Tests 2275@section Ada Language Testsuites 2276 2277The Ada testsuite includes executable tests from the ACATS 2278testsuite, publicly available at 2279@uref{http://www.ada-auth.org/acats.html}. 2280 2281These tests are integrated in the GCC testsuite in the 2282@file{ada/acats} directory, and 2283enabled automatically when running @code{make check}, assuming 2284the Ada language has been enabled when configuring GCC@. 2285 2286You can also run the Ada testsuite independently, using 2287@code{make check-ada}, or run a subset of the tests by specifying which 2288chapter to run, e.g.: 2289 2290@smallexample 2291$ make check-ada CHAPTERS="c3 c9" 2292@end smallexample 2293 2294The tests are organized by directory, each directory corresponding to 2295a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds 2296to chapter 9, which deals with tasking features of the language. 2297 2298There is also an extra chapter called @file{gcc} containing a template for 2299creating new executable tests, although this is deprecated in favor of 2300the @file{gnat.dg} testsuite. 2301 2302The tests are run using two @command{sh} scripts: @file{run_acats} and 2303@file{run_all.sh}. To run the tests using a simulator or a cross 2304target, see the small 2305customization section at the top of @file{run_all.sh}. 2306 2307These tests are run using the build tree: they can be run without doing 2308a @code{make install}. 2309 2310@node C Tests 2311@section C Language Testsuites 2312 2313GCC contains the following C language testsuites, in the 2314@file{gcc/testsuite} directory: 2315 2316@table @file 2317@item gcc.dg 2318This contains tests of particular features of the C compiler, using the 2319more modern @samp{dg} harness. Correctness tests for various compiler 2320features should go here if possible. 2321 2322Magic comments determine whether the file 2323is preprocessed, compiled, linked or run. In these tests, error and warning 2324message texts are compared against expected texts or regular expressions 2325given in comments. These tests are run with the options @samp{-ansi -pedantic} 2326unless other options are given in the test. Except as noted below they 2327are not run with multiple optimization options. 2328@item gcc.dg/compat 2329This subdirectory contains tests for binary compatibility using 2330@file{lib/compat.exp}, which in turn uses the language-independent support 2331(@pxref{compat Testing, , Support for testing binary compatibility}). 2332@item gcc.dg/cpp 2333This subdirectory contains tests of the preprocessor. 2334@item gcc.dg/debug 2335This subdirectory contains tests for debug formats. Tests in this 2336subdirectory are run for each debug format that the compiler supports. 2337@item gcc.dg/format 2338This subdirectory contains tests of the @option{-Wformat} format 2339checking. Tests in this directory are run with and without 2340@option{-DWIDE}. 2341@item gcc.dg/noncompile 2342This subdirectory contains tests of code that should not compile and 2343does not need any special compilation options. They are run with 2344multiple optimization options, since sometimes invalid code crashes 2345the compiler with optimization. 2346@item gcc.dg/special 2347FIXME: describe this. 2348 2349@item gcc.c-torture 2350This contains particular code fragments which have historically broken easily. 2351These tests are run with multiple optimization options, so tests for features 2352which only break at some optimization levels belong here. This also contains 2353tests to check that certain optimizations occur. It might be worthwhile to 2354separate the correctness tests cleanly from the code quality tests, but 2355it hasn't been done yet. 2356 2357@item gcc.c-torture/compat 2358FIXME: describe this. 2359 2360This directory should probably not be used for new tests. 2361@item gcc.c-torture/compile 2362This testsuite contains test cases that should compile, but do not 2363need to link or run. These test cases are compiled with several 2364different combinations of optimization options. All warnings are 2365disabled for these test cases, so this directory is not suitable if 2366you wish to test for the presence or absence of compiler warnings. 2367While special options can be set, and tests disabled on specific 2368platforms, by the use of @file{.x} files, mostly these test cases 2369should not contain platform dependencies. FIXME: discuss how defines 2370such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. 2371@item gcc.c-torture/execute 2372This testsuite contains test cases that should compile, link and run; 2373otherwise the same comments as for @file{gcc.c-torture/compile} apply. 2374@item gcc.c-torture/execute/ieee 2375This contains tests which are specific to IEEE floating point. 2376@item gcc.c-torture/unsorted 2377FIXME: describe this. 2378 2379This directory should probably not be used for new tests. 2380@item gcc.misc-tests 2381This directory contains C tests that require special handling. Some 2382of these tests have individual expect files, and others share 2383special-purpose expect files: 2384 2385@table @file 2386@item @code{bprob*.c} 2387Test @option{-fbranch-probabilities} using 2388@file{gcc.misc-tests/bprob.exp}, which 2389in turn uses the generic, language-independent framework 2390(@pxref{profopt Testing, , Support for testing profile-directed 2391optimizations}). 2392 2393@item @code{gcov*.c} 2394Test @command{gcov} output using @file{gcov.exp}, which in turn uses the 2395language-independent support (@pxref{gcov Testing, , Support for testing gcov}). 2396 2397@item @code{i386-pf-*.c} 2398Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. 2399@end table 2400 2401@item gcc.test-framework 2402@table @file 2403@item @code{dg-*.c} 2404Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}. 2405@end table 2406 2407@end table 2408 2409FIXME: merge in @file{testsuite/README.gcc} and discuss the format of 2410test cases and magic comments more. 2411 2412@node libgcj Tests 2413@section The Java library testsuites. 2414 2415Runtime tests are executed via @samp{make check} in the 2416@file{@var{target}/libjava/testsuite} directory in the build 2417tree. Additional runtime tests can be checked into this testsuite. 2418 2419Regression testing of the core packages in libgcj is also covered by the 2420Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} 2421develops tests for the Java Class Libraries. These tests are run as part 2422of libgcj testing by placing the Mauve tree within the libjava testsuite 2423sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying 2424the location of that tree when invoking @samp{make}, as in 2425@samp{make MAUVEDIR=~/mauve check}. 2426 2427To detect regressions, a mechanism in @file{mauve.exp} compares the 2428failures for a test run against the list of expected failures in 2429@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. 2430Update this file when adding new failing tests to Mauve, or when fixing 2431bugs in libgcj that had caused Mauve test failures. 2432 2433We encourage developers to contribute test cases to Mauve. 2434 2435@node LTO Testing 2436@section Support for testing link-time optimizations 2437 2438Tests for link-time optimizations usually require multiple source files 2439that are compiled separately, perhaps with different sets of options. 2440There are several special-purpose test directives used for these tests. 2441 2442@table @code 2443@item @{ dg-lto-do @var{do-what-keyword} @} 2444@var{do-what-keyword} specifies how the test is compiled and whether 2445it is executed. It is one of: 2446 2447@table @code 2448@item assemble 2449Compile with @option{-c} to produce a relocatable object file. 2450@item link 2451Compile, assemble, and link to produce an executable file. 2452@item run 2453Produce and run an executable file, which is expected to return 2454an exit code of 0. 2455@end table 2456 2457The default is @code{assemble}. That can be overridden for a set of 2458tests by redefining @code{dg-do-what-default} within the @code{.exp} 2459file for those tests. 2460 2461Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional 2462@samp{target} or @samp{xfail} list. Use @code{dg-skip-if}, 2463@code{dg-xfail-if}, or @code{dg-xfail-run-if}. 2464 2465@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} 2466This directive provides a list of one or more sets of compiler options 2467to override @var{LTO_OPTIONS}. Each test will be compiled and run with 2468each of these sets of options. 2469 2470@item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@} 2471This directive adds @var{options} to the linker options used. 2472 2473@item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@} 2474This directive removes @var{options} from the set of linker options used. 2475@end table 2476 2477@node gcov Testing 2478@section Support for testing @command{gcov} 2479 2480Language-independent support for testing @command{gcov}, and for checking 2481that branch profiling produces expected values, is provided by the 2482expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures 2483in @file{lib/gcc-dg.exp} to compile and run the test program. A typical 2484@command{gcov} test contains the following DejaGnu commands within comments: 2485 2486@smallexample 2487@{ dg-options "-fprofile-arcs -ftest-coverage" @} 2488@{ dg-do run @{ target native @} @} 2489@{ dg-final @{ run-gcov sourcefile @} @} 2490@end smallexample 2491 2492Checks of @command{gcov} output can include line counts, branch percentages, 2493and call return percentages. All of these checks are requested via 2494commands that appear in comments in the test's source file. 2495Commands to check line counts are processed by default. 2496Commands to check branch percentages and call return percentages are 2497processed if the @command{run-gcov} command has arguments @code{branches} 2498or @code{calls}, respectively. For example, the following specifies 2499checking both, as well as passing @option{-b} to @command{gcov}: 2500 2501@smallexample 2502@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} 2503@end smallexample 2504 2505A line count command appears within a comment on the source line 2506that is expected to get the specified count and has the form 2507@code{count(@var{cnt})}. A test should only check line counts for 2508lines that will get the same count for any architecture. 2509 2510Commands to check branch percentages (@code{branch}) and call 2511return percentages (@code{returns}) are very similar to each other. 2512A beginning command appears on or before the first of a range of 2513lines that will report the percentage, and the ending command 2514follows that range of lines. The beginning command can include a 2515list of percentages, all of which are expected to be found within 2516the range. A range is terminated by the next command of the same 2517kind. A command @code{branch(end)} or @code{returns(end)} marks 2518the end of a range without starting a new one. For example: 2519 2520@smallexample 2521if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ 2522 /* @r{branch(end)} */ 2523 foo (i, j); 2524@end smallexample 2525 2526For a call return percentage, the value specified is the 2527percentage of calls reported to return. For a branch percentage, 2528the value is either the expected percentage or 100 minus that 2529value, since the direction of a branch can differ depending on the 2530target or the optimization level. 2531 2532Not all branches and calls need to be checked. A test should not 2533check for branches that might be optimized away or replaced with 2534predicated instructions. Don't check for calls inserted by the 2535compiler or ones that might be inlined or optimized away. 2536 2537A single test can check for combinations of line counts, branch 2538percentages, and call return percentages. The command to check a 2539line count must appear on the line that will report that count, but 2540commands to check branch percentages and call return percentages can 2541bracket the lines that report them. 2542 2543@node profopt Testing 2544@section Support for testing profile-directed optimizations 2545 2546The file @file{profopt.exp} provides language-independent support for 2547checking correct execution of a test built with profile-directed 2548optimization. This testing requires that a test program be built and 2549executed twice. The first time it is compiled to generate profile 2550data, and the second time it is compiled to use the data that was 2551generated during the first execution. The second execution is to 2552verify that the test produces the expected results. 2553 2554To check that the optimization actually generated better code, a 2555test can be built and run a third time with normal optimizations to 2556verify that the performance is better with the profile-directed 2557optimizations. @file{profopt.exp} has the beginnings of this kind 2558of support. 2559 2560@file{profopt.exp} provides generic support for profile-directed 2561optimizations. Each set of tests that uses it provides information 2562about a specific optimization: 2563 2564@table @code 2565@item tool 2566tool being tested, e.g., @command{gcc} 2567 2568@item profile_option 2569options used to generate profile data 2570 2571@item feedback_option 2572options used to optimize using that profile data 2573 2574@item prof_ext 2575suffix of profile data files 2576 2577@item PROFOPT_OPTIONS 2578list of options with which to run each test, similar to the lists for 2579torture tests 2580 2581@item @{ dg-final-generate @{ @var{local-directive} @} @} 2582This directive is similar to @code{dg-final}, but the 2583@var{local-directive} is run after the generation of profile data. 2584 2585@item @{ dg-final-use @{ @var{local-directive} @} @} 2586The @var{local-directive} is run after the profile data have been 2587used. 2588@end table 2589 2590@node compat Testing 2591@section Support for testing binary compatibility 2592 2593The file @file{compat.exp} provides language-independent support for 2594binary compatibility testing. It supports testing interoperability of 2595two compilers that follow the same ABI, or of multiple sets of 2596compiler options that should not affect binary compatibility. It is 2597intended to be used for testsuites that complement ABI testsuites. 2598 2599A test supported by this framework has three parts, each in a 2600separate source file: a main program and two pieces that interact 2601with each other to split up the functionality being tested. 2602 2603@table @file 2604@item @var{testname}_main.@var{suffix} 2605Contains the main program, which calls a function in file 2606@file{@var{testname}_x.@var{suffix}}. 2607 2608@item @var{testname}_x.@var{suffix} 2609Contains at least one call to a function in 2610@file{@var{testname}_y.@var{suffix}}. 2611 2612@item @var{testname}_y.@var{suffix} 2613Shares data with, or gets arguments from, 2614@file{@var{testname}_x.@var{suffix}}. 2615@end table 2616 2617Within each test, the main program and one functional piece are 2618compiled by the GCC under test. The other piece can be compiled by 2619an alternate compiler. If no alternate compiler is specified, 2620then all three source files are all compiled by the GCC under test. 2621You can specify pairs of sets of compiler options. The first element 2622of such a pair specifies options used with the GCC under test, and the 2623second element of the pair specifies options used with the alternate 2624compiler. Each test is compiled with each pair of options. 2625 2626@file{compat.exp} defines default pairs of compiler options. 2627These can be overridden by defining the environment variable 2628@env{COMPAT_OPTIONS} as: 2629 2630@smallexample 2631COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] 2632 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]" 2633@end smallexample 2634 2635where @var{tsti} and @var{alti} are lists of options, with @var{tsti} 2636used by the compiler under test and @var{alti} used by the alternate 2637compiler. For example, with 2638@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, 2639the test is first built with @option{-g -O0} by the compiler under 2640test and with @option{-O3} by the alternate compiler. The test is 2641built a second time using @option{-fpic} by the compiler under test 2642and @option{-fPIC -O2} by the alternate compiler. 2643 2644An alternate compiler is specified by defining an environment 2645variable to be the full pathname of an installed compiler; for C 2646define @env{ALT_CC_UNDER_TEST}, and for C++ define 2647@env{ALT_CXX_UNDER_TEST}. These will be written to the 2648@file{site.exp} file used by DejaGnu. The default is to build each 2649test with the compiler under test using the first of each pair of 2650compiler options from @env{COMPAT_OPTIONS}. When 2651@env{ALT_CC_UNDER_TEST} or 2652@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using 2653the compiler under test but with combinations of the options from 2654@env{COMPAT_OPTIONS}. 2655 2656To run only the C++ compatibility suite using the compiler under test 2657and another version of GCC using specific compiler options, do the 2658following from @file{@var{objdir}/gcc}: 2659 2660@smallexample 2661rm site.exp 2662make -k \ 2663 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ 2664 COMPAT_OPTIONS="@var{lists as shown above}" \ 2665 check-c++ \ 2666 RUNTESTFLAGS="compat.exp" 2667@end smallexample 2668 2669A test that fails when the source files are compiled with different 2670compilers, but passes when the files are compiled with the same 2671compiler, demonstrates incompatibility of the generated code or 2672runtime support. A test that fails for the alternate compiler but 2673passes for the compiler under test probably tests for a bug that was 2674fixed in the compiler under test but is present in the alternate 2675compiler. 2676 2677The binary compatibility tests support a small number of test framework 2678commands that appear within comments in a test file. 2679 2680@table @code 2681@item dg-require-* 2682These commands can be used in @file{@var{testname}_main.@var{suffix}} 2683to skip the test if specific support is not available on the target. 2684 2685@item dg-options 2686The specified options are used for compiling this particular source 2687file, appended to the options from @env{COMPAT_OPTIONS}. When this 2688command appears in @file{@var{testname}_main.@var{suffix}} the options 2689are also used to link the test program. 2690 2691@item dg-xfail-if 2692This command can be used in a secondary source file to specify that 2693compilation is expected to fail for particular options on particular 2694targets. 2695@end table 2696 2697@node Torture Tests 2698@section Support for torture testing using multiple options 2699 2700Throughout the compiler testsuite there are several directories whose 2701tests are run multiple times, each with a different set of options. 2702These are known as torture tests. 2703@file{lib/torture-options.exp} defines procedures to 2704set up these lists: 2705 2706@table @code 2707@item torture-init 2708Initialize use of torture lists. 2709@item set-torture-options 2710Set lists of torture options to use for tests with and without loops. 2711Optionally combine a set of torture options with a set of other 2712options, as is done with Objective-C runtime options. 2713@item torture-finish 2714Finalize use of torture lists. 2715@end table 2716 2717The @file{.exp} file for a set of tests that use torture options must 2718include calls to these three procedures if: 2719 2720@itemize @bullet 2721@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}. 2722 2723@item It calls @var{$@{tool@}}@code{-torture} or 2724@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c}, 2725@code{fortran}, or @code{objc}. 2726 2727@item It calls @code{dg-pch}. 2728@end itemize 2729 2730It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest} 2731to call the torture procedures if the tests should use the list in 2732@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}. 2733 2734Most uses of torture options can override the default lists by defining 2735@var{TORTURE_OPTIONS} or add to the default list by defining 2736@var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc} 2737file or add them to the @file{site.exp} file; for example 2738 2739@smallexample 2740set ADDITIONAL_TORTURE_OPTIONS [list \ 2741 @{ -O2 -ftree-loop-linear @} \ 2742 @{ -O2 -fpeel-loops @} ] 2743@end smallexample 2744