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