1169689Skan@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc. 290075Sobrien@c This is part of the GCC manual. 390075Sobrien@c For copying conditions, see the file gcc.texi. 490075Sobrien 590075Sobrien@node Source Tree 690075Sobrien@chapter Source Tree Structure and Build System 790075Sobrien 890075SobrienThis chapter describes the structure of the GCC source tree, and how 990075SobrienGCC is built. The user documentation for building and installing GCC 1090075Sobrienis in a separate manual (@uref{http://gcc.gnu.org/install/}), with 1190075Sobrienwhich it is presumed that you are familiar. 1290075Sobrien 1390075Sobrien@menu 1490075Sobrien* Configure Terms:: Configuration terminology and history. 1590075Sobrien* Top Level:: The top level source directory. 1690075Sobrien* gcc Directory:: The @file{gcc} subdirectory. 17132718Skan* Testsuites:: The GCC testsuites. 1890075Sobrien@end menu 1990075Sobrien 2090075Sobrien@include configterms.texi 2190075Sobrien 2290075Sobrien@node Top Level 2390075Sobrien@section Top Level Source Directory 2490075Sobrien 2590075SobrienThe top level source directory in a GCC distribution contains several 2690075Sobrienfiles and directories that are shared with other software 2790075Sobriendistributions such as that of GNU Binutils. It also contains several 2890075Sobriensubdirectories that contain parts of GCC and its runtime libraries: 2990075Sobrien 3090075Sobrien@table @file 3190075Sobrien@item boehm-gc 3290075SobrienThe Boehm conservative garbage collector, used as part of the Java 3390075Sobrienruntime library. 3490075Sobrien 3590075Sobrien@item contrib 3690075SobrienContributed scripts that may be found useful in conjunction with GCC@. 3790075SobrienOne of these, @file{contrib/texi2pod.pl}, is used to generate man 3890075Sobrienpages from Texinfo manuals as part of the GCC build process. 3990075Sobrien 4090075Sobrien@item fastjar 4190075SobrienAn implementation of the @command{jar} command, used with the Java 4290075Sobrienfront end. 4390075Sobrien 4490075Sobrien@item gcc 4590075SobrienThe main sources of GCC itself (except for runtime libraries), 4690075Sobrienincluding optimizers, support for different target architectures, 47132718Skanlanguage front ends, and testsuites. @xref{gcc Directory, , The 4890075Sobrien@file{gcc} Subdirectory}, for details. 4990075Sobrien 5090075Sobrien@item include 5190075SobrienHeaders for the @code{libiberty} library. 5290075Sobrien 53169689Skan@item libada 54169689SkanThe Ada runtime library. 55169689Skan 56169689Skan@item libcpp 57169689SkanThe C preprocessor library. 58169689Skan 59169689Skan@item libgfortran 6090075SobrienThe Fortran runtime library. 6190075Sobrien 6290075Sobrien@item libffi 6390075SobrienThe @code{libffi} library, used as part of the Java runtime library. 6490075Sobrien 6590075Sobrien@item libiberty 6696263SobrienThe @code{libiberty} library, used for portability and for some 6790075Sobriengenerally useful data structures and algorithms. @xref{Top, , 6890075SobrienIntroduction, libiberty, @sc{gnu} libiberty}, for more information 6990075Sobrienabout this library. 7090075Sobrien 7190075Sobrien@item libjava 7290075SobrienThe Java runtime library. 7390075Sobrien 74169689Skan@item libmudflap 75169689SkanThe @code{libmudflap} library, used for instrumenting pointer and array 76169689Skandereferencing operations. 77169689Skan 7890075Sobrien@item libstdc++-v3 7990075SobrienThe C++ runtime library. 8090075Sobrien 8190075Sobrien@item maintainer-scripts 8290075SobrienScripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. 8390075Sobrien 8490075Sobrien@item zlib 8590075SobrienThe @code{zlib} compression library, used by the Java front end and as 8690075Sobrienpart of the Java runtime library. 8790075Sobrien@end table 8890075Sobrien 8990075SobrienThe build system in the top level directory, including how recursion 9090075Sobrieninto subdirectories works and how building runtime libraries for 9190075Sobrienmultilibs is handled, is documented in a separate manual, included 9290075Sobrienwith GNU Binutils. @xref{Top, , GNU configure and build system, 9390075Sobrienconfigure, The GNU configure and build system}, for details. 9490075Sobrien 9590075Sobrien@node gcc Directory 9690075Sobrien@section The @file{gcc} Subdirectory 9790075Sobrien 9890075SobrienThe @file{gcc} directory contains many files that are part of the C 9990075Sobriensources of GCC, other files used as part of the configuration and 10090075Sobrienbuild process, and subdirectories including documentation and a 101132718Skantestsuite. The files that are sources of GCC are documented in a 10290075Sobrienseparate chapter. @xref{Passes, , Passes and Files of the Compiler}. 10390075Sobrien 10490075Sobrien@menu 10590075Sobrien* Subdirectories:: Subdirectories of @file{gcc}. 10690075Sobrien* Configuration:: The configuration process, and the files it uses. 10790075Sobrien* Build:: The build system in the @file{gcc} directory. 10890075Sobrien* Makefile:: Targets in @file{gcc/Makefile}. 10990075Sobrien* Library Files:: Library source files and headers under @file{gcc/}. 11090075Sobrien* Headers:: Headers installed by GCC. 11190075Sobrien* Documentation:: Building documentation in GCC. 11290075Sobrien* Front End:: Anatomy of a language front end. 11390075Sobrien* Back End:: Anatomy of a target back end. 11490075Sobrien@end menu 11590075Sobrien 11690075Sobrien@node Subdirectories 11790075Sobrien@subsection Subdirectories of @file{gcc} 11890075Sobrien 11990075SobrienThe @file{gcc} directory contains the following subdirectories: 12090075Sobrien 12190075Sobrien@table @file 12290075Sobrien@item @var{language} 12390075SobrienSubdirectories for various languages. Directories containing a file 12490075Sobrien@file{config-lang.in} are language subdirectories. The contents of 125220755Sdimthe subdirectory @file{cp} (for C++) is documented in this manual 126169689Skan(@pxref{Passes, , Passes and Files of the Compiler}); those for other 127169689Skanlanguages are not. @xref{Front End, , Anatomy of a Language Front End}, 128169689Skanfor details of the files in these directories. 12990075Sobrien 13090075Sobrien@item config 13190075SobrienConfiguration files for supported architectures and operating 13290075Sobriensystems. @xref{Back End, , Anatomy of a Target Back End}, for 133117395Skandetails of the files in this directory. 13490075Sobrien 13590075Sobrien@item doc 13690075SobrienTexinfo documentation for GCC, together with automatically generated 13790075Sobrienman pages and support for converting the installation manual to 13890075SobrienHTML@. @xref{Documentation}. 13990075Sobrien 14090075Sobrien@item fixinc 14190075SobrienThe support for fixing system headers to work with GCC@. See 14290075Sobrien@file{fixinc/README} for more information. The headers fixed by this 14390075Sobrienmechanism are installed in @file{@var{libsubdir}/include}. Along with 14490075Sobrienthose headers, @file{README-fixinc} is also installed, as 14590075Sobrien@file{@var{libsubdir}/include/README}. 14690075Sobrien 14790075Sobrien@item ginclude 14890075SobrienSystem headers installed by GCC, mainly those required by the C 14990075Sobrienstandard of freestanding implementations. @xref{Headers, , Headers 15090075SobrienInstalled by GCC}, for details of when these and other headers are 15190075Sobrieninstalled. 15290075Sobrien 15390075Sobrien@item intl 15490075SobrienGNU @code{libintl}, from GNU @code{gettext}, for systems which do not 15590075Sobrieninclude it in libc. Properly, this directory should be at top level, 15690075Sobrienparallel to the @file{gcc} directory. 15790075Sobrien 15890075Sobrien@item po 15990075SobrienMessage catalogs with translations of messages produced by GCC into 16090075Sobrienvarious languages, @file{@var{language}.po}. This directory also 16190075Sobriencontains @file{gcc.pot}, the template for these message catalogues, 16290075Sobrien@file{exgettext}, a wrapper around @command{gettext} to extract the 16390075Sobrienmessages from the GCC sources and create @file{gcc.pot}, which is run 164117395Skanby @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from 16590075Sobrienwhich messages should not be extracted. 16690075Sobrien 16790075Sobrien@item testsuite 168132718SkanThe GCC testsuites (except for those for runtime libraries). 169132718Skan@xref{Testsuites}. 17090075Sobrien@end table 17190075Sobrien 17290075Sobrien@node Configuration 17390075Sobrien@subsection Configuration in the @file{gcc} Directory 17490075Sobrien 17590075SobrienThe @file{gcc} directory is configured with an Autoconf-generated 17690075Sobrienscript @file{configure}. The @file{configure} script is generated 177132718Skanfrom @file{configure.ac} and @file{aclocal.m4}. From the files 178132718Skan@file{configure.ac} and @file{acconfig.h}, Autoheader generates the 17990075Sobrienfile @file{config.in}. The file @file{cstamp-h.in} is used as a 18090075Sobrientimestamp. 18190075Sobrien 18290075Sobrien@menu 18390075Sobrien* Config Fragments:: Scripts used by @file{configure}. 184132718Skan* System Config:: The @file{config.build}, @file{config.host}, and 185132718Skan @file{config.gcc} files. 18690075Sobrien* Configuration Files:: Files created by running @file{configure}. 18790075Sobrien@end menu 18890075Sobrien 18990075Sobrien@node Config Fragments 19090075Sobrien@subsubsection Scripts Used by @file{configure} 19190075Sobrien 19290075Sobrien@file{configure} uses some other scripts to help in its work: 19390075Sobrien 19490075Sobrien@itemize @bullet 19590075Sobrien@item The standard GNU @file{config.sub} and @file{config.guess} 19690075Sobrienfiles, kept in the top level directory, are used. FIXME: when is the 19790075Sobrien@file{config.guess} file in the @file{gcc} directory (that just calls 19890075Sobrienthe top level one) used? 19990075Sobrien 20090075Sobrien@item The file @file{config.gcc} is used to handle configuration 201132718Skanspecific to the particular target machine. The file 202132718Skan@file{config.build} is used to handle configuration specific to the 203132718Skanparticular build machine. The file @file{config.host} is used to handle 204132718Skanconfiguration specific to the particular host machine. (In general, 205132718Skanthese should only be used for features that cannot reasonably be tested in 206132718SkanAutoconf feature tests.) 207132718Skan@xref{System Config, , The @file{config.build}; @file{config.host}; 208132718Skanand @file{config.gcc} Files}, for details of the contents of these files. 20990075Sobrien 21090075Sobrien@item Each language subdirectory has a file 21190075Sobrien@file{@var{language}/config-lang.in} that is used for 21290075Sobrienfront-end-specific configuration. @xref{Front End Config, , The Front 21390075SobrienEnd @file{config-lang.in} File}, for details of this file. 21490075Sobrien 21590075Sobrien@item A helper script @file{configure.frag} is used as part of 21690075Sobriencreating the output of @file{configure}. 21790075Sobrien@end itemize 21890075Sobrien 21990075Sobrien@node System Config 220132718Skan@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files 22190075Sobrien 222132718SkanThe @file{config.build} file contains specific rules for particular systems 223132718Skanwhich GCC is built on. This should be used as rarely as possible, as the 224132718Skanbehavior of the build system can always be detected by autoconf. 225132718Skan 226132718SkanThe @file{config.host} file contains specific rules for particular systems 227132718Skanwhich GCC will run on. This is rarely needed. 228132718Skan 229132718SkanThe @file{config.gcc} file contains specific rules for particular systems 230132718Skanwhich GCC will generate code for. This is usually needed. 231132718Skan 232132718SkanEach file has a list of the shell variables it sets, with descriptions, at the 233132718Skantop of the file. 234132718Skan 235132718SkanFIXME: document the contents of these files, and what variables should 23690075Sobrienbe set to control build, host and target configuration. 23790075Sobrien 23890075Sobrien@include configfiles.texi 23990075Sobrien 24090075Sobrien@node Build 24190075Sobrien@subsection Build System in the @file{gcc} Directory 24290075Sobrien 24390075SobrienFIXME: describe the build system, including what is built in what 24490075Sobrienstages. Also list the various source files that are used in the build 24590075Sobrienprocess but aren't source files of GCC itself and so aren't documented 24690075Sobrienbelow (@pxref{Passes}). 24790075Sobrien 24890075Sobrien@include makefile.texi 24990075Sobrien 25090075Sobrien@node Library Files 25190075Sobrien@subsection Library Source Files and Headers under the @file{gcc} Directory 25290075Sobrien 25390075SobrienFIXME: list here, with explanation, all the C source files and headers 25490075Sobrienunder the @file{gcc} directory that aren't built into the GCC 25590075Sobrienexecutable but rather are part of runtime libraries and object files, 25690075Sobriensuch as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , 25790075SobrienHeaders Installed by GCC}, for more information about the 25890075Sobrien@file{ginclude} directory. 25990075Sobrien 26090075Sobrien@node Headers 26190075Sobrien@subsection Headers Installed by GCC 26290075Sobrien 26390075SobrienIn general, GCC expects the system C library to provide most of the 26490075Sobrienheaders to be used with it. However, GCC will fix those headers if 26590075Sobriennecessary to make them work with GCC, and will install some headers 26690075Sobrienrequired of freestanding implementations. These headers are installed 26790075Sobrienin @file{@var{libsubdir}/include}. Headers for non-C runtime 26890075Sobrienlibraries are also installed by GCC; these are not documented here. 26990075Sobrien(FIXME: document them somewhere.) 27090075Sobrien 27190075SobrienSeveral of the headers GCC installs are in the @file{ginclude} 27290075Sobriendirectory. These headers, @file{iso646.h}, 273117395Skan@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, 274117395Skanare installed in @file{@var{libsubdir}/include}, 27590075Sobrienunless the target Makefile fragment (@pxref{Target Fragment}) 27690075Sobrienoverrides this by setting @code{USER_H}. 27790075Sobrien 27890075SobrienIn addition to these headers and those generated by fixing system 27990075Sobrienheaders to work with GCC, some other headers may also be installed in 28090075Sobrien@file{@var{libsubdir}/include}. @file{config.gcc} may set 28190075Sobrien@code{extra_headers}; this specifies additional headers under 282117395Skan@file{config} to be installed on some systems. 283117395Skan 284117395SkanGCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. 285132718SkanThis is done to cope with command-line options that change the 286117395Skanrepresentation of floating point numbers. 287117395Skan 288117395SkanGCC also installs its own version of @code{<limits.h>}; this is generated 28990075Sobrienfrom @file{glimits.h}, together with @file{limitx.h} and 29090075Sobrien@file{limity.h} if the system also has its own version of 29190075Sobrien@code{<limits.h>}. (GCC provides its own header because it is 29290075Sobrienrequired of ISO C freestanding implementations, but needs to include 29390075Sobrienthe system header from its own header as well because other standards 29490075Sobriensuch as POSIX specify additional values to be defined in 29590075Sobrien@code{<limits.h>}.) The system's @code{<limits.h>} header is used via 29690075Sobrien@file{@var{libsubdir}/include/syslimits.h}, which is copied from 29790075Sobrien@file{gsyslimits.h} if it does not need fixing to work with GCC; if it 29890075Sobrienneeds fixing, @file{syslimits.h} is the fixed copy. 29990075Sobrien 30090075Sobrien@node Documentation 30190075Sobrien@subsection Building Documentation 30290075Sobrien 30390075SobrienThe main GCC documentation is in the form of manuals in Texinfo 304169689Skanformat. These are installed in Info format; DVI versions may be 305169689Skangenerated by @samp{make dvi}, PDF versions by @samp{make pdf}, and 306169689SkanHTML versions by @command{make html}. In addition, some man pages are 30790075Sobriengenerated from the Texinfo manuals, there are some other text files 30890075Sobrienwith miscellaneous documentation, and runtime libraries have their own 30990075Sobriendocumentation outside the @file{gcc} directory. FIXME: document the 31090075Sobriendocumentation for runtime libraries somewhere. 31190075Sobrien 31290075Sobrien@menu 31390075Sobrien* Texinfo Manuals:: GCC manuals in Texinfo format. 31490075Sobrien* Man Page Generation:: Generating man pages from Texinfo manuals. 31590075Sobrien* Miscellaneous Docs:: Miscellaneous text files with documentation. 31690075Sobrien@end menu 31790075Sobrien 31890075Sobrien@node Texinfo Manuals 31990075Sobrien@subsubsection Texinfo Manuals 32090075Sobrien 32190075SobrienThe manuals for GCC as a whole, and the C and C++ front ends, are in 32290075Sobrienfiles @file{doc/*.texi}. Other front ends have their own manuals in 32390075Sobrienfiles @file{@var{language}/*.texi}. Common files 32490075Sobrien@file{doc/include/*.texi} are provided which may be included in 32590075Sobrienmultiple manuals; the following files are in @file{doc/include}: 32690075Sobrien 32790075Sobrien@table @file 32890075Sobrien@item fdl.texi 32990075SobrienThe GNU Free Documentation License. 33090075Sobrien@item funding.texi 33190075SobrienThe section ``Funding Free Software''. 33290075Sobrien@item gcc-common.texi 33390075SobrienCommon definitions for manuals. 33490075Sobrien@item gpl.texi 33590075SobrienThe GNU General Public License. 33690075Sobrien@item texinfo.tex 33790075SobrienA copy of @file{texinfo.tex} known to work with the GCC manuals. 33890075Sobrien@end table 33990075Sobrien 340169689SkanDVI-formatted manuals are generated by @samp{make dvi}, which uses 341169689Skan@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). 342169689SkanPDF-formatted manuals are generated by @samp{make pdf}, which uses 343169689Skan@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML 344169689Skanformatted manuals are generated by @command{make html}. Info 345117395Skanmanuals are generated by @samp{make info} (which is run as part of 34690075Sobriena bootstrap); this generates the manuals in the source directory, 34790075Sobrienusing @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, 34890075Sobrienand they are included in release distributions. 34990075Sobrien 35090075SobrienManuals are also provided on the GCC web site, in both HTML and 35190075SobrienPostScript forms. This is done via the script 35290075Sobrien@file{maintainer-scripts/update_web_docs}. Each manual to be 35390075Sobrienprovided online must be listed in the definition of @code{MANUALS} in 35490075Sobrienthat file; a file @file{@var{name}.texi} must only appear once in the 35590075Sobriensource tree, and the output manual must have the same name as the 35690075Sobriensource file. (However, other Texinfo files, included in manuals but 35790075Sobriennot themselves the root files of manuals, may have names that appear 35890075Sobrienmore than once in the source tree.) The manual file 35990075Sobrien@file{@var{name}.texi} should only include other files in its own 36090075Sobriendirectory or in @file{doc/include}. HTML manuals will be generated by 361169689Skan@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} 362169689Skanand @command{dvips}, and PDF manuals by @command{texi2pdf}. 363169689SkanAll Texinfo files that are parts of manuals must 36490075Sobrienbe checked into CVS, even if they are generated files, for the 36590075Sobriengeneration of online manuals to work. 36690075Sobrien 36790075SobrienThe installation manual, @file{doc/install.texi}, is also provided on 36890075Sobrienthe GCC web site. The HTML version is generated by the script 36990075Sobrien@file{doc/install.texi2html}. 37090075Sobrien 37190075Sobrien@node Man Page Generation 37290075Sobrien@subsubsection Man Page Generation 37390075Sobrien 37490075SobrienBecause of user demand, in addition to full Texinfo manuals, man pages 37590075Sobrienare provided which contain extracts from those manuals. These man 37690075Sobrienpages are generated from the Texinfo manuals using 37790075Sobrien@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for 37890075Sobrien@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference 37990075Sobriento @file{gcc.1}, but all the other man pages are generated from 38090075SobrienTexinfo manuals.) 38190075Sobrien 38290075SobrienBecause many systems may not have the necessary tools installed to 38390075Sobriengenerate the man pages, they are only generated if the 38490075Sobrien@file{configure} script detects that recent enough tools are 38590075Sobrieninstalled, and the Makefiles allow generating man pages to fail 38690075Sobrienwithout aborting the build. Man pages are also included in release 38790075Sobriendistributions. They are generated in the source directory. 38890075Sobrien 38990075SobrienMagic comments in Texinfo files starting @samp{@@c man} control what 39090075Sobrienparts of a Texinfo file go into a man page. Only a subset of Texinfo 39190075Sobrienis supported by @file{texi2pod.pl}, and it may be necessary to add 39290075Sobriensupport for more Texinfo features to this script when generating new 39390075Sobrienman pages. To improve the man page output, some special Texinfo 39490075Sobrienmacros are provided in @file{doc/include/gcc-common.texi} which 39590075Sobrien@file{texi2pod.pl} understands: 39690075Sobrien 39790075Sobrien@table @code 39890075Sobrien@item @@gcctabopt 39990075SobrienUse in the form @samp{@@table @@gcctabopt} for tables of options, 40090075Sobrienwhere for printed output the effect of @samp{@@code} is better than 40190075Sobrienthat of @samp{@@option} but for man page output a different effect is 40290075Sobrienwanted. 40390075Sobrien@item @@gccoptlist 40490075SobrienUse for summary lists of options in manuals. 40590075Sobrien@item @@gol 40690075SobrienUse at the end of each line inside @samp{@@gccoptlist}. This is 40790075Sobriennecessary to avoid problems with differences in how the 40890075Sobrien@samp{@@gccoptlist} macro is handled by different Texinfo formatters. 40990075Sobrien@end table 41090075Sobrien 41190075SobrienFIXME: describe the @file{texi2pod.pl} input language and magic 41290075Sobriencomments in more detail. 41390075Sobrien 41490075Sobrien@node Miscellaneous Docs 41590075Sobrien@subsubsection Miscellaneous Documentation 41690075Sobrien 41790075SobrienIn addition to the formal documentation that is installed by GCC, 41890075Sobrienthere are several other text files with miscellaneous documentation: 41990075Sobrien 42090075Sobrien@table @file 42190075Sobrien@item ABOUT-GCC-NLS 42290075SobrienNotes on GCC's Native Language Support. FIXME: this should be part of 42390075Sobrienthis manual rather than a separate file. 42490075Sobrien@item ABOUT-NLS 42590075SobrienNotes on the Free Translation Project. 42690075Sobrien@item COPYING 42790075SobrienThe GNU General Public License. 42890075Sobrien@item COPYING.LIB 42990075SobrienThe GNU Lesser General Public License. 43090075Sobrien@item *ChangeLog* 43190075Sobrien@itemx */ChangeLog* 43290075SobrienChange log files for various parts of GCC@. 43390075Sobrien@item LANGUAGES 43490075SobrienDetails of a few changes to the GCC front-end interface. FIXME: the 43590075Sobrieninformation in this file should be part of general documentation of 43690075Sobrienthe front-end interface in this manual. 43790075Sobrien@item ONEWS 43890075SobrienInformation about new features in old versions of GCC@. (For recent 43990075Sobrienversions, the information is on the GCC web site.) 44090075Sobrien@item README.Portability 44190075SobrienInformation about portability issues when writing code in GCC@. FIXME: 44290075Sobrienwhy isn't this part of this manual or of the GCC Coding Conventions? 44390075Sobrien@item SERVICE 44490075SobrienA pointer to the GNU Service Directory. 44590075Sobrien@end table 44690075Sobrien 44790075SobrienFIXME: document such files in subdirectories, at least @file{config}, 448220755Sdim@file{cp}, @file{testsuite}. 44990075Sobrien 45090075Sobrien@node Front End 45190075Sobrien@subsection Anatomy of a Language Front End 45290075Sobrien 45390075SobrienA front end for a language in GCC has the following parts: 45490075Sobrien 45590075Sobrien@itemize @bullet 45690075Sobrien@item 45790075SobrienA directory @file{@var{language}} under @file{gcc} containing source 45890075Sobrienfiles for that front end. @xref{Front End Directory, , The Front End 45990075Sobrien@file{@var{language}} Directory}, for details. 46090075Sobrien@item 46190075SobrienA mention of the language in the list of supported languages in 46290075Sobrien@file{gcc/doc/install.texi}. 46390075Sobrien@item 464132718SkanA mention of the name under which the language's runtime library is 465132718Skanrecognized by @option{--enable-shared=@var{package}} in the 466132718Skandocumentation of that option in @file{gcc/doc/install.texi}. 467132718Skan@item 468132718SkanA mention of any special prerequisites for building the front end in 469132718Skanthe documentation of prerequisites in @file{gcc/doc/install.texi}. 470132718Skan@item 47190075SobrienDetails of contributors to that front end in 47290075Sobrien@file{gcc/doc/contrib.texi}. If the details are in that front end's 47390075Sobrienown manual then there should be a link to that manual's list in 47490075Sobrien@file{contrib.texi}. 47590075Sobrien@item 47690075SobrienInformation about support for that language in 47790075Sobrien@file{gcc/doc/frontends.texi}. 47890075Sobrien@item 47990075SobrienInformation about standards for that language, and the front end's 48090075Sobriensupport for them, in @file{gcc/doc/standards.texi}. This may be a 48190075Sobrienlink to such information in the front end's own manual. 48290075Sobrien@item 48390075SobrienDetails of source file suffixes for that language and @option{-x 48490075Sobrien@var{lang}} options supported, in @file{gcc/doc/invoke.texi}. 48590075Sobrien@item 48690075SobrienEntries in @code{default_compilers} in @file{gcc.c} for source file 48790075Sobriensuffixes for that language. 48890075Sobrien@item 489132718SkanPreferably testsuites, which may be under @file{gcc/testsuite} or 49090075Sobrienruntime library directories. FIXME: document somewhere how to write 491132718Skantestsuite harnesses. 49290075Sobrien@item 49390075SobrienProbably a runtime library for the language, outside the @file{gcc} 49490075Sobriendirectory. FIXME: document this further. 49590075Sobrien@item 49690075SobrienDetails of the directories of any runtime libraries in 49790075Sobrien@file{gcc/doc/sourcebuild.texi}. 49890075Sobrien@end itemize 49990075Sobrien 50090075SobrienIf the front end is added to the official GCC CVS repository, the 50190075Sobrienfollowing are also necessary: 50290075Sobrien 50390075Sobrien@itemize @bullet 50490075Sobrien@item 505119256SkanAt least one Bugzilla component for bugs in that front end and runtime 50690075Sobrienlibraries. This category needs to be mentioned in 507119256Skan@file{gcc/gccbug.in}, as well as being added to the Bugzilla database. 50890075Sobrien@item 50990075SobrienNormally, one or more maintainers of that front end listed in 51090075Sobrien@file{MAINTAINERS}. 51190075Sobrien@item 51290075SobrienMentions on the GCC web site in @file{index.html} and 51390075Sobrien@file{frontends.html}, with any relevant links on 51490075Sobrien@file{readings.html}. (Front ends that are not an official part of 51590075SobrienGCC may also be listed on @file{frontends.html}, with relevant links.) 51690075Sobrien@item 51790075SobrienA news item on @file{index.html}, and possibly an announcement on the 51890075Sobrien@email{gcc-announce@@gcc.gnu.org} mailing list. 51990075Sobrien@item 52090075SobrienThe front end's manuals should be mentioned in 52190075Sobrien@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals}) 52290075Sobrienand the online manuals should be linked to from 52390075Sobrien@file{onlinedocs/index.html}. 52490075Sobrien@item 52590075SobrienAny old releases or CVS repositories of the front end, before its 52690075Sobrieninclusion in GCC, should be made available on the GCC FTP site 52790075Sobrien@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. 52890075Sobrien@item 52990075SobrienThe release and snapshot script @file{maintainer-scripts/gcc_release} 53090075Sobrienshould be updated to generate appropriate tarballs for this front end. 531117395SkanThe associated @file{maintainer-scripts/snapshot-README} and 532117395Skan@file{maintainer-scripts/snapshot-index.html} files should be updated 533117395Skanto list the tarballs and diffs for this front end. 53490075Sobrien@item 53590075SobrienIf this front end includes its own version files that include the 53690075Sobriencurrent date, @file{maintainer-scripts/update_version} should be 53790075Sobrienupdated accordingly. 53890075Sobrien@item 53990075Sobrien@file{CVSROOT/modules} in the GCC CVS repository should be updated. 54090075Sobrien@end itemize 54190075Sobrien 54290075Sobrien@menu 54390075Sobrien* Front End Directory:: The front end @file{@var{language}} directory. 54490075Sobrien* Front End Config:: The front end @file{config-lang.in} file. 54590075Sobrien@end menu 54690075Sobrien 54790075Sobrien@node Front End Directory 54890075Sobrien@subsubsection The Front End @file{@var{language}} Directory 54990075Sobrien 55090075SobrienA front end @file{@var{language}} directory contains the source files 55190075Sobrienof that front end (but not of any runtime libraries, which should be 55290075Sobrienoutside the @file{gcc} directory). This includes documentation, and 55390075Sobrienpossibly some subsidiary programs build alongside the front end. 55490075SobrienCertain files are special and other parts of the compiler depend on 55590075Sobrientheir names: 55690075Sobrien 55790075Sobrien@table @file 55890075Sobrien@item config-lang.in 55990075SobrienThis file is required in all language subdirectories. @xref{Front End 56090075SobrienConfig, , The Front End @file{config-lang.in} File}, for details of 56190075Sobrienits contents 56290075Sobrien@item Make-lang.in 56390075SobrienThis file is required in all language subdirectories. It contains 56490075Sobrientargets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the 56590075Sobriensetting of @code{language} in @file{config-lang.in}) for the following 56690075Sobrienvalues of @code{@var{hook}}, and any other Makefile rules required to 56790075Sobrienbuild those targets (which may if necessary use other Makefiles 56890075Sobrienspecified in @code{outputs} in @file{config-lang.in}, although this is 569169689Skandeprecated). It also adds any testsuite targets that can use the 570132718Skanstandard rule in @file{gcc/Makefile.in} to the variable 571132718Skan@code{lang_checks}. 57290075Sobrien 57390075Sobrien@table @code 57490075Sobrien@itemx all.cross 57590075Sobrien@itemx start.encap 57690075Sobrien@itemx rest.encap 57790075SobrienFIXME: exactly what goes in each of these targets? 578132718Skan@item tags 579132718SkanBuild an @command{etags} @file{TAGS} file in the language subdirectory 580132718Skanin the source tree. 58190075Sobrien@item info 582132718SkanBuild info documentation for the front end, in the build directory. 583117395SkanThis target is only called by @samp{make bootstrap} if a suitable 58490075Sobrienversion of @command{makeinfo} is available, so does not need to check 58590075Sobrienfor this, and should fail if an error occurs. 58690075Sobrien@item dvi 58790075SobrienBuild DVI documentation for the front end, in the build directory. 58890075SobrienThis should be done using @code{$(TEXI2DVI)}, with appropriate 58990075Sobrien@option{-I} arguments pointing to directories of included files. 590169689Skan@item pdf 591169689SkanBuild PDF documentation for the front end, in the build directory. 592169689SkanThis should be done using @code{$(TEXI2PDF)}, with appropriate 593169689Skan@option{-I} arguments pointing to directories of included files. 594169689Skan@item html 595169689SkanBuild HTML documentation for the front end, in the build directory. 596132718Skan@item man 59790075SobrienBuild generated man pages for the front end from Texinfo manuals 598132718Skan(@pxref{Man Page Generation}), in the build directory. This target 59990075Sobrienis only called if the necessary tools are available, but should ignore 60090075Sobrienerrors so as not to stop the build if errors occur; man pages are 60190075Sobrienoptional and the tools involved may be installed in a broken way. 60290075Sobrien@item install-common 60390075SobrienInstall everything that is part of the front end, apart from the 60490075Sobriencompiler executables listed in @code{compilers} in 605132718Skan@file{config-lang.in}. 60690075Sobrien@item install-info 60790075SobrienInstall info documentation for the front end, if it is present in the 608132718Skansource directory. This target should have dependencies on info files 609169689Skanthat should be installed. 61090075Sobrien@item install-man 61190075SobrienInstall man pages for the front end. This target should ignore 61290075Sobrienerrors. 613132718Skan@item srcextra 614132718SkanCopies its dependencies into the source directory. This generally should 615169689Skanbe used for generated files such as Bison output files which are not 616132718Skanpresent in CVS, but should be included in any release tarballs. This 617132718Skantarget will be executed during a bootstrap if 618132718Skan@samp{--enable-generated-files-in-srcdir} was specified as a 619132718Skan@file{configure} option. 620132718Skan@item srcinfo 621132718Skan@itemx srcman 622132718SkanCopies its dependencies into the source directory. These targets will be 623132718Skanexecuted during a bootstrap if @samp{--enable-generated-files-in-srcdir} 624132718Skanwas specified as a @file{configure} option. 62590075Sobrien@item uninstall 62690075SobrienUninstall files installed by installing the compiler. This is 62790075Sobriencurrently documented not to be supported, so the hook need not do 62890075Sobrienanything. 62990075Sobrien@item mostlyclean 63090075Sobrien@itemx clean 63190075Sobrien@itemx distclean 63290075Sobrien@itemx maintainer-clean 633132718SkanThe language parts of the standard GNU 634169689Skan@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for 63590075SobrienUsers, standards, GNU Coding Standards}, for details of the standard 636132718Skantargets. For GCC, @code{maintainer-clean} should delete 63790075Sobrienall generated files in the source directory that are not checked into 63890075SobrienCVS, but should not delete anything checked into CVS@. 63990075Sobrien@item stage1 64090075Sobrien@itemx stage2 64190075Sobrien@itemx stage3 64290075Sobrien@itemx stage4 643132718Skan@itemx stageprofile 644132718Skan@itemx stagefeedback 64590075SobrienMove to the stage directory files not included in @code{stagestuff} in 64690075Sobrien@file{config-lang.in} or otherwise moved by the main @file{Makefile}. 64790075Sobrien@end table 64890075Sobrien 649132718Skan@item lang.opt 650132718SkanThis file registers the set of switches that the front end accepts on 651169689Skanthe command line, and their @option{--help} text. @xref{Options}. 65290075Sobrien@item lang-specs.h 65390075SobrienThis file provides entries for @code{default_compilers} in 65490075Sobrien@file{gcc.c} which override the default of giving an error that a 65590075Sobriencompiler for that language is not installed. 65690075Sobrien@item @var{language}-tree.def 65790075SobrienThis file, which need not exist, defines any language-specific tree 65890075Sobriencodes. 65990075Sobrien@end table 66090075Sobrien 66190075Sobrien@node Front End Config 66290075Sobrien@subsubsection The Front End @file{config-lang.in} File 66390075Sobrien 664117395SkanEach language subdirectory contains a @file{config-lang.in} file. In 665117395Skanaddition the main directory contains @file{c-config-lang.in}, which 666117395Skancontains limited information for the C language. This file is a shell 667117395Skanscript that may define some variables describing the language: 66890075Sobrien 66990075Sobrien@table @code 67090075Sobrien@item language 67190075SobrienThis definition must be present, and gives the name of the language 67290075Sobrienfor some purposes such as arguments to @option{--enable-languages}. 67390075Sobrien@item lang_requires 67490075SobrienIf defined, this variable lists (space-separated) language front ends 67590075Sobrienother than C that this front end requires to be enabled (with the 67690075Sobriennames given being their @code{language} settings). For example, the 67790075SobrienJava front end depends on the C++ front end, so sets 67890075Sobrien@samp{lang_requires=c++}. 679169689Skan@item subdir_requires 680169689SkanIf defined, this variable lists (space-separated) front end directories 681220755Sdimother than C that this front end requires to be present. 68290075Sobrien@item target_libs 68390075SobrienIf defined, this variable lists (space-separated) targets in the top 68490075Sobrienlevel @file{Makefile} to build the runtime libraries for this 685220755Sdimlanguage. 68690075Sobrien@item lang_dirs 68790075SobrienIf defined, this variable lists (space-separated) top level 68890075Sobriendirectories (parallel to @file{gcc}), apart from the runtime libraries, 68990075Sobrienthat should not be configured if this front end is not built. 69090075Sobrien@item build_by_default 69190075SobrienIf defined to @samp{no}, this language front end is not built unless 69290075Sobrienenabled in a @option{--enable-languages} argument. Otherwise, front 69390075Sobrienends are built by default, subject to any special logic in 694132718Skan@file{configure.ac} (as is present to disable the Ada front end if the 69590075SobrienAda compiler is not already installed). 69690075Sobrien@item boot_language 69790075SobrienIf defined to @samp{yes}, this front end is built in stage 1 of the 69890075Sobrienbootstrap. This is only relevant to front ends written in their own 69990075Sobrienlanguages. 70090075Sobrien@item compilers 701132718SkanIf defined, a space-separated list of compiler executables that will 702132718Skanbe run by the driver. The names here will each end 70390075Sobrienwith @samp{\$(exeext)}. 70490075Sobrien@item stagestuff 70590075SobrienIf defined, a space-separated list of files that should be moved to 70690075Sobrienthe @file{stage@var{n}} directories in each stage of bootstrap. 70790075Sobrien@item outputs 70890075SobrienIf defined, a space-separated list of files that should be generated 70990075Sobrienby @file{configure} substituting values in them. This mechanism can 71090075Sobrienbe used to create a file @file{@var{language}/Makefile} from 71190075Sobrien@file{@var{language}/Makefile.in}, but this is deprecated, building 71290075Sobrieneverything from the single @file{gcc/Makefile} is preferred. 713117395Skan@item gtfiles 714117395SkanIf defined, a space-separated list of files that should be scanned by 715117395Skangengtype.c to generate the garbage collection tables and routines for 716117395Skanthis language. This excludes the files that are common to all front 717169689Skanends. @xref{Type Information}. 718169689Skan@item need_gmp 719169689SkanIf defined to @samp{yes}, this frontend requires the GMP library. 720169689SkanEnables configure tests for GMP, which set @code{GMPLIBS} and 721169689Skan@code{GMPINC} appropriately. 722117395Skan 72390075Sobrien@end table 72490075Sobrien 72590075Sobrien@node Back End 72690075Sobrien@subsection Anatomy of a Target Back End 72790075Sobrien 72890075SobrienA back end for a target architecture in GCC has the following parts: 72990075Sobrien 73090075Sobrien@itemize @bullet 73190075Sobrien@item 73290075SobrienA directory @file{@var{machine}} under @file{gcc/config}, containing a 73390075Sobrienmachine description @file{@var{machine}.md} file (@pxref{Machine Desc, 73490075Sobrien, Machine Descriptions}), header files @file{@var{machine}.h} and 73590075Sobrien@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} 73690075Sobrien(@pxref{Target Macros, , Target Description Macros and Functions}), 73790075Sobrienpossibly a target Makefile fragment @file{t-@var{machine}} 73890075Sobrien(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe 73990075Sobriensome other files. The names of these files may be changed from the 74090075Sobriendefaults given by explicit specifications in @file{config.gcc}. 74190075Sobrien@item 742117395SkanIf necessary, a file @file{@var{machine}-modes.def} in the 743117395Skan@file{@var{machine}} directory, containing additional machine modes to 744117395Skanrepresent condition codes. @xref{Condition Code}, for further details. 745117395Skan@item 746169689SkanAn optional @file{@var{machine}.opt} file in the @file{@var{machine}} 747169689Skandirectory, containing a list of target-specific options. You can also 748169689Skanadd other option files using the @code{extra_options} variable in 749169689Skan@file{config.gcc}. @xref{Options}. 750169689Skan@item 75190075SobrienEntries in @file{config.gcc} (@pxref{System Config, , The 75290075Sobrien@file{config.gcc} File}) for the systems with this target 75390075Sobrienarchitecture. 75490075Sobrien@item 75590075SobrienDocumentation in @file{gcc/doc/invoke.texi} for any command-line 75690075Sobrienoptions supported by this target (@pxref{Run-time Target, , Run-time 75790075SobrienTarget Specification}). This means both entries in the summary table 75890075Sobrienof options and details of the individual options. 75990075Sobrien@item 76090075SobrienDocumentation in @file{gcc/doc/extend.texi} for any target-specific 76190075Sobrienattributes supported (@pxref{Target Attributes, , Defining 76290075Sobrientarget-specific uses of @code{__attribute__}}), including where the 76390075Sobriensame attribute is already supported on some targets, which are 76490075Sobrienenumerated in the manual. 76590075Sobrien@item 76690075SobrienDocumentation in @file{gcc/doc/extend.texi} for any target-specific 76790075Sobrienpragmas supported. 76890075Sobrien@item 76990075SobrienDocumentation in @file{gcc/doc/extend.texi} of any target-specific 77090075Sobrienbuilt-in functions supported. 77190075Sobrien@item 772169689SkanDocumentation in @file{gcc/doc/extend.texi} of any target-specific 773169689Skanformat checking styles supported. 774169689Skan@item 77590075SobrienDocumentation in @file{gcc/doc/md.texi} of any target-specific 77690075Sobrienconstraint letters (@pxref{Machine Constraints, , Constraints for 77790075SobrienParticular Machines}). 77890075Sobrien@item 77990075SobrienA note in @file{gcc/doc/contrib.texi} under the person or people who 78090075Sobriencontributed the target support. 78190075Sobrien@item 78290075SobrienEntries in @file{gcc/doc/install.texi} for all target triplets 78390075Sobriensupported with this target architecture, giving details of any special 78490075Sobriennotes about installation for this target, or saying that there are no 78590075Sobrienspecial notes if there are none. 78690075Sobrien@item 78790075SobrienPossibly other support outside the @file{gcc} directory for runtime 78890075Sobrienlibraries. FIXME: reference docs for this. The libstdc++ porting 78990075Sobrienmanual needs to be installed as info for this to work, or to be a 79090075Sobrienchapter of this manual. 79190075Sobrien@end itemize 79290075Sobrien 79390075SobrienIf the back end is added to the official GCC CVS repository, the 79490075Sobrienfollowing are also necessary: 79590075Sobrien 79690075Sobrien@itemize @bullet 79790075Sobrien@item 79890075SobrienAn entry for the target architecture in @file{readings.html} on the 79990075SobrienGCC web site, with any relevant links. 80090075Sobrien@item 801132718SkanDetails of the properties of the back end and target architecture in 802132718Skan@file{backends.html} on the GCC web site. 803132718Skan@item 80490075SobrienA news item about the contribution of support for that target 80590075Sobrienarchitecture, in @file{index.html} on the GCC web site. 80690075Sobrien@item 80790075SobrienNormally, one or more maintainers of that target listed in 80890075Sobrien@file{MAINTAINERS}. Some existing architectures may be unmaintained, 80990075Sobrienbut it would be unusual to add support for a target that does not have 81090075Sobriena maintainer when support is added. 81190075Sobrien@end itemize 81290075Sobrien 813132718Skan@node Testsuites 814132718Skan@section Testsuites 81590075Sobrien 816132718SkanGCC contains several testsuites to help maintain compiler quality. 817132718SkanMost of the runtime libraries and language front ends in GCC have 818132718Skantestsuites. Currently only the C language testsuites are documented 81990075Sobrienhere; FIXME: document the others. 82090075Sobrien 82190075Sobrien@menu 822132718Skan* Test Idioms:: Idioms used in testsuite code. 823169689Skan* Test Directives:: Directives used within DejaGnu tests. 824132718Skan* Ada Tests:: The Ada language testsuites. 825132718Skan* C Tests:: The C language testsuites. 826132718Skan* libgcj Tests:: The Java library testsuites. 827117395Skan* gcov Testing:: Support for testing gcov. 828117395Skan* profopt Testing:: Support for testing profile-directed optimizations. 829117395Skan* compat Testing:: Support for testing binary compatibility. 83090075Sobrien@end menu 83190075Sobrien 83290075Sobrien@node Test Idioms 833132718Skan@subsection Idioms Used in Testsuite Code 83490075Sobrien 835169689SkanIn general, C testcases have a trailing @file{-@var{n}.c}, starting 836132718Skanwith @file{-1.c}, in case other testcases with similar names are added 837132718Skanlater. If the test is a test of some well-defined feature, it should 838132718Skanhave a name referring to that feature such as 839132718Skan@file{@var{feature}-1.c}. If it does not test a well-defined feature 840132718Skanbut just happens to exercise a bug somewhere in the compiler, and a 841132718Skanbug report has been filed for this bug in the GCC bug database, 842132718Skan@file{pr@var{bug-number}-1.c} is the appropriate form of name. 843132718SkanOtherwise (for miscellaneous bugs not filed in the GCC bug database), 844132718Skanand previously more generally, test cases are named after the date on 845132718Skanwhich they were added. This allows people to tell at a glance whether 846132718Skana test failure is because of a recently found bug that has not yet 847132718Skanbeen fixed, or whether it may be a regression, but does not give any 848132718Skanother information about the bug or where discussion of it may be 849132718Skanfound. Some other language testsuites follow similar conventions. 85090075Sobrien 851132718SkanIn the @file{gcc.dg} testsuite, it is often necessary to test that an 85290075Sobrienerror is indeed a hard error and not just a warning---for example, 85390075Sobrienwhere it is a constraint violation in the C standard, which must 85490075Sobrienbecome an error with @option{-pedantic-errors}. The following idiom, 85590075Sobrienwhere the first line shown is line @var{line} of the file and the line 85690075Sobrienthat generates the error, is used for this: 85790075Sobrien 85890075Sobrien@smallexample 85990075Sobrien/* @{ dg-bogus "warning" "warning in place of error" @} */ 86090075Sobrien/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ 86190075Sobrien@end smallexample 86290075Sobrien 86390075SobrienIt may be necessary to check that an expression is an integer constant 86490075Sobrienexpression and has a certain value. To check that @code{@var{E}} has 86590075Sobrienvalue @code{@var{V}}, an idiom similar to the following is used: 86690075Sobrien 86790075Sobrien@smallexample 86890075Sobrienchar x[((E) == (V) ? 1 : -1)]; 86990075Sobrien@end smallexample 87090075Sobrien 87190075SobrienIn @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make 87290075Sobrienassertions about the types of expressions. See, for example, 87390075Sobrien@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the 87490075Sobrienexact rules for the types of conditional expressions in the C 87590075Sobrienstandard; see, for example, @file{gcc.dg/c99-intconst-1.c}. 87690075Sobrien 87790075SobrienIt is useful to be able to test that optimizations are being made 87890075Sobrienproperly. This cannot be done in all cases, but it can be done where 87990075Sobrienthe optimization will lead to code being optimized away (for example, 88090075Sobrienwhere flow analysis or alias analysis should show that certain code 88190075Sobriencannot be called) or to functions not being called because they have 88290075Sobrienbeen expanded as built-in functions. Such tests go in 88390075Sobrien@file{gcc.c-torture/execute}. Where code should be optimized away, a 88490075Sobriencall to a nonexistent function such as @code{link_failure ()} may be 88590075Sobrieninserted; a definition 88690075Sobrien 88790075Sobrien@smallexample 88890075Sobrien#ifndef __OPTIMIZE__ 88990075Sobrienvoid 89090075Sobrienlink_failure (void) 89190075Sobrien@{ 89290075Sobrien abort (); 89390075Sobrien@} 89490075Sobrien#endif 89590075Sobrien@end smallexample 89690075Sobrien 89790075Sobrien@noindent 89890075Sobrienwill also be needed so that linking still succeeds when the test is 89990075Sobrienrun without optimization. When all calls to a built-in function 90090075Sobrienshould have been optimized and no calls to the non-built-in version of 90190075Sobrienthe function should remain, that function may be defined as 90290075Sobrien@code{static} to call @code{abort ()} (although redeclaring a function 90390075Sobrienas static may not work on all targets). 90490075Sobrien 905117395SkanAll testcases must be portable. Target-specific testcases must have 906117395Skanappropriate code to avoid causing failures on unsupported systems; 907117395Skanunfortunately, the mechanisms for this differ by directory. 908117395Skan 909132718SkanFIXME: discuss non-C testsuites here. 91090075Sobrien 911169689Skan@node Test Directives 912169689Skan@subsection Directives used within DejaGnu tests 913169689Skan 914169689SkanTest directives appear within comments in a test source file and begin 915169689Skanwith @code{dg-}. Some of these are defined within DejaGnu and others 916169689Skanare local to the GCC testsuite. 917169689Skan 918169689SkanThe order in which test directives appear in a test can be important: 919169689Skandirectives local to GCC sometimes override information used by the 920169689SkanDejaGnu directives, which know nothing about the GCC directives, so the 921169689SkanDejaGnu directives must precede GCC directives. 922169689Skan 923169689SkanSeveral test directives include selectors which are usually preceded by 924169689Skanthe keyword @code{target} or @code{xfail}. A selector is: one or more 925169689Skantarget triplets, possibly including wildcard characters; a single 926169689Skaneffective-target keyword; or a logical expression. Depending on the 927169689Skancontext, the selector specifies whether a test is skipped and reported 928169689Skanas unsupported or is expected to fail. Use @samp{*-*-*} to match any 929169689Skantarget. 930169689SkanEffective-target keywords are defined in @file{target-supports.exp} in 931169689Skanthe GCC testsuite. 932169689Skan 933169689SkanA selector expression appears within curly braces and uses a single 934169689Skanlogical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An 935169689Skanoperand is another selector expression, an effective-target keyword, 936169689Skana single target triplet, or a list of target triplets within quotes or 937169689Skancurly braces. For example: 938169689Skan 939169689Skan@smallexample 940169689Skan@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} 941169689Skan@{ target @{ powerpc*-*-* && lp64 @} @} 942169689Skan@{ xfail @{ lp64 || vect_no_align @} @} 943169689Skan@end smallexample 944169689Skan 945169689Skan@table @code 946169689Skan@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} 947169689Skan@var{do-what-keyword} specifies how the test is compiled and whether 948169689Skanit is executed. It is one of: 949169689Skan 950169689Skan@table @code 951169689Skan@item preprocess 952169689SkanCompile with @option{-E} to run only the preprocessor. 953169689Skan@item assemble 954169689SkanCompile with @option{-S} to produce an assembly code file. 955169689Skan@item compile 956169689SkanCompile with @option{-c} to produce a relocatable object file. 957169689Skan@item link 958169689SkanCompile, assemble, and link to produce an executable file. 959169689Skan@item run 960169689SkanProduce and run an executable file, which is expected to return 961169689Skanan exit code of 0. 962169689Skan@end table 963169689Skan 964169689SkanThe default is @code{compile}. That can be overridden for a set of 965169689Skantests by redefining @code{dg-do-what-default} within the @code{.exp} 966169689Skanfile for those tests. 967169689Skan 968169689SkanIf the directive includes the optional @samp{@{ target @var{selector} @}} 969169689Skanthen the test is skipped unless the target system is included in the 970169689Skanlist of target triplets or matches the effective-target keyword. 971169689Skan 972169689SkanIf the directive includes the optional @samp{@{ xfail @var{selector} @}} 973169689Skanand the selector is met then the test is expected to fail. For 974169689Skan@code{dg-do run}, execution is expected to fail but compilation 975169689Skanis expected to pass. 976169689Skan 977169689Skan@item @{ dg-options @var{options} [@{ target @var{selector} @}] @} 978169689SkanThis DejaGnu directive provides a list of compiler options, to be used 979169689Skanif the target system matches @var{selector}, that replace the default 980169689Skanoptions used for this set of tests. 981169689Skan 982169689Skan@item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 983169689SkanSkip the test if the test system is included in @var{selector} and if 984169689Skaneach of the options in @var{include-opts} is in the set of options with 985169689Skanwhich the test would be compiled and if none of the options in 986169689Skan@var{exclude-opts} is in the set of options with which the test would be 987169689Skancompiled. 988169689Skan 989169689SkanUse @samp{"*"} for an empty @var{include-opts} list and @samp{""} for 990169689Skanan empty @var{exclude-opts} list. 991169689Skan 992169689Skan@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 993169689SkanExpect the test to fail if the conditions (which are the same as for 994169689Skan@code{dg-skip-if}) are met. 995169689Skan 996169689Skan@item @{ dg-require-@var{support} args @} 997169689SkanSkip the test if the target does not provide the required support; 998169689Skansee @file{gcc-dg.exp} in the GCC testsuite for the actual directives. 999169689SkanThese directives must appear after any @code{dg-do} directive in the test. 1000169689SkanThey require at least one argument, which can be an empty string if the 1001169689Skanspecific procedure does not examine the argument. 1002169689Skan 1003169689Skan@item @{ dg-require-effective-target @var{keyword} @} 1004169689SkanSkip the test if the test target, including current multilib flags, 1005169689Skanis not covered by the effective-target keyword. 1006169689SkanThis directive must appear after any @code{dg-do} directive in the test. 1007169689Skan 1008169689Skan@item @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} 1009169689SkanExpect the test executable to return a nonzero exit status if the 1010169689Skanconditions (which are the same as for @code{dg-skip-if}) are met. 1011169689Skan 1012169689Skan@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1013169689SkanThis DejaGnu directive appears on a source line that is expected to get 1014169689Skanan error message, or else specifies the source line associated with the 1015169689Skanmessage. If there is no message for that line or if the text of that 1016169689Skanmessage is not matched by @var{regexp} then the check fails and 1017169689Skan@var{comment} is included in the @code{FAIL} message. The check does 1018169689Skannot look for the string @samp{"error"} unless it is part of @var{regexp}. 1019169689Skan 1020169689Skan@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1021169689SkanThis DejaGnu directive appears on a source line that is expected to get 1022169689Skana warning message, or else specifies the source line associated with the 1023169689Skanmessage. If there is no message for that line or if the text of that 1024169689Skanmessage is not matched by @var{regexp} then the check fails and 1025169689Skan@var{comment} is included in the @code{FAIL} message. The check does 1026169689Skannot look for the string @samp{"warning"} unless it is part of @var{regexp}. 1027169689Skan 1028169689Skan@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} 1029169689SkanThis DejaGnu directive appears on a source line that should not get a 1030169689Skanmessage matching @var{regexp}, or else specifies the source line 1031169689Skanassociated with the bogus message. It is usually used with @samp{xfail} 1032169689Skanto indicate that the message is a known problem for a particular set of 1033169689Skantargets. 1034169689Skan 1035169689Skan@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} 1036169689SkanThis DejaGnu directive indicates that the test is expected to fail due 1037169689Skanto compiler messages that are not handled by @samp{dg-error}, 1038169689Skan@samp{dg-warning} or @samp{dg-bogus}. 1039169689Skan 1040169689Skan@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} 1041169689SkanThis DejaGnu directive compares @var{regexp} to the combined output 1042169689Skanthat the test executable writes to @file{stdout} and @file{stderr}. 1043169689Skan 1044169689Skan@item @{ dg-prune-output @var{regexp} @} 1045169689SkanPrune messages matching @var{regexp} from test output. 1046169689Skan 1047169689Skan@item @{ dg-additional-files "@var{filelist}" @} 1048169689SkanSpecify additional files, other than source files, that must be copied 1049169689Skanto the system where the compiler runs. 1050169689Skan 1051169689Skan@item @{ dg-additional-sources "@var{filelist}" @} 1052169689SkanSpecify additional source files to appear in the compile line 1053169689Skanfollowing the main test file. 1054169689Skan 1055169689Skan@item @{ dg-final @{ @var{local-directive} @} @} 1056169689SkanThis DejaGnu directive is placed within a comment anywhere in the 1057169689Skansource file and is processed after the test has been compiled and run. 1058169689SkanMultiple @samp{dg-final} commands are processed in the order in which 1059169689Skanthey appear in the source file. 1060169689Skan 1061169689SkanThe GCC testsuite defines the following directives to be used within 1062169689Skan@code{dg-final}. 1063169689Skan 1064169689Skan@table @code 1065169689Skan@item cleanup-coverage-files 1066169689SkanRemoves coverage data files generated for this test. 1067169689Skan 1068169689Skan@item cleanup-repo-files 1069169689SkanRemoves files generated for this test for @option{-frepo}. 1070169689Skan 1071169689Skan@item cleanup-rtl-dump @var{suffix} 1072169689SkanRemoves RTL dump files generated for this test. 1073169689Skan 1074169689Skan@item cleanup-tree-dump @var{suffix} 1075169689SkanRemoves tree dump files matching @var{suffix} which were generated for 1076169689Skanthis test. 1077169689Skan 1078169689Skan@item cleanup-saved-temps 1079169689SkanRemoves files for the current test which were kept for @option{--save-temps}. 1080169689Skan 1081169689Skan@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1082169689SkanPasses if @var{regexp} matches text in @var{filename}. 1083169689Skan 1084169689Skan@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] 1085169689SkanPasses if @var{regexp} does not match text in @var{filename}. 1086169689Skan 1087169689Skan@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 1088169689SkanPasses if @var{symbol} is defined as a hidden symbol in the test's 1089169689Skanassembly output. 1090169689Skan 1091169689Skan@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] 1092169689SkanPasses if @var{symbol} is not defined as a hidden symbol in the test's 1093169689Skanassembly output. 1094169689Skan 1095169689Skan@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] 1096169689SkanPasses if @var{regex} is matched exactly @var{num} times in the test's 1097169689Skanassembler output. 1098169689Skan 1099169689Skan@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] 1100169689SkanPasses if @var{regex} matches text in the test's assembler output. 1101169689Skan 1102169689Skan@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] 1103169689SkanPasses if @var{regex} does not match text in the test's assembler output. 1104169689Skan 1105169689Skan@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] 1106169689SkanPasses if @var{regex} matches text in the test's demangled assembler output. 1107169689Skan 1108169689Skan@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] 1109169689SkanPasses if @var{regex} does not match text in the test's demangled assembler 1110169689Skanoutput. 1111169689Skan 1112169689Skan@item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] 1113169689SkanPasses if @var{regex} is found exactly @var{num} times in the dump file 1114169689Skanwith suffix @var{suffix}. 1115169689Skan 1116169689Skan@item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1117169689SkanPasses if @var{regex} matches text in the dump file with suffix @var{suffix}. 1118169689Skan 1119169689Skan@item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1120169689SkanPasses if @var{regex} does not match text in the dump file with suffix 1121169689Skan@var{suffix}. 1122169689Skan 1123169689Skan@item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1124169689SkanPasses if @var{regex} matches demangled text in the dump file with 1125169689Skansuffix @var{suffix}. 1126169689Skan 1127169689Skan@item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] 1128169689SkanPasses if @var{regex} does not match demangled text in the dump file with 1129169689Skansuffix @var{suffix}. 1130169689Skan 1131169689Skan@item output-exists [@{ target/xfail @var{selector} @}] 1132169689SkanPasses if compiler output file exists. 1133169689Skan 1134169689Skan@item output-exists-not [@{ target/xfail @var{selector} @}] 1135169689SkanPasses if compiler output file does not exist. 1136169689Skan 1137169689Skan@item run-gcov @var{sourcefile} 1138169689SkanCheck line counts in @command{gcov} tests. 1139169689Skan 1140169689Skan@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} 1141169689SkanCheck branch and/or call counts, in addition to line counts, in 1142169689Skan@command{gcov} tests. 1143169689Skan@end table 1144169689Skan@end table 1145169689Skan 1146132718Skan@node Ada Tests 1147132718Skan@subsection Ada Language Testsuites 1148132718Skan 1149132718SkanThe Ada testsuite includes executable tests from the ACATS 2.5 1150132718Skantestsuite, publicly available at 1151132718Skan@uref{http://www.adaic.org/compilers/acats/2.5} 1152132718Skan 1153132718SkanThese tests are integrated in the GCC testsuite in the 1154132718Skan@file{gcc/testsuite/ada/acats} directory, and 1155132718Skanenabled automatically when running @code{make check}, assuming 1156169689Skanthe Ada language has been enabled when configuring GCC@. 1157132718Skan 1158132718SkanYou can also run the Ada testsuite independently, using 1159132718Skan@code{make check-ada}, or run a subset of the tests by specifying which 1160169689Skanchapter to run, e.g.: 1161132718Skan 1162132718Skan@smallexample 1163132718Skan$ make check-ada CHAPTERS="c3 c9" 1164132718Skan@end smallexample 1165132718Skan 1166132718SkanThe tests are organized by directory, each directory corresponding to 1167169689Skana chapter of the Ada Reference Manual. So for example, c9 corresponds 1168132718Skanto chapter 9, which deals with tasking features of the language. 1169132718Skan 1170132718SkanThere is also an extra chapter called @file{gcc} containing a template for 1171132718Skancreating new executable tests. 1172132718Skan 1173169689SkanThe tests are run using two @command{sh} scripts: @file{run_acats} and 1174169689Skan@file{run_all.sh}. To run the tests using a simulator or a cross 1175169689Skantarget, see the small 1176169689Skancustomization section at the top of @file{run_all.sh}. 1177132718Skan 1178132718SkanThese tests are run using the build tree: they can be run without doing 1179132718Skana @code{make install}. 1180132718Skan 118190075Sobrien@node C Tests 1182132718Skan@subsection C Language Testsuites 118390075Sobrien 1184132718SkanGCC contains the following C language testsuites, in the 118590075Sobrien@file{gcc/testsuite} directory: 118690075Sobrien 118790075Sobrien@table @file 1188117395Skan@item gcc.dg 1189132718SkanThis contains tests of particular features of the C compiler, using the 1190117395Skanmore modern @samp{dg} harness. Correctness tests for various compiler 1191117395Skanfeatures should go here if possible. 1192117395Skan 1193132718SkanMagic comments determine whether the file 1194132718Skanis preprocessed, compiled, linked or run. In these tests, error and warning 1195132718Skanmessage texts are compared against expected texts or regular expressions 1196117395Skangiven in comments. These tests are run with the options @samp{-ansi -pedantic} 1197117395Skanunless other options are given in the test. Except as noted below they 1198117395Skanare not run with multiple optimization options. 1199132718Skan@item gcc.dg/compat 1200132718SkanThis subdirectory contains tests for binary compatibility using 1201132718Skan@file{compat.exp}, which in turn uses the language-independent support 1202132718Skan(@pxref{compat Testing, , Support for testing binary compatibility}). 1203117395Skan@item gcc.dg/cpp 1204117395SkanThis subdirectory contains tests of the preprocessor. 1205117395Skan@item gcc.dg/debug 1206117395SkanThis subdirectory contains tests for debug formats. Tests in this 1207117395Skansubdirectory are run for each debug format that the compiler supports. 1208117395Skan@item gcc.dg/format 1209117395SkanThis subdirectory contains tests of the @option{-Wformat} format 1210117395Skanchecking. Tests in this directory are run with and without 1211117395Skan@option{-DWIDE}. 1212117395Skan@item gcc.dg/noncompile 1213117395SkanThis subdirectory contains tests of code that should not compile and 1214117395Skandoes not need any special compilation options. They are run with 1215117395Skanmultiple optimization options, since sometimes invalid code crashes 1216117395Skanthe compiler with optimization. 1217117395Skan@item gcc.dg/special 1218117395SkanFIXME: describe this. 1219117395Skan 1220117395Skan@item gcc.c-torture 1221117395SkanThis contains particular code fragments which have historically broken easily. 1222117395SkanThese tests are run with multiple optimization options, so tests for features 1223117395Skanwhich only break at some optimization levels belong here. This also contains 1224132718Skantests to check that certain optimizations occur. It might be worthwhile to 1225117395Skanseparate the correctness tests cleanly from the code quality tests, but 1226117395Skanit hasn't been done yet. 1227117395Skan 122890075Sobrien@item gcc.c-torture/compat 122990075SobrienFIXME: describe this. 123090075Sobrien 123190075SobrienThis directory should probably not be used for new tests. 123290075Sobrien@item gcc.c-torture/compile 1233132718SkanThis testsuite contains test cases that should compile, but do not 123490075Sobrienneed to link or run. These test cases are compiled with several 123590075Sobriendifferent combinations of optimization options. All warnings are 123690075Sobriendisabled for these test cases, so this directory is not suitable if 123790075Sobrienyou wish to test for the presence or absence of compiler warnings. 123890075SobrienWhile special options can be set, and tests disabled on specific 123990075Sobrienplatforms, by the use of @file{.x} files, mostly these test cases 124090075Sobrienshould not contain platform dependencies. FIXME: discuss how defines 124190075Sobriensuch as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. 124290075Sobrien@item gcc.c-torture/execute 1243132718SkanThis testsuite contains test cases that should compile, link and run; 124490075Sobrienotherwise the same comments as for @file{gcc.c-torture/compile} apply. 1245117395Skan@item gcc.c-torture/execute/ieee 1246117395SkanThis contains tests which are specific to IEEE floating point. 124790075Sobrien@item gcc.c-torture/unsorted 124890075SobrienFIXME: describe this. 124990075Sobrien 125090075SobrienThis directory should probably not be used for new tests. 125190075Sobrien@item gcc.c-torture/misc-tests 1252117395SkanThis directory contains C tests that require special handling. Some 1253117395Skanof these tests have individual expect files, and others share 1254117395Skanspecial-purpose expect files: 1255117395Skan 1256117395Skan@table @file 1257117395Skan@item @code{bprob*.c} 1258117395SkanTest @option{-fbranch-probabilities} using @file{bprob.exp}, which 1259117395Skanin turn uses the generic, language-independent framework 1260117395Skan(@pxref{profopt Testing, , Support for testing profile-directed 1261117395Skanoptimizations}). 1262117395Skan 1263117395Skan@item @code{dg-*.c} 1264117395SkanTest the testsuite itself using @file{dg-test.exp}. 1265117395Skan 1266117395Skan@item @code{gcov*.c} 1267117395SkanTest @command{gcov} output using @file{gcov.exp}, which in turn uses the 1268117395Skanlanguage-independent support (@pxref{gcov Testing, , Support for testing gcov}). 1269117395Skan 1270117395Skan@item @code{i386-pf-*.c} 1271117395SkanTest i386-specific support for data prefetch using @file{i386-prefetch.exp}. 127290075Sobrien@end table 127390075Sobrien 1274117395Skan@end table 1275117395Skan 127690075SobrienFIXME: merge in @file{testsuite/README.gcc} and discuss the format of 127790075Sobrientest cases and magic comments more. 1278107590Sobrien 1279107590Sobrien@node libgcj Tests 1280132718Skan@subsection The Java library testsuites. 1281107590Sobrien 1282119256SkanRuntime tests are executed via @samp{make check} in the 1283119256Skan@file{@var{target}/libjava/testsuite} directory in the build 1284119256Skantree. Additional runtime tests can be checked into this testsuite. 1285107590Sobrien 1286107590SobrienRegression testing of the core packages in libgcj is also covered by the 1287169689SkanMauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} 1288107590Sobriendevelops tests for the Java Class Libraries. These tests are run as part 1289117395Skanof libgcj testing by placing the Mauve tree within the libjava testsuite 1290117395Skansources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying 1291117395Skanthe location of that tree when invoking @samp{make}, as in 1292117395Skan@samp{make MAUVEDIR=~/mauve check}. 1293107590Sobrien 1294117395SkanTo detect regressions, a mechanism in @file{mauve.exp} compares the 1295117395Skanfailures for a test run against the list of expected failures in 1296117395Skan@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. 1297117395SkanUpdate this file when adding new failing tests to Mauve, or when fixing 1298117395Skanbugs in libgcj that had caused Mauve test failures. 1299117395Skan 1300169689SkanThe @uref{http://sourceware.org/mauve/jacks.html,, 1301132718SkanJacks} project provides a testsuite for Java compilers that can be used 1302132718Skanto test changes that affect the GCJ front end. This testsuite is run as 1303169689Skanpart of Java testing by placing the Jacks tree within the libjava 1304117395Skantestsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. 1305107590Sobrien 1306107590SobrienWe encourage developers to contribute test cases to Mauve and Jacks. 1307117395Skan 1308117395Skan@node gcov Testing 1309117395Skan@subsection Support for testing @command{gcov} 1310117395Skan 1311117395SkanLanguage-independent support for testing @command{gcov}, and for checking 1312117395Skanthat branch profiling produces expected values, is provided by the 1313117395Skanexpect file @file{gcov.exp}. @command{gcov} tests also rely on procedures 1314117395Skanin @file{gcc.dg.exp} to compile and run the test program. A typical 1315169689Skan@command{gcov} test contains the following DejaGnu commands within comments: 1316117395Skan 1317117395Skan@smallexample 1318117395Skan@{ dg-options "-fprofile-arcs -ftest-coverage" @} 1319117395Skan@{ dg-do run @{ target native @} @} 1320117395Skan@{ dg-final @{ run-gcov sourcefile @} @} 1321117395Skan@end smallexample 1322117395Skan 1323117395SkanChecks of @command{gcov} output can include line counts, branch percentages, 1324117395Skanand call return percentages. All of these checks are requested via 1325117395Skancommands that appear in comments in the test's source file. 1326117395SkanCommands to check line counts are processed by default. 1327117395SkanCommands to check branch percentages and call return percentages are 1328132718Skanprocessed if the @command{run-gcov} command has arguments @code{branches} 1329132718Skanor @code{calls}, respectively. For example, the following specifies 1330169689Skanchecking both, as well as passing @option{-b} to @command{gcov}: 1331117395Skan 1332132718Skan@smallexample 1333132718Skan@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} 1334132718Skan@end smallexample 1335132718Skan 1336117395SkanA line count command appears within a comment on the source line 1337117395Skanthat is expected to get the specified count and has the form 1338117395Skan@code{count(@var{cnt})}. A test should only check line counts for 1339117395Skanlines that will get the same count for any architecture. 1340117395Skan 1341117395SkanCommands to check branch percentages (@code{branch}) and call 1342117395Skanreturn percentages (@code{returns}) are very similar to each other. 1343117395SkanA beginning command appears on or before the first of a range of 1344117395Skanlines that will report the percentage, and the ending command 1345117395Skanfollows that range of lines. The beginning command can include a 1346117395Skanlist of percentages, all of which are expected to be found within 1347117395Skanthe range. A range is terminated by the next command of the same 1348117395Skankind. A command @code{branch(end)} or @code{returns(end)} marks 1349117395Skanthe end of a range without starting a new one. For example: 1350117395Skan 1351117395Skan@smallexample 1352169689Skanif (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ 1353169689Skan /* @r{branch(end)} */ 1354117395Skan foo (i, j); 1355117395Skan@end smallexample 1356117395Skan 1357117395SkanFor a call return percentage, the value specified is the 1358117395Skanpercentage of calls reported to return. For a branch percentage, 1359117395Skanthe value is either the expected percentage or 100 minus that 1360117395Skanvalue, since the direction of a branch can differ depending on the 1361117395Skantarget or the optimization level. 1362117395Skan 1363117395SkanNot all branches and calls need to be checked. A test should not 1364117395Skancheck for branches that might be optimized away or replaced with 1365117395Skanpredicated instructions. Don't check for calls inserted by the 1366117395Skancompiler or ones that might be inlined or optimized away. 1367117395Skan 1368117395SkanA single test can check for combinations of line counts, branch 1369117395Skanpercentages, and call return percentages. The command to check a 1370117395Skanline count must appear on the line that will report that count, but 1371117395Skancommands to check branch percentages and call return percentages can 1372117395Skanbracket the lines that report them. 1373117395Skan 1374117395Skan@node profopt Testing 1375117395Skan@subsection Support for testing profile-directed optimizations 1376117395Skan 1377117395SkanThe file @file{profopt.exp} provides language-independent support for 1378117395Skanchecking correct execution of a test built with profile-directed 1379117395Skanoptimization. This testing requires that a test program be built and 1380117395Skanexecuted twice. The first time it is compiled to generate profile 1381117395Skandata, and the second time it is compiled to use the data that was 1382117395Skangenerated during the first execution. The second execution is to 1383117395Skanverify that the test produces the expected results. 1384117395Skan 1385117395SkanTo check that the optimization actually generated better code, a 1386117395Skantest can be built and run a third time with normal optimizations to 1387117395Skanverify that the performance is better with the profile-directed 1388117395Skanoptimizations. @file{profopt.exp} has the beginnings of this kind 1389117395Skanof support. 1390117395Skan 1391117395Skan@file{profopt.exp} provides generic support for profile-directed 1392117395Skanoptimizations. Each set of tests that uses it provides information 1393117395Skanabout a specific optimization: 1394117395Skan 1395117395Skan@table @code 1396117395Skan@item tool 1397132718Skantool being tested, e.g., @command{gcc} 1398117395Skan 1399117395Skan@item profile_option 1400117395Skanoptions used to generate profile data 1401117395Skan 1402117395Skan@item feedback_option 1403117395Skanoptions used to optimize using that profile data 1404117395Skan 1405117395Skan@item prof_ext 1406117395Skansuffix of profile data files 1407117395Skan 1408117395Skan@item PROFOPT_OPTIONS 1409117395Skanlist of options with which to run each test, similar to the lists for 1410117395Skantorture tests 1411117395Skan@end table 1412117395Skan 1413117395Skan@node compat Testing 1414117395Skan@subsection Support for testing binary compatibility 1415117395Skan 1416117395SkanThe file @file{compat.exp} provides language-independent support for 1417132718Skanbinary compatibility testing. It supports testing interoperability of 1418132718Skantwo compilers that follow the same ABI, or of multiple sets of 1419132718Skancompiler options that should not affect binary compatibility. It is 1420132718Skanintended to be used for testsuites that complement ABI testsuites. 1421117395Skan 1422117395SkanA test supported by this framework has three parts, each in a 1423117395Skanseparate source file: a main program and two pieces that interact 1424117395Skanwith each other to split up the functionality being tested. 1425117395Skan 1426117395Skan@table @file 1427117395Skan@item @var{testname}_main.@var{suffix} 1428117395SkanContains the main program, which calls a function in file 1429117395Skan@file{@var{testname}_x.@var{suffix}}. 1430117395Skan 1431117395Skan@item @var{testname}_x.@var{suffix} 1432117395SkanContains at least one call to a function in 1433117395Skan@file{@var{testname}_y.@var{suffix}}. 1434117395Skan 1435117395Skan@item @var{testname}_y.@var{suffix} 1436117395SkanShares data with, or gets arguments from, 1437117395Skan@file{@var{testname}_x.@var{suffix}}. 1438117395Skan@end table 1439117395Skan 1440117395SkanWithin each test, the main program and one functional piece are 1441117395Skancompiled by the GCC under test. The other piece can be compiled by 1442117395Skanan alternate compiler. If no alternate compiler is specified, 1443117395Skanthen all three source files are all compiled by the GCC under test. 1444169689SkanYou can specify pairs of sets of compiler options. The first element 1445169689Skanof such a pair specifies options used with the GCC under test, and the 1446169689Skansecond element of the pair specifies options used with the alternate 1447169689Skancompiler. Each test is compiled with each pair of options. 1448117395Skan 1449117395Skan@file{compat.exp} defines default pairs of compiler options. 1450117395SkanThese can be overridden by defining the environment variable 1451117395Skan@env{COMPAT_OPTIONS} as: 1452117395Skan 1453117395Skan@smallexample 1454117395SkanCOMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] 1455117395Skan ...[list @{@var{tstn}@} @{@var{altn}@}]]" 1456117395Skan@end smallexample 1457117395Skan 1458117395Skanwhere @var{tsti} and @var{alti} are lists of options, with @var{tsti} 1459117395Skanused by the compiler under test and @var{alti} used by the alternate 1460117395Skancompiler. For example, with 1461117395Skan@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, 1462169689Skanthe test is first built with @option{-g -O0} by the compiler under 1463169689Skantest and with @option{-O3} by the alternate compiler. The test is 1464169689Skanbuilt a second time using @option{-fpic} by the compiler under test 1465169689Skanand @option{-fPIC -O2} by the alternate compiler. 1466117395Skan 1467117395SkanAn alternate compiler is specified by defining an environment 1468169689Skanvariable to be the full pathname of an installed compiler; for C 1469169689Skandefine @env{ALT_CC_UNDER_TEST}, and for C++ define 1470169689Skan@env{ALT_CXX_UNDER_TEST}. These will be written to the 1471169689Skan@file{site.exp} file used by DejaGnu. The default is to build each 1472117395Skantest with the compiler under test using the first of each pair of 1473117395Skancompiler options from @env{COMPAT_OPTIONS}. When 1474169689Skan@env{ALT_CC_UNDER_TEST} or 1475117395Skan@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using 1476117395Skanthe compiler under test but with combinations of the options from 1477117395Skan@env{COMPAT_OPTIONS}. 1478117395Skan 1479117395SkanTo run only the C++ compatibility suite using the compiler under test 1480117395Skanand another version of GCC using specific compiler options, do the 1481117395Skanfollowing from @file{@var{objdir}/gcc}: 1482117395Skan 1483117395Skan@smallexample 1484117395Skanrm site.exp 1485117395Skanmake -k \ 1486117395Skan ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ 1487117395Skan COMPAT_OPTIONS="lists as shown above" \ 1488117395Skan check-c++ \ 1489117395Skan RUNTESTFLAGS="compat.exp" 1490117395Skan@end smallexample 1491117395Skan 1492117395SkanA test that fails when the source files are compiled with different 1493117395Skancompilers, but passes when the files are compiled with the same 1494117395Skancompiler, demonstrates incompatibility of the generated code or 1495117395Skanruntime support. A test that fails for the alternate compiler but 1496117395Skanpasses for the compiler under test probably tests for a bug that was 1497117395Skanfixed in the compiler under test but is present in the alternate 1498117395Skancompiler. 1499169689Skan 1500169689SkanThe binary compatibility tests support a small number of test framework 1501169689Skancommands that appear within comments in a test file. 1502169689Skan 1503169689Skan@table @code 1504169689Skan@item dg-require-* 1505169689SkanThese commands can be used in @file{@var{testname}_main.@var{suffix}} 1506169689Skanto skip the test if specific support is not available on the target. 1507169689Skan 1508169689Skan@item dg-options 1509169689SkanThe specified options are used for compiling this particular source 1510169689Skanfile, appended to the options from @env{COMPAT_OPTIONS}. When this 1511169689Skancommand appears in @file{@var{testname}_main.@var{suffix}} the options 1512169689Skanare also used to link the test program. 1513169689Skan 1514169689Skan@item dg-xfail-if 1515169689SkanThis command can be used in a secondary source file to specify that 1516169689Skancompilation is expected to fail for particular options on particular 1517169689Skantargets. 1518169689Skan@end table 1519