diff options
Diffstat (limited to 'gcc-4.8.1/gcc/doc/sourcebuild.texi')
| -rw-r--r-- | gcc-4.8.1/gcc/doc/sourcebuild.texi | 2679 |
1 files changed, 0 insertions, 2679 deletions
diff --git a/gcc-4.8.1/gcc/doc/sourcebuild.texi b/gcc-4.8.1/gcc/doc/sourcebuild.texi deleted file mode 100644 index 90bd0bdf2..000000000 --- a/gcc-4.8.1/gcc/doc/sourcebuild.texi +++ /dev/null @@ -1,2679 +0,0 @@ -@c Copyright (C) 2002-2013 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 libatomic -The runtime support library for atomic operations (e.g. for @code{__sync} -and @code{__atomic}). - -@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 libitm -The runtime support library for transactional memory. - -@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 libquadmath -The runtime support library for quad-precision math operations. - -@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{c} (for C), @file{cp} (for C++), -@file{objc} (for Objective-C), @file{objcp} (for Objective-C++), -and @file{lto} (for LTO) 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 common -Source files shared between the compiler drivers (such as -@command{gcc}) and the compilers proper (such as @file{cc1}). If an -architecture defines target hooks shared between those places, it also -has a subdirectory in @file{common/config}. @xref{Target Structure}. - -@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{<float.h>}, 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{<limits.h>}; 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{<limits.h>}. (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{<limits.h>}.) The system's @code{<limits.h>} 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{<tgmath.h>}. 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_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{c}, @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. -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 -@item 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. -@item -Target triplets covering all @file{config.gcc} stanzas for the target, -in the list in @file{contrib/config-list.mk}. -@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, ,}. - -@item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @} -This directive provides a list of compiler options, to be used -if the target system matches @var{selector}, that are added to the default -options used for this set of tests. -@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; -use @samp{*-*-*} to match any target -@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. A context -that allows either @samp{target} or @samp{xfail} also allows -@samp{@{ target @var{selector1} xfail @var{selector2} @}} -to skip the test for targets that don't match @var{selector1} and the -test to fail for targets that match @var{selector2}. - -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 long_neq_int -Target has @code{int} and @code{long} with different sizes. - -@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_hf_eabi -ARM target adheres to the VFP and Advanced SIMD Register Arguments -variant of the ABI for the ARM Architecture (as selected with -@code{-mfloat-abi=hard}). - -@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_neonv2_hw -Test system supports executing NEON v2 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_neonv2_ok -@anchor{arm_neonv2_ok} -ARM Target supports @code{-mfpu=neon-vfpv4 -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. - -@item arm_v8_vfp_ok -ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}. -Some multilibs may be incompatible with these options. - -@item arm_v8_neon_ok -ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}. -Some multilibs may be incompatible with these options. - -@item arm_prefer_ldrd_strd -ARM target prefers @code{LDRD} and @code{STRD} instructions over -@code{LDM} and @code{STM} instructions. - -@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 mmap -Target supports @code{mmap}. - -@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 gld -Target uses GNU @command{ld}. - -@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 naked_functions -Target supports the @code{naked} function attribute. - -@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 pie -Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}. - -@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 "@var{list-of-extra-modules}" -Removes Fortran module files generated for this test, excluding the -module names listed in keep-modules. -Cleaning up module files is usually done automatically by the testsuite -by looking at the source files and removing the modules after the test -has been executed. -@smallexample -module MoD1 -end module MoD1 -module Mod2 -end module Mod2 -module moD3 -end module moD3 -module mod4 -end module mod4 -! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant -! @{ dg-final @{ keep-modules "mod3 mod4" @} @} -@end smallexample - -@item keep-modules "@var{list-of-modules-not-to-delete}" -Whitespace separated list of module names that should not be deleted by -cleanup-modules. -If the list of modules is empty, all modules defined in this file are kept. -@smallexample -module maybe_unneeded -end module maybe_unneeded -module keep1 -end module keep1 -module keep2 -end module keep2 -! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two -! @{ dg-final @{ keep-modules "" @} @} ! keep all -@end smallexample - -@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 -testsuite, publicly available at -@uref{http://www.ada-auth.org/acats.html}. - -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 |