From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/doc/sourcebuild.texi | 2582 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2582 insertions(+) create mode 100644 gcc/doc/sourcebuild.texi (limited to 'gcc/doc/sourcebuild.texi') diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi new file mode 100644 index 000000000..f4a2807a1 --- /dev/null +++ b/gcc/doc/sourcebuild.texi @@ -0,0 +1,2582 @@ +@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010, 2011 +@c Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Source Tree +@chapter Source Tree Structure and Build System + +This chapter describes the structure of the GCC source tree, and how +GCC is built. The user documentation for building and installing GCC +is in a separate manual (@uref{http://gcc.gnu.org/install/}), with +which it is presumed that you are familiar. + +@menu +* Configure Terms:: Configuration terminology and history. +* Top Level:: The top level source directory. +* gcc Directory:: The @file{gcc} subdirectory. +@end menu + +@include configterms.texi + +@node Top Level +@section Top Level Source Directory + +The top level source directory in a GCC distribution contains several +files and directories that are shared with other software +distributions such as that of GNU Binutils. It also contains several +subdirectories that contain parts of GCC and its runtime libraries: + +@table @file +@item boehm-gc +The Boehm conservative garbage collector, used as part of the Java +runtime library. + +@item config +Autoconf macros and Makefile fragments used throughout the tree. + +@item contrib +Contributed scripts that may be found useful in conjunction with GCC@. +One of these, @file{contrib/texi2pod.pl}, is used to generate man +pages from Texinfo manuals as part of the GCC build process. + +@item fixincludes +The support for fixing system headers to work with GCC@. See +@file{fixincludes/README} for more information. The headers fixed by +this mechanism are installed in @file{@var{libsubdir}/include-fixed}. +Along with those headers, @file{README-fixinc} is also installed, as +@file{@var{libsubdir}/include-fixed/README}. + +@item gcc +The main sources of GCC itself (except for runtime libraries), +including optimizers, support for different target architectures, +language front ends, and testsuites. @xref{gcc Directory, , The +@file{gcc} Subdirectory}, for details. + +@item gnattools +Support tools for GNAT. + +@item include +Headers for the @code{libiberty} library. + +@item intl +GNU @code{libintl}, from GNU @code{gettext}, for systems which do not +include it in @code{libc}. + +@item libada +The Ada runtime library. + +@item libcpp +The C preprocessor library. + +@item libdecnumber +The Decimal Float support library. + +@item libffi +The @code{libffi} library, used as part of the Java runtime library. + +@item libgcc +The GCC runtime library. + +@item libgfortran +The Fortran runtime library. + +@item libgo +The Go runtime library. The bulk of this library is mirrored from the +@uref{http://code.google.com/@/p/@/go/, master Go repository}. + +@item libgomp +The GNU OpenMP runtime library. + +@item libiberty +The @code{libiberty} library, used for portability and for some +generally useful data structures and algorithms. @xref{Top, , +Introduction, libiberty, @sc{gnu} libiberty}, for more information +about this library. + +@item libjava +The Java runtime library. + +@item libmudflap +The @code{libmudflap} library, used for instrumenting pointer and array +dereferencing operations. + +@item libobjc +The Objective-C and Objective-C++ runtime library. + +@item libssp +The Stack protector runtime library. + +@item libstdc++-v3 +The C++ runtime library. + +@item lto-plugin +Plugin used by @command{gold} if link-time optimizations are enabled. + +@item maintainer-scripts +Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. + +@item zlib +The @code{zlib} compression library, used by the Java front end, as +part of the Java runtime library, and for compressing and uncompressing +GCC's intermediate language in LTO object files. +@end table + +The build system in the top level directory, including how recursion +into subdirectories works and how building runtime libraries for +multilibs is handled, is documented in a separate manual, included +with GNU Binutils. @xref{Top, , GNU configure and build system, +configure, The GNU configure and build system}, for details. + +@node gcc Directory +@section The @file{gcc} Subdirectory + +The @file{gcc} directory contains many files that are part of the C +sources of GCC, other files used as part of the configuration and +build process, and subdirectories including documentation and a +testsuite. The files that are sources of GCC are documented in a +separate chapter. @xref{Passes, , Passes and Files of the Compiler}. + +@menu +* Subdirectories:: Subdirectories of @file{gcc}. +* Configuration:: The configuration process, and the files it uses. +* Build:: The build system in the @file{gcc} directory. +* Makefile:: Targets in @file{gcc/Makefile}. +* Library Files:: Library source files and headers under @file{gcc/}. +* Headers:: Headers installed by GCC. +* Documentation:: Building documentation in GCC. +* Front End:: Anatomy of a language front end. +* Back End:: Anatomy of a target back end. +@end menu + +@node Subdirectories +@subsection Subdirectories of @file{gcc} + +The @file{gcc} directory contains the following subdirectories: + +@table @file +@item @var{language} +Subdirectories for various languages. Directories containing a file +@file{config-lang.in} are language subdirectories. The contents of +the subdirectories @file{cp} (for C++), @file{lto} (for LTO), +@file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are +documented in this manual (@pxref{Passes, , Passes and Files of the +Compiler}); those for other languages are not. @xref{Front End, , +Anatomy of a Language Front End}, for details of the files in these +directories. + +@item config +Configuration files for supported architectures and operating +systems. @xref{Back End, , Anatomy of a Target Back End}, for +details of the files in this directory. + +@item doc +Texinfo documentation for GCC, together with automatically generated +man pages and support for converting the installation manual to +HTML@. @xref{Documentation}. + +@item ginclude +System headers installed by GCC, mainly those required by the C +standard of freestanding implementations. @xref{Headers, , Headers +Installed by GCC}, for details of when these and other headers are +installed. + +@item po +Message catalogs with translations of messages produced by GCC into +various languages, @file{@var{language}.po}. This directory also +contains @file{gcc.pot}, the template for these message catalogues, +@file{exgettext}, a wrapper around @command{gettext} to extract the +messages from the GCC sources and create @file{gcc.pot}, which is run +by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from +which messages should not be extracted. + +@item testsuite +The GCC testsuites (except for those for runtime libraries). +@xref{Testsuites}. +@end table + +@node Configuration +@subsection Configuration in the @file{gcc} Directory + +The @file{gcc} directory is configured with an Autoconf-generated +script @file{configure}. The @file{configure} script is generated +from @file{configure.ac} and @file{aclocal.m4}. From the files +@file{configure.ac} and @file{acconfig.h}, Autoheader generates the +file @file{config.in}. The file @file{cstamp-h.in} is used as a +timestamp. + +@menu +* Config Fragments:: Scripts used by @file{configure}. +* System Config:: The @file{config.build}, @file{config.host}, and + @file{config.gcc} files. +* Configuration Files:: Files created by running @file{configure}. +@end menu + +@node Config Fragments +@subsubsection Scripts Used by @file{configure} + +@file{configure} uses some other scripts to help in its work: + +@itemize @bullet +@item The standard GNU @file{config.sub} and @file{config.guess} +files, kept in the top level directory, are used. + +@item The file @file{config.gcc} is used to handle configuration +specific to the particular target machine. The file +@file{config.build} is used to handle configuration specific to the +particular build machine. The file @file{config.host} is used to handle +configuration specific to the particular host machine. (In general, +these should only be used for features that cannot reasonably be tested in +Autoconf feature tests.) +@xref{System Config, , The @file{config.build}; @file{config.host}; +and @file{config.gcc} Files}, for details of the contents of these files. + +@item Each language subdirectory has a file +@file{@var{language}/config-lang.in} that is used for +front-end-specific configuration. @xref{Front End Config, , The Front +End @file{config-lang.in} File}, for details of this file. + +@item A helper script @file{configure.frag} is used as part of +creating the output of @file{configure}. +@end itemize + +@node System Config +@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files + +The @file{config.build} file contains specific rules for particular systems +which GCC is built on. This should be used as rarely as possible, as the +behavior of the build system can always be detected by autoconf. + +The @file{config.host} file contains specific rules for particular systems +which GCC will run on. This is rarely needed. + +The @file{config.gcc} file contains specific rules for particular systems +which GCC will generate code for. This is usually needed. + +Each file has a list of the shell variables it sets, with descriptions, at the +top of the file. + +FIXME: document the contents of these files, and what variables should +be set to control build, host and target configuration. + +@include configfiles.texi + +@node Build +@subsection Build System in the @file{gcc} Directory + +FIXME: describe the build system, including what is built in what +stages. Also list the various source files that are used in the build +process but aren't source files of GCC itself and so aren't documented +below (@pxref{Passes}). + +@include makefile.texi + +@node Library Files +@subsection Library Source Files and Headers under the @file{gcc} Directory + +FIXME: list here, with explanation, all the C source files and headers +under the @file{gcc} directory that aren't built into the GCC +executable but rather are part of runtime libraries and object files, +such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , +Headers Installed by GCC}, for more information about the +@file{ginclude} directory. + +@node Headers +@subsection Headers Installed by GCC + +In general, GCC expects the system C library to provide most of the +headers to be used with it. However, GCC will fix those headers if +necessary to make them work with GCC, and will install some headers +required of freestanding implementations. These headers are installed +in @file{@var{libsubdir}/include}. Headers for non-C runtime +libraries are also installed by GCC; these are not documented here. +(FIXME: document them somewhere.) + +Several of the headers GCC installs are in the @file{ginclude} +directory. These headers, @file{iso646.h}, +@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, +are installed in @file{@var{libsubdir}/include}, +unless the target Makefile fragment (@pxref{Target Fragment}) +overrides this by setting @code{USER_H}. + +In addition to these headers and those generated by fixing system +headers to work with GCC, some other headers may also be installed in +@file{@var{libsubdir}/include}. @file{config.gcc} may set +@code{extra_headers}; this specifies additional headers under +@file{config} to be installed on some systems. + +GCC installs its own version of @code{}, from @file{ginclude/float.h}. +This is done to cope with command-line options that change the +representation of floating point numbers. + +GCC also installs its own version of @code{}; this is generated +from @file{glimits.h}, together with @file{limitx.h} and +@file{limity.h} if the system also has its own version of +@code{}. (GCC provides its own header because it is +required of ISO C freestanding implementations, but needs to include +the system header from its own header as well because other standards +such as POSIX specify additional values to be defined in +@code{}.) The system's @code{} header is used via +@file{@var{libsubdir}/include/syslimits.h}, which is copied from +@file{gsyslimits.h} if it does not need fixing to work with GCC; if it +needs fixing, @file{syslimits.h} is the fixed copy. + +GCC can also install @code{}. It will do this when +@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}. + +@node Documentation +@subsection Building Documentation + +The main GCC documentation is in the form of manuals in Texinfo +format. These are installed in Info format; DVI versions may be +generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and +HTML versions by @samp{make html}. In addition, some man pages are +generated from the Texinfo manuals, there are some other text files +with miscellaneous documentation, and runtime libraries have their own +documentation outside the @file{gcc} directory. FIXME: document the +documentation for runtime libraries somewhere. + +@menu +* Texinfo Manuals:: GCC manuals in Texinfo format. +* Man Page Generation:: Generating man pages from Texinfo manuals. +* Miscellaneous Docs:: Miscellaneous text files with documentation. +@end menu + +@node Texinfo Manuals +@subsubsection Texinfo Manuals + +The manuals for GCC as a whole, and the C and C++ front ends, are in +files @file{doc/*.texi}. Other front ends have their own manuals in +files @file{@var{language}/*.texi}. Common files +@file{doc/include/*.texi} are provided which may be included in +multiple manuals; the following files are in @file{doc/include}: + +@table @file +@item fdl.texi +The GNU Free Documentation License. +@item funding.texi +The section ``Funding Free Software''. +@item gcc-common.texi +Common definitions for manuals. +@item gpl.texi +@itemx gpl_v3.texi +The GNU General Public License. +@item texinfo.tex +A copy of @file{texinfo.tex} known to work with the GCC manuals. +@end table + +DVI-formatted manuals are generated by @samp{make dvi}, which uses +@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). +PDF-formatted manuals are generated by @samp{make pdf}, which uses +@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML +formatted manuals are generated by @samp{make html}. Info +manuals are generated by @samp{make info} (which is run as part of +a bootstrap); this generates the manuals in the source directory, +using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, +and they are included in release distributions. + +Manuals are also provided on the GCC web site, in both HTML and +PostScript forms. This is done via the script +@file{maintainer-scripts/update_web_docs_svn}. Each manual to be +provided online must be listed in the definition of @code{MANUALS} in +that file; a file @file{@var{name}.texi} must only appear once in the +source tree, and the output manual must have the same name as the +source file. (However, other Texinfo files, included in manuals but +not themselves the root files of manuals, may have names that appear +more than once in the source tree.) The manual file +@file{@var{name}.texi} should only include other files in its own +directory or in @file{doc/include}. HTML manuals will be generated by +@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} +and @command{dvips}, and PDF manuals by @command{texi2pdf}. +All Texinfo files that are parts of manuals must +be version-controlled, even if they are generated files, for the +generation of online manuals to work. + +The installation manual, @file{doc/install.texi}, is also provided on +the GCC web site. The HTML version is generated by the script +@file{doc/install.texi2html}. + +@node Man Page Generation +@subsubsection Man Page Generation + +Because of user demand, in addition to full Texinfo manuals, man pages +are provided which contain extracts from those manuals. These man +pages are generated from the Texinfo manuals using +@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for +@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference +to @file{gcc.1}, but all the other man pages are generated from +Texinfo manuals.) + +Because many systems may not have the necessary tools installed to +generate the man pages, they are only generated if the +@file{configure} script detects that recent enough tools are +installed, and the Makefiles allow generating man pages to fail +without aborting the build. Man pages are also included in release +distributions. They are generated in the source directory. + +Magic comments in Texinfo files starting @samp{@@c man} control what +parts of a Texinfo file go into a man page. Only a subset of Texinfo +is supported by @file{texi2pod.pl}, and it may be necessary to add +support for more Texinfo features to this script when generating new +man pages. To improve the man page output, some special Texinfo +macros are provided in @file{doc/include/gcc-common.texi} which +@file{texi2pod.pl} understands: + +@table @code +@item @@gcctabopt +Use in the form @samp{@@table @@gcctabopt} for tables of options, +where for printed output the effect of @samp{@@code} is better than +that of @samp{@@option} but for man page output a different effect is +wanted. +@item @@gccoptlist +Use for summary lists of options in manuals. +@item @@gol +Use at the end of each line inside @samp{@@gccoptlist}. This is +necessary to avoid problems with differences in how the +@samp{@@gccoptlist} macro is handled by different Texinfo formatters. +@end table + +FIXME: describe the @file{texi2pod.pl} input language and magic +comments in more detail. + +@node Miscellaneous Docs +@subsubsection Miscellaneous Documentation + +In addition to the formal documentation that is installed by GCC, +there are several other text files in the @file{gcc} subdirectory +with miscellaneous documentation: + +@table @file +@item ABOUT-GCC-NLS +Notes on GCC's Native Language Support. FIXME: this should be part of +this manual rather than a separate file. +@item ABOUT-NLS +Notes on the Free Translation Project. +@item COPYING +@itemx COPYING3 +The GNU General Public License, Versions 2 and 3. +@item COPYING.LIB +@itemx COPYING3.LIB +The GNU Lesser General Public License, Versions 2.1 and 3. +@item *ChangeLog* +@itemx */ChangeLog* +Change log files for various parts of GCC@. +@item LANGUAGES +Details of a few changes to the GCC front-end interface. FIXME: the +information in this file should be part of general documentation of +the front-end interface in this manual. +@item ONEWS +Information about new features in old versions of GCC@. (For recent +versions, the information is on the GCC web site.) +@item README.Portability +Information about portability issues when writing code in GCC@. FIXME: +why isn't this part of this manual or of the GCC Coding Conventions? +@end table + +FIXME: document such files in subdirectories, at least @file{config}, +@file{cp}, @file{objc}, @file{testsuite}. + +@node Front End +@subsection Anatomy of a Language Front End + +A front end for a language in GCC has the following parts: + +@itemize @bullet +@item +A directory @file{@var{language}} under @file{gcc} containing source +files for that front end. @xref{Front End Directory, , The Front End +@file{@var{language}} Directory}, for details. +@item +A mention of the language in the list of supported languages in +@file{gcc/doc/install.texi}. +@item +A mention of the name under which the language's runtime library is +recognized by @option{--enable-shared=@var{package}} in the +documentation of that option in @file{gcc/doc/install.texi}. +@item +A mention of any special prerequisites for building the front end in +the documentation of prerequisites in @file{gcc/doc/install.texi}. +@item +Details of contributors to that front end in +@file{gcc/doc/contrib.texi}. If the details are in that front end's +own manual then there should be a link to that manual's list in +@file{contrib.texi}. +@item +Information about support for that language in +@file{gcc/doc/frontends.texi}. +@item +Information about standards for that language, and the front end's +support for them, in @file{gcc/doc/standards.texi}. This may be a +link to such information in the front end's own manual. +@item +Details of source file suffixes for that language and @option{-x +@var{lang}} options supported, in @file{gcc/doc/invoke.texi}. +@item +Entries in @code{default_compilers} in @file{gcc.c} for source file +suffixes for that language. +@item +Preferably testsuites, which may be under @file{gcc/testsuite} or +runtime library directories. FIXME: document somewhere how to write +testsuite harnesses. +@item +Probably a runtime library for the language, outside the @file{gcc} +directory. FIXME: document this further. +@item +Details of the directories of any runtime libraries in +@file{gcc/doc/sourcebuild.texi}. +@item +Check targets in @file{Makefile.def} for the top-level @file{Makefile} +to check just the compiler or the compiler and runtime library for the +language. +@end itemize + +If the front end is added to the official GCC source repository, the +following are also necessary: + +@itemize @bullet +@item +At least one Bugzilla component for bugs in that front end and runtime +libraries. This category needs to be added to the Bugzilla database. +@item +Normally, one or more maintainers of that front end listed in +@file{MAINTAINERS}. +@item +Mentions on the GCC web site in @file{index.html} and +@file{frontends.html}, with any relevant links on +@file{readings.html}. (Front ends that are not an official part of +GCC may also be listed on @file{frontends.html}, with relevant links.) +@item +A news item on @file{index.html}, and possibly an announcement on the +@email{gcc-announce@@gcc.gnu.org} mailing list. +@item +The front end's manuals should be mentioned in +@file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals}) +and the online manuals should be linked to from +@file{onlinedocs/index.html}. +@item +Any old releases or CVS repositories of the front end, before its +inclusion in GCC, should be made available on the GCC FTP site +@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. +@item +The release and snapshot script @file{maintainer-scripts/gcc_release} +should be updated to generate appropriate tarballs for this front end. +@item +If this front end includes its own version files that include the +current date, @file{maintainer-scripts/update_version} should be +updated accordingly. +@end itemize + +@menu +* Front End Directory:: The front end @file{@var{language}} directory. +* Front End Config:: The front end @file{config-lang.in} file. +* Front End Makefile:: The front end @file{Make-lang.in} file. +@end menu + +@node Front End Directory +@subsubsection The Front End @file{@var{language}} Directory + +A front end @file{@var{language}} directory contains the source files +of that front end (but not of any runtime libraries, which should be +outside the @file{gcc} directory). This includes documentation, and +possibly some subsidiary programs built alongside the front end. +Certain files are special and other parts of the compiler depend on +their names: + +@table @file +@item config-lang.in +This file is required in all language subdirectories. @xref{Front End +Config, , The Front End @file{config-lang.in} File}, for details of +its contents +@item Make-lang.in +This file is required in all language subdirectories. @xref{Front End +Makefile, , The Front End @file{Make-lang.in} File}, for details of its +contents. +@item lang.opt +This file registers the set of switches that the front end accepts on +the command line, and their @option{--help} text. @xref{Options}. +@item lang-specs.h +This file provides entries for @code{default_compilers} in +@file{gcc.c} which override the default of giving an error that a +compiler for that language is not installed. +@item @var{language}-tree.def +This file, which need not exist, defines any language-specific tree +codes. +@end table + +@node Front End Config +@subsubsection The Front End @file{config-lang.in} File + +Each language subdirectory contains a @file{config-lang.in} file. In +addition the main directory contains @file{c-config-lang.in}, which +contains limited information for the C language. This file is a shell +script that may define some variables describing the language: + +@table @code +@item language +This definition must be present, and gives the name of the language +for some purposes such as arguments to @option{--enable-languages}. +@item lang_requires +If defined, this variable lists (space-separated) language front ends +other than C that this front end requires to be enabled (with the +names given being their @code{language} settings). For example, the +Java front end depends on the C++ front end, so sets +@samp{lang_requires=c++}. +@item subdir_requires +If defined, this variable lists (space-separated) front end directories +other than C that this front end requires to be present. For example, +the Objective-C++ front end uses source files from the C++ and +Objective-C front ends, so sets @samp{subdir_requires="cp objc"}. +@item target_libs +If defined, this variable lists (space-separated) targets in the top +level @file{Makefile} to build the runtime libraries for this +language, such as @code{target-libobjc}. +@item lang_dirs +If defined, this variable lists (space-separated) top level +directories (parallel to @file{gcc}), apart from the runtime libraries, +that should not be configured if this front end is not built. +@item build_by_default +If defined to @samp{no}, this language front end is not built unless +enabled in a @option{--enable-languages} argument. Otherwise, front +ends are built by default, subject to any special logic in +@file{configure.ac} (as is present to disable the Ada front end if the +Ada compiler is not already installed). +@item boot_language +If defined to @samp{yes}, this front end is built in stage1 of the +bootstrap. This is only relevant to front ends written in their own +languages. +@item compilers +If defined, a space-separated list of compiler executables that will +be run by the driver. The names here will each end +with @samp{\$(exeext)}. +@item outputs +If defined, a space-separated list of files that should be generated +by @file{configure} substituting values in them. This mechanism can +be used to create a file @file{@var{language}/Makefile} from +@file{@var{language}/Makefile.in}, but this is deprecated, building +everything from the single @file{gcc/Makefile} is preferred. +@item gtfiles +If defined, a space-separated list of files that should be scanned by +@file{gengtype.c} to generate the garbage collection tables and routines for +this language. This excludes the files that are common to all front +ends. @xref{Type Information}. + +@end table + +@node Front End Makefile +@subsubsection The Front End @file{Make-lang.in} File + +Each language subdirectory contains a @file{Make-lang.in} file. It contains +targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the +setting of @code{language} in @file{config-lang.in}) for the following +values of @code{@var{hook}}, and any other Makefile rules required to +build those targets (which may if necessary use other Makefiles +specified in @code{outputs} in @file{config-lang.in}, although this is +deprecated). It also adds any testsuite targets that can use the +standard rule in @file{gcc/Makefile.in} to the variable +@code{lang_checks}. + +@table @code +@itemx all.cross +@itemx start.encap +@itemx rest.encap +FIXME: exactly what goes in each of these targets? +@item tags +Build an @command{etags} @file{TAGS} file in the language subdirectory +in the source tree. +@item info +Build info documentation for the front end, in the build directory. +This target is only called by @samp{make bootstrap} if a suitable +version of @command{makeinfo} is available, so does not need to check +for this, and should fail if an error occurs. +@item dvi +Build DVI documentation for the front end, in the build directory. +This should be done using @code{$(TEXI2DVI)}, with appropriate +@option{-I} arguments pointing to directories of included files. +@item pdf +Build PDF documentation for the front end, in the build directory. +This should be done using @code{$(TEXI2PDF)}, with appropriate +@option{-I} arguments pointing to directories of included files. +@item html +Build HTML documentation for the front end, in the build directory. +@item man +Build generated man pages for the front end from Texinfo manuals +(@pxref{Man Page Generation}), in the build directory. This target +is only called if the necessary tools are available, but should ignore +errors so as not to stop the build if errors occur; man pages are +optional and the tools involved may be installed in a broken way. +@item install-common +Install everything that is part of the front end, apart from the +compiler executables listed in @code{compilers} in +@file{config-lang.in}. +@item install-info +Install info documentation for the front end, if it is present in the +source directory. This target should have dependencies on info files +that should be installed. +@item install-man +Install man pages for the front end. This target should ignore +errors. +@item install-plugin +Install headers needed for plugins. +@item srcextra +Copies its dependencies into the source directory. This generally should +be used for generated files such as Bison output files which are not +version-controlled, but should be included in any release tarballs. This +target will be executed during a bootstrap if +@samp{--enable-generated-files-in-srcdir} was specified as a +@file{configure} option. +@item srcinfo +@itemx srcman +Copies its dependencies into the source directory. These targets will be +executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} +was specified as a @file{configure} option. +@item uninstall +Uninstall files installed by installing the compiler. This is +currently documented not to be supported, so the hook need not do +anything. +@item mostlyclean +@itemx clean +@itemx distclean +@itemx maintainer-clean +The language parts of the standard GNU +@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for +Users, standards, GNU Coding Standards}, for details of the standard +targets. For GCC, @code{maintainer-clean} should delete +all generated files in the source directory that are not version-controlled, +but should not delete anything that is. +@end table + +@file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS} +to a list of host object files that are used by that language. + +@node Back End +@subsection Anatomy of a Target Back End + +A back end for a target architecture in GCC has the following parts: + +@itemize @bullet +@item +A directory @file{@var{machine}} under @file{gcc/config}, containing a +machine description @file{@var{machine}.md} file (@pxref{Machine Desc, +, Machine Descriptions}), header files @file{@var{machine}.h} and +@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} +(@pxref{Target Macros, , Target Description Macros and Functions}), +possibly a target Makefile fragment @file{t-@var{machine}} +(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe +some other files. The names of these files may be changed from the +defaults given by explicit specifications in @file{config.gcc}. +@item +If necessary, a file @file{@var{machine}-modes.def} in the +@file{@var{machine}} directory, containing additional machine modes to +represent condition codes. @xref{Condition Code}, for further details. +@item +An optional @file{@var{machine}.opt} file in the @file{@var{machine}} +directory, containing a list of target-specific options. You can also +add other option files using the @code{extra_options} variable in +@file{config.gcc}. @xref{Options}. +@item +Entries in @file{config.gcc} (@pxref{System Config, , The +@file{config.gcc} File}) for the systems with this target +architecture. +@item +Documentation in @file{gcc/doc/invoke.texi} for any command-line +options supported by this target (@pxref{Run-time Target, , Run-time +Target Specification}). This means both entries in the summary table +of options and details of the individual options. +@item +Documentation in @file{gcc/doc/extend.texi} for any target-specific +attributes supported (@pxref{Target Attributes, , Defining +target-specific uses of @code{__attribute__}}), including where the +same attribute is already supported on some targets, which are +enumerated in the manual. +@item +Documentation in @file{gcc/doc/extend.texi} for any target-specific +pragmas supported. +@item +Documentation in @file{gcc/doc/extend.texi} of any target-specific +built-in functions supported. +@item +Documentation in @file{gcc/doc/extend.texi} of any target-specific +format checking styles supported. +@item +Documentation in @file{gcc/doc/md.texi} of any target-specific +constraint letters (@pxref{Machine Constraints, , Constraints for +Particular Machines}). +@item +A note in @file{gcc/doc/contrib.texi} under the person or people who +contributed the target support. +@item +Entries in @file{gcc/doc/install.texi} for all target triplets +supported with this target architecture, giving details of any special +notes about installation for this target, or saying that there are no +special notes if there are none. +@item +Possibly other support outside the @file{gcc} directory for runtime +libraries. FIXME: reference docs for this. The @code{libstdc++} porting +manual needs to be installed as info for this to work, or to be a +chapter of this manual. +@end itemize + +If the back end is added to the official GCC source repository, the +following are also necessary: + +@itemize @bullet +@item +An entry for the target architecture in @file{readings.html} on the +GCC web site, with any relevant links. +@item +Details of the properties of the back end and target architecture in +@file{backends.html} on the GCC web site. +@item +A news item about the contribution of support for that target +architecture, in @file{index.html} on the GCC web site. +@item +Normally, one or more maintainers of that target listed in +@file{MAINTAINERS}. Some existing architectures may be unmaintained, +but it would be unusual to add support for a target that does not have +a maintainer when support is added. +@end itemize + +@node Testsuites +@chapter Testsuites + +GCC contains several testsuites to help maintain compiler quality. +Most of the runtime libraries and language front ends in GCC have +testsuites. Currently only the C language testsuites are documented +here; FIXME: document the others. + +@menu +* Test Idioms:: Idioms used in testsuite code. +* Test Directives:: Directives used within DejaGnu tests. +* Ada Tests:: The Ada language testsuites. +* C Tests:: The C language testsuites. +* libgcj Tests:: The Java library testsuites. +* LTO Testing:: Support for testing link-time optimizations. +* gcov Testing:: Support for testing gcov. +* profopt Testing:: Support for testing profile-directed optimizations. +* compat Testing:: Support for testing binary compatibility. +* Torture Tests:: Support for torture testing using multiple options. +@end menu + +@node Test Idioms +@section Idioms Used in Testsuite Code + +In general, C testcases have a trailing @file{-@var{n}.c}, starting +with @file{-1.c}, in case other testcases with similar names are added +later. If the test is a test of some well-defined feature, it should +have a name referring to that feature such as +@file{@var{feature}-1.c}. If it does not test a well-defined feature +but just happens to exercise a bug somewhere in the compiler, and a +bug report has been filed for this bug in the GCC bug database, +@file{pr@var{bug-number}-1.c} is the appropriate form of name. +Otherwise (for miscellaneous bugs not filed in the GCC bug database), +and previously more generally, test cases are named after the date on +which they were added. This allows people to tell at a glance whether +a test failure is because of a recently found bug that has not yet +been fixed, or whether it may be a regression, but does not give any +other information about the bug or where discussion of it may be +found. Some other language testsuites follow similar conventions. + +In the @file{gcc.dg} testsuite, it is often necessary to test that an +error is indeed a hard error and not just a warning---for example, +where it is a constraint violation in the C standard, which must +become an error with @option{-pedantic-errors}. The following idiom, +where the first line shown is line @var{line} of the file and the line +that generates the error, is used for this: + +@smallexample +/* @{ dg-bogus "warning" "warning in place of error" @} */ +/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ +@end smallexample + +It may be necessary to check that an expression is an integer constant +expression and has a certain value. To check that @code{@var{E}} has +value @code{@var{V}}, an idiom similar to the following is used: + +@smallexample +char x[((E) == (V) ? 1 : -1)]; +@end smallexample + +In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make +assertions about the types of expressions. See, for example, +@file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the +exact rules for the types of conditional expressions in the C +standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. + +It is useful to be able to test that optimizations are being made +properly. This cannot be done in all cases, but it can be done where +the optimization will lead to code being optimized away (for example, +where flow analysis or alias analysis should show that certain code +cannot be called) or to functions not being called because they have +been expanded as built-in functions. Such tests go in +@file{gcc.c-torture/execute}. Where code should be optimized away, a +call to a nonexistent function such as @code{link_failure ()} may be +inserted; a definition + +@smallexample +#ifndef __OPTIMIZE__ +void +link_failure (void) +@{ + abort (); +@} +#endif +@end smallexample + +@noindent +will also be needed so that linking still succeeds when the test is +run without optimization. When all calls to a built-in function +should have been optimized and no calls to the non-built-in version of +the function should remain, that function may be defined as +@code{static} to call @code{abort ()} (although redeclaring a function +as static may not work on all targets). + +All testcases must be portable. Target-specific testcases must have +appropriate code to avoid causing failures on unsupported systems; +unfortunately, the mechanisms for this differ by directory. + +FIXME: discuss non-C testsuites here. + +@node Test Directives +@section Directives used within DejaGnu tests + +@menu +* Directives:: Syntax and descriptions of test directives. +* Selectors:: Selecting targets to which a test applies. +* Effective-Target Keywords:: Keywords describing target attributes. +* Add Options:: Features for @code{dg-add-options} +* Require Support:: Variants of @code{dg-require-@var{support}} +* Final Actions:: Commands for use in @code{dg-final} +@end menu + +@node Directives +@subsection Syntax and Descriptions of test directives + +Test directives appear within comments in a test source file and begin +with @code{dg-}. Some of these are defined within DejaGnu and others +are local to the GCC testsuite. + +The order in which test directives appear in a test can be important: +directives local to GCC sometimes override information used by the +DejaGnu directives, which know nothing about the GCC directives, so the +DejaGnu directives must precede GCC directives. + +Several test directives include selectors (@pxref{Selectors, , }) +which are usually preceded by the keyword @code{target} or @code{xfail}. + +@subsubsection Specify how to build the test + +@table @code +@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} +@var{do-what-keyword} specifies how the test is compiled and whether +it is executed. It is one of: + +@table @code +@item preprocess +Compile with @option{-E} to run only the preprocessor. +@item compile +Compile with @option{-S} to produce an assembly code file. +@item assemble +Compile with @option{-c} to produce a relocatable object file. +@item link +Compile, assemble, and link to produce an executable file. +@item run +Produce and run an executable file, which is expected to return +an exit code of 0. +@end table + +The default is @code{compile}. That can be overridden for a set of +tests by redefining @code{dg-do-what-default} within the @code{.exp} +file for those tests. + +If the directive includes the optional @samp{@{ target @var{selector} @}} +then the test is skipped unless the target system matches the +@var{selector}. + +If @var{do-what-keyword} is @code{run} and the directive includes +the optional @samp{@{ xfail @var{selector} @}} and the selector is met +then the test is expected to fail. The @code{xfail} clause is ignored +for other values of @var{do-what-keyword}; those tests can use +directive @code{dg-xfail-if}. +@end table + +@subsubsection Specify additional compiler options + +@table @code +@item @{ dg-options @var{options} [@{ target @var{selector} @}] @} +This DejaGnu directive provides a list of compiler options, to be used +if the target system matches @var{selector}, that replace the default +options used for this set of tests. + +@item @{ dg-add-options @var{feature} @dots{} @} +Add any compiler options that are needed to access certain features. +This directive does nothing on targets that enable the features by +default, or that don't provide them at all. It must come after +all @code{dg-options} directives. +For supported values of @var{feature} see @ref{Add Options, ,}. +@end table + +@subsubsection Modify the test timeout value + +The normal timeout limit, in seconds, is found by searching the +following in order: + +@itemize @bullet +@item the value defined by an earlier @code{dg-timeout} directive in +the test + +@item variable @var{tool_timeout} defined by the set of tests + +@item @var{gcc},@var{timeout} set in the target board + +@item 300 +@end itemize + +@table @code +@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @} +Set the time limit for the compilation and for the execution of the test +to the specified number of seconds. + +@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @} +Multiply the normal time limit for compilation and execution of the test +by the specified floating-point factor. +@end table + +@subsubsection Skip a test for some targets + +@table @code +@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} +Arguments @var{include-opts} and @var{exclude-opts} are lists in which +each element is a string of zero or more GCC options. +Skip the test if all of the following conditions are met: +@itemize @bullet +@item the test system is included in @var{selector} + +@item for at least one of the option strings in @var{include-opts}, +every option from that string is in the set of options with which +the test would be compiled; use @samp{"*"} for an @var{include-opts} list +that matches any options; that is the default if @var{include-opts} is +not specified + +@item for each of the option strings in @var{exclude-opts}, at least one +option from that string is not in the set of options with which the test +would be compiled; use @samp{""} for an empty @var{exclude-opts} list; +that is the default if @var{exclude-opts} is not specified +@end itemize + +For example, to skip a test if option @code{-Os} is present: + +@smallexample +/* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */ +@end smallexample + +To skip a test if both options @code{-O2} and @code{-g} are present: + +@smallexample +/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */ +@end smallexample + +To skip a test if either @code{-O2} or @code{-O3} is present: + +@smallexample +/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */ +@end smallexample + +To skip a test unless option @code{-Os} is present: + +@smallexample +/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */ +@end smallexample + +To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g} +but not if @code{-fpic} is also present: + +@smallexample +/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */ +@end smallexample + +@item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @} +Skip the test if the test target, including current multilib flags, +is not covered by the effective-target keyword. +If the directive includes the optional @samp{@{ @var{selector} @}} +then the effective-target test is only performed if the target system +matches the @var{selector}. +This directive must appear after any @code{dg-do} directive in the test +and before any @code{dg-additional-sources} directive. +@xref{Effective-Target Keywords, , }. + +@item @{ dg-require-@var{support} args @} +Skip the test if the target does not provide the required support. +These directives must appear after any @code{dg-do} directive in the test +and before any @code{dg-additional-sources} directive. +They require at least one argument, which can be an empty string if the +specific procedure does not examine the argument. +@xref{Require Support, , }, for a complete list of these directives. +@end table + +@subsubsection Expect a test to fail for some targets + +@table @code +@item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} +Expect the test to fail if the conditions (which are the same as for +@code{dg-skip-if}) are met. This does not affect the execute step. + +@item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} +Expect the execute step of a test to fail if the conditions (which are +the same as for @code{dg-skip-if}) are met. +@end table + +@subsubsection Expect the test executable to fail + +@table @code +@item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} +Expect the test executable to return a nonzero exit status if the +conditions (which are the same as for @code{dg-skip-if}) are met. +@end table + +@subsubsection Verify compiler messages + +@table @code +@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} +This DejaGnu directive appears on a source line that is expected to get +an error message, or else specifies the source line associated with the +message. If there is no message for that line or if the text of that +message is not matched by @var{regexp} then the check fails and +@var{comment} is included in the @code{FAIL} message. The check does +not look for the string @samp{error} unless it is part of @var{regexp}. + +@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} +This DejaGnu directive appears on a source line that is expected to get +a warning message, or else specifies the source line associated with the +message. If there is no message for that line or if the text of that +message is not matched by @var{regexp} then the check fails and +@var{comment} is included in the @code{FAIL} message. The check does +not look for the string @samp{warning} unless it is part of @var{regexp}. + +@item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} +The line is expected to get a message other than an error or warning. +If there is no message for that line or if the text of that message is +not matched by @var{regexp} then the check fails and @var{comment} is +included in the @code{FAIL} message. + +@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @} +This DejaGnu directive appears on a source line that should not get a +message matching @var{regexp}, or else specifies the source line +associated with the bogus message. It is usually used with @samp{xfail} +to indicate that the message is a known problem for a particular set of +targets. + +@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} +This DejaGnu directive indicates that the test is expected to fail due +to compiler messages that are not handled by @samp{dg-error}, +@samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail} +has the same effect as @samp{target}. + +@item @{ dg-prune-output @var{regexp} @} +Prune messages matching @var{regexp} from the test output. +@end table + +@subsubsection Verify output of the test executable + +@table @code +@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} +This DejaGnu directive compares @var{regexp} to the combined output +that the test executable writes to @file{stdout} and @file{stderr}. +@end table + +@subsubsection Specify additional files for a test + +@table @code +@item @{ dg-additional-files "@var{filelist}" @} +Specify additional files, other than source files, that must be copied +to the system where the compiler runs. + +@item @{ dg-additional-sources "@var{filelist}" @} +Specify additional source files to appear in the compile line +following the main test file. +@end table + +@subsubsection Add checks at the end of a test + +@table @code +@item @{ dg-final @{ @var{local-directive} @} @} +This DejaGnu directive is placed within a comment anywhere in the +source file and is processed after the test has been compiled and run. +Multiple @samp{dg-final} commands are processed in the order in which +they appear in the source file. @xref{Final Actions, , }, for a list +of directives that can be used within @code{dg-final}. +@end table + +@node Selectors +@subsection Selecting targets to which a test applies + +Several test directives include @var{selector}s to limit the targets +for which a test is run or to declare that a test is expected to fail +on particular targets. + +A selector is: +@itemize @bullet +@item one or more target triplets, possibly including wildcard characters +@item a single effective-target keyword (@pxref{Effective-Target Keywords}) +@item a logical expression +@end itemize + +Depending on the +context, the selector specifies whether a test is skipped and reported +as unsupported or is expected to fail. Use @samp{*-*-*} to match any +target. + +A selector expression appears within curly braces and uses a single +logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An +operand is another selector expression, an effective-target keyword, +a single target triplet, or a list of target triplets within quotes or +curly braces. For example: + +@smallexample +@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} +@{ target @{ powerpc*-*-* && lp64 @} @} +@{ xfail @{ lp64 || vect_no_align @} @} +@end smallexample + +@node Effective-Target Keywords +@subsection Keywords describing target attributes + +Effective-target keywords identify sets of targets that support +particular functionality. They are used to limit tests to be run only +for particular targets, or to specify that particular sets of targets +are expected to fail some tests. + +Effective-target keywords are defined in @file{lib/target-supports.exp} in +the GCC testsuite, with the exception of those that are documented as +being local to a particular test directory. + +The @samp{effective target} takes into account all of the compiler options +with which the test will be compiled, including the multilib options. +By convention, keywords ending in @code{_nocache} can also include options +specified for the particular test in an earlier @code{dg-options} or +@code{dg-add-options} directive. + +@subsubsection Data type sizes + +@table @code +@item ilp32 +Target has 32-bit @code{int}, @code{long}, and pointers. + +@item lp64 +Target has 32-bit @code{int}, 64-bit @code{long} and pointers. + +@item llp64 +Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long} +and pointers. + +@item double64 +Target has 64-bit @code{double}. + +@item double64plus +Target has @code{double} that is 64 bits or longer. + +@item int32plus +Target has @code{int} that is at 32 bits or longer. + +@item int16 +Target has @code{int} that is 16 bits or shorter. + +@item large_double +Target supports @code{double} that is longer than @code{float}. + +@item large_long_double +Target supports @code{long double} that is longer than @code{double}. + +@item ptr32plus +Target has pointers that are 32 bits or longer. + +@item size32plus +Target supports array and structure sizes that are 32 bits or longer. + +@item 4byte_wchar_t +Target has @code{wchar_t} that is at least 4 bytes. +@end table + +@subsubsection Fortran-specific attributes + +@table @code +@item fortran_integer_16 +Target supports Fortran @code{integer} that is 16 bytes or longer. + +@item fortran_large_int +Target supports Fortran @code{integer} kinds larger than @code{integer(8)}. + +@item fortran_large_real +Target supports Fortran @code{real} kinds larger than @code{real(8)}. +@end table + +@subsubsection Vector-specific attributes + +@table @code +@item vect_condition +Target supports vector conditional operations. + +@item vect_double +Target supports hardware vectors of @code{double}. + +@item vect_float +Target supports hardware vectors of @code{float}. + +@item vect_int +Target supports hardware vectors of @code{int}. + +@item vect_long +Target supports hardware vectors of @code{long}. + +@item vect_long_long +Target supports hardware vectors of @code{long long}. + +@item vect_aligned_arrays +Target aligns arrays to vector alignment boundary. + +@item vect_hw_misalign +Target supports a vector misalign access. + +@item vect_no_align +Target does not support a vector alignment mechanism. + +@item vect_no_int_max +Target does not support a vector max instruction on @code{int}. + +@item vect_no_int_add +Target does not support a vector add instruction on @code{int}. + +@item vect_no_bitwise +Target does not support vector bitwise instructions. + +@item vect_char_mult +Target supports @code{vector char} multiplication. + +@item vect_short_mult +Target supports @code{vector short} multiplication. + +@item vect_int_mult +Target supports @code{vector int} multiplication. + +@item vect_extract_even_odd +Target supports vector even/odd element extraction. + +@item vect_extract_even_odd_wide +Target supports vector even/odd element extraction of vectors with elements +@code{SImode} or larger. + +@item vect_interleave +Target supports vector interleaving. + +@item vect_strided +Target supports vector interleaving and extract even/odd. + +@item vect_strided_wide +Target supports vector interleaving and extract even/odd for wide +element types. + +@item vect_perm +Target supports vector permutation. + +@item vect_shift +Target supports a hardware vector shift operation. + +@item vect_widen_sum_hi_to_si +Target supports a vector widening summation of @code{short} operands +into @code{int} results, or can promote (unpack) from @code{short} +to @code{int}. + +@item vect_widen_sum_qi_to_hi +Target supports a vector widening summation of @code{char} operands +into @code{short} results, or can promote (unpack) from @code{char} +to @code{short}. + +@item vect_widen_sum_qi_to_si +Target supports a vector widening summation of @code{char} operands +into @code{int} results. + +@item vect_widen_mult_qi_to_hi +Target supports a vector widening multiplication of @code{char} operands +into @code{short} results, or can promote (unpack) from @code{char} to +@code{short} and perform non-widening multiplication of @code{short}. + +@item vect_widen_mult_hi_to_si +Target supports a vector widening multiplication of @code{short} operands +into @code{int} results, or can promote (unpack) from @code{short} to +@code{int} and perform non-widening multiplication of @code{int}. + +@item vect_sdot_qi +Target supports a vector dot-product of @code{signed char}. + +@item vect_udot_qi +Target supports a vector dot-product of @code{unsigned char}. + +@item vect_sdot_hi +Target supports a vector dot-product of @code{signed short}. + +@item vect_udot_hi +Target supports a vector dot-product of @code{unsigned short}. + +@item vect_pack_trunc +Target supports a vector demotion (packing) of @code{short} to @code{char} +and from @code{int} to @code{short} using modulo arithmetic. + +@item vect_unpack +Target supports a vector promotion (unpacking) of @code{char} to @code{short} +and from @code{char} to @code{int}. + +@item vect_intfloat_cvt +Target supports conversion from @code{signed int} to @code{float}. + +@item vect_uintfloat_cvt +Target supports conversion from @code{unsigned int} to @code{float}. + +@item vect_floatint_cvt +Target supports conversion from @code{float} to @code{signed int}. + +@item vect_floatuint_cvt +Target supports conversion from @code{float} to @code{unsigned int}. +@end table + +@subsubsection Thread Local Storage attributes + +@table @code +@item tls +Target supports thread-local storage. + +@item tls_native +Target supports native (rather than emulated) thread-local storage. + +@item tls_runtime +Test system supports executing TLS executables. +@end table + +@subsubsection Decimal floating point attributes + +@table @code +@item dfp +Targets supports compiling decimal floating point extension to C. + +@item dfp_nocache +Including the options used to compile this particular test, the +target supports compiling decimal floating point extension to C. + +@item dfprt +Test system can execute decimal floating point tests. + +@item dfprt_nocache +Including the options used to compile this particular test, the +test system can execute decimal floating point tests. + +@item hard_dfp +Target generates decimal floating point instructions with current options. +@end table + +@subsubsection ARM-specific attributes + +@table @code +@item arm32 +ARM target generates 32-bit code. + +@item arm_eabi +ARM target adheres to the ABI for the ARM Architecture. + +@item arm_hard_vfp_ok +ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. +Some multilibs may be incompatible with these options. + +@item arm_iwmmxt_ok +ARM target supports @code{-mcpu=iwmmxt}. +Some multilibs may be incompatible with this option. + +@item arm_neon +ARM target supports generating NEON instructions. + +@item arm_neon_hw +Test system supports executing NEON instructions. + +@item arm_neon_ok +@anchor{arm_neon_ok} +ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible +options. Some multilibs may be incompatible with these options. + +@item arm_neon_fp16_ok +@anchor{arm_neon_fp16_ok} +ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible +options. Some multilibs may be incompatible with these options. + +@item arm_thumb1_ok +ARM target generates Thumb-1 code for @code{-mthumb}. + +@item arm_thumb2_ok +ARM target generates Thumb-2 code for @code{-mthumb}. + +@item arm_vfp_ok +ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. +Some multilibs may be incompatible with these options. +@end table + +@subsubsection MIPS-specific attributes + +@table @code +@item mips64 +MIPS target supports 64-bit instructions. + +@item nomips16 +MIPS target does not produce MIPS16 code. + +@item mips16_attribute +MIPS target can generate MIPS16 code. + +@item mips_loongson +MIPS target is a Loongson-2E or -2F target using an ABI that supports +the Loongson vector modes. + +@item mips_newabi_large_long_double +MIPS target supports @code{long double} larger than @code{double} +when using the new ABI. + +@item mpaired_single +MIPS target supports @code{-mpaired-single}. +@end table + +@subsubsection PowerPC-specific attributes + +@table @code +@item powerpc64 +Test system supports executing 64-bit instructions. + +@item powerpc_altivec +PowerPC target supports AltiVec. + +@item powerpc_altivec_ok +PowerPC target supports @code{-maltivec}. + +@item powerpc_fprs +PowerPC target supports floating-point registers. + +@item powerpc_hard_double +PowerPC target supports hardware double-precision floating-point. + +@item powerpc_ppu_ok +PowerPC target supports @code{-mcpu=cell}. + +@item powerpc_spe +PowerPC target supports PowerPC SPE. + +@item powerpc_spe_nocache +Including the options used to compile this particular test, the +PowerPC target supports PowerPC SPE. + +@item powerpc_spu +PowerPC target supports PowerPC SPU. + +@item spu_auto_overlay +SPU target has toolchain that supports automatic overlay generation. + +@item powerpc_vsx_ok +PowerPC target supports @code{-mvsx}. + +@item powerpc_405_nocache +Including the options used to compile this particular test, the +PowerPC target supports PowerPC 405. + +@item vmx_hw +PowerPC target supports executing AltiVec instructions. +@end table + +@subsubsection Other hardware attributes + +@table @code +@item avx +Target supports compiling @code{avx} instructions. + +@item avx_runtime +Target supports the execution of @code{avx} instructions. + +@item cell_hw +Test system can execute AltiVec and Cell PPU instructions. + +@item coldfire_fpu +Target uses a ColdFire FPU. + +@item hard_float +Target supports FPU instructions. + +@item sse +Target supports compiling @code{sse} instructions. + +@item sse_runtime +Target supports the execution of @code{sse} instructions. + +@item sse2 +Target supports compiling @code{sse2} instructions. + +@item sse2_runtime +Target supports the execution of @code{sse2} instructions. + +@item sync_char_short +Target supports atomic operations on @code{char} and @code{short}. + +@item sync_int_long +Target supports atomic operations on @code{int} and @code{long}. + +@item ultrasparc_hw +Test environment appears to run executables on a simulator that +accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS} +or @code{EM_SPARCV9} executables. + +@item vect_cmdline_needed +Target requires a command line argument to enable a SIMD instruction set. +@end table + +@subsubsection Environment attributes + +@table @code +@item c +The language for the compiler under test is C. + +@item c++ +The language for the compiler under test is C++. + +@item c99_runtime +Target provides a full C99 runtime. + +@item correct_iso_cpp_string_wchar_protos +Target @code{string.h} and @code{wchar.h} headers provide C++ required +overloads for @code{strchr} etc. functions. + +@item dummy_wcsftime +Target uses a dummy @code{wcsftime} function that always returns zero. + +@item fd_truncate +Target can truncate a file from a file descriptor, as used by +@file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or +@code{chsize}. + +@item freestanding +Target is @samp{freestanding} as defined in section 4 of the C99 standard. +Effectively, it is a target which supports no extra headers or libraries +other than what is considered essential. + +@item init_priority +Target supports constructors with initialization priority arguments. + +@item inttypes_types +Target has the basic signed and unsigned types in @code{inttypes.h}. +This is for tests that GCC's notions of these types agree with those +in the header, as some systems have only @code{inttypes.h}. + +@item lax_strtofp +Target might have errors of a few ULP in string to floating-point +conversion functions and overflow is not always detected correctly by +those functions. + +@item newlib +Target supports Newlib. + +@item pow10 +Target provides @code{pow10} function. + +@item pthread +Target can compile using @code{pthread.h} with no errors or warnings. + +@item pthread_h +Target has @code{pthread.h}. + +@item run_expensive_tests +Expensive testcases (usually those that consume excessive amounts of CPU +time) should be run on this target. This can be enabled by setting the +@env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string. + +@item simulator +Test system runs executables on a simulator (i.e. slowly) rather than +hardware (i.e. fast). + +@item stdint_types +Target has the basic signed and unsigned C types in @code{stdint.h}. +This will be obsolete when GCC ensures a working @code{stdint.h} for +all targets. + +@item trampolines +Target supports trampolines. + +@item uclibc +Target supports uClibc. + +@item unwrapped +Target does not use a status wrapper. + +@item vxworks_kernel +Target is a VxWorks kernel. + +@item vxworks_rtp +Target is a VxWorks RTP. + +@item wchar +Target supports wide characters. +@end table + +@subsubsection Other attributes + +@table @code +@item automatic_stack_alignment +Target supports automatic stack alignment. + +@item cxa_atexit +Target uses @code{__cxa_atexit}. + +@item default_packed +Target has packed layout of structure members by default. + +@item fgraphite +Target supports Graphite optimizations. + +@item fixed_point +Target supports fixed-point extension to C. + +@item fopenmp +Target supports OpenMP via @option{-fopenmp}. + +@item fpic +Target supports @option{-fpic} and @option{-fPIC}. + +@item freorder +Target supports @option{-freorder-blocks-and-partition}. + +@item fstack_protector +Target supports @option{-fstack-protector}. + +@item gas +Target uses GNU @command{as}. + +@item gc_sections +Target supports @option{--gc-sections}. + +@item keeps_null_pointer_checks +Target keeps null pointer checks, either due to the use of +@option{-fno-delete-null-pointer-checks} or hardwired into the target. + +@item lto +Compiler has been configured to support link-time optimization (LTO). + +@item named_sections +Target supports named sections. + +@item natural_alignment_32 +Target uses natural alignment (aligned to type size) for types of +32 bits or less. + +@item target_natural_alignment_64 +Target uses natural alignment (aligned to type size) for types of +64 bits or less. + +@item nonpic +Target does not generate PIC by default. + +@item pcc_bitfield_type_matters +Target defines @code{PCC_BITFIELD_TYPE_MATTERS}. + +@item pe_aligned_commons +Target supports @option{-mpe-aligned-commons}. + +@item section_anchors +Target supports section anchors. + +@item short_enums +Target defaults to short enums. + +@item static +Target supports @option{-static}. + +@item static_libgfortran +Target supports statically linking @samp{libgfortran}. + +@item string_merging +Target supports merging string constants at link time. + +@item ucn +Target supports compiling and assembling UCN. + +@item ucn_nocache +Including the options used to compile this particular test, the +target supports compiling and assembling UCN. + +@item unaligned_stack +Target does not guarantee that its @code{STACK_BOUNDARY} is greater than +or equal to the required vector alignment. + +@item vector_alignment_reachable +Vector alignment is reachable for types of 32 bits or less. + +@item vector_alignment_reachable_for_64bit +Vector alignment is reachable for types of 64 bits or less. + +@item wchar_t_char16_t_compatible +Target supports @code{wchar_t} that is compatible with @code{char16_t}. + +@item wchar_t_char32_t_compatible +Target supports @code{wchar_t} that is compatible with @code{char32_t}. +@end table + +@subsubsection Local to tests in @code{gcc.target/i386} + +@table @code +@item 3dnow +Target supports compiling @code{3dnow} instructions. + +@item aes +Target supports compiling @code{aes} instructions. + +@item fma4 +Target supports compiling @code{fma4} instructions. + +@item ms_hook_prologue +Target supports attribute @code{ms_hook_prologue}. + +@item pclmul +Target supports compiling @code{pclmul} instructions. + +@item sse3 +Target supports compiling @code{sse3} instructions. + +@item sse4 +Target supports compiling @code{sse4} instructions. + +@item sse4a +Target supports compiling @code{sse4a} instructions. + +@item ssse3 +Target supports compiling @code{ssse3} instructions. + +@item vaes +Target supports compiling @code{vaes} instructions. + +@item vpclmul +Target supports compiling @code{vpclmul} instructions. + +@item xop +Target supports compiling @code{xop} instructions. +@end table + +@subsubsection Local to tests in @code{gcc.target/spu/ea} + +@table @code +@item ealib +Target @code{__ea} library functions are available. +@end table + +@subsubsection Local to tests in @code{gcc.test-framework} + +@table @code +@item no +Always returns 0. + +@item yes +Always returns 1. +@end table + +@node Add Options +@subsection Features for @code{dg-add-options} + +The supported values of @var{feature} for directive @code{dg-add-options} +are: + +@table @code +@item arm_neon +NEON support. Only ARM targets support this feature, and only then +in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target +keyword}. + +@item arm_neon_fp16 +NEON and half-precision floating point support. Only ARM targets +support this feature, and only then in certain modes; see +the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}. + +@item bind_pic_locally +Add the target-specific flags needed to enable functions to bind +locally when using pic/PIC passes in the testsuite. + +@item c99_runtime +Add the target-specific flags needed to access the C99 runtime. + +@item ieee +Add the target-specific flags needed to enable full IEEE +compliance mode. + +@item mips16_attribute +@code{mips16} function attributes. +Only MIPS targets support this feature, and only then in certain modes. + +@item tls +Add the target-specific flags needed to use thread-local storage. +@end table + +@node Require Support +@subsection Variants of @code{dg-require-@var{support}} + +A few of the @code{dg-require} directives take arguments. + +@table @code +@item dg-require-iconv @var{codeset} +Skip the test if the target does not support iconv. @var{codeset} is +the codeset to convert to. + +@item dg-require-profiling @var{profopt} +Skip the test if the target does not support profiling with option +@var{profopt}. + +@item dg-require-visibility @var{vis} +Skip the test if the target does not support the @code{visibility} attribute. +If @var{vis} is @code{""}, support for @code{visibility("hidden")} is +checked, for @code{visibility("@var{vis}")} otherwise. +@end table + +The original @code{dg-require} directives were defined before there +was support for effective-target keywords. The directives that do not +take arguments could be replaced with effective-target keywords. + +@table @code +@item dg-require-alias "" +Skip the test if the target does not support the @samp{alias} attribute. + +@item dg-require-ascii-locale "" +Skip the test if the host does not support an ASCII locale. + +@item dg-require-compat-dfp "" +Skip this test unless both compilers in a @file{compat} testsuite +support decimal floating point. + +@item dg-require-cxa-atexit "" +Skip the test if the target does not support @code{__cxa_atexit}. +This is equivalent to @code{dg-require-effective-target cxa_atexit}. + +@item dg-require-dll "" +Skip the test if the target does not support DLL attributes. + +@item dg-require-fork "" +Skip the test if the target does not support @code{fork}. + +@item dg-require-gc-sections "" +Skip the test if the target's linker does not support the +@code{--gc-sections} flags. +This is equivalent to @code{dg-require-effective-target gc-sections}. + +@item dg-require-host-local "" +Skip the test if the host is remote, rather than the same as the build +system. Some tests are incompatible with DejaGnu's handling of remote +hosts, which involves copying the source file to the host and compiling +it with a relative path and "@code{-o a.out}". + +@item dg-require-mkfifo "" +Skip the test if the target does not support @code{mkfifo}. + +@item dg-require-named-sections "" +Skip the test is the target does not support named sections. +This is equivalent to @code{dg-require-effective-target named_sections}. + +@item dg-require-weak "" +Skip the test if the target does not support weak symbols. + +@item dg-require-weak-override "" +Skip the test if the target does not support overriding weak symbols. +@end table + +@node Final Actions +@subsection Commands for use in @code{dg-final} + +The GCC testsuite defines the following directives to be used within +@code{dg-final}. + +@subsubsection Scan a particular file + +@table @code +@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] +Passes if @var{regexp} matches text in @var{filename}. +@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] +Passes if @var{regexp} does not match text in @var{filename}. +@item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}] +Passes if @var{regexp} matches in Fortran module @var{module}. +@end table + +@subsubsection Scan the assembly output + +@table @code +@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} matches text in the test's assembler output. + +@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} does not match text in the test's assembler output. + +@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} is matched exactly @var{num} times in the test's +assembler output. + +@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} matches text in the test's demangled assembler output. + +@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} does not match text in the test's demangled assembler +output. + +@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] +Passes if @var{symbol} is defined as a hidden symbol in the test's +assembly output. + +@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] +Passes if @var{symbol} is not defined as a hidden symbol in the test's +assembly output. +@end table + +@subsubsection Scan optimization dump files + +These commands are available for @var{kind} of @code{tree}, @code{rtl}, +and @code{ipa}. + +@table @code +@item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. + +@item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} does not match text in the dump file with suffix +@var{suffix}. + +@item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} is found exactly @var{num} times in the dump file +with suffix @var{suffix}. + +@item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} matches demangled text in the dump file with +suffix @var{suffix}. + +@item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] +Passes if @var{regex} does not match demangled text in the dump file with +suffix @var{suffix}. +@end table + +@subsubsection Verify that an output files exists or not + +@table @code +@item output-exists [@{ target/xfail @var{selector} @}] +Passes if compiler output file exists. + +@item output-exists-not [@{ target/xfail @var{selector} @}] +Passes if compiler output file does not exist. +@end table + +@subsubsection Check for LTO tests + +@table @code +@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] +Passes if the pattern is present in the final executable. +@end table + +@subsubsection Checks for @command{gcov} tests + +@table @code +@item run-gcov @var{sourcefile} +Check line counts in @command{gcov} tests. + +@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} +Check branch and/or call counts, in addition to line counts, in +@command{gcov} tests. +@end table + +@subsubsection Clean up generated test files + +@table @code +@item cleanup-coverage-files +Removes coverage data files generated for this test. + +@item cleanup-ipa-dump @var{suffix} +Removes IPA dump files generated for this test. + +@item cleanup-modules +Removes Fortran module files generated for this test. + +@item cleanup-profile-file +Removes profiling files generated for this test. + +@item cleanup-repo-files +Removes files generated for this test for @option{-frepo}. + +@item cleanup-rtl-dump @var{suffix} +Removes RTL dump files generated for this test. + +@item cleanup-saved-temps +Removes files for the current test which were kept for @option{-save-temps}. + +@item cleanup-tree-dump @var{suffix} +Removes tree dump files matching @var{suffix} which were generated for +this test. +@end table + +@node Ada Tests +@section Ada Language Testsuites + +The Ada testsuite includes executable tests from the ACATS 2.5 +testsuite, publicly available at +@uref{http://www.adaic.org/compilers/acats/2.5}. + +These tests are integrated in the GCC testsuite in the +@file{ada/acats} directory, and +enabled automatically when running @code{make check}, assuming +the Ada language has been enabled when configuring GCC@. + +You can also run the Ada testsuite independently, using +@code{make check-ada}, or run a subset of the tests by specifying which +chapter to run, e.g.: + +@smallexample +$ make check-ada CHAPTERS="c3 c9" +@end smallexample + +The tests are organized by directory, each directory corresponding to +a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds +to chapter 9, which deals with tasking features of the language. + +There is also an extra chapter called @file{gcc} containing a template for +creating new executable tests, although this is deprecated in favor of +the @file{gnat.dg} testsuite. + +The tests are run using two @command{sh} scripts: @file{run_acats} and +@file{run_all.sh}. To run the tests using a simulator or a cross +target, see the small +customization section at the top of @file{run_all.sh}. + +These tests are run using the build tree: they can be run without doing +a @code{make install}. + +@node C Tests +@section C Language Testsuites + +GCC contains the following C language testsuites, in the +@file{gcc/testsuite} directory: + +@table @file +@item gcc.dg +This contains tests of particular features of the C compiler, using the +more modern @samp{dg} harness. Correctness tests for various compiler +features should go here if possible. + +Magic comments determine whether the file +is preprocessed, compiled, linked or run. In these tests, error and warning +message texts are compared against expected texts or regular expressions +given in comments. These tests are run with the options @samp{-ansi -pedantic} +unless other options are given in the test. Except as noted below they +are not run with multiple optimization options. +@item gcc.dg/compat +This subdirectory contains tests for binary compatibility using +@file{lib/compat.exp}, which in turn uses the language-independent support +(@pxref{compat Testing, , Support for testing binary compatibility}). +@item gcc.dg/cpp +This subdirectory contains tests of the preprocessor. +@item gcc.dg/debug +This subdirectory contains tests for debug formats. Tests in this +subdirectory are run for each debug format that the compiler supports. +@item gcc.dg/format +This subdirectory contains tests of the @option{-Wformat} format +checking. Tests in this directory are run with and without +@option{-DWIDE}. +@item gcc.dg/noncompile +This subdirectory contains tests of code that should not compile and +does not need any special compilation options. They are run with +multiple optimization options, since sometimes invalid code crashes +the compiler with optimization. +@item gcc.dg/special +FIXME: describe this. + +@item gcc.c-torture +This contains particular code fragments which have historically broken easily. +These tests are run with multiple optimization options, so tests for features +which only break at some optimization levels belong here. This also contains +tests to check that certain optimizations occur. It might be worthwhile to +separate the correctness tests cleanly from the code quality tests, but +it hasn't been done yet. + +@item gcc.c-torture/compat +FIXME: describe this. + +This directory should probably not be used for new tests. +@item gcc.c-torture/compile +This testsuite contains test cases that should compile, but do not +need to link or run. These test cases are compiled with several +different combinations of optimization options. All warnings are +disabled for these test cases, so this directory is not suitable if +you wish to test for the presence or absence of compiler warnings. +While special options can be set, and tests disabled on specific +platforms, by the use of @file{.x} files, mostly these test cases +should not contain platform dependencies. FIXME: discuss how defines +such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. +@item gcc.c-torture/execute +This testsuite contains test cases that should compile, link and run; +otherwise the same comments as for @file{gcc.c-torture/compile} apply. +@item gcc.c-torture/execute/ieee +This contains tests which are specific to IEEE floating point. +@item gcc.c-torture/unsorted +FIXME: describe this. + +This directory should probably not be used for new tests. +@item gcc.misc-tests +This directory contains C tests that require special handling. Some +of these tests have individual expect files, and others share +special-purpose expect files: + +@table @file +@item @code{bprob*.c} +Test @option{-fbranch-probabilities} using +@file{gcc.misc-tests/bprob.exp}, which +in turn uses the generic, language-independent framework +(@pxref{profopt Testing, , Support for testing profile-directed +optimizations}). + +@item @code{gcov*.c} +Test @command{gcov} output using @file{gcov.exp}, which in turn uses the +language-independent support (@pxref{gcov Testing, , Support for testing gcov}). + +@item @code{i386-pf-*.c} +Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. +@end table + +@item gcc.test-framework +@table @file +@item @code{dg-*.c} +Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}. +@end table + +@end table + +FIXME: merge in @file{testsuite/README.gcc} and discuss the format of +test cases and magic comments more. + +@node libgcj Tests +@section The Java library testsuites. + +Runtime tests are executed via @samp{make check} in the +@file{@var{target}/libjava/testsuite} directory in the build +tree. Additional runtime tests can be checked into this testsuite. + +Regression testing of the core packages in libgcj is also covered by the +Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project} +develops tests for the Java Class Libraries. These tests are run as part +of libgcj testing by placing the Mauve tree within the libjava testsuite +sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying +the location of that tree when invoking @samp{make}, as in +@samp{make MAUVEDIR=~/mauve check}. + +To detect regressions, a mechanism in @file{mauve.exp} compares the +failures for a test run against the list of expected failures in +@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. +Update this file when adding new failing tests to Mauve, or when fixing +bugs in libgcj that had caused Mauve test failures. + +We encourage developers to contribute test cases to Mauve. + +@node LTO Testing +@section Support for testing link-time optimizations + +Tests for link-time optimizations usually require multiple source files +that are compiled separately, perhaps with different sets of options. +There are several special-purpose test directives used for these tests. + +@table @code +@item @{ dg-lto-do @var{do-what-keyword} @} +@var{do-what-keyword} specifies how the test is compiled and whether +it is executed. It is one of: + +@table @code +@item assemble +Compile with @option{-c} to produce a relocatable object file. +@item link +Compile, assemble, and link to produce an executable file. +@item run +Produce and run an executable file, which is expected to return +an exit code of 0. +@end table + +The default is @code{assemble}. That can be overridden for a set of +tests by redefining @code{dg-do-what-default} within the @code{.exp} +file for those tests. + +Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional +@samp{target} or @samp{xfail} list. Use @code{dg-skip-if}, +@code{dg-xfail-if}, or @code{dg-xfail-run-if}. + +@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} +This directive provides a list of one or more sets of compiler options +to override @var{LTO_OPTIONS}. Each test will be compiled and run with +each of these sets of options. + +@item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@} +This directive adds @var{options} to the linker options used. + +@item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@} +This directive removes @var{options} from the set of linker options used. +@end table + +@node gcov Testing +@section Support for testing @command{gcov} + +Language-independent support for testing @command{gcov}, and for checking +that branch profiling produces expected values, is provided by the +expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures +in @file{lib/gcc-dg.exp} to compile and run the test program. A typical +@command{gcov} test contains the following DejaGnu commands within comments: + +@smallexample +@{ dg-options "-fprofile-arcs -ftest-coverage" @} +@{ dg-do run @{ target native @} @} +@{ dg-final @{ run-gcov sourcefile @} @} +@end smallexample + +Checks of @command{gcov} output can include line counts, branch percentages, +and call return percentages. All of these checks are requested via +commands that appear in comments in the test's source file. +Commands to check line counts are processed by default. +Commands to check branch percentages and call return percentages are +processed if the @command{run-gcov} command has arguments @code{branches} +or @code{calls}, respectively. For example, the following specifies +checking both, as well as passing @option{-b} to @command{gcov}: + +@smallexample +@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} +@end smallexample + +A line count command appears within a comment on the source line +that is expected to get the specified count and has the form +@code{count(@var{cnt})}. A test should only check line counts for +lines that will get the same count for any architecture. + +Commands to check branch percentages (@code{branch}) and call +return percentages (@code{returns}) are very similar to each other. +A beginning command appears on or before the first of a range of +lines that will report the percentage, and the ending command +follows that range of lines. The beginning command can include a +list of percentages, all of which are expected to be found within +the range. A range is terminated by the next command of the same +kind. A command @code{branch(end)} or @code{returns(end)} marks +the end of a range without starting a new one. For example: + +@smallexample +if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ + /* @r{branch(end)} */ + foo (i, j); +@end smallexample + +For a call return percentage, the value specified is the +percentage of calls reported to return. For a branch percentage, +the value is either the expected percentage or 100 minus that +value, since the direction of a branch can differ depending on the +target or the optimization level. + +Not all branches and calls need to be checked. A test should not +check for branches that might be optimized away or replaced with +predicated instructions. Don't check for calls inserted by the +compiler or ones that might be inlined or optimized away. + +A single test can check for combinations of line counts, branch +percentages, and call return percentages. The command to check a +line count must appear on the line that will report that count, but +commands to check branch percentages and call return percentages can +bracket the lines that report them. + +@node profopt Testing +@section Support for testing profile-directed optimizations + +The file @file{profopt.exp} provides language-independent support for +checking correct execution of a test built with profile-directed +optimization. This testing requires that a test program be built and +executed twice. The first time it is compiled to generate profile +data, and the second time it is compiled to use the data that was +generated during the first execution. The second execution is to +verify that the test produces the expected results. + +To check that the optimization actually generated better code, a +test can be built and run a third time with normal optimizations to +verify that the performance is better with the profile-directed +optimizations. @file{profopt.exp} has the beginnings of this kind +of support. + +@file{profopt.exp} provides generic support for profile-directed +optimizations. Each set of tests that uses it provides information +about a specific optimization: + +@table @code +@item tool +tool being tested, e.g., @command{gcc} + +@item profile_option +options used to generate profile data + +@item feedback_option +options used to optimize using that profile data + +@item prof_ext +suffix of profile data files + +@item PROFOPT_OPTIONS +list of options with which to run each test, similar to the lists for +torture tests + +@item @{ dg-final-generate @{ @var{local-directive} @} @} +This directive is similar to @code{dg-final}, but the +@var{local-directive} is run after the generation of profile data. + +@item @{ dg-final-use @{ @var{local-directive} @} @} +The @var{local-directive} is run after the profile data have been +used. +@end table + +@node compat Testing +@section Support for testing binary compatibility + +The file @file{compat.exp} provides language-independent support for +binary compatibility testing. It supports testing interoperability of +two compilers that follow the same ABI, or of multiple sets of +compiler options that should not affect binary compatibility. It is +intended to be used for testsuites that complement ABI testsuites. + +A test supported by this framework has three parts, each in a +separate source file: a main program and two pieces that interact +with each other to split up the functionality being tested. + +@table @file +@item @var{testname}_main.@var{suffix} +Contains the main program, which calls a function in file +@file{@var{testname}_x.@var{suffix}}. + +@item @var{testname}_x.@var{suffix} +Contains at least one call to a function in +@file{@var{testname}_y.@var{suffix}}. + +@item @var{testname}_y.@var{suffix} +Shares data with, or gets arguments from, +@file{@var{testname}_x.@var{suffix}}. +@end table + +Within each test, the main program and one functional piece are +compiled by the GCC under test. The other piece can be compiled by +an alternate compiler. If no alternate compiler is specified, +then all three source files are all compiled by the GCC under test. +You can specify pairs of sets of compiler options. The first element +of such a pair specifies options used with the GCC under test, and the +second element of the pair specifies options used with the alternate +compiler. Each test is compiled with each pair of options. + +@file{compat.exp} defines default pairs of compiler options. +These can be overridden by defining the environment variable +@env{COMPAT_OPTIONS} as: + +@smallexample +COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] + @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]" +@end smallexample + +where @var{tsti} and @var{alti} are lists of options, with @var{tsti} +used by the compiler under test and @var{alti} used by the alternate +compiler. For example, with +@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, +the test is first built with @option{-g -O0} by the compiler under +test and with @option{-O3} by the alternate compiler. The test is +built a second time using @option{-fpic} by the compiler under test +and @option{-fPIC -O2} by the alternate compiler. + +An alternate compiler is specified by defining an environment +variable to be the full pathname of an installed compiler; for C +define @env{ALT_CC_UNDER_TEST}, and for C++ define +@env{ALT_CXX_UNDER_TEST}. These will be written to the +@file{site.exp} file used by DejaGnu. The default is to build each +test with the compiler under test using the first of each pair of +compiler options from @env{COMPAT_OPTIONS}. When +@env{ALT_CC_UNDER_TEST} or +@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using +the compiler under test but with combinations of the options from +@env{COMPAT_OPTIONS}. + +To run only the C++ compatibility suite using the compiler under test +and another version of GCC using specific compiler options, do the +following from @file{@var{objdir}/gcc}: + +@smallexample +rm site.exp +make -k \ + ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ + COMPAT_OPTIONS="@var{lists as shown above}" \ + check-c++ \ + RUNTESTFLAGS="compat.exp" +@end smallexample + +A test that fails when the source files are compiled with different +compilers, but passes when the files are compiled with the same +compiler, demonstrates incompatibility of the generated code or +runtime support. A test that fails for the alternate compiler but +passes for the compiler under test probably tests for a bug that was +fixed in the compiler under test but is present in the alternate +compiler. + +The binary compatibility tests support a small number of test framework +commands that appear within comments in a test file. + +@table @code +@item dg-require-* +These commands can be used in @file{@var{testname}_main.@var{suffix}} +to skip the test if specific support is not available on the target. + +@item dg-options +The specified options are used for compiling this particular source +file, appended to the options from @env{COMPAT_OPTIONS}. When this +command appears in @file{@var{testname}_main.@var{suffix}} the options +are also used to link the test program. + +@item dg-xfail-if +This command can be used in a secondary source file to specify that +compilation is expected to fail for particular options on particular +targets. +@end table + +@node Torture Tests +@section Support for torture testing using multiple options + +Throughout the compiler testsuite there are several directories whose +tests are run multiple times, each with a different set of options. +These are known as torture tests. +@file{lib/torture-options.exp} defines procedures to +set up these lists: + +@table @code +@item torture-init +Initialize use of torture lists. +@item set-torture-options +Set lists of torture options to use for tests with and without loops. +Optionally combine a set of torture options with a set of other +options, as is done with Objective-C runtime options. +@item torture-finish +Finalize use of torture lists. +@end table + +The @file{.exp} file for a set of tests that use torture options must +include calls to these three procedures if: + +@itemize @bullet +@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}. + +@item It calls @var{$@{tool@}}@code{-torture} or +@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c}, +@code{fortran}, or @code{objc}. + +@item It calls @code{dg-pch}. +@end itemize + +It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest} +to call the torture procedures if the tests should use the list in +@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}. + +Most uses of torture options can override the default lists by defining +@var{TORTURE_OPTIONS} or add to the default list by defining +@var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc} +file or add them to the @file{site.exp} file; for example + +@smallexample +set ADDITIONAL_TORTURE_OPTIONS [list \ + @{ -O2 -ftree-loop-linear @} \ + @{ -O2 -fpeel-loops @} ] +@end smallexample -- cgit v1.2.3