1@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010, 2011 2@c Free Software Foundation, Inc. 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@node Source Tree 7@chapter Source Tree Structure and Build System 8 9This chapter describes the structure of the GCC source tree, and how 10GCC is built. The user documentation for building and installing GCC 11is in a separate manual (@uref{http://gcc.gnu.org/install/}), with 12which it is presumed that you are familiar. 13 14@menu 15* Configure Terms:: Configuration terminology and history. 16* Top Level:: The top level source directory. 17* gcc Directory:: The @file{gcc} subdirectory. 18@end menu 19 20@include configterms.texi 21 22@node Top Level 23@section Top Level Source Directory 24 25The top level source directory in a GCC distribution contains several 26files and directories that are shared with other software 27distributions such as that of GNU Binutils. It also contains several 28subdirectories that contain parts of GCC and its runtime libraries: 29 30@table @file 31@item boehm-gc 32The Boehm conservative garbage collector, used as part of the Java 33runtime library. 34 35@item config 36Autoconf macros and Makefile fragments used throughout the tree. 37 38@item contrib 39Contributed scripts that may be found useful in conjunction with GCC@. 40One of these, @file{contrib/texi2pod.pl}, is used to generate man 41pages from Texinfo manuals as part of the GCC build process. 42 43@item fixincludes 44The support for fixing system headers to work with GCC@. See 45@file{fixincludes/README} for more information. The headers fixed by 46this mechanism are installed in @file{@var{libsubdir}/include-fixed}. 47Along with those headers, @file{README-fixinc} is also installed, as 48@file{@var{libsubdir}/include-fixed/README}. 49 50@item gcc 51The main sources of GCC itself (except for runtime libraries), 52including optimizers, support for different target architectures, 53language front ends, and testsuites. @xref{gcc Directory, , The 54@file{gcc} Subdirectory}, for details. 55 56@item gnattools 57Support tools for GNAT. 58 59@item include 60Headers for the @code{libiberty} library. 61 62@item intl 63GNU @code{libintl}, from GNU @code{gettext}, for systems which do not 64include it in @code{libc}. 65 66@item libada 67The Ada runtime library. 68 69@item libcpp 70The C preprocessor library. 71 72@item libdecnumber 73The Decimal Float support library. 74 75@item libffi 76The @code{libffi} library, used as part of the Java runtime library. 77 78@item libgcc 79The GCC runtime library. 80 81@item libgfortran 82The Fortran runtime library. 83 84@item libgomp 85The GNU OpenMP runtime library. 86 87@item libiberty 88The @code{libiberty} library, used for portability and for some 89generally useful data structures and algorithms. @xref{Top, , 90Introduction, libiberty, @sc{gnu} libiberty}, for more information 91about this library. 92 93@item libjava 94The Java runtime library. 95 96@item libmudflap 97The @code{libmudflap} library, used for instrumenting pointer and array 98dereferencing operations. 99 100@item libobjc 101The Objective-C and Objective-C++ runtime library. 102 103@item libssp 104The Stack protector runtime library. 105 106@item libstdc++-v3 107The C++ runtime library. 108 109@item lto-plugin 110Plugin used by @command{gold} if link-time optimizations are enabled. 111 112@item maintainer-scripts 113Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. 114 115@item zlib 116The @code{zlib} compression library, used by the Java front end, as 117part of the Java runtime library, and for compressing and uncompressing 118GCC's intermediate language in LTO object files. 119@end table 120 121The build system in the top level directory, including how recursion 122into subdirectories works and how building runtime libraries for 123multilibs is handled, is documented in a separate manual, included 124with GNU Binutils. @xref{Top, , GNU configure and build system, 125configure, The GNU configure and build system}, for details. 126 127@node gcc Directory 128@section The @file{gcc} Subdirectory 129 130The @file{gcc} directory contains many files that are part of the C 131sources of GCC, other files used as part of the configuration and 132build process, and subdirectories including documentation and a 133testsuite. The files that are sources of GCC are documented in a 134separate chapter. @xref{Passes, , Passes and Files of the Compiler}. 135 136@menu 137* Subdirectories:: Subdirectories of @file{gcc}. 138* Configuration:: The configuration process, and the files it uses. 139* Build:: The build system in the @file{gcc} directory. 140* Makefile:: Targets in @file{gcc/Makefile}. 141* Library Files:: Library source files and headers under @file{gcc/}. 142* Headers:: Headers installed by GCC. 143* Documentation:: Building documentation in GCC. 144* Front End:: Anatomy of a language front end. 145* Back End:: Anatomy of a target back end. 146@end menu 147 148@node Subdirectories 149@subsection Subdirectories of @file{gcc} 150 151The @file{gcc} directory contains the following subdirectories: 152 153@table @file 154@item @var{language} 155Subdirectories for various languages. Directories containing a file 156@file{config-lang.in} are language subdirectories. The contents of 157the subdirectories @file{cp} (for C++), @file{lto} (for LTO), 158@file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are 159documented in this manual (@pxref{Passes, , Passes and Files of the 160Compiler}); those for other languages are not. @xref{Front End, , 161Anatomy of a Language Front End}, for details of the files in these 162directories. 163 164@item config 165Configuration files for supported architectures and operating 166systems. @xref{Back End, , Anatomy of a Target Back End}, for 167details of the files in this directory. 168 169@item doc 170Texinfo documentation for GCC, together with automatically generated 171man pages and support for converting the installation manual to 172HTML@. @xref{Documentation}. 173 174@item ginclude 175System headers installed by GCC, mainly those required by the C 176standard of freestanding implementations. @xref{Headers, , Headers 177Installed by GCC}, for details of when these and other headers are 178installed. 179 180@item po 181Message catalogs with translations of messages produced by GCC into 182various languages, @file{@var{language}.po}. This directory also 183contains @file{gcc.pot}, the template for these message catalogues, 184@file{exgettext}, a wrapper around @command{gettext} to extract the 185messages from the GCC sources and create @file{gcc.pot}, which is run 186by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from 187which messages should not be extracted. 188 189@item testsuite 190The GCC testsuites (except for those for runtime libraries). 191@xref{Testsuites}. 192@end table 193 194@node Configuration 195@subsection Configuration in the @file{gcc} Directory 196 197The @file{gcc} directory is configured with an Autoconf-generated 198script @file{configure}. The @file{configure} script is generated 199from @file{configure.ac} and @file{aclocal.m4}. From the files 200@file{configure.ac} and @file{acconfig.h}, Autoheader generates the 201file @file{config.in}. The file @file{cstamp-h.in} is used as a 202timestamp. 203 204@menu 205* Config Fragments:: Scripts used by @file{configure}. 206* System Config:: The @file{config.build}, @file{config.host}, and 207 @file{config.gcc} files. 208* Configuration Files:: Files created by running @file{configure}. 209@end menu 210 211@node Config Fragments 212@subsubsection Scripts Used by @file{configure} 213 214@file{configure} uses some other scripts to help in its work: 215 216@itemize @bullet 217@item The standard GNU @file{config.sub} and @file{config.guess} 218files, kept in the top level directory, are used. 219 220@item The file @file{config.gcc} is used to handle configuration 221specific to the particular target machine. The file 222@file{config.build} is used to handle configuration specific to the 223particular build machine. The file @file{config.host} is used to handle 224configuration specific to the particular host machine. (In general, 225these should only be used for features that cannot reasonably be tested in 226Autoconf feature tests.) 227@xref{System Config, , The @file{config.build}; @file{config.host}; 228and @file{config.gcc} Files}, for details of the contents of these files. 229 230@item Each language subdirectory has a file 231@file{@var{language}/config-lang.in} that is used for 232front-end-specific configuration. @xref{Front End Config, , The Front 233End @file{config-lang.in} File}, for details of this file. 234 235@item A helper script @file{configure.frag} is used as part of 236creating the output of @file{configure}. 237@end itemize 238 239@node System Config 240@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files 241 242The @file{config.build} file contains specific rules for particular systems 243which GCC is built on. This should be used as rarely as possible, as the 244behavior of the build system can always be detected by autoconf. 245 246The @file{config.host} file contains specific rules for particular systems 247which GCC will run on. This is rarely needed. 248 249The @file{config.gcc} file contains specific rules for particular systems 250which GCC will generate code for. This is usually needed. 251 252Each file has a list of the shell variables it sets, with descriptions, at the 253top of the file. 254 255FIXME: document the contents of these files, and what variables should 256be set to control build, host and target configuration. 257 258@include configfiles.texi 259 260@node Build 261@subsection Build System in the @file{gcc} Directory 262 263FIXME: describe the build system, including what is built in what 264stages. Also list the various source files that are used in the build 265process but aren't source files of GCC itself and so aren't documented 266below (@pxref{Passes}). 267 268@include makefile.texi 269 270@node Library Files 271@subsection Library Source Files and Headers under the @file{gcc} Directory 272 273FIXME: list here, with explanation, all the C source files and headers 274under the @file{gcc} directory that aren't built into the GCC 275executable but rather are part of runtime libraries and object files, 276such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , 277Headers Installed by GCC}, for more information about the 278@file{ginclude} directory. 279 280@node Headers 281@subsection Headers Installed by GCC 282 283In general, GCC expects the system C library to provide most of the 284headers to be used with it. However, GCC will fix those headers if 285necessary to make them work with GCC, and will install some headers 286required of freestanding implementations. These headers are installed 287in @file{@var{libsubdir}/include}. Headers for non-C runtime 288libraries are also installed by GCC; these are not documented here. 289(FIXME: document them somewhere.) 290 291Several of the headers GCC installs are in the @file{ginclude} 292directory. These headers, @file{iso646.h}, 293@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, 294are installed in @file{@var{libsubdir}/include}, 295unless the target Makefile fragment (@pxref{Target Fragment}) 296overrides this by setting @code{USER_H}. 297 298In addition to these headers and those generated by fixing system 299headers to work with GCC, some other headers may also be installed in 300@file{@var{libsubdir}/include}. @file{config.gcc} may set 301@code{extra_headers}; this specifies additional headers under 302@file{config} to be installed on some systems. 303 304GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. 305This is done to cope with command-line options that change the 306representation of floating point numbers. 307 308GCC also installs its own version of @code{<limits.h>}; this is generated 309from @file{glimits.h}, together with @file{limitx.h} and 310@file{limity.h} if the system also has its own version of 311@code{<limits.h>}. (GCC provides its own header because it is 312required of ISO C freestanding implementations, but needs to include 313the system header from its own header as well because other standards 314such as POSIX specify additional values to be defined in 315@code{<limits.h>}.) The system's @code{<limits.h>} header is used via 316@file{@var{libsubdir}/include/syslimits.h}, which is copied from 317@file{gsyslimits.h} if it does not need fixing to work with GCC; if it 318needs fixing, @file{syslimits.h} is the fixed copy. 319 320GCC can also install @code{<tgmath.h>}. It will do this when 321@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}. 322 323@node Documentation 324@subsection Building Documentation 325 326The main GCC documentation is in the form of manuals in Texinfo 327format. These are installed in Info format; DVI versions may be 328generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and 329HTML versions by @samp{make html}. In addition, some man pages are 330generated from the Texinfo manuals, there are some other text files 331with miscellaneous documentation, and runtime libraries have their own 332documentation outside the @file{gcc} directory. FIXME: document the 333documentation for runtime libraries somewhere. 334 335@menu 336* Texinfo Manuals:: GCC manuals in Texinfo format. 337* Man Page Generation:: Generating man pages from Texinfo manuals. 338* Miscellaneous Docs:: Miscellaneous text files with documentation. 339@end menu 340 341@node Texinfo Manuals 342@subsubsection Texinfo Manuals 343 344The manuals for GCC as a whole, and the C and C++ front ends, are in 345files @file{doc/*.texi}. Other front ends have their own manuals in 346files @file{@var{language}/*.texi}. Common files 347@file{doc/include/*.texi} are provided which may be included in 348multiple manuals; the following files are in @file{doc/include}: 349 350@table @file 351@item fdl.texi 352The GNU Free Documentation License. 353@item funding.texi 354The section ``Funding Free Software''. 355@item gcc-common.texi 356Common definitions for manuals. 357@item gpl.texi 358@itemx gpl_v3.texi 359The GNU General Public License. 360@item texinfo.tex 361A copy of @file{texinfo.tex} known to work with the GCC manuals. 362@end table 363 364DVI-formatted manuals are generated by @samp{make dvi}, which uses 365@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). 366PDF-formatted manuals are generated by @samp{make pdf}, which uses 367@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML 368formatted manuals are generated by @samp{make html}. Info 369manuals are generated by @samp{make info} (which is run as part of 370a bootstrap); this generates the manuals in the source directory, 371using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, 372and they are included in release distributions. 373 374Manuals are also provided on the GCC web site, in both HTML and 375PostScript forms. This is done via the script 376@file{maintainer-scripts/update_web_docs}. Each manual to be 377provided online must be listed in the definition of @code{MANUALS} in 378that file; a file @file{@var{name}.texi} must only appear once in the 379source tree, and the output manual must have the same name as the 380source file. (However, other Texinfo files, included in manuals but 381not themselves the root files of manuals, may have names that appear 382more than once in the source tree.) The manual file 383@file{@var{name}.texi} should only include other files in its own 384directory or in @file{doc/include}. HTML manuals will be generated by 385@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} 386and @command{dvips}, and PDF manuals by @command{texi2pdf}. 387All Texinfo files that are parts of manuals must 388be version-controlled, even if they are generated files, for the 389generation of online manuals to work. 390 391The installation manual, @file{doc/install.texi}, is also provided on 392the GCC web site. The HTML version is generated by the script 393@file{doc/install.texi2html}. 394 395@node Man Page Generation 396@subsubsection Man Page Generation 397 398Because of user demand, in addition to full Texinfo manuals, man pages 399are provided which contain extracts from those manuals. These man 400pages are generated from the Texinfo manuals using 401@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for 402@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference 403to @file{gcc.1}, but all the other man pages are generated from 404Texinfo manuals.) 405 406Because many systems may not have the necessary tools installed to 407generate the man pages, they are only generated if the 408@file{configure} script detects that recent enough tools are 409installed, and the Makefiles allow generating man pages to fail 410without aborting the build. Man pages are also included in release 411distributions. They are generated in the source directory. 412 413Magic comments in Texinfo files starting @samp{@@c man} control what 414parts of a Texinfo file go into a man page. Only a subset of Texinfo 415is supported by @file{texi2pod.pl}, and it may be necessary to add 416support for more Texinfo features to this script when generating new 417man pages. To improve the man page output, some special Texinfo 418macros are provided in @file{doc/include/gcc-common.texi} which 419@file{texi2pod.pl} understands: 420 421@table @code 422@item @@gcctabopt 423Use in the form @samp{@@table @@gcctabopt} for tables of options, 424where for printed output the effect of @samp{@@code} is better than 425that of @samp{@@option} but for man page output a different effect is 426wanted. 427@item @@gccoptlist 428Use for summary lists of options in manuals. 429@item @@gol 430Use at the end of each line inside @samp{@@gccoptlist}. This is 431necessary to avoid problems with differences in how the 432@samp{@@gccoptlist} macro is handled by different Texinfo formatters. 433@end table 434 435FIXME: describe the @file{texi2pod.pl} input language and magic 436comments in more detail. 437 438@node Miscellaneous Docs 439@subsubsection Miscellaneous Documentation 440 441In addition to the formal documentation that is installed by GCC, 442there are several other text files in the @file{gcc} subdirectory 443with miscellaneous documentation: 444 445@table @file 446@item ABOUT-GCC-NLS 447Notes on GCC's Native Language Support. FIXME: this should be part of 448this manual rather than a separate file. 449@item ABOUT-NLS 450Notes on the Free Translation Project. 451@item COPYING 452@itemx COPYING3 453The GNU General Public License, Versions 2 and 3. 454@item COPYING.LIB 455@itemx COPYING3.LIB 456The GNU Lesser General Public License, Versions 2.1 and 3. 457@item *ChangeLog* 458@itemx */ChangeLog* 459Change log files for various parts of GCC@. 460@item LANGUAGES 461Details of a few changes to the GCC front-end interface. FIXME: the 462information in this file should be part of general documentation of 463the front-end interface in this manual. 464@item ONEWS 465Information about new features in old versions of GCC@. (For recent 466versions, the information is on the GCC web site.) 467@item README.Portability 468Information about portability issues when writing code in GCC@. FIXME: 469why isn't this part of this manual or of the GCC Coding Conventions? 470@end table 471 472FIXME: document such files in subdirectories, at least @file{config}, 473@file{cp}, @file{objc}, @file{testsuite}. 474 475@node Front End 476@subsection Anatomy of a Language Front End 477 478A front end for a language in GCC has the following parts: 479 480@itemize @bullet 481@item 482A directory @file{@var{language}} under @file{gcc} containing source 483files for that front end. @xref{Front End Directory, , The Front End 484@file{@var{language}} Directory}, for details. 485@item 486A mention of the language in the list of supported languages in 487@file{gcc/doc/install.texi}. 488@item 489A mention of the name under which the language's runtime library is 490recognized by @option{--enable-shared=@var{package}} in the 491documentation of that option in @file{gcc/doc/install.texi}. 492@item 493A mention of any special prerequisites for building the front end in 494the documentation of prerequisites in @file{gcc/doc/install.texi}. 495@item 496Details of contributors to that front end in 497@file{gcc/doc/contrib.texi}. If the details are in that front end's 498own manual then there should be a link to that manual's list in 499@file{contrib.texi}. 500@item 501Information about support for that language in 502@file{gcc/doc/frontends.texi}. 503@item 504Information about standards for that language, and the front end's 505support for them, in @file{gcc/doc/standards.texi}. This may be a 506link to such information in the front end's own manual. 507@item 508Details of source file suffixes for that language and @option{-x 509@var{lang}} options supported, in @file{gcc/doc/invoke.texi}. 510@item 511Entries in @code{default_compilers} in @file{gcc.c} for source file 512suffixes for that language. 513@item 514Preferably testsuites, which may be under @file{gcc/testsuite} or 515runtime library directories. FIXME: document somewhere how to write 516testsuite harnesses. 517@item 518Probably a runtime library for the language, outside the @file{gcc} 519directory. FIXME: document this further. 520@item 521Details of the directories of any runtime libraries in 522@file{gcc/doc/sourcebuild.texi}. 523@item 524Check targets in @file{Makefile.def} for the top-level @file{Makefile} 525to check just the compiler or the compiler and runtime library for the 526language. 527@end itemize 528 529If the front end is added to the official GCC source repository, the 530following are also necessary: 531 532@itemize @bullet 533@item 534At least one Bugzilla component for bugs in that front end and runtime 535libraries. This category needs to be mentioned in 536@file{gcc/gccbug.in}, as well as being added to the Bugzilla database. 537@item 538Normally, one or more maintainers of that front end listed in 539@file{MAINTAINERS}. 540@item 541Mentions on the GCC web site in @file{index.html} and 542@file{frontends.html}, with any relevant links on 543@file{readings.html}. (Front ends that are not an official part of 544GCC may also be listed on @file{frontends.html}, with relevant links.) 545@item 546A news item on @file{index.html}, and possibly an announcement on the 547@email{gcc-announce@@gcc.gnu.org} mailing list. 548@item 549The front end's manuals should be mentioned in 550@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals}) 551and the online manuals should be linked to from 552@file{onlinedocs/index.html}. 553@item 554Any old releases or CVS repositories of the front end, before its 555inclusion in GCC, should be made available on the GCC FTP site 556@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. 557@item 558The release and snapshot script @file{maintainer-scripts/gcc_release} 559should be updated to generate appropriate tarballs for this front end. 560The associated @file{maintainer-scripts/snapshot-README} and 561@file{maintainer-scripts/snapshot-index.html} files should be updated 562to list the tarballs and diffs for this front end. 563@item 564If this front end includes its own version files that include the 565current date, @file{maintainer-scripts/update_version} should be 566updated accordingly. 567@end itemize 568 569@menu 570* Front End Directory:: The front end @file{@var{language}} directory. 571* Front End Config:: The front end @file{config-lang.in} file. 572* Front End Makefile:: The front end @file{Make-lang.in} file. 573@end menu 574 575@node Front End Directory 576@subsubsection The Front End @file{@var{language}} Directory 577 578A front end @file{@var{language}} directory contains the source files 579of that front end (but not of any runtime libraries, which should be 580outside the @file{gcc} directory). This includes documentation, and 581possibly some subsidiary programs built alongside the front end. 582Certain files are special and other parts of the compiler depend on 583their names: 584 585@table @file 586@item config-lang.in 587This file is required in all language subdirectories. @xref{Front End 588Config, , The Front End @file{config-lang.in} File}, for details of 589its contents 590@item Make-lang.in 591This file is required in all language subdirectories. @xref{Front End 592Makefile, , The Front End @file{Make-lang.in} File}, for details of its 593contents. 594@item lang.opt 595This file registers the set of switches that the front end accepts on 596the command line, and their @option{--help} text. @xref{Options}. 597@item lang-specs.h 598This file provides entries for @code{default_compilers} in 599@file{gcc.c} which override the default of giving an error that a 600compiler for that language is not installed. 601@item @var{language}-tree.def 602This file, which need not exist, defines any language-specific tree 603codes. 604@end table 605 606@node Front End Config 607@subsubsection The Front End @file{config-lang.in} File 608 609Each language subdirectory contains a @file{config-lang.in} file. In 610addition the main directory contains @file{c-config-lang.in}, which 611contains limited information for the C language. This file is a shell 612script that may define some variables describing the language: 613 614@table @code 615@item language 616This definition must be present, and gives the name of the language 617for some purposes such as arguments to @option{--enable-languages}. 618@item lang_requires 619If defined, this variable lists (space-separated) language front ends 620other than C that this front end requires to be enabled (with the 621names given being their @code{language} settings). For example, the 622Java front end depends on the C++ front end, so sets 623@samp{lang_requires=c++}. 624@item subdir_requires 625If defined, this variable lists (space-separated) front end directories 626other than C that this front end requires to be present. For example, 627the Objective-C++ front end uses source files from the C++ and 628Objective-C front ends, so sets @samp{subdir_requires="cp objc"}. 629@item target_libs 630If defined, this variable lists (space-separated) targets in the top 631level @file{Makefile} to build the runtime libraries for this 632language, such as @code{target-libobjc}. 633@item lang_dirs 634If defined, this variable lists (space-separated) top level 635directories (parallel to @file{gcc}), apart from the runtime libraries, 636that should not be configured if this front end is not built. 637@item build_by_default 638If defined to @samp{no}, this language front end is not built unless 639enabled in a @option{--enable-languages} argument. Otherwise, front 640ends are built by default, subject to any special logic in 641@file{configure.ac} (as is present to disable the Ada front end if the 642Ada compiler is not already installed). 643@item boot_language 644If defined to @samp{yes}, this front end is built in stage1 of the 645bootstrap. This is only relevant to front ends written in their own 646languages. 647@item compilers 648If defined, a space-separated list of compiler executables that will 649be run by the driver. The names here will each end 650with @samp{\$(exeext)}. 651@item outputs 652If defined, a space-separated list of files that should be generated 653by @file{configure} substituting values in them. This mechanism can 654be used to create a file @file{@var{language}/Makefile} from 655@file{@var{language}/Makefile.in}, but this is deprecated, building 656everything from the single @file{gcc/Makefile} is preferred. 657@item gtfiles 658If defined, a space-separated list of files that should be scanned by 659@file{gengtype.c} to generate the garbage collection tables and routines for 660this language. This excludes the files that are common to all front 661ends. @xref{Type Information}. 662 663@end table 664 665@node Front End Makefile 666@subsubsection The Front End @file{Make-lang.in} File 667 668Each language subdirectory contains a @file{Make-lang.in} file. It contains 669targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the 670setting of @code{language} in @file{config-lang.in}) for the following 671values of @code{@var{hook}}, and any other Makefile rules required to 672build those targets (which may if necessary use other Makefiles 673specified in @code{outputs} in @file{config-lang.in}, although this is 674deprecated). It also adds any testsuite targets that can use the 675standard rule in @file{gcc/Makefile.in} to the variable 676@code{lang_checks}. 677 678@table @code 679@itemx all.cross 680@itemx start.encap 681@itemx rest.encap 682FIXME: exactly what goes in each of these targets? 683@item tags 684Build an @command{etags} @file{TAGS} file in the language subdirectory 685in the source tree. 686@item info 687Build info documentation for the front end, in the build directory. 688This target is only called by @samp{make bootstrap} if a suitable 689version of @command{makeinfo} is available, so does not need to check 690for this, and should fail if an error occurs. 691@item dvi 692Build DVI documentation for the front end, in the build directory. 693This should be done using @code{$(TEXI2DVI)}, with appropriate 694@option{-I} arguments pointing to directories of included files. 695@item pdf 696Build PDF documentation for the front end, in the build directory. 697This should be done using @code{$(TEXI2PDF)}, with appropriate 698@option{-I} arguments pointing to directories of included files. 699@item html 700Build HTML documentation for the front end, in the build directory. 701@item man 702Build generated man pages for the front end from Texinfo manuals 703(@pxref{Man Page Generation}), in the build directory. This target 704is only called if the necessary tools are available, but should ignore 705errors so as not to stop the build if errors occur; man pages are 706optional and the tools involved may be installed in a broken way. 707@item install-common 708Install everything that is part of the front end, apart from the 709compiler executables listed in @code{compilers} in 710@file{config-lang.in}. 711@item install-info 712Install info documentation for the front end, if it is present in the 713source directory. This target should have dependencies on info files 714that should be installed. 715@item install-man 716Install man pages for the front end. This target should ignore 717errors. 718@item install-plugin 719Install headers needed for plugins. 720@item srcextra 721Copies its dependencies into the source directory. This generally should 722be used for generated files such as Bison output files which are not 723version-controlled, but should be included in any release tarballs. This 724target will be executed during a bootstrap if 725@samp{--enable-generated-files-in-srcdir} was specified as a 726@file{configure} option. 727@item srcinfo 728@itemx srcman 729Copies its dependencies into the source directory. These targets will be 730executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} 731was specified as a @file{configure} option. 732@item uninstall 733Uninstall files installed by installing the compiler. This is 734currently documented not to be supported, so the hook need not do 735anything. 736@item mostlyclean 737@itemx clean 738@itemx distclean 739@itemx maintainer-clean 740The language parts of the standard GNU 741@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for 742Users, standards, GNU Coding Standards}, for details of the standard 743targets. For GCC, @code{maintainer-clean} should delete 744all generated files in the source directory that are not version-controlled, 745but should not delete anything that is. 746@end table 747 748@file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS} 749to a list of host object files that are used by that language. 750 751@node Back End 752@subsection Anatomy of a Target Back End 753 754A back end for a target architecture in GCC has the following parts: 755 756@itemize @bullet 757@item 758A directory @file{@var{machine}} under @file{gcc/config}, containing a 759machine description @file{@var{machine}.md} file (@pxref{Machine Desc, 760, Machine Descriptions}), header files @file{@var{machine}.h} and 761@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} 762(@pxref{Target Macros, , Target Description Macros and Functions}), 763possibly a target Makefile fragment @file{t-@var{machine}} 764(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe 765some other files. The names of these files may be changed from the 766defaults given by explicit specifications in @file{config.gcc}. 767@item 768If necessary, a file @file{@var{machine}-modes.def} in the 769@file{@var{machine}} directory, containing additional machine modes to 770represent condition codes. @xref{Condition Code}, for further details. 771@item 772An optional @file{@var{machine}.opt} file in the @file{@var{machine}} 773directory, containing a list of target-specific options. You can also 774add other option files using the @code{extra_options} variable in 775@file{config.gcc}. @xref{Options}. 776@item 777Entries in @file{config.gcc} (@pxref{System Config, , The 778@file{config.gcc} File}) for the systems with this target 779architecture. 780@item 781Documentation in @file{gcc/doc/invoke.texi} for any command-line 782options supported by this target (@pxref{Run-time Target, , Run-time 783Target Specification}). This means both entries in the summary table 784of options and details of the individual options. 785@item 786Documentation in @file{gcc/doc/extend.texi} for any target-specific 787attributes supported (@pxref{Target Attributes, , Defining 788target-specific uses of @code{__attribute__}}), including where the 789same attribute is already supported on some targets, which are 790enumerated in the manual. 791@item 792Documentation in @file{gcc/doc/extend.texi} for any target-specific 793pragmas supported. 794@item 795Documentation in @file{gcc/doc/extend.texi} of any target-specific 796built-in functions supported. 797@item 798Documentation in @file{gcc/doc/extend.texi} of any target-specific 799format checking styles supported. 800@item 801Documentation in @file{gcc/doc/md.texi} of any target-specific 802constraint letters (@pxref{Machine Constraints, , Constraints for 803Particular Machines}). 804@item 805A note in @file{gcc/doc/contrib.texi} under the person or people who 806contributed the target support. 807@item 808Entries in @file{gcc/doc/install.texi} for all target triplets 809supported with this target architecture, giving details of any special 810notes about installation for this target, or saying that there are no 811special notes if there are none. 812@item 813Possibly other support outside the @file{gcc} directory for runtime 814libraries. FIXME: reference docs for this. The @code{libstdc++} porting 815manual needs to be installed as info for this to work, or to be a 816chapter of this manual. 817@end itemize 818 819If the back end is added to the official GCC source repository, the 820following are also necessary: 821 822@itemize @bullet 823@item 824An entry for the target architecture in @file{readings.html} on the 825GCC web site, with any relevant links. 826@item 827Details of the properties of the back end and target architecture in 828@file{backends.html} on the GCC web site. 829@item 830A news item about the contribution of support for that target 831architecture, in @file{index.html} on the GCC web site. 832@item 833Normally, one or more maintainers of that target listed in 834@file{MAINTAINERS}. Some existing architectures may be unmaintained, 835but it would be unusual to add support for a target that does not have 836a maintainer when support is added. 837@end itemize 838 839@node Testsuites 840@chapter Testsuites 841 842GCC contains several testsuites to help maintain compiler quality. 843Most of the runtime libraries and language front ends in GCC have 844testsuites. Currently only the C language testsuites are documented 845here; FIXME: document the others. 846 847@menu 848* Test Idioms:: Idioms used in testsuite code. 849* Test Directives:: Directives used within DejaGnu tests. 850* Ada Tests:: The Ada language testsuites. 851* C Tests:: The C language testsuites. 852* libgcj Tests:: The Java library testsuites. 853* LTO Testing:: Support for testing link-time optimizations. 854* gcov Testing:: Support for testing gcov. 855* profopt Testing:: Support for testing profile-directed optimizations. 856* compat Testing:: Support for testing binary compatibility. 857* Torture Tests:: Support for torture testing using multiple options. 858@end menu 859 860@node Test Idioms 861@section Idioms Used in Testsuite Code 862 863In general, C testcases have a trailing @file{-@var{n}.c}, starting 864with @file{-1.c}, in case other testcases with similar names are added 865later. If the test is a test of some well-defined feature, it should 866have a name referring to that feature such as 867@file{@var{feature}-1.c}. If it does not test a well-defined feature 868but just happens to exercise a bug somewhere in the compiler, and a 869bug report has been filed for this bug in the GCC bug database, 870@file{pr@var{bug-number}-1.c} is the appropriate form of name. 871Otherwise (for miscellaneous bugs not filed in the GCC bug database), 872and previously more generally, test cases are named after the date on 873which they were added. This allows people to tell at a glance whether 874a test failure is because of a recently found bug that has not yet 875been fixed, or whether it may be a regression, but does not give any 876other information about the bug or where discussion of it may be 877found. Some other language testsuites follow similar conventions. 878 879In the @file{gcc.dg} testsuite, it is often necessary to test that an 880error is indeed a hard error and not just a warning---for example, 881where it is a constraint violation in the C standard, which must 882become an error with @option{-pedantic-errors}. The following idiom, 883where the first line shown is line @var{line} of the file and the line 884that generates the error, is used for this: 885 886@smallexample 887/* @{ dg-bogus "warning" "warning in place of error" @} */ 888/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ 889@end smallexample 890 891It may be necessary to check that an expression is an integer constant 892expression and has a certain value. To check that @code{@var{E}} has 893value @code{@var{V}}, an idiom similar to the following is used: 894 895@smallexample 896char x[((E) == (V) ? 1 : -1)]; 897@end smallexample 898 899In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make 900assertions about the types of expressions. See, for example, 901@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the 902exact rules for the types of conditional expressions in the C 903standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. 904 905It is useful to be able to test that optimizations are being made 906properly. This cannot be done in all cases, but it can be done where 907the optimization will lead to code being optimized away (for example, 908where flow analysis or alias analysis should show that certain code 909cannot be called) or to functions not being called because they have 910been expanded as built-in functions. Such tests go in 911@file{gcc.c-torture/execute}. Where code should be optimized away, a 912call to a nonexistent function such as @code{link_failure ()} may be 913inserted; a definition 914 915@smallexample 916#ifndef __OPTIMIZE__ 917void 918link_failure (void) 919@{ 920 abort (); 921@} 922#endif 923@end smallexample 924 925@noindent 926will also be needed so that linking still succeeds when the test is 927run without optimization. When all calls to a built-in function 928should have been optimized and no calls to the non-built-in version of 929the function should remain, that function may be defined as 930@code{static} to call @code{abort ()} (although redeclaring a function 931as static may not work on all targets). 932 933All testcases must be portable. Target-specific testcases must have 934appropriate code to avoid causing failures on unsupported systems; 935unfortunately, the mechanisms for this differ by directory. 936 937FIXME: discuss non-C testsuites here. 938 939@node Test Directives 940@section Directives used within DejaGnu tests 941 942@menu 943* Directives:: Syntax and descriptions of test directives. 944* Selectors:: Selecting targets to which a test applies. 945* Effective-Target Keywords:: Keywords describing target attributes. 946* Add Options:: Features for @code{dg-add-options} 947* Require Support:: Variants of @code{dg-require-@var{support}} 948* Final Actions:: Commands for use in @code{dg-final} 949@end menu 950 951@node Directives 952@subsection Syntax and Descriptions of test directives 953 954Test directives appear within comments in a test source file and begin 955with @code{dg-}. Some of these are defined within DejaGnu and others 956are local to the GCC testsuite. 957 958The order in which test directives appear in a test can be important: 959directives local to GCC sometimes override information used by the 960DejaGnu directives, which know nothing about the GCC directives, so the 961DejaGnu directives must precede GCC directives. 962 963Several test directives include selectors (@pxref{Selectors, , }) 964which are usually preceded by the keyword @code{target} or @code{xfail}. 965 966@subsubsection Specify how to build the test 967 968@table @code 969@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} 970@var{do-what-keyword} specifies how the test is compiled and whether 971it is executed. It is one of: 972 973@table @code 974@item preprocess 975Compile with @option{-E} to run only the preprocessor. 976@item compile 977Compile with @option{-S} to produce an assembly code file. 978@item assemble 979Compile with @option{-c} to produce a relocatable object file. 980@item link 981Compile, assemble, and link to produce an executable file. 982@item run 983Produce and run an executable file, which is expected to return 984an exit code of 0. 985@end table 986 987The default is @code{compile}. That can be overridden for a set of 988tests by redefining @code{dg-do-what-default} within the @code{.exp} 989file for those tests. 990 991If the directive includes the optional @samp{@{ target @var{selector} @}} 992then the test is skipped unless the target system matches the 993@var{selector}. 994 995If @var{do-what-keyword} is @code{run} and the directive includes 996the optional @samp{@{ xfail @var{selector} @}} and the selector is met 997then the test is expected to fail. The @code{xfail} clause is ignored 998for other values of @var{do-what-keyword}; those tests can use 999directive @code{dg-xfail-if}. 1000@end table 1001 1002@subsubsection Specify additional compiler options 1003 1004@table @code 1005@item @{ dg-options @var{options} [@{ target @var{selector} @}] @} 1006This DejaGnu directive provides a list of compiler options, to be used 1007if the target system matches @var{selector}, that replace the default 1008options used for this set of tests. 1009 1010@item @{ dg-add-options @var{feature} @dots{} @} 1011Add any compiler options that are needed to access certain features. 1012This directive does nothing on targets that enable the features by 1013default, or that don't provide them at all. It must come after 1014all @code{dg-options} directives. 1015For supported values of @var{feature} see @ref{Add Options, ,}. 1016@end table 1017 1018@subsubsection Modify the test timeout value 1019 1020The normal timeout limit, in seconds, is found by searching the 1021following in order: 1022 1023@itemize @bullet 1024@item the value defined by an earlier @code{dg-timeout} directive in 1025the test 1026 1027@item variable @var{tool_timeout} defined by the set of tests 1028 1029@item @var{gcc},@var{timeout} set in the target board 1030 1031@item 300 1032@end itemize 1033 1034@table @code 1035@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @} 1036Set the time limit for the compilation and for the execution of the test 1037to the specified number of seconds. 1038 1039@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @} 1040Multiply the normal time limit for compilation and execution of the test 1041by the specified floating-point factor. 1042@end table 1043 1044@subsubsection Skip a test for some targets 1045 1046@table @code 1047@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1048Arguments @var{include-opts} and @var{exclude-opts} are lists in which 1049each element is a string of zero or more GCC options. 1050Skip the test if all of the following conditions are met: 1051@itemize @bullet 1052@item the test system is included in @var{selector} 1053 1054@item for at least one of the option strings in @var{include-opts}, 1055every option from that string is in the set of options with which 1056the test would be compiled; use @samp{"*"} for an @var{include-opts} list 1057that matches any options; that is the default if @var{include-opts} is 1058not specified 1059 1060@item for each of the option strings in @var{exclude-opts}, at least one 1061option from that string is not in the set of options with which the test 1062would be compiled; use @samp{""} for an empty @var{exclude-opts} list; 1063that is the default if @var{exclude-opts} is not specified 1064@end itemize 1065 1066For example, to skip a test if option @code{-Os} is present: 1067 1068@smallexample 1069/* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */ 1070@end smallexample 1071 1072To skip a test if both options @code{-O2} and @code{-g} are present: 1073 1074@smallexample 1075/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */ 1076@end smallexample 1077 1078To skip a test if either @code{-O2} or @code{-O3} is present: 1079 1080@smallexample 1081/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */ 1082@end smallexample 1083 1084To skip a test unless option @code{-Os} is present: 1085 1086@smallexample 1087/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */ 1088@end smallexample 1089 1090To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g} 1091but not if @code{-fpic} is also present: 1092 1093@smallexample 1094/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */ 1095@end smallexample 1096 1097@item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @} 1098Skip the test if the test target, including current multilib flags, 1099is not covered by the effective-target keyword. 1100If the directive includes the optional @samp{@{ @var{selector} @}} 1101then the effective-target test is only performed if the target system 1102matches the @var{selector}. 1103This directive must appear after any @code{dg-do} directive in the test 1104and before any @code{dg-additional-sources} directive. 1105@xref{Effective-Target Keywords, , }. 1106 1107@item @{ dg-require-@var{support} args @} 1108Skip the test if the target does not provide the required support. 1109These directives must appear after any @code{dg-do} directive in the test 1110and before any @code{dg-additional-sources} directive. 1111They require at least one argument, which can be an empty string if the 1112specific procedure does not examine the argument. 1113@xref{Require Support, , }, for a complete list of these directives. 1114@end table 1115 1116@subsubsection Expect a test to fail for some targets 1117 1118@table @code 1119@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1120Expect the test to fail if the conditions (which are the same as for 1121@code{dg-skip-if}) are met. This does not affect the execute step. 1122 1123@item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} 1124Expect the execute step of a test to fail if the conditions (which are 1125the same as for @code{dg-skip-if}) are met. 1126@end table 1127 1128@subsubsection Expect the test executable to fail 1129 1130@table @code 1131@item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} 1132Expect the test executable to return a nonzero exit status if the 1133conditions (which are the same as for @code{dg-skip-if}) are met. 1134@end table 1135 1136@subsubsection Verify compiler messages 1137 1138@table @code 1139@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1140This DejaGnu directive appears on a source line that is expected to get 1141an error message, or else specifies the source line associated with the 1142message. If there is no message for that line or if the text of that 1143message is not matched by @var{regexp} then the check fails and 1144@var{comment} is included in the @code{FAIL} message. The check does 1145not look for the string @samp{error} unless it is part of @var{regexp}. 1146 1147@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1148This DejaGnu directive appears on a source line that is expected to get 1149a warning message, or else specifies the source line associated with the 1150message. If there is no message for that line or if the text of that 1151message is not matched by @var{regexp} then the check fails and 1152@var{comment} is included in the @code{FAIL} message. The check does 1153not look for the string @samp{warning} unless it is part of @var{regexp}. 1154 1155@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1156The line is expected to get a message other than an error or warning. 1157If there is no message for that line or if the text of that message is 1158not matched by @var{regexp} then the check fails and @var{comment} is 1159included in the @code{FAIL} message. 1160 1161@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1162This DejaGnu directive appears on a source line that should not get a 1163message matching @var{regexp}, or else specifies the source line 1164associated with the bogus message. It is usually used with @samp{xfail} 1165to indicate that the message is a known problem for a particular set of 1166targets. 1167 1168@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} 1169This DejaGnu directive indicates that the test is expected to fail due 1170to compiler messages that are not handled by @samp{dg-error}, 1171@samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail} 1172has the same effect as @samp{target}. 1173 1174@item @{ dg-prune-output @var{regexp} @} 1175Prune messages matching @var{regexp} from the test output. 1176@end table 1177 1178@subsubsection Verify output of the test executable 1179 1180@table @code 1181@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} 1182This DejaGnu directive compares @var{regexp} to the combined output 1183that the test executable writes to @file{stdout} and @file{stderr}. 1184@end table 1185 1186@subsubsection Specify additional files for a test 1187 1188@table @code 1189@item @{ dg-additional-files "@var{filelist}" @} 1190Specify additional files, other than source files, that must be copied 1191to the system where the compiler runs. 1192 1193@item @{ dg-additional-sources "@var{filelist}" @} 1194Specify additional source files to appear in the compile line 1195following the main test file. 1196@end table 1197 1198@subsubsection Add checks at the end of a test 1199 1200@table @code 1201@item @{ dg-final @{ @var{local-directive} @} @} 1202This DejaGnu directive is placed within a comment anywhere in the 1203source file and is processed after the test has been compiled and run. 1204Multiple @samp{dg-final} commands are processed in the order in which 1205they appear in the source file. @xref{Final Actions, , }, for a list 1206of directives that can be used within @code{dg-final}. 1207@end table 1208 1209@node Selectors 1210@subsection Selecting targets to which a test applies 1211 1212Several test directives include @var{selector}s to limit the targets 1213for which a test is run or to declare that a test is expected to fail 1214on particular targets. 1215 1216A selector is: 1217@itemize @bullet 1218@item one or more target triplets, possibly including wildcard characters 1219@item a single effective-target keyword (@pxref{Effective-Target Keywords}) 1220@item a logical expression 1221@end itemize 1222 1223Depending on the 1224context, the selector specifies whether a test is skipped and reported 1225as unsupported or is expected to fail. Use @samp{*-*-*} to match any 1226target. 1227 1228A selector expression appears within curly braces and uses a single 1229logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An 1230operand is another selector expression, an effective-target keyword, 1231a single target triplet, or a list of target triplets within quotes or 1232curly braces. For example: 1233 1234@smallexample 1235@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} 1236@{ target @{ powerpc*-*-* && lp64 @} @} 1237@{ xfail @{ lp64 || vect_no_align @} @} 1238@end smallexample 1239 1240@node Effective-Target Keywords 1241@subsection Keywords describing target attributes 1242 1243Effective-target keywords identify sets of targets that support 1244particular functionality. They are used to limit tests to be run only 1245for particular targets, or to specify that particular sets of targets 1246are expected to fail some tests. 1247 1248Effective-target keywords are defined in @file{lib/target-supports.exp} in 1249the GCC testsuite, with the exception of those that are documented as 1250being local to a particular test directory. 1251 1252The @samp{effective target} takes into account all of the compiler options 1253with which the test will be compiled, including the multilib options. 1254By convention, keywords ending in @code{_nocache} can also include options 1255specified for the particular test in an earlier @code{dg-options} or 1256@code{dg-add-options} directive. 1257 1258@subsubsection Data type sizes 1259 1260@table @code 1261@item ilp32 1262Target has 32-bit @code{int}, @code{long}, and pointers. 1263 1264@item lp64 1265Target has 32-bit @code{int}, 64-bit @code{long} and pointers. 1266 1267@item llp64 1268Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long} 1269and pointers. 1270 1271@item double64 1272Target has 64-bit @code{double}. 1273 1274@item double64plus 1275Target has @code{double} that is 64 bits or longer. 1276 1277@item int32plus 1278Target has @code{int} that is at 32 bits or longer. 1279 1280@item int16 1281Target has @code{int} that is 16 bits or shorter. 1282 1283@item large_double 1284Target supports @code{double} that is longer than @code{float}. 1285 1286@item large_long_double 1287Target supports @code{long double} that is longer than @code{double}. 1288 1289@item ptr32plus 1290Target has pointers that are 32 bits or longer. 1291 1292@item size32plus 1293Target supports array and structure sizes that are 32 bits or longer. 1294 1295@item 4byte_wchar_t 1296Target has @code{wchar_t} that is at least 4 bytes. 1297@end table 1298 1299@subsubsection Fortran-specific attributes 1300 1301@table @code 1302@item fortran_integer_16 1303Target supports Fortran @code{integer} that is 16 bytes or longer. 1304 1305@item fortran_large_int 1306Target supports Fortran @code{integer} kinds larger than @code{integer(8)}. 1307 1308@item fortran_large_real 1309Target supports Fortran @code{real} kinds larger than @code{real(8)}. 1310@end table 1311 1312@subsubsection Vector-specific attributes 1313 1314@table @code 1315@item vect_condition 1316Target supports vector conditional operations. 1317 1318@item vect_double 1319Target supports hardware vectors of @code{double}. 1320 1321@item vect_float 1322Target supports hardware vectors of @code{float}. 1323 1324@item vect_int 1325Target supports hardware vectors of @code{int}. 1326 1327@item vect_int_mult 1328Target supports a vector widening multiplication of @code{short} operands 1329into an @code{int} result, or supports promotion (unpacking) from 1330@code{short} to @code{int} and a non-widening multiplication of @code{int}. 1331 1332@item vect_long 1333Target supports hardware vectors of @code{long}. 1334 1335@item vect_long_long 1336Target supports hardware vectors of @code{long long}. 1337 1338@item vect_aligned_arrays 1339Target aligns arrays to vector alignment boundary. 1340 1341@item vect_hw_misalign 1342Target supports a vector misalign access. 1343 1344@item vect_no_align 1345Target does not support a vector alignment mechanism. 1346 1347@item vect_no_int_max 1348Target does not support a vector max instruction on @code{int}. 1349 1350@item vect_no_int_add 1351Target does not support a vector add instruction on @code{int}. 1352 1353@item vect_no_bitwise 1354Target does not support vector bitwise instructions. 1355 1356@item vect_char_mult 1357Target supports @code{vector char} multiplication. 1358 1359@item vect_short_mult 1360Target supports @code{vector short} multiplication. 1361 1362@item vect_int_mult 1363Target supports @code{vector int} multiplication. 1364 1365@item vect_extract_even_odd 1366Target supports vector even/odd element extraction. 1367 1368@item vect_extract_even_odd_wide 1369Target supports vector even/odd element extraction of vectors with elements 1370@code{SImode} or larger. 1371 1372@item vect_interleave 1373Target supports vector interleaving. 1374 1375@item vect_strided 1376Target supports vector interleaving and extract even/odd. 1377 1378@item vect_strided_wide 1379Target supports vector interleaving and extract even/odd for wide 1380element types. 1381 1382@item vect_perm 1383Target supports vector permutation. 1384 1385@item vect_shift 1386Target supports a hardware vector shift operation. 1387 1388@item vect_widen_sum_hi_to_si 1389Target supports a vector widening summation of @code{short} operands 1390into @code{int} results, or can promote (unpack) from @code{short} 1391to @code{int}. 1392 1393@item vect_widen_sum_qi_to_hi 1394Target supports a vector widening summation of @code{char} operands 1395into @code{short} results, or can promote (unpack) from @code{char} 1396to @code{short}. 1397 1398@item vect_widen_sum_qi_to_si 1399Target supports a vector widening summation of @code{char} operands 1400into @code{int} results. 1401 1402@item vect_widen_mult_qi_to_hi 1403Target supports a vector widening multiplication of @code{char} operands 1404into @code{short} results, or can promote (unpack) from @code{char} to 1405@code{short} and perform non-widening multiplication of @code{short}. 1406 1407@item vect_widen_mult_hi_to_si 1408Target supports a vector widening multiplication of @code{short} operands 1409into @code{int} results, or can promote (unpack) from @code{short} to 1410@code{int} and perform non-widening multiplication of @code{int}. 1411 1412@item vect_sdot_qi 1413Target supports a vector dot-product of @code{signed char}. 1414 1415@item vect_udot_qi 1416Target supports a vector dot-product of @code{unsigned char}. 1417 1418@item vect_sdot_hi 1419Target supports a vector dot-product of @code{signed short}. 1420 1421@item vect_udot_hi 1422Target supports a vector dot-product of @code{unsigned short}. 1423 1424@item vect_pack_trunc 1425Target supports a vector demotion (packing) of @code{short} to @code{char} 1426and from @code{int} to @code{short} using modulo arithmetic. 1427 1428@item vect_unpack 1429Target supports a vector promotion (unpacking) of @code{char} to @code{short} 1430and from @code{char} to @code{int}. 1431 1432@item vect_intfloat_cvt 1433Target supports conversion from @code{signed int} to @code{float}. 1434 1435@item vect_uintfloat_cvt 1436Target supports conversion from @code{unsigned int} to @code{float}. 1437 1438@item vect_floatint_cvt 1439Target supports conversion from @code{float} to @code{signed int}. 1440 1441@item vect_floatuint_cvt 1442Target supports conversion from @code{float} to @code{unsigned int}. 1443@end table 1444 1445@subsubsection Thread Local Storage attributes 1446 1447@table @code 1448@item tls 1449Target supports thread-local storage. 1450 1451@item tls_native 1452Target supports native (rather than emulated) thread-local storage. 1453 1454@item tls_runtime 1455Test system supports executing TLS executables. 1456@end table 1457 1458@subsubsection Decimal floating point attributes 1459 1460@table @code 1461@item dfp 1462Targets supports compiling decimal floating point extension to C. 1463 1464@item dfp_nocache 1465Including the options used to compile this particular test, the 1466target supports compiling decimal floating point extension to C. 1467 1468@item dfprt 1469Test system can execute decimal floating point tests. 1470 1471@item dfprt_nocache 1472Including the options used to compile this particular test, the 1473test system can execute decimal floating point tests. 1474 1475@item hard_dfp 1476Target generates decimal floating point instructions with current options. 1477@end table 1478 1479@subsubsection ARM-specific attributes 1480 1481@table @code 1482@item arm32 1483ARM target generates 32-bit code. 1484 1485@item arm_eabi 1486ARM target adheres to the ABI for the ARM Architecture. 1487 1488@item arm_hard_vfp_ok 1489ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. 1490Some multilibs may be incompatible with these options. 1491 1492@item arm_iwmmxt_ok 1493ARM target supports @code{-mcpu=iwmmxt}. 1494Some multilibs may be incompatible with this option. 1495 1496@item arm_neon 1497ARM target supports generating NEON instructions. 1498 1499@item arm_neon_hw 1500Test system supports executing NEON instructions. 1501 1502@item arm_neon_ok 1503ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp}. 1504Some multilibs may be incompatible with these options. 1505 1506@item arm_thumb1_ok 1507ARM target generates Thumb-1 code for @code{-mthumb}. 1508 1509@item arm_thumb2_ok 1510ARM target generates Thumb-2 code for @code{-mthumb}. 1511 1512@item arm_vfp_ok 1513ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. 1514Some multilibs may be incompatible with these options. 1515@end table 1516 1517@subsubsection MIPS-specific attributes 1518 1519@table @code 1520@item mips64 1521MIPS target supports 64-bit instructions. 1522 1523@item nomips16 1524MIPS target does not produce MIPS16 code. 1525 1526@item mips16_attribute 1527MIPS target can generate MIPS16 code. 1528 1529@item mips_loongson 1530MIPS target is a Loongson-2E or -2F target using an ABI that supports 1531the Loongson vector modes. 1532 1533@item mips_newabi_large_long_double 1534MIPS target supports @code{long double} larger than @code{double} 1535when using the new ABI. 1536 1537@item mpaired_single 1538MIPS target supports @code{-mpaired-single}. 1539@end table 1540 1541@subsubsection PowerPC-specific attributes 1542 1543@table @code 1544@item powerpc64 1545Test system supports executing 64-bit instructions. 1546 1547@item powerpc_altivec 1548PowerPC target supports AltiVec. 1549 1550@item powerpc_altivec_ok 1551PowerPC target supports @code{-maltivec}. 1552 1553@item powerpc_fprs 1554PowerPC target supports floating-point registers. 1555 1556@item powerpc_hard_double 1557PowerPC target supports hardware double-precision floating-point. 1558 1559@item powerpc_ppu_ok 1560PowerPC target supports @code{-mcpu=cell}. 1561 1562@item powerpc_spe 1563PowerPC target supports PowerPC SPE. 1564 1565@item powerpc_spe_nocache 1566Including the options used to compile this particular test, the 1567PowerPC target supports PowerPC SPE. 1568 1569@item powerpc_spu 1570PowerPC target supports PowerPC SPU. 1571 1572@item spu_auto_overlay 1573SPU target has toolchain that supports automatic overlay generation. 1574 1575@item powerpc_vsx_ok 1576PowerPC target supports @code{-mvsx}. 1577 1578@item powerpc_405_nocache 1579Including the options used to compile this particular test, the 1580PowerPC target supports PowerPC 405. 1581 1582@item vmx_hw 1583PowerPC target supports executing AltiVec instructions. 1584@end table 1585 1586@subsubsection Other hardware attributes 1587 1588@table @code 1589@item avx 1590Target supports compiling AVX instructions. 1591 1592@item cell_hw 1593Test system can execute AltiVec and Cell PPU instructions. 1594 1595@item coldfire_fpu 1596Target uses a ColdFire FPU. 1597 1598@item hard_float 1599Target supports FPU instructions. 1600 1601@item sse 1602Target supports compiling @code{sse} instructions. 1603 1604@item sse_runtime 1605Target supports the execution of @code{sse} instructions. 1606 1607@item sse2 1608Target supports compiling @code{sse2} instructions. 1609 1610@item sse2_runtime 1611Target supports the execution of @code{sse2} instructions. 1612 1613@item sync_char_short 1614Target supports atomic operations on @code{char} and @code{short}. 1615 1616@item sync_int_long 1617Target supports atomic operations on @code{int} and @code{long}. 1618 1619@item ultrasparc_hw 1620Test environment appears to run executables on a simulator that 1621accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS} 1622or @code{EM_SPARCV9} executables. 1623 1624@item vect_cmdline_needed 1625Target requires a command line argument to enable a SIMD instruction set. 1626@end table 1627 1628@subsubsection Environment attributes 1629 1630@table @code 1631@item c 1632The language for the compiler under test is C. 1633 1634@item c++ 1635The language for the compiler under test is C++. 1636 1637@item c99_runtime 1638Target provides a full C99 runtime. 1639 1640@item correct_iso_cpp_string_wchar_protos 1641Target @code{string.h} and @code{wchar.h} headers provide C++ required 1642overloads for @code{strchr} etc. functions. 1643 1644@item dummy_wcsftime 1645Target uses a dummy @code{wcsftime} function that always returns zero. 1646 1647@item fd_truncate 1648Target can truncate a file from a file descriptor, as used by 1649@file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or 1650@code{chsize}. 1651 1652@item freestanding 1653Target is @samp{freestanding} as defined in section 4 of the C99 standard. 1654Effectively, it is a target which supports no extra headers or libraries 1655other than what is considered essential. 1656 1657@item init_priority 1658Target supports constructors with initialization priority arguments. 1659 1660@item inttypes_types 1661Target has the basic signed and unsigned types in @code{inttypes.h}. 1662This is for tests that GCC's notions of these types agree with those 1663in the header, as some systems have only @code{inttypes.h}. 1664 1665@item lax_strtofp 1666Target might have errors of a few ULP in string to floating-point 1667conversion functions and overflow is not always detected correctly by 1668those functions. 1669 1670@item newlib 1671Target supports Newlib. 1672 1673@item pow10 1674Target provides @code{pow10} function. 1675 1676@item pthread 1677Target can compile using @code{pthread.h} with no errors or warnings. 1678 1679@item pthread_h 1680Target has @code{pthread.h}. 1681 1682@item run_expensive_tests 1683Expensive testcases (usually those that consume excessive amounts of CPU 1684time) should be run on this target. This can be enabled by setting the 1685@env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string. 1686 1687@item simulator 1688Test system runs executables on a simulator (i.e. slowly) rather than 1689hardware (i.e. fast). 1690 1691@item stdint_types 1692Target has the basic signed and unsigned C types in @code{stdint.h}. 1693This will be obsolete when GCC ensures a working @code{stdint.h} for 1694all targets. 1695 1696@item trampolines 1697Target supports trampolines. 1698 1699@item uclibc 1700Target supports uClibc. 1701 1702@item unwrapped 1703Target does not use a status wrapper. 1704 1705@item vxworks_kernel 1706Target is a VxWorks kernel. 1707 1708@item vxworks_rtp 1709Target is a VxWorks RTP. 1710 1711@item wchar 1712Target supports wide characters. 1713@end table 1714 1715@subsubsection Other attributes 1716 1717@table @code 1718@item automatic_stack_alignment 1719Target supports automatic stack alignment. 1720 1721@item cxa_atexit 1722Target uses @code{__cxa_atexit}. 1723 1724@item default_packed 1725Target has packed layout of structure members by default. 1726 1727@item fgraphite 1728Target supports Graphite optimizations. 1729 1730@item fixed_point 1731Target supports fixed-point extension to C. 1732 1733@item fopenmp 1734Target supports OpenMP via @option{-fopenmp}. 1735 1736@item fpic 1737Target supports @option{-fpic} and @option{-fPIC}. 1738 1739@item freorder 1740Target supports @option{-freorder-blocks-and-partition}. 1741 1742@item fstack_protector 1743Target supports @option{-fstack-protector}. 1744 1745@item gas 1746Target uses GNU @command{as}. 1747 1748@item gc_sections 1749Target supports @option{--gc-sections}. 1750 1751@item keeps_null_pointer_checks 1752Target keeps null pointer checks, either due to the use of 1753@option{-fno-delete-null-pointer-checks} or hardwired into the target. 1754 1755@item lto 1756Compiler has been configured to support link-time optimization (LTO). 1757 1758@item named_sections 1759Target supports named sections. 1760 1761@item natural_alignment_32 1762Target uses natural alignment (aligned to type size) for types of 176332 bits or less. 1764 1765@item target_natural_alignment_64 1766Target uses natural alignment (aligned to type size) for types of 176764 bits or less. 1768 1769@item nonpic 1770Target does not generate PIC by default. 1771 1772@item pcc_bitfield_type_matters 1773Target defines @code{PCC_BITFIELD_TYPE_MATTERS}. 1774 1775@item pe_aligned_commons 1776Target supports @option{-mpe-aligned-commons}. 1777 1778@item section_anchors 1779Target supports section anchors. 1780 1781@item short_enums 1782Target defaults to short enums. 1783 1784@item static 1785Target supports @option{-static}. 1786 1787@item static_libgfortran 1788Target supports statically linking @samp{libgfortran}. 1789 1790@item string_merging 1791Target supports merging string constants at link time. 1792 1793@item ucn 1794Target supports compiling and assembling UCN. 1795 1796@item ucn_nocache 1797Including the options used to compile this particular test, the 1798target supports compiling and assembling UCN. 1799 1800@item unaligned_stack 1801Target does not guarantee that its @code{STACK_BOUNDARY} is greater than 1802or equal to the required vector alignment. 1803 1804@item vector_alignment_reachable 1805Vector alignment is reachable for types of 32 bits or less. 1806 1807@item vector_alignment_reachable_for_64bit 1808Vector alignment is reachable for types of 64 bits or less. 1809 1810@item wchar_t_char16_t_compatible 1811Target supports @code{wchar_t} that is compatible with @code{char16_t}. 1812 1813@item wchar_t_char32_t_compatible 1814Target supports @code{wchar_t} that is compatible with @code{char32_t}. 1815@end table 1816 1817@subsubsection Local to tests in @code{gcc.target/i386} 1818 1819@table @code 1820@item 3dnow 1821Target supports compiling @code{3dnow} instructions. 1822 1823@item aes 1824Target supports compiling @code{aes} instructions. 1825 1826@item fma4 1827Target supports compiling @code{fma4} instructions. 1828 1829@item ms_hook_prologue 1830Target supports attribute @code{ms_hook_prologue}. 1831 1832@item pclmul 1833Target supports compiling @code{pclmul} instructions. 1834 1835@item sse3 1836Target supports compiling @code{sse3} instructions. 1837 1838@item sse4 1839Target supports compiling @code{sse4} instructions. 1840 1841@item sse4a 1842Target supports compiling @code{sse4a} instructions. 1843 1844@item ssse3 1845Target supports compiling @code{ssse3} instructions. 1846 1847@item vaes 1848Target supports compiling @code{vaes} instructions. 1849 1850@item vpclmul 1851Target supports compiling @code{vpclmul} instructions. 1852 1853@item xop 1854Target supports compiling @code{xop} instructions. 1855@end table 1856 1857@subsubsection Local to tests in @code{gcc.target/spu/ea} 1858 1859@table @code 1860@item ealib 1861Target @code{__ea} library functions are available. 1862@end table 1863 1864@subsubsection Local to tests in @code{gcc.test-framework} 1865 1866@table @code 1867@item no 1868Always returns 0. 1869 1870@item yes 1871Always returns 1. 1872@end table 1873 1874@node Add Options 1875@subsection Features for @code{dg-add-options} 1876 1877The supported values of @var{feature} for directive @code{dg-add-options} 1878are: 1879 1880@table @code 1881@item bind_pic_locally 1882Add the target-specific flags needed to enable functions to bind 1883locally when using pic/PIC passes in the testsuite. 1884 1885@item c99_runtime 1886Add the target-specific flags needed to access the C99 runtime. 1887 1888@item ieee 1889Add the target-specific flags needed to enable full IEEE 1890compliance mode. 1891 1892@item mips16_attribute 1893@code{mips16} function attributes. 1894Only MIPS targets support this feature, and only then in certain modes. 1895 1896@item tls 1897Add the target-specific flags needed to use thread-local storage. 1898@end table 1899 1900@node Require Support 1901@subsection Variants of @code{dg-require-@var{support}} 1902 1903A few of the @code{dg-require} directives take arguments. 1904 1905@table @code 1906@item dg-require-iconv @var{codeset} 1907Skip the test if the target does not support iconv. @var{codeset} is 1908the codeset to convert to. 1909 1910@item dg-require-profiling @var{profopt} 1911Skip the test if the target does not support profiling with option 1912@var{profopt}. 1913 1914@item dg-require-visibility @var{vis} 1915Skip the test if the target does not support the @code{visibility} attribute. 1916If @var{vis} is @code{""}, support for @code{visibility("hidden")} is 1917checked, for @code{visibility("@var{vis}")} otherwise. 1918@end table 1919 1920The original @code{dg-require} directives were defined before there 1921was support for effective-target keywords. The directives that do not 1922take arguments could be replaced with effective-target keywords. 1923 1924@table @code 1925@item dg-require-alias "" 1926Skip the test if the target does not support the @samp{alias} attribute. 1927 1928@item dg-require-ascii-locale "" 1929Skip the test if the host does not support an ASCII locale. 1930 1931@item dg-require-compat-dfp "" 1932Skip this test unless both compilers in a @file{compat} testsuite 1933support decimal floating point. 1934 1935@item dg-require-cxa-atexit "" 1936Skip the test if the target does not support @code{__cxa_atexit}. 1937This is equivalent to @code{dg-require-effective-target cxa_atexit}. 1938 1939@item dg-require-dll "" 1940Skip the test if the target does not support DLL attributes. 1941 1942@item dg-require-fork "" 1943Skip the test if the target does not support @code{fork}. 1944 1945@item dg-require-gc-sections "" 1946Skip the test if the target's linker does not support the 1947@code{--gc-sections} flags. 1948This is equivalent to @code{dg-require-effective-target gc-sections}. 1949 1950@item dg-require-host-local "" 1951Skip the test if the host is remote, rather than the same as the build 1952system. Some tests are incompatible with DejaGnu's handling of remote 1953hosts, which involves copying the source file to the host and compiling 1954it with a relative path and "@code{-o a.out}". 1955 1956@item dg-require-mkfifo "" 1957Skip the test if the target does not support @code{mkfifo}. 1958 1959@item dg-require-named-sections "" 1960Skip the test is the target does not support named sections. 1961This is equivalent to @code{dg-require-effective-target named_sections}. 1962 1963@item dg-require-weak "" 1964Skip the test if the target does not support weak symbols. 1965 1966@item dg-require-weak-override "" 1967Skip the test if the target does not support overriding weak symbols. 1968@end table 1969 1970@node Final Actions 1971@subsection Commands for use in @code{dg-final} 1972 1973The GCC testsuite defines the following directives to be used within 1974@code{dg-final}. 1975 1976@subsubsection Scan a particular file 1977 1978@table @code 1979@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1980Passes if @var{regexp} matches text in @var{filename}. 1981@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1982Passes if @var{regexp} does not match text in @var{filename}. 1983@item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}] 1984Passes if @var{regexp} matches in Fortran module @var{module}. 1985@end table 1986 1987@subsubsection Scan the assembly output 1988 1989@table @code 1990@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] 1991Passes if @var{regex} matches text in the test's assembler output. 1992 1993@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] 1994Passes if @var{regex} does not match text in the test's assembler output. 1995 1996@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] 1997Passes if @var{regex} is matched exactly @var{num} times in the test's 1998assembler output. 1999 2000@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] 2001Passes if @var{regex} matches text in the test's demangled assembler output. 2002 2003@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] 2004Passes if @var{regex} does not match text in the test's demangled assembler 2005output. 2006 2007@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 2008Passes if @var{symbol} is defined as a hidden symbol in the test's 2009assembly output. 2010 2011@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 2012Passes if @var{symbol} is not defined as a hidden symbol in the test's 2013assembly output. 2014@end table 2015 2016@subsubsection Scan optimization dump files 2017 2018These commands are available for @var{kind} of @code{tree}, @code{rtl}, 2019and @code{ipa}. 2020 2021@table @code 2022@item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2023Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. 2024 2025@item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2026Passes if @var{regex} does not match text in the dump file with suffix 2027@var{suffix}. 2028 2029@item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] 2030Passes if @var{regex} is found exactly @var{num} times in the dump file 2031with suffix @var{suffix}. 2032 2033@item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2034Passes if @var{regex} matches demangled text in the dump file with 2035suffix @var{suffix}. 2036 2037@item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 2038Passes if @var{regex} does not match demangled text in the dump file with 2039suffix @var{suffix}. 2040@end table 2041 2042@subsubsection Verify that an output files exists or not 2043 2044@table @code 2045@item output-exists [@{ target/xfail @var{selector} @}] 2046Passes if compiler output file exists. 2047 2048@item output-exists-not [@{ target/xfail @var{selector} @}] 2049Passes if compiler output file does not exist. 2050@end table 2051 2052@subsubsection Check for LTO tests 2053 2054@table @code 2055@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] 2056Passes if the pattern is present in the final executable. 2057@end table 2058 2059@subsubsection Checks for @command{gcov} tests 2060 2061@table @code 2062@item run-gcov @var{sourcefile} 2063Check line counts in @command{gcov} tests. 2064 2065@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} 2066Check branch and/or call counts, in addition to line counts, in 2067@command{gcov} tests. 2068@end table 2069 2070@subsubsection Clean up generated test files 2071 2072@table @code 2073@item cleanup-coverage-files 2074Removes coverage data files generated for this test. 2075 2076@item cleanup-ipa-dump @var{suffix} 2077Removes IPA dump files generated for this test. 2078 2079@item cleanup-modules 2080Removes Fortran module files generated for this test. 2081 2082@item cleanup-profile-file 2083Removes profiling files generated for this test. 2084 2085@item cleanup-repo-files 2086Removes files generated for this test for @option{-frepo}. 2087 2088@item cleanup-rtl-dump @var{suffix} 2089Removes RTL dump files generated for this test. 2090 2091@item cleanup-saved-temps 2092Removes files for the current test which were kept for @option{-save-temps}. 2093 2094@item cleanup-tree-dump @var{suffix} 2095Removes tree dump files matching @var{suffix} which were generated for 2096this test. 2097@end table 2098 2099@node Ada Tests 2100@section Ada Language Testsuites 2101 2102The Ada testsuite includes executable tests from the ACATS 2.5 2103testsuite, publicly available at 2104@uref{http://www.adaic.org/compilers/acats/2.5}. 2105 2106These tests are integrated in the GCC testsuite in the 2107@file{ada/acats} directory, and 2108enabled automatically when running @code{make check}, assuming 2109the Ada language has been enabled when configuring GCC@. 2110 2111You can also run the Ada testsuite independently, using 2112@code{make check-ada}, or run a subset of the tests by specifying which 2113chapter to run, e.g.: 2114 2115@smallexample 2116$ make check-ada CHAPTERS="c3 c9" 2117@end smallexample 2118 2119The tests are organized by directory, each directory corresponding to 2120a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds 2121to chapter 9, which deals with tasking features of the language. 2122 2123There is also an extra chapter called @file{gcc} containing a template for 2124creating new executable tests, although this is deprecated in favor of 2125the @file{gnat.dg} testsuite. 2126 2127The tests are run using two @command{sh} scripts: @file{run_acats} and 2128@file{run_all.sh}. To run the tests using a simulator or a cross 2129target, see the small 2130customization section at the top of @file{run_all.sh}. 2131 2132These tests are run using the build tree: they can be run without doing 2133a @code{make install}. 2134 2135@node C Tests 2136@section C Language Testsuites 2137 2138GCC contains the following C language testsuites, in the 2139@file{gcc/testsuite} directory: 2140 2141@table @file 2142@item gcc.dg 2143This contains tests of particular features of the C compiler, using the 2144more modern @samp{dg} harness. Correctness tests for various compiler 2145features should go here if possible. 2146 2147Magic comments determine whether the file 2148is preprocessed, compiled, linked or run. In these tests, error and warning 2149message texts are compared against expected texts or regular expressions 2150given in comments. These tests are run with the options @samp{-ansi -pedantic} 2151unless other options are given in the test. Except as noted below they 2152are not run with multiple optimization options. 2153@item gcc.dg/compat 2154This subdirectory contains tests for binary compatibility using 2155@file{lib/compat.exp}, which in turn uses the language-independent support 2156(@pxref{compat Testing, , Support for testing binary compatibility}). 2157@item gcc.dg/cpp 2158This subdirectory contains tests of the preprocessor. 2159@item gcc.dg/debug 2160This subdirectory contains tests for debug formats. Tests in this 2161subdirectory are run for each debug format that the compiler supports. 2162@item gcc.dg/format 2163This subdirectory contains tests of the @option{-Wformat} format 2164checking. Tests in this directory are run with and without 2165@option{-DWIDE}. 2166@item gcc.dg/noncompile 2167This subdirectory contains tests of code that should not compile and 2168does not need any special compilation options. They are run with 2169multiple optimization options, since sometimes invalid code crashes 2170the compiler with optimization. 2171@item gcc.dg/special 2172FIXME: describe this. 2173 2174@item gcc.c-torture 2175This contains particular code fragments which have historically broken easily. 2176These tests are run with multiple optimization options, so tests for features 2177which only break at some optimization levels belong here. This also contains 2178tests to check that certain optimizations occur. It might be worthwhile to 2179separate the correctness tests cleanly from the code quality tests, but 2180it hasn't been done yet. 2181 2182@item gcc.c-torture/compat 2183FIXME: describe this. 2184 2185This directory should probably not be used for new tests. 2186@item gcc.c-torture/compile 2187This testsuite contains test cases that should compile, but do not 2188need to link or run. These test cases are compiled with several 2189different combinations of optimization options. All warnings are 2190disabled for these test cases, so this directory is not suitable if 2191you wish to test for the presence or absence of compiler warnings. 2192While special options can be set, and tests disabled on specific 2193platforms, by the use of @file{.x} files, mostly these test cases 2194should not contain platform dependencies. FIXME: discuss how defines 2195such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. 2196@item gcc.c-torture/execute 2197This testsuite contains test cases that should compile, link and run; 2198otherwise the same comments as for @file{gcc.c-torture/compile} apply. 2199@item gcc.c-torture/execute/ieee 2200This contains tests which are specific to IEEE floating point. 2201@item gcc.c-torture/unsorted 2202FIXME: describe this. 2203 2204This directory should probably not be used for new tests. 2205@item gcc.misc-tests 2206This directory contains C tests that require special handling. Some 2207of these tests have individual expect files, and others share 2208special-purpose expect files: 2209 2210@table @file 2211@item @code{bprob*.c} 2212Test @option{-fbranch-probabilities} using 2213@file{gcc.misc-tests/bprob.exp}, which 2214in turn uses the generic, language-independent framework 2215(@pxref{profopt Testing, , Support for testing profile-directed 2216optimizations}). 2217 2218@item @code{gcov*.c} 2219Test @command{gcov} output using @file{gcov.exp}, which in turn uses the 2220language-independent support (@pxref{gcov Testing, , Support for testing gcov}). 2221 2222@item @code{i386-pf-*.c} 2223Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. 2224@end table 2225 2226@item gcc.test-framework 2227@table @file 2228@item @code{dg-*.c} 2229Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}. 2230@end table 2231 2232@end table 2233 2234FIXME: merge in @file{testsuite/README.gcc} and discuss the format of 2235test cases and magic comments more. 2236 2237@node libgcj Tests 2238@section The Java library testsuites. 2239 2240Runtime tests are executed via @samp{make check} in the 2241@file{@var{target}/libjava/testsuite} directory in the build 2242tree. Additional runtime tests can be checked into this testsuite. 2243 2244Regression testing of the core packages in libgcj is also covered by the 2245Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} 2246develops tests for the Java Class Libraries. These tests are run as part 2247of libgcj testing by placing the Mauve tree within the libjava testsuite 2248sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying 2249the location of that tree when invoking @samp{make}, as in 2250@samp{make MAUVEDIR=~/mauve check}. 2251 2252To detect regressions, a mechanism in @file{mauve.exp} compares the 2253failures for a test run against the list of expected failures in 2254@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. 2255Update this file when adding new failing tests to Mauve, or when fixing 2256bugs in libgcj that had caused Mauve test failures. 2257 2258We encourage developers to contribute test cases to Mauve. 2259 2260@node LTO Testing 2261@section Support for testing link-time optimizations 2262 2263Tests for link-time optimizations usually require multiple source files 2264that are compiled separately, perhaps with different sets of options. 2265There are several special-purpose test directives used for these tests. 2266 2267@table @code 2268@item @{ dg-lto-do @var{do-what-keyword} @} 2269@var{do-what-keyword} specifies how the test is compiled and whether 2270it is executed. It is one of: 2271 2272@table @code 2273@item assemble 2274Compile with @option{-c} to produce a relocatable object file. 2275@item link 2276Compile, assemble, and link to produce an executable file. 2277@item run 2278Produce and run an executable file, which is expected to return 2279an exit code of 0. 2280@end table 2281 2282The default is @code{assemble}. That can be overridden for a set of 2283tests by redefining @code{dg-do-what-default} within the @code{.exp} 2284file for those tests. 2285 2286Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional 2287@samp{target} or @samp{xfail} list. Use @code{dg-skip-if}, 2288@code{dg-xfail-if}, or @code{dg-xfail-run-if}. 2289 2290@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} 2291This directive provides a list of one or more sets of compiler options 2292to override @var{LTO_OPTIONS}. Each test will be compiled and run with 2293each of these sets of options. 2294 2295@item @{ dg-extra-ld-options @var{options} @} 2296This directive adds @var{options} to the linker options used. 2297 2298@item @{ dg-suppress-ld-options @var{options} @} 2299This directive removes @var{options} from the set of linker options used. 2300@end table 2301 2302@node gcov Testing 2303@section Support for testing @command{gcov} 2304 2305Language-independent support for testing @command{gcov}, and for checking 2306that branch profiling produces expected values, is provided by the 2307expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures 2308in @file{lib/gcc-dg.exp} to compile and run the test program. A typical 2309@command{gcov} test contains the following DejaGnu commands within comments: 2310 2311@smallexample 2312@{ dg-options "-fprofile-arcs -ftest-coverage" @} 2313@{ dg-do run @{ target native @} @} 2314@{ dg-final @{ run-gcov sourcefile @} @} 2315@end smallexample 2316 2317Checks of @command{gcov} output can include line counts, branch percentages, 2318and call return percentages. All of these checks are requested via 2319commands that appear in comments in the test's source file. 2320Commands to check line counts are processed by default. 2321Commands to check branch percentages and call return percentages are 2322processed if the @command{run-gcov} command has arguments @code{branches} 2323or @code{calls}, respectively. For example, the following specifies 2324checking both, as well as passing @option{-b} to @command{gcov}: 2325 2326@smallexample 2327@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} 2328@end smallexample 2329 2330A line count command appears within a comment on the source line 2331that is expected to get the specified count and has the form 2332@code{count(@var{cnt})}. A test should only check line counts for 2333lines that will get the same count for any architecture. 2334 2335Commands to check branch percentages (@code{branch}) and call 2336return percentages (@code{returns}) are very similar to each other. 2337A beginning command appears on or before the first of a range of 2338lines that will report the percentage, and the ending command 2339follows that range of lines. The beginning command can include a 2340list of percentages, all of which are expected to be found within 2341the range. A range is terminated by the next command of the same 2342kind. A command @code{branch(end)} or @code{returns(end)} marks 2343the end of a range without starting a new one. For example: 2344 2345@smallexample 2346if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ 2347 /* @r{branch(end)} */ 2348 foo (i, j); 2349@end smallexample 2350 2351For a call return percentage, the value specified is the 2352percentage of calls reported to return. For a branch percentage, 2353the value is either the expected percentage or 100 minus that 2354value, since the direction of a branch can differ depending on the 2355target or the optimization level. 2356 2357Not all branches and calls need to be checked. A test should not 2358check for branches that might be optimized away or replaced with 2359predicated instructions. Don't check for calls inserted by the 2360compiler or ones that might be inlined or optimized away. 2361 2362A single test can check for combinations of line counts, branch 2363percentages, and call return percentages. The command to check a 2364line count must appear on the line that will report that count, but 2365commands to check branch percentages and call return percentages can 2366bracket the lines that report them. 2367 2368@node profopt Testing 2369@section Support for testing profile-directed optimizations 2370 2371The file @file{profopt.exp} provides language-independent support for 2372checking correct execution of a test built with profile-directed 2373optimization. This testing requires that a test program be built and 2374executed twice. The first time it is compiled to generate profile 2375data, and the second time it is compiled to use the data that was 2376generated during the first execution. The second execution is to 2377verify that the test produces the expected results. 2378 2379To check that the optimization actually generated better code, a 2380test can be built and run a third time with normal optimizations to 2381verify that the performance is better with the profile-directed 2382optimizations. @file{profopt.exp} has the beginnings of this kind 2383of support. 2384 2385@file{profopt.exp} provides generic support for profile-directed 2386optimizations. Each set of tests that uses it provides information 2387about a specific optimization: 2388 2389@table @code 2390@item tool 2391tool being tested, e.g., @command{gcc} 2392 2393@item profile_option 2394options used to generate profile data 2395 2396@item feedback_option 2397options used to optimize using that profile data 2398 2399@item prof_ext 2400suffix of profile data files 2401 2402@item PROFOPT_OPTIONS 2403list of options with which to run each test, similar to the lists for 2404torture tests 2405 2406@item @{ dg-final-generate @{ @var{local-directive} @} @} 2407This directive is similar to @code{dg-final}, but the 2408@var{local-directive} is run after the generation of profile data. 2409 2410@item @{ dg-final-use @{ @var{local-directive} @} @} 2411The @var{local-directive} is run after the profile data have been 2412used. 2413@end table 2414 2415@node compat Testing 2416@section Support for testing binary compatibility 2417 2418The file @file{compat.exp} provides language-independent support for 2419binary compatibility testing. It supports testing interoperability of 2420two compilers that follow the same ABI, or of multiple sets of 2421compiler options that should not affect binary compatibility. It is 2422intended to be used for testsuites that complement ABI testsuites. 2423 2424A test supported by this framework has three parts, each in a 2425separate source file: a main program and two pieces that interact 2426with each other to split up the functionality being tested. 2427 2428@table @file 2429@item @var{testname}_main.@var{suffix} 2430Contains the main program, which calls a function in file 2431@file{@var{testname}_x.@var{suffix}}. 2432 2433@item @var{testname}_x.@var{suffix} 2434Contains at least one call to a function in 2435@file{@var{testname}_y.@var{suffix}}. 2436 2437@item @var{testname}_y.@var{suffix} 2438Shares data with, or gets arguments from, 2439@file{@var{testname}_x.@var{suffix}}. 2440@end table 2441 2442Within each test, the main program and one functional piece are 2443compiled by the GCC under test. The other piece can be compiled by 2444an alternate compiler. If no alternate compiler is specified, 2445then all three source files are all compiled by the GCC under test. 2446You can specify pairs of sets of compiler options. The first element 2447of such a pair specifies options used with the GCC under test, and the 2448second element of the pair specifies options used with the alternate 2449compiler. Each test is compiled with each pair of options. 2450 2451@file{compat.exp} defines default pairs of compiler options. 2452These can be overridden by defining the environment variable 2453@env{COMPAT_OPTIONS} as: 2454 2455@smallexample 2456COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] 2457 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]" 2458@end smallexample 2459 2460where @var{tsti} and @var{alti} are lists of options, with @var{tsti} 2461used by the compiler under test and @var{alti} used by the alternate 2462compiler. For example, with 2463@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, 2464the test is first built with @option{-g -O0} by the compiler under 2465test and with @option{-O3} by the alternate compiler. The test is 2466built a second time using @option{-fpic} by the compiler under test 2467and @option{-fPIC -O2} by the alternate compiler. 2468 2469An alternate compiler is specified by defining an environment 2470variable to be the full pathname of an installed compiler; for C 2471define @env{ALT_CC_UNDER_TEST}, and for C++ define 2472@env{ALT_CXX_UNDER_TEST}. These will be written to the 2473@file{site.exp} file used by DejaGnu. The default is to build each 2474test with the compiler under test using the first of each pair of 2475compiler options from @env{COMPAT_OPTIONS}. When 2476@env{ALT_CC_UNDER_TEST} or 2477@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using 2478the compiler under test but with combinations of the options from 2479@env{COMPAT_OPTIONS}. 2480 2481To run only the C++ compatibility suite using the compiler under test 2482and another version of GCC using specific compiler options, do the 2483following from @file{@var{objdir}/gcc}: 2484 2485@smallexample 2486rm site.exp 2487make -k \ 2488 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ 2489 COMPAT_OPTIONS="@var{lists as shown above}" \ 2490 check-c++ \ 2491 RUNTESTFLAGS="compat.exp" 2492@end smallexample 2493 2494A test that fails when the source files are compiled with different 2495compilers, but passes when the files are compiled with the same 2496compiler, demonstrates incompatibility of the generated code or 2497runtime support. A test that fails for the alternate compiler but 2498passes for the compiler under test probably tests for a bug that was 2499fixed in the compiler under test but is present in the alternate 2500compiler. 2501 2502The binary compatibility tests support a small number of test framework 2503commands that appear within comments in a test file. 2504 2505@table @code 2506@item dg-require-* 2507These commands can be used in @file{@var{testname}_main.@var{suffix}} 2508to skip the test if specific support is not available on the target. 2509 2510@item dg-options 2511The specified options are used for compiling this particular source 2512file, appended to the options from @env{COMPAT_OPTIONS}. When this 2513command appears in @file{@var{testname}_main.@var{suffix}} the options 2514are also used to link the test program. 2515 2516@item dg-xfail-if 2517This command can be used in a secondary source file to specify that 2518compilation is expected to fail for particular options on particular 2519targets. 2520@end table 2521 2522@node Torture Tests 2523@section Support for torture testing using multiple options 2524 2525Throughout the compiler testsuite there are several directories whose 2526tests are run multiple times, each with a different set of options. 2527These are known as torture tests. 2528@file{lib/torture-options.exp} defines procedures to 2529set up these lists: 2530 2531@table @code 2532@item torture-init 2533Initialize use of torture lists. 2534@item set-torture-options 2535Set lists of torture options to use for tests with and without loops. 2536Optionally combine a set of torture options with a set of other 2537options, as is done with Objective-C runtime options. 2538@item torture-finish 2539Finalize use of torture lists. 2540@end table 2541 2542The @file{.exp} file for a set of tests that use torture options must 2543include calls to these three procedures if: 2544 2545@itemize @bullet 2546@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}. 2547 2548@item It calls @var{$@{tool@}}@code{-torture} or 2549@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c}, 2550@code{fortran}, or @code{objc}. 2551 2552@item It calls @code{dg-pch}. 2553@end itemize 2554 2555It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest} 2556to call the torture procedures if the tests should use the list in 2557@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}. 2558 2559Most uses of torture options can override the default lists by defining 2560@var{TORTURE_OPTIONS} or add to the default list by defining 2561@var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc} 2562file or add them to the @file{site.exp} file; for example 2563 2564@smallexample 2565set ADDITIONAL_TORTURE_OPTIONS [list \ 2566 @{ -O2 -ftree-loop-linear @} \ 2567 @{ -O2 -fpeel-loops @} ] 2568@end smallexample 2569