1 @c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010, 2011, 2012
2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Source Tree Structure and Build System
9 This chapter describes the structure of the GCC source tree, and how
10 GCC is built. The user documentation for building and installing GCC
11 is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
12 which it is presumed that you are familiar.
15 * Configure Terms:: Configuration terminology and history.
16 * Top Level:: The top level source directory.
17 * gcc Directory:: The @file{gcc} subdirectory.
20 @include configterms.texi
23 @section Top Level Source Directory
25 The top level source directory in a GCC distribution contains several
26 files and directories that are shared with other software
27 distributions such as that of GNU Binutils. It also contains several
28 subdirectories that contain parts of GCC and its runtime libraries:
32 The Boehm conservative garbage collector, used as part of the Java
36 Autoconf macros and Makefile fragments used throughout the tree.
39 Contributed scripts that may be found useful in conjunction with GCC@.
40 One of these, @file{contrib/texi2pod.pl}, is used to generate man
41 pages from Texinfo manuals as part of the GCC build process.
44 The support for fixing system headers to work with GCC@. See
45 @file{fixincludes/README} for more information. The headers fixed by
46 this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
47 Along with those headers, @file{README-fixinc} is also installed, as
48 @file{@var{libsubdir}/include-fixed/README}.
51 The main sources of GCC itself (except for runtime libraries),
52 including optimizers, support for different target architectures,
53 language front ends, and testsuites. @xref{gcc Directory, , The
54 @file{gcc} Subdirectory}, for details.
57 Support tools for GNAT.
60 Headers for the @code{libiberty} library.
63 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
64 include it in @code{libc}.
67 The Ada runtime library.
70 The runtime support library for atomic operations (e.g. for @code{__sync}
74 The C preprocessor library.
77 The Decimal Float support library.
80 The @code{libffi} library, used as part of the Java runtime library.
83 The GCC runtime library.
86 The Fortran runtime library.
89 The Go runtime library. The bulk of this library is mirrored from the
90 @uref{http://code.google.com/@/p/@/go/, master Go repository}.
93 The GNU OpenMP runtime library.
96 The @code{libiberty} library, used for portability and for some
97 generally useful data structures and algorithms. @xref{Top, ,
98 Introduction, libiberty, @sc{gnu} libiberty}, for more information
102 The runtime support library for transactional memory.
105 The Java runtime library.
108 The @code{libmudflap} library, used for instrumenting pointer and array
109 dereferencing operations.
112 The Objective-C and Objective-C++ runtime library.
115 The runtime support library for quad-precision math operations.
118 The Stack protector runtime library.
121 The C++ runtime library.
124 Plugin used by @command{gold} if link-time optimizations are enabled.
126 @item maintainer-scripts
127 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
130 The @code{zlib} compression library, used by the Java front end, as
131 part of the Java runtime library, and for compressing and uncompressing
132 GCC's intermediate language in LTO object files.
135 The build system in the top level directory, including how recursion
136 into subdirectories works and how building runtime libraries for
137 multilibs is handled, is documented in a separate manual, included
138 with GNU Binutils. @xref{Top, , GNU configure and build system,
139 configure, The GNU configure and build system}, for details.
142 @section The @file{gcc} Subdirectory
144 The @file{gcc} directory contains many files that are part of the C
145 sources of GCC, other files used as part of the configuration and
146 build process, and subdirectories including documentation and a
147 testsuite. The files that are sources of GCC are documented in a
148 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
151 * Subdirectories:: Subdirectories of @file{gcc}.
152 * Configuration:: The configuration process, and the files it uses.
153 * Build:: The build system in the @file{gcc} directory.
154 * Makefile:: Targets in @file{gcc/Makefile}.
155 * Library Files:: Library source files and headers under @file{gcc/}.
156 * Headers:: Headers installed by GCC.
157 * Documentation:: Building documentation in GCC.
158 * Front End:: Anatomy of a language front end.
159 * Back End:: Anatomy of a target back end.
163 @subsection Subdirectories of @file{gcc}
165 The @file{gcc} directory contains the following subdirectories:
169 Subdirectories for various languages. Directories containing a file
170 @file{config-lang.in} are language subdirectories. The contents of
171 the subdirectories @file{cp} (for C++), @file{lto} (for LTO),
172 @file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are
173 documented in this manual (@pxref{Passes, , Passes and Files of the
174 Compiler}); those for other languages are not. @xref{Front End, ,
175 Anatomy of a Language Front End}, for details of the files in these
179 Configuration files for supported architectures and operating
180 systems. @xref{Back End, , Anatomy of a Target Back End}, for
181 details of the files in this directory.
184 Texinfo documentation for GCC, together with automatically generated
185 man pages and support for converting the installation manual to
186 HTML@. @xref{Documentation}.
189 System headers installed by GCC, mainly those required by the C
190 standard of freestanding implementations. @xref{Headers, , Headers
191 Installed by GCC}, for details of when these and other headers are
195 Message catalogs with translations of messages produced by GCC into
196 various languages, @file{@var{language}.po}. This directory also
197 contains @file{gcc.pot}, the template for these message catalogues,
198 @file{exgettext}, a wrapper around @command{gettext} to extract the
199 messages from the GCC sources and create @file{gcc.pot}, which is run
200 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
201 which messages should not be extracted.
204 The GCC testsuites (except for those for runtime libraries).
209 @subsection Configuration in the @file{gcc} Directory
211 The @file{gcc} directory is configured with an Autoconf-generated
212 script @file{configure}. The @file{configure} script is generated
213 from @file{configure.ac} and @file{aclocal.m4}. From the files
214 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
215 file @file{config.in}. The file @file{cstamp-h.in} is used as a
219 * Config Fragments:: Scripts used by @file{configure}.
220 * System Config:: The @file{config.build}, @file{config.host}, and
221 @file{config.gcc} files.
222 * Configuration Files:: Files created by running @file{configure}.
225 @node Config Fragments
226 @subsubsection Scripts Used by @file{configure}
228 @file{configure} uses some other scripts to help in its work:
231 @item The standard GNU @file{config.sub} and @file{config.guess}
232 files, kept in the top level directory, are used.
234 @item The file @file{config.gcc} is used to handle configuration
235 specific to the particular target machine. The file
236 @file{config.build} is used to handle configuration specific to the
237 particular build machine. The file @file{config.host} is used to handle
238 configuration specific to the particular host machine. (In general,
239 these should only be used for features that cannot reasonably be tested in
240 Autoconf feature tests.)
241 @xref{System Config, , The @file{config.build}; @file{config.host};
242 and @file{config.gcc} Files}, for details of the contents of these files.
244 @item Each language subdirectory has a file
245 @file{@var{language}/config-lang.in} that is used for
246 front-end-specific configuration. @xref{Front End Config, , The Front
247 End @file{config-lang.in} File}, for details of this file.
249 @item A helper script @file{configure.frag} is used as part of
250 creating the output of @file{configure}.
254 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
256 The @file{config.build} file contains specific rules for particular systems
257 which GCC is built on. This should be used as rarely as possible, as the
258 behavior of the build system can always be detected by autoconf.
260 The @file{config.host} file contains specific rules for particular systems
261 which GCC will run on. This is rarely needed.
263 The @file{config.gcc} file contains specific rules for particular systems
264 which GCC will generate code for. This is usually needed.
266 Each file has a list of the shell variables it sets, with descriptions, at the
269 FIXME: document the contents of these files, and what variables should
270 be set to control build, host and target configuration.
272 @include configfiles.texi
275 @subsection Build System in the @file{gcc} Directory
277 FIXME: describe the build system, including what is built in what
278 stages. Also list the various source files that are used in the build
279 process but aren't source files of GCC itself and so aren't documented
280 below (@pxref{Passes}).
282 @include makefile.texi
285 @subsection Library Source Files and Headers under the @file{gcc} Directory
287 FIXME: list here, with explanation, all the C source files and headers
288 under the @file{gcc} directory that aren't built into the GCC
289 executable but rather are part of runtime libraries and object files,
290 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
291 Headers Installed by GCC}, for more information about the
292 @file{ginclude} directory.
295 @subsection Headers Installed by GCC
297 In general, GCC expects the system C library to provide most of the
298 headers to be used with it. However, GCC will fix those headers if
299 necessary to make them work with GCC, and will install some headers
300 required of freestanding implementations. These headers are installed
301 in @file{@var{libsubdir}/include}. Headers for non-C runtime
302 libraries are also installed by GCC; these are not documented here.
303 (FIXME: document them somewhere.)
305 Several of the headers GCC installs are in the @file{ginclude}
306 directory. These headers, @file{iso646.h},
307 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
308 are installed in @file{@var{libsubdir}/include},
309 unless the target Makefile fragment (@pxref{Target Fragment})
310 overrides this by setting @code{USER_H}.
312 In addition to these headers and those generated by fixing system
313 headers to work with GCC, some other headers may also be installed in
314 @file{@var{libsubdir}/include}. @file{config.gcc} may set
315 @code{extra_headers}; this specifies additional headers under
316 @file{config} to be installed on some systems.
318 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
319 This is done to cope with command-line options that change the
320 representation of floating point numbers.
322 GCC also installs its own version of @code{<limits.h>}; this is generated
323 from @file{glimits.h}, together with @file{limitx.h} and
324 @file{limity.h} if the system also has its own version of
325 @code{<limits.h>}. (GCC provides its own header because it is
326 required of ISO C freestanding implementations, but needs to include
327 the system header from its own header as well because other standards
328 such as POSIX specify additional values to be defined in
329 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
330 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
331 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
332 needs fixing, @file{syslimits.h} is the fixed copy.
334 GCC can also install @code{<tgmath.h>}. It will do this when
335 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
338 @subsection Building Documentation
340 The main GCC documentation is in the form of manuals in Texinfo
341 format. These are installed in Info format; DVI versions may be
342 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
343 HTML versions by @samp{make html}. In addition, some man pages are
344 generated from the Texinfo manuals, there are some other text files
345 with miscellaneous documentation, and runtime libraries have their own
346 documentation outside the @file{gcc} directory. FIXME: document the
347 documentation for runtime libraries somewhere.
350 * Texinfo Manuals:: GCC manuals in Texinfo format.
351 * Man Page Generation:: Generating man pages from Texinfo manuals.
352 * Miscellaneous Docs:: Miscellaneous text files with documentation.
355 @node Texinfo Manuals
356 @subsubsection Texinfo Manuals
358 The manuals for GCC as a whole, and the C and C++ front ends, are in
359 files @file{doc/*.texi}. Other front ends have their own manuals in
360 files @file{@var{language}/*.texi}. Common files
361 @file{doc/include/*.texi} are provided which may be included in
362 multiple manuals; the following files are in @file{doc/include}:
366 The GNU Free Documentation License.
368 The section ``Funding Free Software''.
369 @item gcc-common.texi
370 Common definitions for manuals.
372 The GNU General Public License.
374 A copy of @file{texinfo.tex} known to work with the GCC manuals.
377 DVI-formatted manuals are generated by @samp{make dvi}, which uses
378 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
379 PDF-formatted manuals are generated by @samp{make pdf}, which uses
380 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
381 formatted manuals are generated by @samp{make html}. Info
382 manuals are generated by @samp{make info} (which is run as part of
383 a bootstrap); this generates the manuals in the source directory,
384 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
385 and they are included in release distributions.
387 Manuals are also provided on the GCC web site, in both HTML and
388 PostScript forms. This is done via the script
389 @file{maintainer-scripts/update_web_docs_svn}. Each manual to be
390 provided online must be listed in the definition of @code{MANUALS} in
391 that file; a file @file{@var{name}.texi} must only appear once in the
392 source tree, and the output manual must have the same name as the
393 source file. (However, other Texinfo files, included in manuals but
394 not themselves the root files of manuals, may have names that appear
395 more than once in the source tree.) The manual file
396 @file{@var{name}.texi} should only include other files in its own
397 directory or in @file{doc/include}. HTML manuals will be generated by
398 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
399 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
400 All Texinfo files that are parts of manuals must
401 be version-controlled, even if they are generated files, for the
402 generation of online manuals to work.
404 The installation manual, @file{doc/install.texi}, is also provided on
405 the GCC web site. The HTML version is generated by the script
406 @file{doc/install.texi2html}.
408 @node Man Page Generation
409 @subsubsection Man Page Generation
411 Because of user demand, in addition to full Texinfo manuals, man pages
412 are provided which contain extracts from those manuals. These man
413 pages are generated from the Texinfo manuals using
414 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
415 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
416 to @file{gcc.1}, but all the other man pages are generated from
419 Because many systems may not have the necessary tools installed to
420 generate the man pages, they are only generated if the
421 @file{configure} script detects that recent enough tools are
422 installed, and the Makefiles allow generating man pages to fail
423 without aborting the build. Man pages are also included in release
424 distributions. They are generated in the source directory.
426 Magic comments in Texinfo files starting @samp{@@c man} control what
427 parts of a Texinfo file go into a man page. Only a subset of Texinfo
428 is supported by @file{texi2pod.pl}, and it may be necessary to add
429 support for more Texinfo features to this script when generating new
430 man pages. To improve the man page output, some special Texinfo
431 macros are provided in @file{doc/include/gcc-common.texi} which
432 @file{texi2pod.pl} understands:
436 Use in the form @samp{@@table @@gcctabopt} for tables of options,
437 where for printed output the effect of @samp{@@code} is better than
438 that of @samp{@@option} but for man page output a different effect is
441 Use for summary lists of options in manuals.
443 Use at the end of each line inside @samp{@@gccoptlist}. This is
444 necessary to avoid problems with differences in how the
445 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
448 FIXME: describe the @file{texi2pod.pl} input language and magic
449 comments in more detail.
451 @node Miscellaneous Docs
452 @subsubsection Miscellaneous Documentation
454 In addition to the formal documentation that is installed by GCC,
455 there are several other text files in the @file{gcc} subdirectory
456 with miscellaneous documentation:
460 Notes on GCC's Native Language Support. FIXME: this should be part of
461 this manual rather than a separate file.
463 Notes on the Free Translation Project.
466 The GNU General Public License, Versions 2 and 3.
469 The GNU Lesser General Public License, Versions 2.1 and 3.
472 Change log files for various parts of GCC@.
474 Details of a few changes to the GCC front-end interface. FIXME: the
475 information in this file should be part of general documentation of
476 the front-end interface in this manual.
478 Information about new features in old versions of GCC@. (For recent
479 versions, the information is on the GCC web site.)
480 @item README.Portability
481 Information about portability issues when writing code in GCC@. FIXME:
482 why isn't this part of this manual or of the GCC Coding Conventions?
485 FIXME: document such files in subdirectories, at least @file{config},
486 @file{cp}, @file{objc}, @file{testsuite}.
489 @subsection Anatomy of a Language Front End
491 A front end for a language in GCC has the following parts:
495 A directory @file{@var{language}} under @file{gcc} containing source
496 files for that front end. @xref{Front End Directory, , The Front End
497 @file{@var{language}} Directory}, for details.
499 A mention of the language in the list of supported languages in
500 @file{gcc/doc/install.texi}.
502 A mention of the name under which the language's runtime library is
503 recognized by @option{--enable-shared=@var{package}} in the
504 documentation of that option in @file{gcc/doc/install.texi}.
506 A mention of any special prerequisites for building the front end in
507 the documentation of prerequisites in @file{gcc/doc/install.texi}.
509 Details of contributors to that front end in
510 @file{gcc/doc/contrib.texi}. If the details are in that front end's
511 own manual then there should be a link to that manual's list in
514 Information about support for that language in
515 @file{gcc/doc/frontends.texi}.
517 Information about standards for that language, and the front end's
518 support for them, in @file{gcc/doc/standards.texi}. This may be a
519 link to such information in the front end's own manual.
521 Details of source file suffixes for that language and @option{-x
522 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
524 Entries in @code{default_compilers} in @file{gcc.c} for source file
525 suffixes for that language.
527 Preferably testsuites, which may be under @file{gcc/testsuite} or
528 runtime library directories. FIXME: document somewhere how to write
531 Probably a runtime library for the language, outside the @file{gcc}
532 directory. FIXME: document this further.
534 Details of the directories of any runtime libraries in
535 @file{gcc/doc/sourcebuild.texi}.
537 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
538 to check just the compiler or the compiler and runtime library for the
542 If the front end is added to the official GCC source repository, the
543 following are also necessary:
547 At least one Bugzilla component for bugs in that front end and runtime
548 libraries. This category needs to be added to the Bugzilla database.
550 Normally, one or more maintainers of that front end listed in
553 Mentions on the GCC web site in @file{index.html} and
554 @file{frontends.html}, with any relevant links on
555 @file{readings.html}. (Front ends that are not an official part of
556 GCC may also be listed on @file{frontends.html}, with relevant links.)
558 A news item on @file{index.html}, and possibly an announcement on the
559 @email{gcc-announce@@gcc.gnu.org} mailing list.
561 The front end's manuals should be mentioned in
562 @file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals})
563 and the online manuals should be linked to from
564 @file{onlinedocs/index.html}.
566 Any old releases or CVS repositories of the front end, before its
567 inclusion in GCC, should be made available on the GCC FTP site
568 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
570 The release and snapshot script @file{maintainer-scripts/gcc_release}
571 should be updated to generate appropriate tarballs for this front end.
573 If this front end includes its own version files that include the
574 current date, @file{maintainer-scripts/update_version} should be
579 * Front End Directory:: The front end @file{@var{language}} directory.
580 * Front End Config:: The front end @file{config-lang.in} file.
581 * Front End Makefile:: The front end @file{Make-lang.in} file.
584 @node Front End Directory
585 @subsubsection The Front End @file{@var{language}} Directory
587 A front end @file{@var{language}} directory contains the source files
588 of that front end (but not of any runtime libraries, which should be
589 outside the @file{gcc} directory). This includes documentation, and
590 possibly some subsidiary programs built alongside the front end.
591 Certain files are special and other parts of the compiler depend on
596 This file is required in all language subdirectories. @xref{Front End
597 Config, , The Front End @file{config-lang.in} File}, for details of
600 This file is required in all language subdirectories. @xref{Front End
601 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
604 This file registers the set of switches that the front end accepts on
605 the command line, and their @option{--help} text. @xref{Options}.
607 This file provides entries for @code{default_compilers} in
608 @file{gcc.c} which override the default of giving an error that a
609 compiler for that language is not installed.
610 @item @var{language}-tree.def
611 This file, which need not exist, defines any language-specific tree
615 @node Front End Config
616 @subsubsection The Front End @file{config-lang.in} File
618 Each language subdirectory contains a @file{config-lang.in} file. In
619 addition the main directory contains @file{c-config-lang.in}, which
620 contains limited information for the C language. This file is a shell
621 script that may define some variables describing the language:
625 This definition must be present, and gives the name of the language
626 for some purposes such as arguments to @option{--enable-languages}.
628 If defined, this variable lists (space-separated) language front ends
629 other than C that this front end requires to be enabled (with the
630 names given being their @code{language} settings). For example, the
631 Java front end depends on the C++ front end, so sets
632 @samp{lang_requires=c++}.
633 @item subdir_requires
634 If defined, this variable lists (space-separated) front end directories
635 other than C that this front end requires to be present. For example,
636 the Objective-C++ front end uses source files from the C++ and
637 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
639 If defined, this variable lists (space-separated) targets in the top
640 level @file{Makefile} to build the runtime libraries for this
641 language, such as @code{target-libobjc}.
643 If defined, this variable lists (space-separated) top level
644 directories (parallel to @file{gcc}), apart from the runtime libraries,
645 that should not be configured if this front end is not built.
646 @item build_by_default
647 If defined to @samp{no}, this language front end is not built unless
648 enabled in a @option{--enable-languages} argument. Otherwise, front
649 ends are built by default, subject to any special logic in
650 @file{configure.ac} (as is present to disable the Ada front end if the
651 Ada compiler is not already installed).
653 If defined to @samp{yes}, this front end is built in stage1 of the
654 bootstrap. This is only relevant to front ends written in their own
657 If defined, a space-separated list of compiler executables that will
658 be run by the driver. The names here will each end
659 with @samp{\$(exeext)}.
661 If defined, a space-separated list of files that should be generated
662 by @file{configure} substituting values in them. This mechanism can
663 be used to create a file @file{@var{language}/Makefile} from
664 @file{@var{language}/Makefile.in}, but this is deprecated, building
665 everything from the single @file{gcc/Makefile} is preferred.
667 If defined, a space-separated list of files that should be scanned by
668 @file{gengtype.c} to generate the garbage collection tables and routines for
669 this language. This excludes the files that are common to all front
670 ends. @xref{Type Information}.
674 @node Front End Makefile
675 @subsubsection The Front End @file{Make-lang.in} File
677 Each language subdirectory contains a @file{Make-lang.in} file. It contains
678 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
679 setting of @code{language} in @file{config-lang.in}) for the following
680 values of @code{@var{hook}}, and any other Makefile rules required to
681 build those targets (which may if necessary use other Makefiles
682 specified in @code{outputs} in @file{config-lang.in}, although this is
683 deprecated). It also adds any testsuite targets that can use the
684 standard rule in @file{gcc/Makefile.in} to the variable
691 FIXME: exactly what goes in each of these targets?
693 Build an @command{etags} @file{TAGS} file in the language subdirectory
696 Build info documentation for the front end, in the build directory.
697 This target is only called by @samp{make bootstrap} if a suitable
698 version of @command{makeinfo} is available, so does not need to check
699 for this, and should fail if an error occurs.
701 Build DVI documentation for the front end, in the build directory.
702 This should be done using @code{$(TEXI2DVI)}, with appropriate
703 @option{-I} arguments pointing to directories of included files.
705 Build PDF documentation for the front end, in the build directory.
706 This should be done using @code{$(TEXI2PDF)}, with appropriate
707 @option{-I} arguments pointing to directories of included files.
709 Build HTML documentation for the front end, in the build directory.
711 Build generated man pages for the front end from Texinfo manuals
712 (@pxref{Man Page Generation}), in the build directory. This target
713 is only called if the necessary tools are available, but should ignore
714 errors so as not to stop the build if errors occur; man pages are
715 optional and the tools involved may be installed in a broken way.
717 Install everything that is part of the front end, apart from the
718 compiler executables listed in @code{compilers} in
719 @file{config-lang.in}.
721 Install info documentation for the front end, if it is present in the
722 source directory. This target should have dependencies on info files
723 that should be installed.
725 Install man pages for the front end. This target should ignore
728 Install headers needed for plugins.
730 Copies its dependencies into the source directory. This generally should
731 be used for generated files such as Bison output files which are not
732 version-controlled, but should be included in any release tarballs. This
733 target will be executed during a bootstrap if
734 @samp{--enable-generated-files-in-srcdir} was specified as a
735 @file{configure} option.
738 Copies its dependencies into the source directory. These targets will be
739 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
740 was specified as a @file{configure} option.
742 Uninstall files installed by installing the compiler. This is
743 currently documented not to be supported, so the hook need not do
748 @itemx maintainer-clean
749 The language parts of the standard GNU
750 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
751 Users, standards, GNU Coding Standards}, for details of the standard
752 targets. For GCC, @code{maintainer-clean} should delete
753 all generated files in the source directory that are not version-controlled,
754 but should not delete anything that is.
757 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
758 to a list of host object files that are used by that language.
761 @subsection Anatomy of a Target Back End
763 A back end for a target architecture in GCC has the following parts:
767 A directory @file{@var{machine}} under @file{gcc/config}, containing a
768 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
769 , Machine Descriptions}), header files @file{@var{machine}.h} and
770 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
771 (@pxref{Target Macros, , Target Description Macros and Functions}),
772 possibly a target Makefile fragment @file{t-@var{machine}}
773 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
774 some other files. The names of these files may be changed from the
775 defaults given by explicit specifications in @file{config.gcc}.
777 If necessary, a file @file{@var{machine}-modes.def} in the
778 @file{@var{machine}} directory, containing additional machine modes to
779 represent condition codes. @xref{Condition Code}, for further details.
781 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
782 directory, containing a list of target-specific options. You can also
783 add other option files using the @code{extra_options} variable in
784 @file{config.gcc}. @xref{Options}.
786 Entries in @file{config.gcc} (@pxref{System Config, , The
787 @file{config.gcc} File}) for the systems with this target
790 Documentation in @file{gcc/doc/invoke.texi} for any command-line
791 options supported by this target (@pxref{Run-time Target, , Run-time
792 Target Specification}). This means both entries in the summary table
793 of options and details of the individual options.
795 Documentation in @file{gcc/doc/extend.texi} for any target-specific
796 attributes supported (@pxref{Target Attributes, , Defining
797 target-specific uses of @code{__attribute__}}), including where the
798 same attribute is already supported on some targets, which are
799 enumerated in the manual.
801 Documentation in @file{gcc/doc/extend.texi} for any target-specific
804 Documentation in @file{gcc/doc/extend.texi} of any target-specific
805 built-in functions supported.
807 Documentation in @file{gcc/doc/extend.texi} of any target-specific
808 format checking styles supported.
810 Documentation in @file{gcc/doc/md.texi} of any target-specific
811 constraint letters (@pxref{Machine Constraints, , Constraints for
812 Particular Machines}).
814 A note in @file{gcc/doc/contrib.texi} under the person or people who
815 contributed the target support.
817 Entries in @file{gcc/doc/install.texi} for all target triplets
818 supported with this target architecture, giving details of any special
819 notes about installation for this target, or saying that there are no
820 special notes if there are none.
822 Possibly other support outside the @file{gcc} directory for runtime
823 libraries. FIXME: reference docs for this. The @code{libstdc++} porting
824 manual needs to be installed as info for this to work, or to be a
825 chapter of this manual.
828 If the back end is added to the official GCC source repository, the
829 following are also necessary:
833 An entry for the target architecture in @file{readings.html} on the
834 GCC web site, with any relevant links.
836 Details of the properties of the back end and target architecture in
837 @file{backends.html} on the GCC web site.
839 A news item about the contribution of support for that target
840 architecture, in @file{index.html} on the GCC web site.
842 Normally, one or more maintainers of that target listed in
843 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
844 but it would be unusual to add support for a target that does not have
845 a maintainer when support is added.
847 Target triplets covering all @file{config.gcc} stanzas for the target,
848 in the list in @file{contrib/config-list.mk}.
854 GCC contains several testsuites to help maintain compiler quality.
855 Most of the runtime libraries and language front ends in GCC have
856 testsuites. Currently only the C language testsuites are documented
857 here; FIXME: document the others.
860 * Test Idioms:: Idioms used in testsuite code.
861 * Test Directives:: Directives used within DejaGnu tests.
862 * Ada Tests:: The Ada language testsuites.
863 * C Tests:: The C language testsuites.
864 * libgcj Tests:: The Java library testsuites.
865 * LTO Testing:: Support for testing link-time optimizations.
866 * gcov Testing:: Support for testing gcov.
867 * profopt Testing:: Support for testing profile-directed optimizations.
868 * compat Testing:: Support for testing binary compatibility.
869 * Torture Tests:: Support for torture testing using multiple options.
873 @section Idioms Used in Testsuite Code
875 In general, C testcases have a trailing @file{-@var{n}.c}, starting
876 with @file{-1.c}, in case other testcases with similar names are added
877 later. If the test is a test of some well-defined feature, it should
878 have a name referring to that feature such as
879 @file{@var{feature}-1.c}. If it does not test a well-defined feature
880 but just happens to exercise a bug somewhere in the compiler, and a
881 bug report has been filed for this bug in the GCC bug database,
882 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
883 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
884 and previously more generally, test cases are named after the date on
885 which they were added. This allows people to tell at a glance whether
886 a test failure is because of a recently found bug that has not yet
887 been fixed, or whether it may be a regression, but does not give any
888 other information about the bug or where discussion of it may be
889 found. Some other language testsuites follow similar conventions.
891 In the @file{gcc.dg} testsuite, it is often necessary to test that an
892 error is indeed a hard error and not just a warning---for example,
893 where it is a constraint violation in the C standard, which must
894 become an error with @option{-pedantic-errors}. The following idiom,
895 where the first line shown is line @var{line} of the file and the line
896 that generates the error, is used for this:
899 /* @{ dg-bogus "warning" "warning in place of error" @} */
900 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
903 It may be necessary to check that an expression is an integer constant
904 expression and has a certain value. To check that @code{@var{E}} has
905 value @code{@var{V}}, an idiom similar to the following is used:
908 char x[((E) == (V) ? 1 : -1)];
911 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
912 assertions about the types of expressions. See, for example,
913 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
914 exact rules for the types of conditional expressions in the C
915 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
917 It is useful to be able to test that optimizations are being made
918 properly. This cannot be done in all cases, but it can be done where
919 the optimization will lead to code being optimized away (for example,
920 where flow analysis or alias analysis should show that certain code
921 cannot be called) or to functions not being called because they have
922 been expanded as built-in functions. Such tests go in
923 @file{gcc.c-torture/execute}. Where code should be optimized away, a
924 call to a nonexistent function such as @code{link_failure ()} may be
925 inserted; a definition
938 will also be needed so that linking still succeeds when the test is
939 run without optimization. When all calls to a built-in function
940 should have been optimized and no calls to the non-built-in version of
941 the function should remain, that function may be defined as
942 @code{static} to call @code{abort ()} (although redeclaring a function
943 as static may not work on all targets).
945 All testcases must be portable. Target-specific testcases must have
946 appropriate code to avoid causing failures on unsupported systems;
947 unfortunately, the mechanisms for this differ by directory.
949 FIXME: discuss non-C testsuites here.
951 @node Test Directives
952 @section Directives used within DejaGnu tests
955 * Directives:: Syntax and descriptions of test directives.
956 * Selectors:: Selecting targets to which a test applies.
957 * Effective-Target Keywords:: Keywords describing target attributes.
958 * Add Options:: Features for @code{dg-add-options}
959 * Require Support:: Variants of @code{dg-require-@var{support}}
960 * Final Actions:: Commands for use in @code{dg-final}
964 @subsection Syntax and Descriptions of test directives
966 Test directives appear within comments in a test source file and begin
967 with @code{dg-}. Some of these are defined within DejaGnu and others
968 are local to the GCC testsuite.
970 The order in which test directives appear in a test can be important:
971 directives local to GCC sometimes override information used by the
972 DejaGnu directives, which know nothing about the GCC directives, so the
973 DejaGnu directives must precede GCC directives.
975 Several test directives include selectors (@pxref{Selectors, , })
976 which are usually preceded by the keyword @code{target} or @code{xfail}.
978 @subsubsection Specify how to build the test
981 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
982 @var{do-what-keyword} specifies how the test is compiled and whether
983 it is executed. It is one of:
987 Compile with @option{-E} to run only the preprocessor.
989 Compile with @option{-S} to produce an assembly code file.
991 Compile with @option{-c} to produce a relocatable object file.
993 Compile, assemble, and link to produce an executable file.
995 Produce and run an executable file, which is expected to return
999 The default is @code{compile}. That can be overridden for a set of
1000 tests by redefining @code{dg-do-what-default} within the @code{.exp}
1001 file for those tests.
1003 If the directive includes the optional @samp{@{ target @var{selector} @}}
1004 then the test is skipped unless the target system matches the
1007 If @var{do-what-keyword} is @code{run} and the directive includes
1008 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1009 then the test is expected to fail. The @code{xfail} clause is ignored
1010 for other values of @var{do-what-keyword}; those tests can use
1011 directive @code{dg-xfail-if}.
1014 @subsubsection Specify additional compiler options
1017 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1018 This DejaGnu directive provides a list of compiler options, to be used
1019 if the target system matches @var{selector}, that replace the default
1020 options used for this set of tests.
1022 @item @{ dg-add-options @var{feature} @dots{} @}
1023 Add any compiler options that are needed to access certain features.
1024 This directive does nothing on targets that enable the features by
1025 default, or that don't provide them at all. It must come after
1026 all @code{dg-options} directives.
1027 For supported values of @var{feature} see @ref{Add Options, ,}.
1029 @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @}
1030 This directive provides a list of compiler options, to be used
1031 if the target system matches @var{selector}, that are added to the default
1032 options used for this set of tests.
1035 @subsubsection Modify the test timeout value
1037 The normal timeout limit, in seconds, is found by searching the
1041 @item the value defined by an earlier @code{dg-timeout} directive in
1044 @item variable @var{tool_timeout} defined by the set of tests
1046 @item @var{gcc},@var{timeout} set in the target board
1052 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1053 Set the time limit for the compilation and for the execution of the test
1054 to the specified number of seconds.
1056 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1057 Multiply the normal time limit for compilation and execution of the test
1058 by the specified floating-point factor.
1061 @subsubsection Skip a test for some targets
1064 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1065 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1066 each element is a string of zero or more GCC options.
1067 Skip the test if all of the following conditions are met:
1069 @item the test system is included in @var{selector}
1071 @item for at least one of the option strings in @var{include-opts},
1072 every option from that string is in the set of options with which
1073 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1074 that matches any options; that is the default if @var{include-opts} is
1077 @item for each of the option strings in @var{exclude-opts}, at least one
1078 option from that string is not in the set of options with which the test
1079 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1080 that is the default if @var{exclude-opts} is not specified
1083 For example, to skip a test if option @code{-Os} is present:
1086 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
1089 To skip a test if both options @code{-O2} and @code{-g} are present:
1092 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
1095 To skip a test if either @code{-O2} or @code{-O3} is present:
1098 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
1101 To skip a test unless option @code{-Os} is present:
1104 /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
1107 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1108 but not if @code{-fpic} is also present:
1111 /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1114 @item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @}
1115 Skip the test if the test target, including current multilib flags,
1116 is not covered by the effective-target keyword.
1117 If the directive includes the optional @samp{@{ @var{selector} @}}
1118 then the effective-target test is only performed if the target system
1119 matches the @var{selector}.
1120 This directive must appear after any @code{dg-do} directive in the test
1121 and before any @code{dg-additional-sources} directive.
1122 @xref{Effective-Target Keywords, , }.
1124 @item @{ dg-require-@var{support} args @}
1125 Skip the test if the target does not provide the required support.
1126 These directives must appear after any @code{dg-do} directive in the test
1127 and before any @code{dg-additional-sources} directive.
1128 They require at least one argument, which can be an empty string if the
1129 specific procedure does not examine the argument.
1130 @xref{Require Support, , }, for a complete list of these directives.
1133 @subsubsection Expect a test to fail for some targets
1136 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1137 Expect the test to fail if the conditions (which are the same as for
1138 @code{dg-skip-if}) are met. This does not affect the execute step.
1140 @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1141 Expect the execute step of a test to fail if the conditions (which are
1142 the same as for @code{dg-skip-if}) are met.
1145 @subsubsection Expect the test executable to fail
1148 @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1149 Expect the test executable to return a nonzero exit status if the
1150 conditions (which are the same as for @code{dg-skip-if}) are met.
1153 @subsubsection Verify compiler messages
1156 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1157 This DejaGnu directive appears on a source line that is expected to get
1158 an error message, or else specifies the source line associated with the
1159 message. If there is no message for that line or if the text of that
1160 message is not matched by @var{regexp} then the check fails and
1161 @var{comment} is included in the @code{FAIL} message. The check does
1162 not look for the string @samp{error} unless it is part of @var{regexp}.
1164 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1165 This DejaGnu directive appears on a source line that is expected to get
1166 a warning message, or else specifies the source line associated with the
1167 message. If there is no message for that line or if the text of that
1168 message is not matched by @var{regexp} then the check fails and
1169 @var{comment} is included in the @code{FAIL} message. The check does
1170 not look for the string @samp{warning} unless it is part of @var{regexp}.
1172 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1173 The line is expected to get a message other than an error or warning.
1174 If there is no message for that line or if the text of that message is
1175 not matched by @var{regexp} then the check fails and @var{comment} is
1176 included in the @code{FAIL} message.
1178 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1179 This DejaGnu directive appears on a source line that should not get a
1180 message matching @var{regexp}, or else specifies the source line
1181 associated with the bogus message. It is usually used with @samp{xfail}
1182 to indicate that the message is a known problem for a particular set of
1185 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1186 This DejaGnu directive indicates that the test is expected to fail due
1187 to compiler messages that are not handled by @samp{dg-error},
1188 @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail}
1189 has the same effect as @samp{target}.
1191 @item @{ dg-prune-output @var{regexp} @}
1192 Prune messages matching @var{regexp} from the test output.
1195 @subsubsection Verify output of the test executable
1198 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1199 This DejaGnu directive compares @var{regexp} to the combined output
1200 that the test executable writes to @file{stdout} and @file{stderr}.
1203 @subsubsection Specify additional files for a test
1206 @item @{ dg-additional-files "@var{filelist}" @}
1207 Specify additional files, other than source files, that must be copied
1208 to the system where the compiler runs.
1210 @item @{ dg-additional-sources "@var{filelist}" @}
1211 Specify additional source files to appear in the compile line
1212 following the main test file.
1215 @subsubsection Add checks at the end of a test
1218 @item @{ dg-final @{ @var{local-directive} @} @}
1219 This DejaGnu directive is placed within a comment anywhere in the
1220 source file and is processed after the test has been compiled and run.
1221 Multiple @samp{dg-final} commands are processed in the order in which
1222 they appear in the source file. @xref{Final Actions, , }, for a list
1223 of directives that can be used within @code{dg-final}.
1227 @subsection Selecting targets to which a test applies
1229 Several test directives include @var{selector}s to limit the targets
1230 for which a test is run or to declare that a test is expected to fail
1231 on particular targets.
1235 @item one or more target triplets, possibly including wildcard characters
1236 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1237 @item a logical expression
1241 context, the selector specifies whether a test is skipped and reported
1242 as unsupported or is expected to fail. Use @samp{*-*-*} to match any
1245 A selector expression appears within curly braces and uses a single
1246 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
1247 operand is another selector expression, an effective-target keyword,
1248 a single target triplet, or a list of target triplets within quotes or
1249 curly braces. For example:
1252 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1253 @{ target @{ powerpc*-*-* && lp64 @} @}
1254 @{ xfail @{ lp64 || vect_no_align @} @}
1257 @node Effective-Target Keywords
1258 @subsection Keywords describing target attributes
1260 Effective-target keywords identify sets of targets that support
1261 particular functionality. They are used to limit tests to be run only
1262 for particular targets, or to specify that particular sets of targets
1263 are expected to fail some tests.
1265 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1266 the GCC testsuite, with the exception of those that are documented as
1267 being local to a particular test directory.
1269 The @samp{effective target} takes into account all of the compiler options
1270 with which the test will be compiled, including the multilib options.
1271 By convention, keywords ending in @code{_nocache} can also include options
1272 specified for the particular test in an earlier @code{dg-options} or
1273 @code{dg-add-options} directive.
1275 @subsubsection Data type sizes
1279 Target has 32-bit @code{int}, @code{long}, and pointers.
1282 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1285 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1289 Target has 64-bit @code{double}.
1292 Target has @code{double} that is 64 bits or longer.
1295 Target has @code{int} that is at 32 bits or longer.
1298 Target has @code{int} that is 16 bits or shorter.
1301 Target supports @code{double} that is longer than @code{float}.
1303 @item large_long_double
1304 Target supports @code{long double} that is longer than @code{double}.
1307 Target has pointers that are 32 bits or longer.
1310 Target supports array and structure sizes that are 32 bits or longer.
1313 Target has @code{wchar_t} that is at least 4 bytes.
1316 @subsubsection Fortran-specific attributes
1319 @item fortran_integer_16
1320 Target supports Fortran @code{integer} that is 16 bytes or longer.
1322 @item fortran_large_int
1323 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1325 @item fortran_large_real
1326 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1329 @subsubsection Vector-specific attributes
1332 @item vect_condition
1333 Target supports vector conditional operations.
1336 Target supports hardware vectors of @code{double}.
1339 Target supports hardware vectors of @code{float}.
1342 Target supports hardware vectors of @code{int}.
1345 Target supports hardware vectors of @code{long}.
1347 @item vect_long_long
1348 Target supports hardware vectors of @code{long long}.
1350 @item vect_aligned_arrays
1351 Target aligns arrays to vector alignment boundary.
1353 @item vect_hw_misalign
1354 Target supports a vector misalign access.
1357 Target does not support a vector alignment mechanism.
1359 @item vect_no_int_max
1360 Target does not support a vector max instruction on @code{int}.
1362 @item vect_no_int_add
1363 Target does not support a vector add instruction on @code{int}.
1365 @item vect_no_bitwise
1366 Target does not support vector bitwise instructions.
1368 @item vect_char_mult
1369 Target supports @code{vector char} multiplication.
1371 @item vect_short_mult
1372 Target supports @code{vector short} multiplication.
1375 Target supports @code{vector int} multiplication.
1377 @item vect_extract_even_odd
1378 Target supports vector even/odd element extraction.
1380 @item vect_extract_even_odd_wide
1381 Target supports vector even/odd element extraction of vectors with elements
1382 @code{SImode} or larger.
1384 @item vect_interleave
1385 Target supports vector interleaving.
1388 Target supports vector interleaving and extract even/odd.
1390 @item vect_strided_wide
1391 Target supports vector interleaving and extract even/odd for wide
1395 Target supports vector permutation.
1398 Target supports a hardware vector shift operation.
1400 @item vect_widen_sum_hi_to_si
1401 Target supports a vector widening summation of @code{short} operands
1402 into @code{int} results, or can promote (unpack) from @code{short}
1405 @item vect_widen_sum_qi_to_hi
1406 Target supports a vector widening summation of @code{char} operands
1407 into @code{short} results, or can promote (unpack) from @code{char}
1410 @item vect_widen_sum_qi_to_si
1411 Target supports a vector widening summation of @code{char} operands
1412 into @code{int} results.
1414 @item vect_widen_mult_qi_to_hi
1415 Target supports a vector widening multiplication of @code{char} operands
1416 into @code{short} results, or can promote (unpack) from @code{char} to
1417 @code{short} and perform non-widening multiplication of @code{short}.
1419 @item vect_widen_mult_hi_to_si
1420 Target supports a vector widening multiplication of @code{short} operands
1421 into @code{int} results, or can promote (unpack) from @code{short} to
1422 @code{int} and perform non-widening multiplication of @code{int}.
1425 Target supports a vector dot-product of @code{signed char}.
1428 Target supports a vector dot-product of @code{unsigned char}.
1431 Target supports a vector dot-product of @code{signed short}.
1434 Target supports a vector dot-product of @code{unsigned short}.
1436 @item vect_pack_trunc
1437 Target supports a vector demotion (packing) of @code{short} to @code{char}
1438 and from @code{int} to @code{short} using modulo arithmetic.
1441 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1442 and from @code{char} to @code{int}.
1444 @item vect_intfloat_cvt
1445 Target supports conversion from @code{signed int} to @code{float}.
1447 @item vect_uintfloat_cvt
1448 Target supports conversion from @code{unsigned int} to @code{float}.
1450 @item vect_floatint_cvt
1451 Target supports conversion from @code{float} to @code{signed int}.
1453 @item vect_floatuint_cvt
1454 Target supports conversion from @code{float} to @code{unsigned int}.
1457 @subsubsection Thread Local Storage attributes
1461 Target supports thread-local storage.
1464 Target supports native (rather than emulated) thread-local storage.
1467 Test system supports executing TLS executables.
1470 @subsubsection Decimal floating point attributes
1474 Targets supports compiling decimal floating point extension to C.
1477 Including the options used to compile this particular test, the
1478 target supports compiling decimal floating point extension to C.
1481 Test system can execute decimal floating point tests.
1484 Including the options used to compile this particular test, the
1485 test system can execute decimal floating point tests.
1488 Target generates decimal floating point instructions with current options.
1491 @subsubsection ARM-specific attributes
1495 ARM target generates 32-bit code.
1498 ARM target adheres to the ABI for the ARM Architecture.
1500 @item arm_hard_vfp_ok
1501 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
1502 Some multilibs may be incompatible with these options.
1505 ARM target supports @code{-mcpu=iwmmxt}.
1506 Some multilibs may be incompatible with this option.
1509 ARM target supports generating NEON instructions.
1512 Test system supports executing NEON instructions.
1515 @anchor{arm_neon_ok}
1516 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
1517 options. Some multilibs may be incompatible with these options.
1519 @item arm_neon_fp16_ok
1520 @anchor{arm_neon_fp16_ok}
1521 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
1522 options. Some multilibs may be incompatible with these options.
1525 ARM target generates Thumb-1 code for @code{-mthumb}.
1528 ARM target generates Thumb-2 code for @code{-mthumb}.
1531 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
1532 Some multilibs may be incompatible with these options.
1535 @subsubsection MIPS-specific attributes
1539 MIPS target supports 64-bit instructions.
1542 MIPS target does not produce MIPS16 code.
1544 @item mips16_attribute
1545 MIPS target can generate MIPS16 code.
1548 MIPS target is a Loongson-2E or -2F target using an ABI that supports
1549 the Loongson vector modes.
1551 @item mips_newabi_large_long_double
1552 MIPS target supports @code{long double} larger than @code{double}
1553 when using the new ABI.
1555 @item mpaired_single
1556 MIPS target supports @code{-mpaired-single}.
1559 @subsubsection PowerPC-specific attributes
1563 Test system supports executing 64-bit instructions.
1565 @item powerpc_altivec
1566 PowerPC target supports AltiVec.
1568 @item powerpc_altivec_ok
1569 PowerPC target supports @code{-maltivec}.
1572 PowerPC target supports floating-point registers.
1574 @item powerpc_hard_double
1575 PowerPC target supports hardware double-precision floating-point.
1577 @item powerpc_ppu_ok
1578 PowerPC target supports @code{-mcpu=cell}.
1581 PowerPC target supports PowerPC SPE.
1583 @item powerpc_spe_nocache
1584 Including the options used to compile this particular test, the
1585 PowerPC target supports PowerPC SPE.
1588 PowerPC target supports PowerPC SPU.
1590 @item spu_auto_overlay
1591 SPU target has toolchain that supports automatic overlay generation.
1593 @item powerpc_vsx_ok
1594 PowerPC target supports @code{-mvsx}.
1596 @item powerpc_405_nocache
1597 Including the options used to compile this particular test, the
1598 PowerPC target supports PowerPC 405.
1601 PowerPC target supports executing AltiVec instructions.
1604 @subsubsection Other hardware attributes
1608 Target supports compiling @code{avx} instructions.
1611 Target supports the execution of @code{avx} instructions.
1614 Test system can execute AltiVec and Cell PPU instructions.
1617 Target uses a ColdFire FPU.
1620 Target supports FPU instructions.
1623 Target supports compiling @code{sse} instructions.
1626 Target supports the execution of @code{sse} instructions.
1629 Target supports compiling @code{sse2} instructions.
1632 Target supports the execution of @code{sse2} instructions.
1634 @item sync_char_short
1635 Target supports atomic operations on @code{char} and @code{short}.
1638 Target supports atomic operations on @code{int} and @code{long}.
1641 Test environment appears to run executables on a simulator that
1642 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
1643 or @code{EM_SPARCV9} executables.
1645 @item vect_cmdline_needed
1646 Target requires a command line argument to enable a SIMD instruction set.
1649 @subsubsection Environment attributes
1653 The language for the compiler under test is C.
1656 The language for the compiler under test is C++.
1659 Target provides a full C99 runtime.
1661 @item correct_iso_cpp_string_wchar_protos
1662 Target @code{string.h} and @code{wchar.h} headers provide C++ required
1663 overloads for @code{strchr} etc. functions.
1665 @item dummy_wcsftime
1666 Target uses a dummy @code{wcsftime} function that always returns zero.
1669 Target can truncate a file from a file descriptor, as used by
1670 @file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or
1674 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
1675 Effectively, it is a target which supports no extra headers or libraries
1676 other than what is considered essential.
1679 Target supports constructors with initialization priority arguments.
1681 @item inttypes_types
1682 Target has the basic signed and unsigned types in @code{inttypes.h}.
1683 This is for tests that GCC's notions of these types agree with those
1684 in the header, as some systems have only @code{inttypes.h}.
1687 Target might have errors of a few ULP in string to floating-point
1688 conversion functions and overflow is not always detected correctly by
1692 Target supports @code{mmap}.
1695 Target supports Newlib.
1698 Target provides @code{pow10} function.
1701 Target can compile using @code{pthread.h} with no errors or warnings.
1704 Target has @code{pthread.h}.
1706 @item run_expensive_tests
1707 Expensive testcases (usually those that consume excessive amounts of CPU
1708 time) should be run on this target. This can be enabled by setting the
1709 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
1712 Test system runs executables on a simulator (i.e. slowly) rather than
1713 hardware (i.e. fast).
1716 Target has the basic signed and unsigned C types in @code{stdint.h}.
1717 This will be obsolete when GCC ensures a working @code{stdint.h} for
1721 Target supports trampolines.
1724 Target supports uClibc.
1727 Target does not use a status wrapper.
1729 @item vxworks_kernel
1730 Target is a VxWorks kernel.
1733 Target is a VxWorks RTP.
1736 Target supports wide characters.
1739 @subsubsection Other attributes
1742 @item automatic_stack_alignment
1743 Target supports automatic stack alignment.
1746 Target uses @code{__cxa_atexit}.
1748 @item default_packed
1749 Target has packed layout of structure members by default.
1752 Target supports Graphite optimizations.
1755 Target supports fixed-point extension to C.
1758 Target supports OpenMP via @option{-fopenmp}.
1761 Target supports @option{-fpic} and @option{-fPIC}.
1764 Target supports @option{-freorder-blocks-and-partition}.
1766 @item fstack_protector
1767 Target supports @option{-fstack-protector}.
1770 Target uses GNU @command{as}.
1773 Target supports @option{--gc-sections}.
1776 Target uses GNU @command{ld}.
1778 @item keeps_null_pointer_checks
1779 Target keeps null pointer checks, either due to the use of
1780 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
1783 Compiler has been configured to support link-time optimization (LTO).
1785 @item named_sections
1786 Target supports named sections.
1788 @item natural_alignment_32
1789 Target uses natural alignment (aligned to type size) for types of
1792 @item target_natural_alignment_64
1793 Target uses natural alignment (aligned to type size) for types of
1797 Target does not generate PIC by default.
1799 @item pcc_bitfield_type_matters
1800 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
1802 @item pe_aligned_commons
1803 Target supports @option{-mpe-aligned-commons}.
1806 Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}.
1808 @item section_anchors
1809 Target supports section anchors.
1812 Target defaults to short enums.
1815 Target supports @option{-static}.
1817 @item static_libgfortran
1818 Target supports statically linking @samp{libgfortran}.
1820 @item string_merging
1821 Target supports merging string constants at link time.
1824 Target supports compiling and assembling UCN.
1827 Including the options used to compile this particular test, the
1828 target supports compiling and assembling UCN.
1830 @item unaligned_stack
1831 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
1832 or equal to the required vector alignment.
1834 @item vector_alignment_reachable
1835 Vector alignment is reachable for types of 32 bits or less.
1837 @item vector_alignment_reachable_for_64bit
1838 Vector alignment is reachable for types of 64 bits or less.
1840 @item wchar_t_char16_t_compatible
1841 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
1843 @item wchar_t_char32_t_compatible
1844 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
1847 @subsubsection Local to tests in @code{gcc.target/i386}
1851 Target supports compiling @code{3dnow} instructions.
1854 Target supports compiling @code{aes} instructions.
1857 Target supports compiling @code{fma4} instructions.
1859 @item ms_hook_prologue
1860 Target supports attribute @code{ms_hook_prologue}.
1863 Target supports compiling @code{pclmul} instructions.
1866 Target supports compiling @code{sse3} instructions.
1869 Target supports compiling @code{sse4} instructions.
1872 Target supports compiling @code{sse4a} instructions.
1875 Target supports compiling @code{ssse3} instructions.
1878 Target supports compiling @code{vaes} instructions.
1881 Target supports compiling @code{vpclmul} instructions.
1884 Target supports compiling @code{xop} instructions.
1887 @subsubsection Local to tests in @code{gcc.target/spu/ea}
1891 Target @code{__ea} library functions are available.
1894 @subsubsection Local to tests in @code{gcc.test-framework}
1905 @subsection Features for @code{dg-add-options}
1907 The supported values of @var{feature} for directive @code{dg-add-options}
1912 NEON support. Only ARM targets support this feature, and only then
1913 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
1917 NEON and half-precision floating point support. Only ARM targets
1918 support this feature, and only then in certain modes; see
1919 the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}.
1921 @item bind_pic_locally
1922 Add the target-specific flags needed to enable functions to bind
1923 locally when using pic/PIC passes in the testsuite.
1926 Add the target-specific flags needed to access the C99 runtime.
1929 Add the target-specific flags needed to enable full IEEE
1932 @item mips16_attribute
1933 @code{mips16} function attributes.
1934 Only MIPS targets support this feature, and only then in certain modes.
1937 Add the target-specific flags needed to use thread-local storage.
1940 @node Require Support
1941 @subsection Variants of @code{dg-require-@var{support}}
1943 A few of the @code{dg-require} directives take arguments.
1946 @item dg-require-iconv @var{codeset}
1947 Skip the test if the target does not support iconv. @var{codeset} is
1948 the codeset to convert to.
1950 @item dg-require-profiling @var{profopt}
1951 Skip the test if the target does not support profiling with option
1954 @item dg-require-visibility @var{vis}
1955 Skip the test if the target does not support the @code{visibility} attribute.
1956 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
1957 checked, for @code{visibility("@var{vis}")} otherwise.
1960 The original @code{dg-require} directives were defined before there
1961 was support for effective-target keywords. The directives that do not
1962 take arguments could be replaced with effective-target keywords.
1965 @item dg-require-alias ""
1966 Skip the test if the target does not support the @samp{alias} attribute.
1968 @item dg-require-ascii-locale ""
1969 Skip the test if the host does not support an ASCII locale.
1971 @item dg-require-compat-dfp ""
1972 Skip this test unless both compilers in a @file{compat} testsuite
1973 support decimal floating point.
1975 @item dg-require-cxa-atexit ""
1976 Skip the test if the target does not support @code{__cxa_atexit}.
1977 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
1979 @item dg-require-dll ""
1980 Skip the test if the target does not support DLL attributes.
1982 @item dg-require-fork ""
1983 Skip the test if the target does not support @code{fork}.
1985 @item dg-require-gc-sections ""
1986 Skip the test if the target's linker does not support the
1987 @code{--gc-sections} flags.
1988 This is equivalent to @code{dg-require-effective-target gc-sections}.
1990 @item dg-require-host-local ""
1991 Skip the test if the host is remote, rather than the same as the build
1992 system. Some tests are incompatible with DejaGnu's handling of remote
1993 hosts, which involves copying the source file to the host and compiling
1994 it with a relative path and "@code{-o a.out}".
1996 @item dg-require-mkfifo ""
1997 Skip the test if the target does not support @code{mkfifo}.
1999 @item dg-require-named-sections ""
2000 Skip the test is the target does not support named sections.
2001 This is equivalent to @code{dg-require-effective-target named_sections}.
2003 @item dg-require-weak ""
2004 Skip the test if the target does not support weak symbols.
2006 @item dg-require-weak-override ""
2007 Skip the test if the target does not support overriding weak symbols.
2011 @subsection Commands for use in @code{dg-final}
2013 The GCC testsuite defines the following directives to be used within
2016 @subsubsection Scan a particular file
2019 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2020 Passes if @var{regexp} matches text in @var{filename}.
2021 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
2022 Passes if @var{regexp} does not match text in @var{filename}.
2023 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
2024 Passes if @var{regexp} matches in Fortran module @var{module}.
2027 @subsubsection Scan the assembly output
2030 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
2031 Passes if @var{regex} matches text in the test's assembler output.
2033 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
2034 Passes if @var{regex} does not match text in the test's assembler output.
2036 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
2037 Passes if @var{regex} is matched exactly @var{num} times in the test's
2040 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
2041 Passes if @var{regex} matches text in the test's demangled assembler output.
2043 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
2044 Passes if @var{regex} does not match text in the test's demangled assembler
2047 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2048 Passes if @var{symbol} is defined as a hidden symbol in the test's
2051 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2052 Passes if @var{symbol} is not defined as a hidden symbol in the test's
2056 @subsubsection Scan optimization dump files
2058 These commands are available for @var{kind} of @code{tree}, @code{rtl},
2062 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2063 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
2065 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2066 Passes if @var{regex} does not match text in the dump file with suffix
2069 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
2070 Passes if @var{regex} is found exactly @var{num} times in the dump file
2071 with suffix @var{suffix}.
2073 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2074 Passes if @var{regex} matches demangled text in the dump file with
2075 suffix @var{suffix}.
2077 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2078 Passes if @var{regex} does not match demangled text in the dump file with
2079 suffix @var{suffix}.
2082 @subsubsection Verify that an output files exists or not
2085 @item output-exists [@{ target/xfail @var{selector} @}]
2086 Passes if compiler output file exists.
2088 @item output-exists-not [@{ target/xfail @var{selector} @}]
2089 Passes if compiler output file does not exist.
2092 @subsubsection Check for LTO tests
2095 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
2096 Passes if the pattern is present in the final executable.
2099 @subsubsection Checks for @command{gcov} tests
2102 @item run-gcov @var{sourcefile}
2103 Check line counts in @command{gcov} tests.
2105 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
2106 Check branch and/or call counts, in addition to line counts, in
2107 @command{gcov} tests.
2110 @subsubsection Clean up generated test files
2113 @item cleanup-coverage-files
2114 Removes coverage data files generated for this test.
2116 @item cleanup-ipa-dump @var{suffix}
2117 Removes IPA dump files generated for this test.
2119 @item cleanup-modules "@var{list-of-extra-modules}"
2120 Removes Fortran module files generated for this test, excluding the
2121 module names listed in keep-modules.
2122 Cleaning up module files is usually done automatically by the testsuite
2123 by looking at the source files and removing the modules after the test
2134 ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant
2135 ! @{ dg-final @{ keep-modules "mod3 mod4" @} @}
2138 @item keep-modules "@var{list-of-modules-not-to-delete}"
2139 Whitespace separated list of module names that should not be deleted by
2141 If the list of modules is empty, all modules defined in this file are kept.
2143 module maybe_unneeded
2144 end module maybe_unneeded
2149 ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two
2150 ! @{ dg-final @{ keep-modules "" @} @} ! keep all
2153 @item cleanup-profile-file
2154 Removes profiling files generated for this test.
2156 @item cleanup-repo-files
2157 Removes files generated for this test for @option{-frepo}.
2159 @item cleanup-rtl-dump @var{suffix}
2160 Removes RTL dump files generated for this test.
2162 @item cleanup-saved-temps
2163 Removes files for the current test which were kept for @option{-save-temps}.
2165 @item cleanup-tree-dump @var{suffix}
2166 Removes tree dump files matching @var{suffix} which were generated for
2171 @section Ada Language Testsuites
2173 The Ada testsuite includes executable tests from the ACATS
2174 testsuite, publicly available at
2175 @uref{http://www.ada-auth.org/acats.html}.
2177 These tests are integrated in the GCC testsuite in the
2178 @file{ada/acats} directory, and
2179 enabled automatically when running @code{make check}, assuming
2180 the Ada language has been enabled when configuring GCC@.
2182 You can also run the Ada testsuite independently, using
2183 @code{make check-ada}, or run a subset of the tests by specifying which
2184 chapter to run, e.g.:
2187 $ make check-ada CHAPTERS="c3 c9"
2190 The tests are organized by directory, each directory corresponding to
2191 a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds
2192 to chapter 9, which deals with tasking features of the language.
2194 There is also an extra chapter called @file{gcc} containing a template for
2195 creating new executable tests, although this is deprecated in favor of
2196 the @file{gnat.dg} testsuite.
2198 The tests are run using two @command{sh} scripts: @file{run_acats} and
2199 @file{run_all.sh}. To run the tests using a simulator or a cross
2200 target, see the small
2201 customization section at the top of @file{run_all.sh}.
2203 These tests are run using the build tree: they can be run without doing
2204 a @code{make install}.
2207 @section C Language Testsuites
2209 GCC contains the following C language testsuites, in the
2210 @file{gcc/testsuite} directory:
2214 This contains tests of particular features of the C compiler, using the
2215 more modern @samp{dg} harness. Correctness tests for various compiler
2216 features should go here if possible.
2218 Magic comments determine whether the file
2219 is preprocessed, compiled, linked or run. In these tests, error and warning
2220 message texts are compared against expected texts or regular expressions
2221 given in comments. These tests are run with the options @samp{-ansi -pedantic}
2222 unless other options are given in the test. Except as noted below they
2223 are not run with multiple optimization options.
2225 This subdirectory contains tests for binary compatibility using
2226 @file{lib/compat.exp}, which in turn uses the language-independent support
2227 (@pxref{compat Testing, , Support for testing binary compatibility}).
2229 This subdirectory contains tests of the preprocessor.
2231 This subdirectory contains tests for debug formats. Tests in this
2232 subdirectory are run for each debug format that the compiler supports.
2234 This subdirectory contains tests of the @option{-Wformat} format
2235 checking. Tests in this directory are run with and without
2237 @item gcc.dg/noncompile
2238 This subdirectory contains tests of code that should not compile and
2239 does not need any special compilation options. They are run with
2240 multiple optimization options, since sometimes invalid code crashes
2241 the compiler with optimization.
2242 @item gcc.dg/special
2243 FIXME: describe this.
2246 This contains particular code fragments which have historically broken easily.
2247 These tests are run with multiple optimization options, so tests for features
2248 which only break at some optimization levels belong here. This also contains
2249 tests to check that certain optimizations occur. It might be worthwhile to
2250 separate the correctness tests cleanly from the code quality tests, but
2251 it hasn't been done yet.
2253 @item gcc.c-torture/compat
2254 FIXME: describe this.
2256 This directory should probably not be used for new tests.
2257 @item gcc.c-torture/compile
2258 This testsuite contains test cases that should compile, but do not
2259 need to link or run. These test cases are compiled with several
2260 different combinations of optimization options. All warnings are
2261 disabled for these test cases, so this directory is not suitable if
2262 you wish to test for the presence or absence of compiler warnings.
2263 While special options can be set, and tests disabled on specific
2264 platforms, by the use of @file{.x} files, mostly these test cases
2265 should not contain platform dependencies. FIXME: discuss how defines
2266 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
2267 @item gcc.c-torture/execute
2268 This testsuite contains test cases that should compile, link and run;
2269 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
2270 @item gcc.c-torture/execute/ieee
2271 This contains tests which are specific to IEEE floating point.
2272 @item gcc.c-torture/unsorted
2273 FIXME: describe this.
2275 This directory should probably not be used for new tests.
2276 @item gcc.misc-tests
2277 This directory contains C tests that require special handling. Some
2278 of these tests have individual expect files, and others share
2279 special-purpose expect files:
2282 @item @code{bprob*.c}
2283 Test @option{-fbranch-probabilities} using
2284 @file{gcc.misc-tests/bprob.exp}, which
2285 in turn uses the generic, language-independent framework
2286 (@pxref{profopt Testing, , Support for testing profile-directed
2289 @item @code{gcov*.c}
2290 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
2291 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
2293 @item @code{i386-pf-*.c}
2294 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
2297 @item gcc.test-framework
2300 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
2305 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
2306 test cases and magic comments more.
2309 @section The Java library testsuites.
2311 Runtime tests are executed via @samp{make check} in the
2312 @file{@var{target}/libjava/testsuite} directory in the build
2313 tree. Additional runtime tests can be checked into this testsuite.
2315 Regression testing of the core packages in libgcj is also covered by the
2316 Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project}
2317 develops tests for the Java Class Libraries. These tests are run as part
2318 of libgcj testing by placing the Mauve tree within the libjava testsuite
2319 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
2320 the location of that tree when invoking @samp{make}, as in
2321 @samp{make MAUVEDIR=~/mauve check}.
2323 To detect regressions, a mechanism in @file{mauve.exp} compares the
2324 failures for a test run against the list of expected failures in
2325 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
2326 Update this file when adding new failing tests to Mauve, or when fixing
2327 bugs in libgcj that had caused Mauve test failures.
2329 We encourage developers to contribute test cases to Mauve.
2332 @section Support for testing link-time optimizations
2334 Tests for link-time optimizations usually require multiple source files
2335 that are compiled separately, perhaps with different sets of options.
2336 There are several special-purpose test directives used for these tests.
2339 @item @{ dg-lto-do @var{do-what-keyword} @}
2340 @var{do-what-keyword} specifies how the test is compiled and whether
2341 it is executed. It is one of:
2345 Compile with @option{-c} to produce a relocatable object file.
2347 Compile, assemble, and link to produce an executable file.
2349 Produce and run an executable file, which is expected to return
2353 The default is @code{assemble}. That can be overridden for a set of
2354 tests by redefining @code{dg-do-what-default} within the @code{.exp}
2355 file for those tests.
2357 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
2358 @samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
2359 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
2361 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
2362 This directive provides a list of one or more sets of compiler options
2363 to override @var{LTO_OPTIONS}. Each test will be compiled and run with
2364 each of these sets of options.
2366 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
2367 This directive adds @var{options} to the linker options used.
2369 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
2370 This directive removes @var{options} from the set of linker options used.
2374 @section Support for testing @command{gcov}
2376 Language-independent support for testing @command{gcov}, and for checking
2377 that branch profiling produces expected values, is provided by the
2378 expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
2379 in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
2380 @command{gcov} test contains the following DejaGnu commands within comments:
2383 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
2384 @{ dg-do run @{ target native @} @}
2385 @{ dg-final @{ run-gcov sourcefile @} @}
2388 Checks of @command{gcov} output can include line counts, branch percentages,
2389 and call return percentages. All of these checks are requested via
2390 commands that appear in comments in the test's source file.
2391 Commands to check line counts are processed by default.
2392 Commands to check branch percentages and call return percentages are
2393 processed if the @command{run-gcov} command has arguments @code{branches}
2394 or @code{calls}, respectively. For example, the following specifies
2395 checking both, as well as passing @option{-b} to @command{gcov}:
2398 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
2401 A line count command appears within a comment on the source line
2402 that is expected to get the specified count and has the form
2403 @code{count(@var{cnt})}. A test should only check line counts for
2404 lines that will get the same count for any architecture.
2406 Commands to check branch percentages (@code{branch}) and call
2407 return percentages (@code{returns}) are very similar to each other.
2408 A beginning command appears on or before the first of a range of
2409 lines that will report the percentage, and the ending command
2410 follows that range of lines. The beginning command can include a
2411 list of percentages, all of which are expected to be found within
2412 the range. A range is terminated by the next command of the same
2413 kind. A command @code{branch(end)} or @code{returns(end)} marks
2414 the end of a range without starting a new one. For example:
2417 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
2418 /* @r{branch(end)} */
2422 For a call return percentage, the value specified is the
2423 percentage of calls reported to return. For a branch percentage,
2424 the value is either the expected percentage or 100 minus that
2425 value, since the direction of a branch can differ depending on the
2426 target or the optimization level.
2428 Not all branches and calls need to be checked. A test should not
2429 check for branches that might be optimized away or replaced with
2430 predicated instructions. Don't check for calls inserted by the
2431 compiler or ones that might be inlined or optimized away.
2433 A single test can check for combinations of line counts, branch
2434 percentages, and call return percentages. The command to check a
2435 line count must appear on the line that will report that count, but
2436 commands to check branch percentages and call return percentages can
2437 bracket the lines that report them.
2439 @node profopt Testing
2440 @section Support for testing profile-directed optimizations
2442 The file @file{profopt.exp} provides language-independent support for
2443 checking correct execution of a test built with profile-directed
2444 optimization. This testing requires that a test program be built and
2445 executed twice. The first time it is compiled to generate profile
2446 data, and the second time it is compiled to use the data that was
2447 generated during the first execution. The second execution is to
2448 verify that the test produces the expected results.
2450 To check that the optimization actually generated better code, a
2451 test can be built and run a third time with normal optimizations to
2452 verify that the performance is better with the profile-directed
2453 optimizations. @file{profopt.exp} has the beginnings of this kind
2456 @file{profopt.exp} provides generic support for profile-directed
2457 optimizations. Each set of tests that uses it provides information
2458 about a specific optimization:
2462 tool being tested, e.g., @command{gcc}
2464 @item profile_option
2465 options used to generate profile data
2467 @item feedback_option
2468 options used to optimize using that profile data
2471 suffix of profile data files
2473 @item PROFOPT_OPTIONS
2474 list of options with which to run each test, similar to the lists for
2477 @item @{ dg-final-generate @{ @var{local-directive} @} @}
2478 This directive is similar to @code{dg-final}, but the
2479 @var{local-directive} is run after the generation of profile data.
2481 @item @{ dg-final-use @{ @var{local-directive} @} @}
2482 The @var{local-directive} is run after the profile data have been
2486 @node compat Testing
2487 @section Support for testing binary compatibility
2489 The file @file{compat.exp} provides language-independent support for
2490 binary compatibility testing. It supports testing interoperability of
2491 two compilers that follow the same ABI, or of multiple sets of
2492 compiler options that should not affect binary compatibility. It is
2493 intended to be used for testsuites that complement ABI testsuites.
2495 A test supported by this framework has three parts, each in a
2496 separate source file: a main program and two pieces that interact
2497 with each other to split up the functionality being tested.
2500 @item @var{testname}_main.@var{suffix}
2501 Contains the main program, which calls a function in file
2502 @file{@var{testname}_x.@var{suffix}}.
2504 @item @var{testname}_x.@var{suffix}
2505 Contains at least one call to a function in
2506 @file{@var{testname}_y.@var{suffix}}.
2508 @item @var{testname}_y.@var{suffix}
2509 Shares data with, or gets arguments from,
2510 @file{@var{testname}_x.@var{suffix}}.
2513 Within each test, the main program and one functional piece are
2514 compiled by the GCC under test. The other piece can be compiled by
2515 an alternate compiler. If no alternate compiler is specified,
2516 then all three source files are all compiled by the GCC under test.
2517 You can specify pairs of sets of compiler options. The first element
2518 of such a pair specifies options used with the GCC under test, and the
2519 second element of the pair specifies options used with the alternate
2520 compiler. Each test is compiled with each pair of options.
2522 @file{compat.exp} defines default pairs of compiler options.
2523 These can be overridden by defining the environment variable
2524 @env{COMPAT_OPTIONS} as:
2527 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
2528 @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
2531 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
2532 used by the compiler under test and @var{alti} used by the alternate
2533 compiler. For example, with
2534 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
2535 the test is first built with @option{-g -O0} by the compiler under
2536 test and with @option{-O3} by the alternate compiler. The test is
2537 built a second time using @option{-fpic} by the compiler under test
2538 and @option{-fPIC -O2} by the alternate compiler.
2540 An alternate compiler is specified by defining an environment
2541 variable to be the full pathname of an installed compiler; for C
2542 define @env{ALT_CC_UNDER_TEST}, and for C++ define
2543 @env{ALT_CXX_UNDER_TEST}. These will be written to the
2544 @file{site.exp} file used by DejaGnu. The default is to build each
2545 test with the compiler under test using the first of each pair of
2546 compiler options from @env{COMPAT_OPTIONS}. When
2547 @env{ALT_CC_UNDER_TEST} or
2548 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
2549 the compiler under test but with combinations of the options from
2550 @env{COMPAT_OPTIONS}.
2552 To run only the C++ compatibility suite using the compiler under test
2553 and another version of GCC using specific compiler options, do the
2554 following from @file{@var{objdir}/gcc}:
2559 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
2560 COMPAT_OPTIONS="@var{lists as shown above}" \
2562 RUNTESTFLAGS="compat.exp"
2565 A test that fails when the source files are compiled with different
2566 compilers, but passes when the files are compiled with the same
2567 compiler, demonstrates incompatibility of the generated code or
2568 runtime support. A test that fails for the alternate compiler but
2569 passes for the compiler under test probably tests for a bug that was
2570 fixed in the compiler under test but is present in the alternate
2573 The binary compatibility tests support a small number of test framework
2574 commands that appear within comments in a test file.
2578 These commands can be used in @file{@var{testname}_main.@var{suffix}}
2579 to skip the test if specific support is not available on the target.
2582 The specified options are used for compiling this particular source
2583 file, appended to the options from @env{COMPAT_OPTIONS}. When this
2584 command appears in @file{@var{testname}_main.@var{suffix}} the options
2585 are also used to link the test program.
2588 This command can be used in a secondary source file to specify that
2589 compilation is expected to fail for particular options on particular
2594 @section Support for torture testing using multiple options
2596 Throughout the compiler testsuite there are several directories whose
2597 tests are run multiple times, each with a different set of options.
2598 These are known as torture tests.
2599 @file{lib/torture-options.exp} defines procedures to
2604 Initialize use of torture lists.
2605 @item set-torture-options
2606 Set lists of torture options to use for tests with and without loops.
2607 Optionally combine a set of torture options with a set of other
2608 options, as is done with Objective-C runtime options.
2609 @item torture-finish
2610 Finalize use of torture lists.
2613 The @file{.exp} file for a set of tests that use torture options must
2614 include calls to these three procedures if:
2617 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
2619 @item It calls @var{$@{tool@}}@code{-torture} or
2620 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
2621 @code{fortran}, or @code{objc}.
2623 @item It calls @code{dg-pch}.
2626 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
2627 to call the torture procedures if the tests should use the list in
2628 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
2630 Most uses of torture options can override the default lists by defining
2631 @var{TORTURE_OPTIONS} or add to the default list by defining
2632 @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
2633 file or add them to the @file{site.exp} file; for example
2636 set ADDITIONAL_TORTURE_OPTIONS [list \
2637 @{ -O2 -ftree-loop-linear @} \
2638 @{ -O2 -fpeel-loops @} ]