diff options
Diffstat (limited to 'gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi')
| -rw-r--r-- | gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi | 1524 |
1 files changed, 0 insertions, 1524 deletions
diff --git a/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi b/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi deleted file mode 100644 index 2db9d10f7..000000000 --- a/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi +++ /dev/null @@ -1,1524 +0,0 @@ -@c Copyright (C) 2002, 2003, 2004, 2005, 2007 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. -* Testsuites:: The GCC testsuites. -@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 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 fastjar -An implementation of the @command{jar} command, used with the Java -front end. - -@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 include -Headers for the @code{libiberty} library. - -@item libada -The Ada runtime library. - -@item libcpp -The C preprocessor library. - -@item libgfortran -The Fortran runtime library. - -@item libffi -The @code{libffi} library, used as part of the Java runtime library. - -@item libiberty -The @code{libiberty} library, used for portability and for some -generally useful data structures and algorithms. @xref{Top, , -Introduction, libiberty, @sc{gnu} libiberty}, for more information -about this library. - -@item libjava -The Java runtime library. - -@item libmudflap -The @code{libmudflap} library, used for instrumenting pointer and array -dereferencing operations. - -@item libobjc -The Objective-C and Objective-C++ runtime library. - -@item libstdc++-v3 -The C++ runtime library. - -@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 and as -part of the Java runtime library. -@end table - -The build system in the top level directory, including how recursion -into subdirectories works and how building runtime libraries for -multilibs is handled, is documented in a separate manual, included -with GNU Binutils. @xref{Top, , GNU configure and build system, -configure, The GNU configure and build system}, for details. - -@node gcc Directory -@section The @file{gcc} Subdirectory - -The @file{gcc} directory contains many files that are part of the C -sources of GCC, other files used as part of the configuration and -build process, and subdirectories including documentation and a -testsuite. The files that are sources of GCC are documented in a -separate chapter. @xref{Passes, , Passes and Files of the Compiler}. - -@menu -* Subdirectories:: Subdirectories of @file{gcc}. -* Configuration:: The configuration process, and the files it uses. -* Build:: The build system in the @file{gcc} directory. -* Makefile:: Targets in @file{gcc/Makefile}. -* Library Files:: Library source files and headers under @file{gcc/}. -* Headers:: Headers installed by GCC. -* Documentation:: Building documentation in GCC. -* Front End:: Anatomy of a language front end. -* Back End:: Anatomy of a target back end. -@end menu - -@node Subdirectories -@subsection Subdirectories of @file{gcc} - -The @file{gcc} directory contains the following subdirectories: - -@table @file -@item @var{language} -Subdirectories for various languages. Directories containing a file -@file{config-lang.in} are language subdirectories. The contents of -the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C) -and @file{objcp} (for Objective-C++) are documented in this manual -(@pxref{Passes, , Passes and Files of the Compiler}); those for other -languages are not. @xref{Front End, , Anatomy of a Language Front End}, -for details of the files in these directories. - -@item config -Configuration files for supported architectures and operating -systems. @xref{Back End, , Anatomy of a Target Back End}, for -details of the files in this directory. - -@item doc -Texinfo documentation for GCC, together with automatically generated -man pages and support for converting the installation manual to -HTML@. @xref{Documentation}. - -@item fixinc -The support for fixing system headers to work with GCC@. See -@file{fixinc/README} for more information. The headers fixed by this -mechanism are installed in @file{@var{libsubdir}/include}. Along with -those headers, @file{README-fixinc} is also installed, as -@file{@var{libsubdir}/include/README}. - -@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 intl -GNU @code{libintl}, from GNU @code{gettext}, for systems which do not -include it in libc. Properly, this directory should be at top level, -parallel to the @file{gcc} directory. - -@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. FIXME: when is the -@file{config.guess} file in the @file{gcc} directory (that just calls -the top level one) 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. - -@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 @command{make html}. In addition, some man pages are -generated from the Texinfo manuals, there are some other text files -with miscellaneous documentation, and runtime libraries have their own -documentation outside the @file{gcc} directory. FIXME: document the -documentation for runtime libraries somewhere. - -@menu -* Texinfo Manuals:: GCC manuals in Texinfo format. -* Man Page Generation:: Generating man pages from Texinfo manuals. -* Miscellaneous Docs:: Miscellaneous text files with documentation. -@end menu - -@node Texinfo Manuals -@subsubsection Texinfo Manuals - -The manuals for GCC as a whole, and the C and C++ front ends, are in -files @file{doc/*.texi}. Other front ends have their own manuals in -files @file{@var{language}/*.texi}. Common files -@file{doc/include/*.texi} are provided which may be included in -multiple manuals; the following files are in @file{doc/include}: - -@table @file -@item fdl.texi -The GNU Free Documentation License. -@item funding.texi -The section ``Funding Free Software''. -@item gcc-common.texi -Common definitions for manuals. -@item gpl.texi -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 @command{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}. 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 checked into CVS, 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 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 -The GNU General Public License. -@item COPYING.LIB -The GNU Lesser General Public License. -@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? -@item SERVICE -A pointer to the GNU Service Directory. -@end table - -FIXME: document such files in subdirectories, at least @file{config}, -@file{cp}, @file{objc}, @file{testsuite}. - -@node Front End -@subsection Anatomy of a Language Front End - -A front end for a language in GCC has the following parts: - -@itemize @bullet -@item -A directory @file{@var{language}} under @file{gcc} containing source -files for that front end. @xref{Front End Directory, , The Front End -@file{@var{language}} Directory}, for details. -@item -A mention of the language in the list of supported languages in -@file{gcc/doc/install.texi}. -@item -A mention of the name under which the language's runtime library is -recognized by @option{--enable-shared=@var{package}} in the -documentation of that option in @file{gcc/doc/install.texi}. -@item -A mention of any special prerequisites for building the front end in -the documentation of prerequisites in @file{gcc/doc/install.texi}. -@item -Details of contributors to that front end in -@file{gcc/doc/contrib.texi}. If the details are in that front end's -own manual then there should be a link to that manual's list in -@file{contrib.texi}. -@item -Information about support for that language in -@file{gcc/doc/frontends.texi}. -@item -Information about standards for that language, and the front end's -support for them, in @file{gcc/doc/standards.texi}. This may be a -link to such information in the front end's own manual. -@item -Details of source file suffixes for that language and @option{-x -@var{lang}} options supported, in @file{gcc/doc/invoke.texi}. -@item -Entries in @code{default_compilers} in @file{gcc.c} for source file -suffixes for that language. -@item -Preferably testsuites, which may be under @file{gcc/testsuite} or -runtime library directories. FIXME: document somewhere how to write -testsuite harnesses. -@item -Probably a runtime library for the language, outside the @file{gcc} -directory. FIXME: document this further. -@item -Details of the directories of any runtime libraries in -@file{gcc/doc/sourcebuild.texi}. -@end itemize - -If the front end is added to the official GCC CVS 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 mentioned in -@file{gcc/gccbug.in}, as well as being 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} (@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. -The associated @file{maintainer-scripts/snapshot-README} and -@file{maintainer-scripts/snapshot-index.html} files should be updated -to list the tarballs and diffs 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. -@item -@file{CVSROOT/modules} in the GCC CVS repository should be updated. -@end itemize - -@menu -* Front End Directory:: The front end @file{@var{language}} directory. -* Front End Config:: The front end @file{config-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 build 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. It contains -targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the -setting of @code{language} in @file{config-lang.in}) for the following -values of @code{@var{hook}}, and any other Makefile rules required to -build those targets (which may if necessary use other Makefiles -specified in @code{outputs} in @file{config-lang.in}, although this is -deprecated). It also adds any testsuite targets that can use the -standard rule in @file{gcc/Makefile.in} to the variable -@code{lang_checks}. - -@table @code -@itemx all.cross -@itemx start.encap -@itemx rest.encap -FIXME: exactly what goes in each of these targets? -@item tags -Build an @command{etags} @file{TAGS} file in the language subdirectory -in the source tree. -@item info -Build info documentation for the front end, in the build directory. -This target is only called by @samp{make bootstrap} if a suitable -version of @command{makeinfo} is available, so does not need to check -for this, and should fail if an error occurs. -@item dvi -Build DVI documentation for the front end, in the build directory. -This should be done using @code{$(TEXI2DVI)}, with appropriate -@option{-I} arguments pointing to directories of included files. -@item pdf -Build PDF documentation for the front end, in the build directory. -This should be done using @code{$(TEXI2PDF)}, with appropriate -@option{-I} arguments pointing to directories of included files. -@item html -Build HTML documentation for the front end, in the build directory. -@item man -Build generated man pages for the front end from Texinfo manuals -(@pxref{Man Page Generation}), in the build directory. This target -is only called if the necessary tools are available, but should ignore -errors so as not to stop the build if errors occur; man pages are -optional and the tools involved may be installed in a broken way. -@item install-common -Install everything that is part of the front end, apart from the -compiler executables listed in @code{compilers} in -@file{config-lang.in}. -@item install-info -Install info documentation for the front end, if it is present in the -source directory. This target should have dependencies on info files -that should be installed. -@item install-man -Install man pages for the front end. This target should ignore -errors. -@item srcextra -Copies its dependencies into the source directory. This generally should -be used for generated files such as Bison output files which are not -present in CVS, 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 checked into -CVS, but should not delete anything checked into CVS@. -@item stage1 -@itemx stage2 -@itemx stage3 -@itemx stage4 -@itemx stageprofile -@itemx stagefeedback -Move to the stage directory files not included in @code{stagestuff} in -@file{config-lang.in} or otherwise moved by the main @file{Makefile}. -@end table - -@item lang.opt -This file registers the set of switches that the front end accepts on -the command line, and their @option{--help} text. @xref{Options}. -@item lang-specs.h -This file provides entries for @code{default_compilers} in -@file{gcc.c} which override the default of giving an error that a -compiler for that language is not installed. -@item @var{language}-tree.def -This file, which need not exist, defines any language-specific tree -codes. -@end table - -@node Front End Config -@subsubsection The Front End @file{config-lang.in} File - -Each language subdirectory contains a @file{config-lang.in} file. In -addition the main directory contains @file{c-config-lang.in}, which -contains limited information for the C language. This file is a shell -script that may define some variables describing the language: - -@table @code -@item language -This definition must be present, and gives the name of the language -for some purposes such as arguments to @option{--enable-languages}. -@item lang_requires -If defined, this variable lists (space-separated) language front ends -other than C that this front end requires to be enabled (with the -names given being their @code{language} settings). For example, the -Java front end depends on the C++ front end, so sets -@samp{lang_requires=c++}. -@item subdir_requires -If defined, this variable lists (space-separated) front end directories -other than C that this front end requires to be present. For example, -the Objective-C++ front end uses source files from the C++ and -Objective-C front ends, so sets @samp{subdir_requires="cp objc"}. -@item target_libs -If defined, this variable lists (space-separated) targets in the top -level @file{Makefile} to build the runtime libraries for this -language, such as @code{target-libobjc}. -@item lang_dirs -If defined, this variable lists (space-separated) top level -directories (parallel to @file{gcc}), apart from the runtime libraries, -that should not be configured if this front end is not built. -@item build_by_default -If defined to @samp{no}, this language front end is not built unless -enabled in a @option{--enable-languages} argument. Otherwise, front -ends are built by default, subject to any special logic in -@file{configure.ac} (as is present to disable the Ada front end if the -Ada compiler is not already installed). -@item boot_language -If defined to @samp{yes}, this front end is built in stage 1 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 stagestuff -If defined, a space-separated list of files that should be moved to -the @file{stage@var{n}} directories in each stage of bootstrap. -@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 -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}. -@item need_gmp -If defined to @samp{yes}, this frontend requires the GMP library. -Enables configure tests for GMP, which set @code{GMPLIBS} and -@code{GMPINC} appropriately. - -@end table - -@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 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 CVS repository, the -following are also necessary: - -@itemize @bullet -@item -An entry for the target architecture in @file{readings.html} on the -GCC web site, with any relevant links. -@item -Details of the properties of the back end and target architecture in -@file{backends.html} on the GCC web site. -@item -A news item about the contribution of support for that target -architecture, in @file{index.html} on the GCC web site. -@item -Normally, one or more maintainers of that target listed in -@file{MAINTAINERS}. Some existing architectures may be unmaintained, -but it would be unusual to add support for a target that does not have -a maintainer when support is added. -@end itemize - -@node Testsuites -@section 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. -* gcov Testing:: Support for testing gcov. -* profopt Testing:: Support for testing profile-directed optimizations. -* compat Testing:: Support for testing binary compatibility. -@end menu - -@node Test Idioms -@subsection 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 -@subsection Directives used within DejaGnu tests - -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 which are usually preceded by -the keyword @code{target} or @code{xfail}. A selector is: one or more -target triplets, possibly including wildcard characters; a single -effective-target keyword; or a logical expression. Depending on the -context, the selector specifies whether a test is skipped and reported -as unsupported or is expected to fail. Use @samp{*-*-*} to match any -target. -Effective-target keywords are defined in @file{target-supports.exp} in -the GCC testsuite. - -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 - -@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 assemble -Compile with @option{-S} to produce an assembly code file. -@item compile -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 is included in the -list of target triplets or matches the effective-target keyword. - -If the directive includes the optional @samp{@{ xfail @var{selector} @}} -and the selector is met then the test is expected to fail. For -@code{dg-do run}, execution is expected to fail but compilation -is expected to pass. - -@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-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @} -Skip the test if the test system is included in @var{selector} and if -each of the options in @var{include-opts} is in the set of options with -which the test would be compiled and if none of the options in -@var{exclude-opts} is in the set of options with which the test would be -compiled. - -Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for -an empty @var{exclude-opts} list. - -@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. - -@item @{ dg-require-@var{support} args @} -Skip the test if the target does not provide the required support; -see @file{gcc-dg.exp} in the GCC testsuite for the actual directives. -These directives must appear after any @code{dg-do} directive in the test. -They require at least one argument, which can be an empty string if the -specific procedure does not examine the argument. - -@item @{ dg-require-effective-target @var{keyword} @} -Skip the test if the test target, including current multilib flags, -is not covered by the effective-target keyword. -This directive must appear after any @code{dg-do} directive in the test. - -@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. - -@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-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}. - -@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}. - -@item @{ dg-prune-output @var{regexp} @} -Prune messages matching @var{regexp} from test output. - -@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. - -@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. - -The GCC testsuite defines the following directives to be used within -@code{dg-final}. - -@table @code -@item cleanup-coverage-files -Removes coverage data 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-tree-dump @var{suffix} -Removes tree dump files matching @var{suffix} which were generated for -this test. - -@item cleanup-saved-temps -Removes files for the current test which were kept for @option{--save-temps}. - -@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-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. - -@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 @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-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-tree-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-tree-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-tree-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-tree-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-tree-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}. - -@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. - -@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 -@end table - -@node Ada Tests -@subsection Ada Language Testsuites - -The Ada testsuite includes executable tests from the ACATS 2.5 -testsuite, publicly available at -@uref{http://www.adaic.org/compilers/acats/2.5} - -These tests are integrated in the GCC testsuite in the -@file{gcc/testsuite/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, 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. - -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 -@subsection 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{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.c-torture/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{bprob.exp}, which -in turn uses the generic, language-independent framework -(@pxref{profopt Testing, , Support for testing profile-directed -optimizations}). - -@item @code{dg-*.c} -Test the testsuite itself using @file{dg-test.exp}. - -@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 - -@end table - -FIXME: merge in @file{testsuite/README.gcc} and discuss the format of -test cases and magic comments more. - -@node libgcj Tests -@subsection 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. - -The @uref{http://sourceware.org/mauve/jacks.html,, -Jacks} project provides a testsuite for Java compilers that can be used -to test changes that affect the GCJ front end. This testsuite is run as -part of Java testing by placing the Jacks tree within the libjava -testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. - -We encourage developers to contribute test cases to Mauve and Jacks. - -@node gcov Testing -@subsection 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{gcov.exp}. @command{gcov} tests also rely on procedures -in @file{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 -@subsection 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 -@end table - -@node compat Testing -@subsection 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}@}] - ...[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="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 |