1@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@node Source Tree 6@chapter Source Tree Structure and Build System 7 8This chapter describes the structure of the GCC source tree, and how 9GCC is built. The user documentation for building and installing GCC 10is in a separate manual (@uref{http://gcc.gnu.org/install/}), with 11which it is presumed that you are familiar. 12 13@menu 14* Configure Terms:: Configuration terminology and history. 15* Top Level:: The top level source directory. 16* gcc Directory:: The @file{gcc} subdirectory. 17* Testsuites:: The GCC testsuites. 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 contrib 36Contributed scripts that may be found useful in conjunction with GCC@. 37One of these, @file{contrib/texi2pod.pl}, is used to generate man 38pages from Texinfo manuals as part of the GCC build process. 39 40@item fastjar 41An implementation of the @command{jar} command, used with the Java 42front end. 43 44@item gcc 45The main sources of GCC itself (except for runtime libraries), 46including optimizers, support for different target architectures, 47language front ends, and testsuites. @xref{gcc Directory, , The 48@file{gcc} Subdirectory}, for details. 49 50@item include 51Headers for the @code{libiberty} library. 52 53@item libada 54The Ada runtime library. 55 56@item libcpp 57The C preprocessor library. 58 59@item libgfortran 60The Fortran runtime library. 61 62@item libffi 63The @code{libffi} library, used as part of the Java runtime library. 64 65@item libiberty 66The @code{libiberty} library, used for portability and for some 67generally useful data structures and algorithms. @xref{Top, , 68Introduction, libiberty, @sc{gnu} libiberty}, for more information 69about this library. 70 71@item libjava 72The Java runtime library. 73 74@item libmudflap 75The @code{libmudflap} library, used for instrumenting pointer and array 76dereferencing operations. 77 78@item libstdc++-v3 79The C++ runtime library. 80 81@item maintainer-scripts 82Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. 83 84@item zlib 85The @code{zlib} compression library, used by the Java front end and as 86part of the Java runtime library. 87@end table 88 89The build system in the top level directory, including how recursion 90into subdirectories works and how building runtime libraries for 91multilibs is handled, is documented in a separate manual, included 92with GNU Binutils. @xref{Top, , GNU configure and build system, 93configure, The GNU configure and build system}, for details. 94 95@node gcc Directory 96@section The @file{gcc} Subdirectory 97 98The @file{gcc} directory contains many files that are part of the C 99sources of GCC, other files used as part of the configuration and 100build process, and subdirectories including documentation and a 101testsuite. The files that are sources of GCC are documented in a 102separate chapter. @xref{Passes, , Passes and Files of the Compiler}. 103 104@menu 105* Subdirectories:: Subdirectories of @file{gcc}. 106* Configuration:: The configuration process, and the files it uses. 107* Build:: The build system in the @file{gcc} directory. 108* Makefile:: Targets in @file{gcc/Makefile}. 109* Library Files:: Library source files and headers under @file{gcc/}. 110* Headers:: Headers installed by GCC. 111* Documentation:: Building documentation in GCC. 112* Front End:: Anatomy of a language front end. 113* Back End:: Anatomy of a target back end. 114@end menu 115 116@node Subdirectories 117@subsection Subdirectories of @file{gcc} 118 119The @file{gcc} directory contains the following subdirectories: 120 121@table @file 122@item @var{language} 123Subdirectories for various languages. Directories containing a file 124@file{config-lang.in} are language subdirectories. The contents of 125the subdirectory @file{cp} (for C++) is documented in this manual 126(@pxref{Passes, , Passes and Files of the Compiler}); those for other 127languages are not. @xref{Front End, , Anatomy of a Language Front End}, 128for details of the files in these directories. 129 130@item config 131Configuration files for supported architectures and operating 132systems. @xref{Back End, , Anatomy of a Target Back End}, for 133details of the files in this directory. 134 135@item doc 136Texinfo documentation for GCC, together with automatically generated 137man pages and support for converting the installation manual to 138HTML@. @xref{Documentation}. 139 140@item fixinc 141The support for fixing system headers to work with GCC@. See 142@file{fixinc/README} for more information. The headers fixed by this 143mechanism are installed in @file{@var{libsubdir}/include}. Along with 144those headers, @file{README-fixinc} is also installed, as 145@file{@var{libsubdir}/include/README}. 146 147@item ginclude 148System headers installed by GCC, mainly those required by the C 149standard of freestanding implementations. @xref{Headers, , Headers 150Installed by GCC}, for details of when these and other headers are 151installed. 152 153@item intl 154GNU @code{libintl}, from GNU @code{gettext}, for systems which do not 155include it in libc. Properly, this directory should be at top level, 156parallel to the @file{gcc} directory. 157 158@item po 159Message catalogs with translations of messages produced by GCC into 160various languages, @file{@var{language}.po}. This directory also 161contains @file{gcc.pot}, the template for these message catalogues, 162@file{exgettext}, a wrapper around @command{gettext} to extract the 163messages from the GCC sources and create @file{gcc.pot}, which is run 164by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from 165which messages should not be extracted. 166 167@item testsuite 168The GCC testsuites (except for those for runtime libraries). 169@xref{Testsuites}. 170@end table 171 172@node Configuration 173@subsection Configuration in the @file{gcc} Directory 174 175The @file{gcc} directory is configured with an Autoconf-generated 176script @file{configure}. The @file{configure} script is generated 177from @file{configure.ac} and @file{aclocal.m4}. From the files 178@file{configure.ac} and @file{acconfig.h}, Autoheader generates the 179file @file{config.in}. The file @file{cstamp-h.in} is used as a 180timestamp. 181 182@menu 183* Config Fragments:: Scripts used by @file{configure}. 184* System Config:: The @file{config.build}, @file{config.host}, and 185 @file{config.gcc} files. 186* Configuration Files:: Files created by running @file{configure}. 187@end menu 188 189@node Config Fragments 190@subsubsection Scripts Used by @file{configure} 191 192@file{configure} uses some other scripts to help in its work: 193 194@itemize @bullet 195@item The standard GNU @file{config.sub} and @file{config.guess} 196files, kept in the top level directory, are used. FIXME: when is the 197@file{config.guess} file in the @file{gcc} directory (that just calls 198the top level one) used? 199 200@item The file @file{config.gcc} is used to handle configuration 201specific to the particular target machine. The file 202@file{config.build} is used to handle configuration specific to the 203particular build machine. The file @file{config.host} is used to handle 204configuration specific to the particular host machine. (In general, 205these should only be used for features that cannot reasonably be tested in 206Autoconf feature tests.) 207@xref{System Config, , The @file{config.build}; @file{config.host}; 208and @file{config.gcc} Files}, for details of the contents of these files. 209 210@item Each language subdirectory has a file 211@file{@var{language}/config-lang.in} that is used for 212front-end-specific configuration. @xref{Front End Config, , The Front 213End @file{config-lang.in} File}, for details of this file. 214 215@item A helper script @file{configure.frag} is used as part of 216creating the output of @file{configure}. 217@end itemize 218 219@node System Config 220@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files 221 222The @file{config.build} file contains specific rules for particular systems 223which GCC is built on. This should be used as rarely as possible, as the 224behavior of the build system can always be detected by autoconf. 225 226The @file{config.host} file contains specific rules for particular systems 227which GCC will run on. This is rarely needed. 228 229The @file{config.gcc} file contains specific rules for particular systems 230which GCC will generate code for. This is usually needed. 231 232Each file has a list of the shell variables it sets, with descriptions, at the 233top of the file. 234 235FIXME: document the contents of these files, and what variables should 236be set to control build, host and target configuration. 237 238@include configfiles.texi 239 240@node Build 241@subsection Build System in the @file{gcc} Directory 242 243FIXME: describe the build system, including what is built in what 244stages. Also list the various source files that are used in the build 245process but aren't source files of GCC itself and so aren't documented 246below (@pxref{Passes}). 247 248@include makefile.texi 249 250@node Library Files 251@subsection Library Source Files and Headers under the @file{gcc} Directory 252 253FIXME: list here, with explanation, all the C source files and headers 254under the @file{gcc} directory that aren't built into the GCC 255executable but rather are part of runtime libraries and object files, 256such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , 257Headers Installed by GCC}, for more information about the 258@file{ginclude} directory. 259 260@node Headers 261@subsection Headers Installed by GCC 262 263In general, GCC expects the system C library to provide most of the 264headers to be used with it. However, GCC will fix those headers if 265necessary to make them work with GCC, and will install some headers 266required of freestanding implementations. These headers are installed 267in @file{@var{libsubdir}/include}. Headers for non-C runtime 268libraries are also installed by GCC; these are not documented here. 269(FIXME: document them somewhere.) 270 271Several of the headers GCC installs are in the @file{ginclude} 272directory. These headers, @file{iso646.h}, 273@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, 274are installed in @file{@var{libsubdir}/include}, 275unless the target Makefile fragment (@pxref{Target Fragment}) 276overrides this by setting @code{USER_H}. 277 278In addition to these headers and those generated by fixing system 279headers to work with GCC, some other headers may also be installed in 280@file{@var{libsubdir}/include}. @file{config.gcc} may set 281@code{extra_headers}; this specifies additional headers under 282@file{config} to be installed on some systems. 283 284GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. 285This is done to cope with command-line options that change the 286representation of floating point numbers. 287 288GCC also installs its own version of @code{<limits.h>}; this is generated 289from @file{glimits.h}, together with @file{limitx.h} and 290@file{limity.h} if the system also has its own version of 291@code{<limits.h>}. (GCC provides its own header because it is 292required of ISO C freestanding implementations, but needs to include 293the system header from its own header as well because other standards 294such as POSIX specify additional values to be defined in 295@code{<limits.h>}.) The system's @code{<limits.h>} header is used via 296@file{@var{libsubdir}/include/syslimits.h}, which is copied from 297@file{gsyslimits.h} if it does not need fixing to work with GCC; if it 298needs fixing, @file{syslimits.h} is the fixed copy. 299 300@node Documentation 301@subsection Building Documentation 302 303The main GCC documentation is in the form of manuals in Texinfo 304format. These are installed in Info format; DVI versions may be 305generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and 306HTML versions by @command{make html}. In addition, some man pages are 307generated from the Texinfo manuals, there are some other text files 308with miscellaneous documentation, and runtime libraries have their own 309documentation outside the @file{gcc} directory. FIXME: document the 310documentation for runtime libraries somewhere. 311 312@menu 313* Texinfo Manuals:: GCC manuals in Texinfo format. 314* Man Page Generation:: Generating man pages from Texinfo manuals. 315* Miscellaneous Docs:: Miscellaneous text files with documentation. 316@end menu 317 318@node Texinfo Manuals 319@subsubsection Texinfo Manuals 320 321The manuals for GCC as a whole, and the C and C++ front ends, are in 322files @file{doc/*.texi}. Other front ends have their own manuals in 323files @file{@var{language}/*.texi}. Common files 324@file{doc/include/*.texi} are provided which may be included in 325multiple manuals; the following files are in @file{doc/include}: 326 327@table @file 328@item fdl.texi 329The GNU Free Documentation License. 330@item funding.texi 331The section ``Funding Free Software''. 332@item gcc-common.texi 333Common definitions for manuals. 334@item gpl.texi 335The GNU General Public License. 336@item texinfo.tex 337A copy of @file{texinfo.tex} known to work with the GCC manuals. 338@end table 339 340DVI-formatted manuals are generated by @samp{make dvi}, which uses 341@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). 342PDF-formatted manuals are generated by @samp{make pdf}, which uses 343@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML 344formatted manuals are generated by @command{make html}. Info 345manuals are generated by @samp{make info} (which is run as part of 346a bootstrap); this generates the manuals in the source directory, 347using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, 348and they are included in release distributions. 349 350Manuals are also provided on the GCC web site, in both HTML and 351PostScript forms. This is done via the script 352@file{maintainer-scripts/update_web_docs}. Each manual to be 353provided online must be listed in the definition of @code{MANUALS} in 354that file; a file @file{@var{name}.texi} must only appear once in the 355source tree, and the output manual must have the same name as the 356source file. (However, other Texinfo files, included in manuals but 357not themselves the root files of manuals, may have names that appear 358more than once in the source tree.) The manual file 359@file{@var{name}.texi} should only include other files in its own 360directory or in @file{doc/include}. HTML manuals will be generated by 361@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} 362and @command{dvips}, and PDF manuals by @command{texi2pdf}. 363All Texinfo files that are parts of manuals must 364be checked into CVS, even if they are generated files, for the 365generation of online manuals to work. 366 367The installation manual, @file{doc/install.texi}, is also provided on 368the GCC web site. The HTML version is generated by the script 369@file{doc/install.texi2html}. 370 371@node Man Page Generation 372@subsubsection Man Page Generation 373 374Because of user demand, in addition to full Texinfo manuals, man pages 375are provided which contain extracts from those manuals. These man 376pages are generated from the Texinfo manuals using 377@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for 378@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference 379to @file{gcc.1}, but all the other man pages are generated from 380Texinfo manuals.) 381 382Because many systems may not have the necessary tools installed to 383generate the man pages, they are only generated if the 384@file{configure} script detects that recent enough tools are 385installed, and the Makefiles allow generating man pages to fail 386without aborting the build. Man pages are also included in release 387distributions. They are generated in the source directory. 388 389Magic comments in Texinfo files starting @samp{@@c man} control what 390parts of a Texinfo file go into a man page. Only a subset of Texinfo 391is supported by @file{texi2pod.pl}, and it may be necessary to add 392support for more Texinfo features to this script when generating new 393man pages. To improve the man page output, some special Texinfo 394macros are provided in @file{doc/include/gcc-common.texi} which 395@file{texi2pod.pl} understands: 396 397@table @code 398@item @@gcctabopt 399Use in the form @samp{@@table @@gcctabopt} for tables of options, 400where for printed output the effect of @samp{@@code} is better than 401that of @samp{@@option} but for man page output a different effect is 402wanted. 403@item @@gccoptlist 404Use for summary lists of options in manuals. 405@item @@gol 406Use at the end of each line inside @samp{@@gccoptlist}. This is 407necessary to avoid problems with differences in how the 408@samp{@@gccoptlist} macro is handled by different Texinfo formatters. 409@end table 410 411FIXME: describe the @file{texi2pod.pl} input language and magic 412comments in more detail. 413 414@node Miscellaneous Docs 415@subsubsection Miscellaneous Documentation 416 417In addition to the formal documentation that is installed by GCC, 418there are several other text files with miscellaneous documentation: 419 420@table @file 421@item ABOUT-GCC-NLS 422Notes on GCC's Native Language Support. FIXME: this should be part of 423this manual rather than a separate file. 424@item ABOUT-NLS 425Notes on the Free Translation Project. 426@item COPYING 427The GNU General Public License. 428@item COPYING.LIB 429The GNU Lesser General Public License. 430@item *ChangeLog* 431@itemx */ChangeLog* 432Change log files for various parts of GCC@. 433@item LANGUAGES 434Details of a few changes to the GCC front-end interface. FIXME: the 435information in this file should be part of general documentation of 436the front-end interface in this manual. 437@item ONEWS 438Information about new features in old versions of GCC@. (For recent 439versions, the information is on the GCC web site.) 440@item README.Portability 441Information about portability issues when writing code in GCC@. FIXME: 442why isn't this part of this manual or of the GCC Coding Conventions? 443@item SERVICE 444A pointer to the GNU Service Directory. 445@end table 446 447FIXME: document such files in subdirectories, at least @file{config}, 448@file{cp}, @file{testsuite}. 449 450@node Front End 451@subsection Anatomy of a Language Front End 452 453A front end for a language in GCC has the following parts: 454 455@itemize @bullet 456@item 457A directory @file{@var{language}} under @file{gcc} containing source 458files for that front end. @xref{Front End Directory, , The Front End 459@file{@var{language}} Directory}, for details. 460@item 461A mention of the language in the list of supported languages in 462@file{gcc/doc/install.texi}. 463@item 464A mention of the name under which the language's runtime library is 465recognized by @option{--enable-shared=@var{package}} in the 466documentation of that option in @file{gcc/doc/install.texi}. 467@item 468A mention of any special prerequisites for building the front end in 469the documentation of prerequisites in @file{gcc/doc/install.texi}. 470@item 471Details of contributors to that front end in 472@file{gcc/doc/contrib.texi}. If the details are in that front end's 473own manual then there should be a link to that manual's list in 474@file{contrib.texi}. 475@item 476Information about support for that language in 477@file{gcc/doc/frontends.texi}. 478@item 479Information about standards for that language, and the front end's 480support for them, in @file{gcc/doc/standards.texi}. This may be a 481link to such information in the front end's own manual. 482@item 483Details of source file suffixes for that language and @option{-x 484@var{lang}} options supported, in @file{gcc/doc/invoke.texi}. 485@item 486Entries in @code{default_compilers} in @file{gcc.c} for source file 487suffixes for that language. 488@item 489Preferably testsuites, which may be under @file{gcc/testsuite} or 490runtime library directories. FIXME: document somewhere how to write 491testsuite harnesses. 492@item 493Probably a runtime library for the language, outside the @file{gcc} 494directory. FIXME: document this further. 495@item 496Details of the directories of any runtime libraries in 497@file{gcc/doc/sourcebuild.texi}. 498@end itemize 499 500If the front end is added to the official GCC CVS repository, the 501following are also necessary: 502 503@itemize @bullet 504@item 505At least one Bugzilla component for bugs in that front end and runtime 506libraries. This category needs to be mentioned in 507@file{gcc/gccbug.in}, as well as being added to the Bugzilla database. 508@item 509Normally, one or more maintainers of that front end listed in 510@file{MAINTAINERS}. 511@item 512Mentions on the GCC web site in @file{index.html} and 513@file{frontends.html}, with any relevant links on 514@file{readings.html}. (Front ends that are not an official part of 515GCC may also be listed on @file{frontends.html}, with relevant links.) 516@item 517A news item on @file{index.html}, and possibly an announcement on the 518@email{gcc-announce@@gcc.gnu.org} mailing list. 519@item 520The front end's manuals should be mentioned in 521@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals}) 522and the online manuals should be linked to from 523@file{onlinedocs/index.html}. 524@item 525Any old releases or CVS repositories of the front end, before its 526inclusion in GCC, should be made available on the GCC FTP site 527@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. 528@item 529The release and snapshot script @file{maintainer-scripts/gcc_release} 530should be updated to generate appropriate tarballs for this front end. 531The associated @file{maintainer-scripts/snapshot-README} and 532@file{maintainer-scripts/snapshot-index.html} files should be updated 533to list the tarballs and diffs for this front end. 534@item 535If this front end includes its own version files that include the 536current date, @file{maintainer-scripts/update_version} should be 537updated accordingly. 538@item 539@file{CVSROOT/modules} in the GCC CVS repository should be updated. 540@end itemize 541 542@menu 543* Front End Directory:: The front end @file{@var{language}} directory. 544* Front End Config:: The front end @file{config-lang.in} file. 545@end menu 546 547@node Front End Directory 548@subsubsection The Front End @file{@var{language}} Directory 549 550A front end @file{@var{language}} directory contains the source files 551of that front end (but not of any runtime libraries, which should be 552outside the @file{gcc} directory). This includes documentation, and 553possibly some subsidiary programs build alongside the front end. 554Certain files are special and other parts of the compiler depend on 555their names: 556 557@table @file 558@item config-lang.in 559This file is required in all language subdirectories. @xref{Front End 560Config, , The Front End @file{config-lang.in} File}, for details of 561its contents 562@item Make-lang.in 563This file is required in all language subdirectories. It contains 564targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the 565setting of @code{language} in @file{config-lang.in}) for the following 566values of @code{@var{hook}}, and any other Makefile rules required to 567build those targets (which may if necessary use other Makefiles 568specified in @code{outputs} in @file{config-lang.in}, although this is 569deprecated). It also adds any testsuite targets that can use the 570standard rule in @file{gcc/Makefile.in} to the variable 571@code{lang_checks}. 572 573@table @code 574@itemx all.cross 575@itemx start.encap 576@itemx rest.encap 577FIXME: exactly what goes in each of these targets? 578@item tags 579Build an @command{etags} @file{TAGS} file in the language subdirectory 580in the source tree. 581@item info 582Build info documentation for the front end, in the build directory. 583This target is only called by @samp{make bootstrap} if a suitable 584version of @command{makeinfo} is available, so does not need to check 585for this, and should fail if an error occurs. 586@item dvi 587Build DVI documentation for the front end, in the build directory. 588This should be done using @code{$(TEXI2DVI)}, with appropriate 589@option{-I} arguments pointing to directories of included files. 590@item pdf 591Build PDF documentation for the front end, in the build directory. 592This should be done using @code{$(TEXI2PDF)}, with appropriate 593@option{-I} arguments pointing to directories of included files. 594@item html 595Build HTML documentation for the front end, in the build directory. 596@item man 597Build generated man pages for the front end from Texinfo manuals 598(@pxref{Man Page Generation}), in the build directory. This target 599is only called if the necessary tools are available, but should ignore 600errors so as not to stop the build if errors occur; man pages are 601optional and the tools involved may be installed in a broken way. 602@item install-common 603Install everything that is part of the front end, apart from the 604compiler executables listed in @code{compilers} in 605@file{config-lang.in}. 606@item install-info 607Install info documentation for the front end, if it is present in the 608source directory. This target should have dependencies on info files 609that should be installed. 610@item install-man 611Install man pages for the front end. This target should ignore 612errors. 613@item srcextra 614Copies its dependencies into the source directory. This generally should 615be used for generated files such as Bison output files which are not 616present in CVS, but should be included in any release tarballs. This 617target will be executed during a bootstrap if 618@samp{--enable-generated-files-in-srcdir} was specified as a 619@file{configure} option. 620@item srcinfo 621@itemx srcman 622Copies its dependencies into the source directory. These targets will be 623executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} 624was specified as a @file{configure} option. 625@item uninstall 626Uninstall files installed by installing the compiler. This is 627currently documented not to be supported, so the hook need not do 628anything. 629@item mostlyclean 630@itemx clean 631@itemx distclean 632@itemx maintainer-clean 633The language parts of the standard GNU 634@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for 635Users, standards, GNU Coding Standards}, for details of the standard 636targets. For GCC, @code{maintainer-clean} should delete 637all generated files in the source directory that are not checked into 638CVS, but should not delete anything checked into CVS@. 639@item stage1 640@itemx stage2 641@itemx stage3 642@itemx stage4 643@itemx stageprofile 644@itemx stagefeedback 645Move to the stage directory files not included in @code{stagestuff} in 646@file{config-lang.in} or otherwise moved by the main @file{Makefile}. 647@end table 648 649@item lang.opt 650This file registers the set of switches that the front end accepts on 651the command line, and their @option{--help} text. @xref{Options}. 652@item lang-specs.h 653This file provides entries for @code{default_compilers} in 654@file{gcc.c} which override the default of giving an error that a 655compiler for that language is not installed. 656@item @var{language}-tree.def 657This file, which need not exist, defines any language-specific tree 658codes. 659@end table 660 661@node Front End Config 662@subsubsection The Front End @file{config-lang.in} File 663 664Each language subdirectory contains a @file{config-lang.in} file. In 665addition the main directory contains @file{c-config-lang.in}, which 666contains limited information for the C language. This file is a shell 667script that may define some variables describing the language: 668 669@table @code 670@item language 671This definition must be present, and gives the name of the language 672for some purposes such as arguments to @option{--enable-languages}. 673@item lang_requires 674If defined, this variable lists (space-separated) language front ends 675other than C that this front end requires to be enabled (with the 676names given being their @code{language} settings). For example, the 677Java front end depends on the C++ front end, so sets 678@samp{lang_requires=c++}. 679@item subdir_requires 680If defined, this variable lists (space-separated) front end directories 681other than C that this front end requires to be present. 682@item target_libs 683If defined, this variable lists (space-separated) targets in the top 684level @file{Makefile} to build the runtime libraries for this 685language. 686@item lang_dirs 687If defined, this variable lists (space-separated) top level 688directories (parallel to @file{gcc}), apart from the runtime libraries, 689that should not be configured if this front end is not built. 690@item build_by_default 691If defined to @samp{no}, this language front end is not built unless 692enabled in a @option{--enable-languages} argument. Otherwise, front 693ends are built by default, subject to any special logic in 694@file{configure.ac} (as is present to disable the Ada front end if the 695Ada compiler is not already installed). 696@item boot_language 697If defined to @samp{yes}, this front end is built in stage 1 of the 698bootstrap. This is only relevant to front ends written in their own 699languages. 700@item compilers 701If defined, a space-separated list of compiler executables that will 702be run by the driver. The names here will each end 703with @samp{\$(exeext)}. 704@item stagestuff 705If defined, a space-separated list of files that should be moved to 706the @file{stage@var{n}} directories in each stage of bootstrap. 707@item outputs 708If defined, a space-separated list of files that should be generated 709by @file{configure} substituting values in them. This mechanism can 710be used to create a file @file{@var{language}/Makefile} from 711@file{@var{language}/Makefile.in}, but this is deprecated, building 712everything from the single @file{gcc/Makefile} is preferred. 713@item gtfiles 714If defined, a space-separated list of files that should be scanned by 715gengtype.c to generate the garbage collection tables and routines for 716this language. This excludes the files that are common to all front 717ends. @xref{Type Information}. 718@item need_gmp 719If defined to @samp{yes}, this frontend requires the GMP library. 720Enables configure tests for GMP, which set @code{GMPLIBS} and 721@code{GMPINC} appropriately. 722 723@end table 724 725@node Back End 726@subsection Anatomy of a Target Back End 727 728A back end for a target architecture in GCC has the following parts: 729 730@itemize @bullet 731@item 732A directory @file{@var{machine}} under @file{gcc/config}, containing a 733machine description @file{@var{machine}.md} file (@pxref{Machine Desc, 734, Machine Descriptions}), header files @file{@var{machine}.h} and 735@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} 736(@pxref{Target Macros, , Target Description Macros and Functions}), 737possibly a target Makefile fragment @file{t-@var{machine}} 738(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe 739some other files. The names of these files may be changed from the 740defaults given by explicit specifications in @file{config.gcc}. 741@item 742If necessary, a file @file{@var{machine}-modes.def} in the 743@file{@var{machine}} directory, containing additional machine modes to 744represent condition codes. @xref{Condition Code}, for further details. 745@item 746An optional @file{@var{machine}.opt} file in the @file{@var{machine}} 747directory, containing a list of target-specific options. You can also 748add other option files using the @code{extra_options} variable in 749@file{config.gcc}. @xref{Options}. 750@item 751Entries in @file{config.gcc} (@pxref{System Config, , The 752@file{config.gcc} File}) for the systems with this target 753architecture. 754@item 755Documentation in @file{gcc/doc/invoke.texi} for any command-line 756options supported by this target (@pxref{Run-time Target, , Run-time 757Target Specification}). This means both entries in the summary table 758of options and details of the individual options. 759@item 760Documentation in @file{gcc/doc/extend.texi} for any target-specific 761attributes supported (@pxref{Target Attributes, , Defining 762target-specific uses of @code{__attribute__}}), including where the 763same attribute is already supported on some targets, which are 764enumerated in the manual. 765@item 766Documentation in @file{gcc/doc/extend.texi} for any target-specific 767pragmas supported. 768@item 769Documentation in @file{gcc/doc/extend.texi} of any target-specific 770built-in functions supported. 771@item 772Documentation in @file{gcc/doc/extend.texi} of any target-specific 773format checking styles supported. 774@item 775Documentation in @file{gcc/doc/md.texi} of any target-specific 776constraint letters (@pxref{Machine Constraints, , Constraints for 777Particular Machines}). 778@item 779A note in @file{gcc/doc/contrib.texi} under the person or people who 780contributed the target support. 781@item 782Entries in @file{gcc/doc/install.texi} for all target triplets 783supported with this target architecture, giving details of any special 784notes about installation for this target, or saying that there are no 785special notes if there are none. 786@item 787Possibly other support outside the @file{gcc} directory for runtime 788libraries. FIXME: reference docs for this. The libstdc++ porting 789manual needs to be installed as info for this to work, or to be a 790chapter of this manual. 791@end itemize 792 793If the back end is added to the official GCC CVS repository, the 794following are also necessary: 795 796@itemize @bullet 797@item 798An entry for the target architecture in @file{readings.html} on the 799GCC web site, with any relevant links. 800@item 801Details of the properties of the back end and target architecture in 802@file{backends.html} on the GCC web site. 803@item 804A news item about the contribution of support for that target 805architecture, in @file{index.html} on the GCC web site. 806@item 807Normally, one or more maintainers of that target listed in 808@file{MAINTAINERS}. Some existing architectures may be unmaintained, 809but it would be unusual to add support for a target that does not have 810a maintainer when support is added. 811@end itemize 812 813@node Testsuites 814@section Testsuites 815 816GCC contains several testsuites to help maintain compiler quality. 817Most of the runtime libraries and language front ends in GCC have 818testsuites. Currently only the C language testsuites are documented 819here; FIXME: document the others. 820 821@menu 822* Test Idioms:: Idioms used in testsuite code. 823* Test Directives:: Directives used within DejaGnu tests. 824* Ada Tests:: The Ada language testsuites. 825* C Tests:: The C language testsuites. 826* libgcj Tests:: The Java library testsuites. 827* gcov Testing:: Support for testing gcov. 828* profopt Testing:: Support for testing profile-directed optimizations. 829* compat Testing:: Support for testing binary compatibility. 830@end menu 831 832@node Test Idioms 833@subsection Idioms Used in Testsuite Code 834 835In general, C testcases have a trailing @file{-@var{n}.c}, starting 836with @file{-1.c}, in case other testcases with similar names are added 837later. If the test is a test of some well-defined feature, it should 838have a name referring to that feature such as 839@file{@var{feature}-1.c}. If it does not test a well-defined feature 840but just happens to exercise a bug somewhere in the compiler, and a 841bug report has been filed for this bug in the GCC bug database, 842@file{pr@var{bug-number}-1.c} is the appropriate form of name. 843Otherwise (for miscellaneous bugs not filed in the GCC bug database), 844and previously more generally, test cases are named after the date on 845which they were added. This allows people to tell at a glance whether 846a test failure is because of a recently found bug that has not yet 847been fixed, or whether it may be a regression, but does not give any 848other information about the bug or where discussion of it may be 849found. Some other language testsuites follow similar conventions. 850 851In the @file{gcc.dg} testsuite, it is often necessary to test that an 852error is indeed a hard error and not just a warning---for example, 853where it is a constraint violation in the C standard, which must 854become an error with @option{-pedantic-errors}. The following idiom, 855where the first line shown is line @var{line} of the file and the line 856that generates the error, is used for this: 857 858@smallexample 859/* @{ dg-bogus "warning" "warning in place of error" @} */ 860/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ 861@end smallexample 862 863It may be necessary to check that an expression is an integer constant 864expression and has a certain value. To check that @code{@var{E}} has 865value @code{@var{V}}, an idiom similar to the following is used: 866 867@smallexample 868char x[((E) == (V) ? 1 : -1)]; 869@end smallexample 870 871In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make 872assertions about the types of expressions. See, for example, 873@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the 874exact rules for the types of conditional expressions in the C 875standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. 876 877It is useful to be able to test that optimizations are being made 878properly. This cannot be done in all cases, but it can be done where 879the optimization will lead to code being optimized away (for example, 880where flow analysis or alias analysis should show that certain code 881cannot be called) or to functions not being called because they have 882been expanded as built-in functions. Such tests go in 883@file{gcc.c-torture/execute}. Where code should be optimized away, a 884call to a nonexistent function such as @code{link_failure ()} may be 885inserted; a definition 886 887@smallexample 888#ifndef __OPTIMIZE__ 889void 890link_failure (void) 891@{ 892 abort (); 893@} 894#endif 895@end smallexample 896 897@noindent 898will also be needed so that linking still succeeds when the test is 899run without optimization. When all calls to a built-in function 900should have been optimized and no calls to the non-built-in version of 901the function should remain, that function may be defined as 902@code{static} to call @code{abort ()} (although redeclaring a function 903as static may not work on all targets). 904 905All testcases must be portable. Target-specific testcases must have 906appropriate code to avoid causing failures on unsupported systems; 907unfortunately, the mechanisms for this differ by directory. 908 909FIXME: discuss non-C testsuites here. 910 911@node Test Directives 912@subsection Directives used within DejaGnu tests 913 914Test directives appear within comments in a test source file and begin 915with @code{dg-}. Some of these are defined within DejaGnu and others 916are local to the GCC testsuite. 917 918The order in which test directives appear in a test can be important: 919directives local to GCC sometimes override information used by the 920DejaGnu directives, which know nothing about the GCC directives, so the 921DejaGnu directives must precede GCC directives. 922 923Several test directives include selectors which are usually preceded by 924the keyword @code{target} or @code{xfail}. A selector is: one or more 925target triplets, possibly including wildcard characters; a single 926effective-target keyword; or a logical expression. Depending on the 927context, the selector specifies whether a test is skipped and reported 928as unsupported or is expected to fail. Use @samp{*-*-*} to match any 929target. 930Effective-target keywords are defined in @file{target-supports.exp} in 931the GCC testsuite. 932 933A selector expression appears within curly braces and uses a single 934logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An 935operand is another selector expression, an effective-target keyword, 936a single target triplet, or a list of target triplets within quotes or 937curly braces. For example: 938 939@smallexample 940@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} 941@{ target @{ powerpc*-*-* && lp64 @} @} 942@{ xfail @{ lp64 || vect_no_align @} @} 943@end smallexample 944 945@table @code 946@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} 947@var{do-what-keyword} specifies how the test is compiled and whether 948it is executed. It is one of: 949 950@table @code 951@item preprocess 952Compile with @option{-E} to run only the preprocessor. 953@item assemble 954Compile with @option{-S} to produce an assembly code file. 955@item compile 956Compile with @option{-c} to produce a relocatable object file. 957@item link 958Compile, assemble, and link to produce an executable file. 959@item run 960Produce and run an executable file, which is expected to return 961an exit code of 0. 962@end table 963 964The default is @code{compile}. That can be overridden for a set of 965tests by redefining @code{dg-do-what-default} within the @code{.exp} 966file for those tests. 967 968If the directive includes the optional @samp{@{ target @var{selector} @}} 969then the test is skipped unless the target system is included in the 970list of target triplets or matches the effective-target keyword. 971 972If the directive includes the optional @samp{@{ xfail @var{selector} @}} 973and the selector is met then the test is expected to fail. For 974@code{dg-do run}, execution is expected to fail but compilation 975is expected to pass. 976 977@item @{ dg-options @var{options} [@{ target @var{selector} @}] @} 978This DejaGnu directive provides a list of compiler options, to be used 979if the target system matches @var{selector}, that replace the default 980options used for this set of tests. 981 982@item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 983Skip the test if the test system is included in @var{selector} and if 984each of the options in @var{include-opts} is in the set of options with 985which the test would be compiled and if none of the options in 986@var{exclude-opts} is in the set of options with which the test would be 987compiled. 988 989Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for 990an empty @var{exclude-opts} list. 991 992@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 993Expect the test to fail if the conditions (which are the same as for 994@code{dg-skip-if}) are met. 995 996@item @{ dg-require-@var{support} args @} 997Skip the test if the target does not provide the required support; 998see @file{gcc-dg.exp} in the GCC testsuite for the actual directives. 999These directives must appear after any @code{dg-do} directive in the test. 1000They require at least one argument, which can be an empty string if the 1001specific procedure does not examine the argument. 1002 1003@item @{ dg-require-effective-target @var{keyword} @} 1004Skip the test if the test target, including current multilib flags, 1005is not covered by the effective-target keyword. 1006This directive must appear after any @code{dg-do} directive in the test. 1007 1008@item @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 1009Expect the test executable to return a nonzero exit status if the 1010conditions (which are the same as for @code{dg-skip-if}) are met. 1011 1012@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1013This DejaGnu directive appears on a source line that is expected to get 1014an error message, or else specifies the source line associated with the 1015message. If there is no message for that line or if the text of that 1016message is not matched by @var{regexp} then the check fails and 1017@var{comment} is included in the @code{FAIL} message. The check does 1018not look for the string @samp{"error"} unless it is part of @var{regexp}. 1019 1020@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1021This DejaGnu directive appears on a source line that is expected to get 1022a warning message, or else specifies the source line associated with the 1023message. If there is no message for that line or if the text of that 1024message is not matched by @var{regexp} then the check fails and 1025@var{comment} is included in the @code{FAIL} message. The check does 1026not look for the string @samp{"warning"} unless it is part of @var{regexp}. 1027 1028@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1029This DejaGnu directive appears on a source line that should not get a 1030message matching @var{regexp}, or else specifies the source line 1031associated with the bogus message. It is usually used with @samp{xfail} 1032to indicate that the message is a known problem for a particular set of 1033targets. 1034 1035@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} 1036This DejaGnu directive indicates that the test is expected to fail due 1037to compiler messages that are not handled by @samp{dg-error}, 1038@samp{dg-warning} or @samp{dg-bogus}. 1039 1040@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} 1041This DejaGnu directive compares @var{regexp} to the combined output 1042that the test executable writes to @file{stdout} and @file{stderr}. 1043 1044@item @{ dg-prune-output @var{regexp} @} 1045Prune messages matching @var{regexp} from test output. 1046 1047@item @{ dg-additional-files "@var{filelist}" @} 1048Specify additional files, other than source files, that must be copied 1049to the system where the compiler runs. 1050 1051@item @{ dg-additional-sources "@var{filelist}" @} 1052Specify additional source files to appear in the compile line 1053following the main test file. 1054 1055@item @{ dg-final @{ @var{local-directive} @} @} 1056This DejaGnu directive is placed within a comment anywhere in the 1057source file and is processed after the test has been compiled and run. 1058Multiple @samp{dg-final} commands are processed in the order in which 1059they appear in the source file. 1060 1061The GCC testsuite defines the following directives to be used within 1062@code{dg-final}. 1063 1064@table @code 1065@item cleanup-coverage-files 1066Removes coverage data files generated for this test. 1067 1068@item cleanup-repo-files 1069Removes files generated for this test for @option{-frepo}. 1070 1071@item cleanup-rtl-dump @var{suffix} 1072Removes RTL dump files generated for this test. 1073 1074@item cleanup-tree-dump @var{suffix} 1075Removes tree dump files matching @var{suffix} which were generated for 1076this test. 1077 1078@item cleanup-saved-temps 1079Removes files for the current test which were kept for @option{--save-temps}. 1080 1081@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1082Passes if @var{regexp} matches text in @var{filename}. 1083 1084@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1085Passes if @var{regexp} does not match text in @var{filename}. 1086 1087@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 1088Passes if @var{symbol} is defined as a hidden symbol in the test's 1089assembly output. 1090 1091@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 1092Passes if @var{symbol} is not defined as a hidden symbol in the test's 1093assembly output. 1094 1095@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] 1096Passes if @var{regex} is matched exactly @var{num} times in the test's 1097assembler output. 1098 1099@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] 1100Passes if @var{regex} matches text in the test's assembler output. 1101 1102@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] 1103Passes if @var{regex} does not match text in the test's assembler output. 1104 1105@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] 1106Passes if @var{regex} matches text in the test's demangled assembler output. 1107 1108@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] 1109Passes if @var{regex} does not match text in the test's demangled assembler 1110output. 1111 1112@item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] 1113Passes if @var{regex} is found exactly @var{num} times in the dump file 1114with suffix @var{suffix}. 1115 1116@item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1117Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. 1118 1119@item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1120Passes if @var{regex} does not match text in the dump file with suffix 1121@var{suffix}. 1122 1123@item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1124Passes if @var{regex} matches demangled text in the dump file with 1125suffix @var{suffix}. 1126 1127@item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1128Passes if @var{regex} does not match demangled text in the dump file with 1129suffix @var{suffix}. 1130 1131@item output-exists [@{ target/xfail @var{selector} @}] 1132Passes if compiler output file exists. 1133 1134@item output-exists-not [@{ target/xfail @var{selector} @}] 1135Passes if compiler output file does not exist. 1136 1137@item run-gcov @var{sourcefile} 1138Check line counts in @command{gcov} tests. 1139 1140@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} 1141Check branch and/or call counts, in addition to line counts, in 1142@command{gcov} tests. 1143@end table 1144@end table 1145 1146@node Ada Tests 1147@subsection Ada Language Testsuites 1148 1149The Ada testsuite includes executable tests from the ACATS 2.5 1150testsuite, publicly available at 1151@uref{http://www.adaic.org/compilers/acats/2.5} 1152 1153These tests are integrated in the GCC testsuite in the 1154@file{gcc/testsuite/ada/acats} directory, and 1155enabled automatically when running @code{make check}, assuming 1156the Ada language has been enabled when configuring GCC@. 1157 1158You can also run the Ada testsuite independently, using 1159@code{make check-ada}, or run a subset of the tests by specifying which 1160chapter to run, e.g.: 1161 1162@smallexample 1163$ make check-ada CHAPTERS="c3 c9" 1164@end smallexample 1165 1166The tests are organized by directory, each directory corresponding to 1167a chapter of the Ada Reference Manual. So for example, c9 corresponds 1168to chapter 9, which deals with tasking features of the language. 1169 1170There is also an extra chapter called @file{gcc} containing a template for 1171creating new executable tests. 1172 1173The tests are run using two @command{sh} scripts: @file{run_acats} and 1174@file{run_all.sh}. To run the tests using a simulator or a cross 1175target, see the small 1176customization section at the top of @file{run_all.sh}. 1177 1178These tests are run using the build tree: they can be run without doing 1179a @code{make install}. 1180 1181@node C Tests 1182@subsection C Language Testsuites 1183 1184GCC contains the following C language testsuites, in the 1185@file{gcc/testsuite} directory: 1186 1187@table @file 1188@item gcc.dg 1189This contains tests of particular features of the C compiler, using the 1190more modern @samp{dg} harness. Correctness tests for various compiler 1191features should go here if possible. 1192 1193Magic comments determine whether the file 1194is preprocessed, compiled, linked or run. In these tests, error and warning 1195message texts are compared against expected texts or regular expressions 1196given in comments. These tests are run with the options @samp{-ansi -pedantic} 1197unless other options are given in the test. Except as noted below they 1198are not run with multiple optimization options. 1199@item gcc.dg/compat 1200This subdirectory contains tests for binary compatibility using 1201@file{compat.exp}, which in turn uses the language-independent support 1202(@pxref{compat Testing, , Support for testing binary compatibility}). 1203@item gcc.dg/cpp 1204This subdirectory contains tests of the preprocessor. 1205@item gcc.dg/debug 1206This subdirectory contains tests for debug formats. Tests in this 1207subdirectory are run for each debug format that the compiler supports. 1208@item gcc.dg/format 1209This subdirectory contains tests of the @option{-Wformat} format 1210checking. Tests in this directory are run with and without 1211@option{-DWIDE}. 1212@item gcc.dg/noncompile 1213This subdirectory contains tests of code that should not compile and 1214does not need any special compilation options. They are run with 1215multiple optimization options, since sometimes invalid code crashes 1216the compiler with optimization. 1217@item gcc.dg/special 1218FIXME: describe this. 1219 1220@item gcc.c-torture 1221This contains particular code fragments which have historically broken easily. 1222These tests are run with multiple optimization options, so tests for features 1223which only break at some optimization levels belong here. This also contains 1224tests to check that certain optimizations occur. It might be worthwhile to 1225separate the correctness tests cleanly from the code quality tests, but 1226it hasn't been done yet. 1227 1228@item gcc.c-torture/compat 1229FIXME: describe this. 1230 1231This directory should probably not be used for new tests. 1232@item gcc.c-torture/compile 1233This testsuite contains test cases that should compile, but do not 1234need to link or run. These test cases are compiled with several 1235different combinations of optimization options. All warnings are 1236disabled for these test cases, so this directory is not suitable if 1237you wish to test for the presence or absence of compiler warnings. 1238While special options can be set, and tests disabled on specific 1239platforms, by the use of @file{.x} files, mostly these test cases 1240should not contain platform dependencies. FIXME: discuss how defines 1241such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. 1242@item gcc.c-torture/execute 1243This testsuite contains test cases that should compile, link and run; 1244otherwise the same comments as for @file{gcc.c-torture/compile} apply. 1245@item gcc.c-torture/execute/ieee 1246This contains tests which are specific to IEEE floating point. 1247@item gcc.c-torture/unsorted 1248FIXME: describe this. 1249 1250This directory should probably not be used for new tests. 1251@item gcc.c-torture/misc-tests 1252This directory contains C tests that require special handling. Some 1253of these tests have individual expect files, and others share 1254special-purpose expect files: 1255 1256@table @file 1257@item @code{bprob*.c} 1258Test @option{-fbranch-probabilities} using @file{bprob.exp}, which 1259in turn uses the generic, language-independent framework 1260(@pxref{profopt Testing, , Support for testing profile-directed 1261optimizations}). 1262 1263@item @code{dg-*.c} 1264Test the testsuite itself using @file{dg-test.exp}. 1265 1266@item @code{gcov*.c} 1267Test @command{gcov} output using @file{gcov.exp}, which in turn uses the 1268language-independent support (@pxref{gcov Testing, , Support for testing gcov}). 1269 1270@item @code{i386-pf-*.c} 1271Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. 1272@end table 1273 1274@end table 1275 1276FIXME: merge in @file{testsuite/README.gcc} and discuss the format of 1277test cases and magic comments more. 1278 1279@node libgcj Tests 1280@subsection The Java library testsuites. 1281 1282Runtime tests are executed via @samp{make check} in the 1283@file{@var{target}/libjava/testsuite} directory in the build 1284tree. Additional runtime tests can be checked into this testsuite. 1285 1286Regression testing of the core packages in libgcj is also covered by the 1287Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} 1288develops tests for the Java Class Libraries. These tests are run as part 1289of libgcj testing by placing the Mauve tree within the libjava testsuite 1290sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying 1291the location of that tree when invoking @samp{make}, as in 1292@samp{make MAUVEDIR=~/mauve check}. 1293 1294To detect regressions, a mechanism in @file{mauve.exp} compares the 1295failures for a test run against the list of expected failures in 1296@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. 1297Update this file when adding new failing tests to Mauve, or when fixing 1298bugs in libgcj that had caused Mauve test failures. 1299 1300The @uref{http://sourceware.org/mauve/jacks.html,, 1301Jacks} project provides a testsuite for Java compilers that can be used 1302to test changes that affect the GCJ front end. This testsuite is run as 1303part of Java testing by placing the Jacks tree within the libjava 1304testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. 1305 1306We encourage developers to contribute test cases to Mauve and Jacks. 1307 1308@node gcov Testing 1309@subsection Support for testing @command{gcov} 1310 1311Language-independent support for testing @command{gcov}, and for checking 1312that branch profiling produces expected values, is provided by the 1313expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures 1314in @file{gcc.dg.exp} to compile and run the test program. A typical 1315@command{gcov} test contains the following DejaGnu commands within comments: 1316 1317@smallexample 1318@{ dg-options "-fprofile-arcs -ftest-coverage" @} 1319@{ dg-do run @{ target native @} @} 1320@{ dg-final @{ run-gcov sourcefile @} @} 1321@end smallexample 1322 1323Checks of @command{gcov} output can include line counts, branch percentages, 1324and call return percentages. All of these checks are requested via 1325commands that appear in comments in the test's source file. 1326Commands to check line counts are processed by default. 1327Commands to check branch percentages and call return percentages are 1328processed if the @command{run-gcov} command has arguments @code{branches} 1329or @code{calls}, respectively. For example, the following specifies 1330checking both, as well as passing @option{-b} to @command{gcov}: 1331 1332@smallexample 1333@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} 1334@end smallexample 1335 1336A line count command appears within a comment on the source line 1337that is expected to get the specified count and has the form 1338@code{count(@var{cnt})}. A test should only check line counts for 1339lines that will get the same count for any architecture. 1340 1341Commands to check branch percentages (@code{branch}) and call 1342return percentages (@code{returns}) are very similar to each other. 1343A beginning command appears on or before the first of a range of 1344lines that will report the percentage, and the ending command 1345follows that range of lines. The beginning command can include a 1346list of percentages, all of which are expected to be found within 1347the range. A range is terminated by the next command of the same 1348kind. A command @code{branch(end)} or @code{returns(end)} marks 1349the end of a range without starting a new one. For example: 1350 1351@smallexample 1352if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ 1353 /* @r{branch(end)} */ 1354 foo (i, j); 1355@end smallexample 1356 1357For a call return percentage, the value specified is the 1358percentage of calls reported to return. For a branch percentage, 1359the value is either the expected percentage or 100 minus that 1360value, since the direction of a branch can differ depending on the 1361target or the optimization level. 1362 1363Not all branches and calls need to be checked. A test should not 1364check for branches that might be optimized away or replaced with 1365predicated instructions. Don't check for calls inserted by the 1366compiler or ones that might be inlined or optimized away. 1367 1368A single test can check for combinations of line counts, branch 1369percentages, and call return percentages. The command to check a 1370line count must appear on the line that will report that count, but 1371commands to check branch percentages and call return percentages can 1372bracket the lines that report them. 1373 1374@node profopt Testing 1375@subsection Support for testing profile-directed optimizations 1376 1377The file @file{profopt.exp} provides language-independent support for 1378checking correct execution of a test built with profile-directed 1379optimization. This testing requires that a test program be built and 1380executed twice. The first time it is compiled to generate profile 1381data, and the second time it is compiled to use the data that was 1382generated during the first execution. The second execution is to 1383verify that the test produces the expected results. 1384 1385To check that the optimization actually generated better code, a 1386test can be built and run a third time with normal optimizations to 1387verify that the performance is better with the profile-directed 1388optimizations. @file{profopt.exp} has the beginnings of this kind 1389of support. 1390 1391@file{profopt.exp} provides generic support for profile-directed 1392optimizations. Each set of tests that uses it provides information 1393about a specific optimization: 1394 1395@table @code 1396@item tool 1397tool being tested, e.g., @command{gcc} 1398 1399@item profile_option 1400options used to generate profile data 1401 1402@item feedback_option 1403options used to optimize using that profile data 1404 1405@item prof_ext 1406suffix of profile data files 1407 1408@item PROFOPT_OPTIONS 1409list of options with which to run each test, similar to the lists for 1410torture tests 1411@end table 1412 1413@node compat Testing 1414@subsection Support for testing binary compatibility 1415 1416The file @file{compat.exp} provides language-independent support for 1417binary compatibility testing. It supports testing interoperability of 1418two compilers that follow the same ABI, or of multiple sets of 1419compiler options that should not affect binary compatibility. It is 1420intended to be used for testsuites that complement ABI testsuites. 1421 1422A test supported by this framework has three parts, each in a 1423separate source file: a main program and two pieces that interact 1424with each other to split up the functionality being tested. 1425 1426@table @file 1427@item @var{testname}_main.@var{suffix} 1428Contains the main program, which calls a function in file 1429@file{@var{testname}_x.@var{suffix}}. 1430 1431@item @var{testname}_x.@var{suffix} 1432Contains at least one call to a function in 1433@file{@var{testname}_y.@var{suffix}}. 1434 1435@item @var{testname}_y.@var{suffix} 1436Shares data with, or gets arguments from, 1437@file{@var{testname}_x.@var{suffix}}. 1438@end table 1439 1440Within each test, the main program and one functional piece are 1441compiled by the GCC under test. The other piece can be compiled by 1442an alternate compiler. If no alternate compiler is specified, 1443then all three source files are all compiled by the GCC under test. 1444You can specify pairs of sets of compiler options. The first element 1445of such a pair specifies options used with the GCC under test, and the 1446second element of the pair specifies options used with the alternate 1447compiler. Each test is compiled with each pair of options. 1448 1449@file{compat.exp} defines default pairs of compiler options. 1450These can be overridden by defining the environment variable 1451@env{COMPAT_OPTIONS} as: 1452 1453@smallexample 1454COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] 1455 ...[list @{@var{tstn}@} @{@var{altn}@}]]" 1456@end smallexample 1457 1458where @var{tsti} and @var{alti} are lists of options, with @var{tsti} 1459used by the compiler under test and @var{alti} used by the alternate 1460compiler. For example, with 1461@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, 1462the test is first built with @option{-g -O0} by the compiler under 1463test and with @option{-O3} by the alternate compiler. The test is 1464built a second time using @option{-fpic} by the compiler under test 1465and @option{-fPIC -O2} by the alternate compiler. 1466 1467An alternate compiler is specified by defining an environment 1468variable to be the full pathname of an installed compiler; for C 1469define @env{ALT_CC_UNDER_TEST}, and for C++ define 1470@env{ALT_CXX_UNDER_TEST}. These will be written to the 1471@file{site.exp} file used by DejaGnu. The default is to build each 1472test with the compiler under test using the first of each pair of 1473compiler options from @env{COMPAT_OPTIONS}. When 1474@env{ALT_CC_UNDER_TEST} or 1475@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using 1476the compiler under test but with combinations of the options from 1477@env{COMPAT_OPTIONS}. 1478 1479To run only the C++ compatibility suite using the compiler under test 1480and another version of GCC using specific compiler options, do the 1481following from @file{@var{objdir}/gcc}: 1482 1483@smallexample 1484rm site.exp 1485make -k \ 1486 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ 1487 COMPAT_OPTIONS="lists as shown above" \ 1488 check-c++ \ 1489 RUNTESTFLAGS="compat.exp" 1490@end smallexample 1491 1492A test that fails when the source files are compiled with different 1493compilers, but passes when the files are compiled with the same 1494compiler, demonstrates incompatibility of the generated code or 1495runtime support. A test that fails for the alternate compiler but 1496passes for the compiler under test probably tests for a bug that was 1497fixed in the compiler under test but is present in the alternate 1498compiler. 1499 1500The binary compatibility tests support a small number of test framework 1501commands that appear within comments in a test file. 1502 1503@table @code 1504@item dg-require-* 1505These commands can be used in @file{@var{testname}_main.@var{suffix}} 1506to skip the test if specific support is not available on the target. 1507 1508@item dg-options 1509The specified options are used for compiling this particular source 1510file, appended to the options from @env{COMPAT_OPTIONS}. When this 1511command appears in @file{@var{testname}_main.@var{suffix}} the options 1512are also used to link the test program. 1513 1514@item dg-xfail-if 1515This command can be used in a secondary source file to specify that 1516compilation is expected to fail for particular options on particular 1517targets. 1518@end table 1519