1 @c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Source Tree Structure and Build System
8 This chapter describes the structure of the GCC source tree, and how
9 GCC is built. The user documentation for building and installing GCC
10 is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
11 which it is presumed that you are familiar.
14 * Configure Terms:: Configuration terminology and history.
15 * Top Level:: The top level source directory.
16 * gcc Directory:: The @file{gcc} subdirectory.
17 * Testsuites:: The GCC testsuites.
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 Contributed scripts that may be found useful in conjunction with GCC@.
37 One of these, @file{contrib/texi2pod.pl}, is used to generate man
38 pages from Texinfo manuals as part of the GCC build process.
41 An implementation of the @command{jar} command, used with the Java
45 The main sources of GCC itself (except for runtime libraries),
46 including optimizers, support for different target architectures,
47 language front ends, and testsuites. @xref{gcc Directory, , The
48 @file{gcc} Subdirectory}, for details.
51 Headers for the @code{libiberty} library.
54 The Ada runtime library.
57 The C preprocessor library.
60 The Fortran runtime library.
63 The @code{libffi} library, used as part of the Java runtime library.
66 The @code{libiberty} library, used for portability and for some
67 generally useful data structures and algorithms. @xref{Top, ,
68 Introduction, libiberty, @sc{gnu} libiberty}, for more information
72 The Java runtime library.
75 The @code{libmudflap} library, used for instrumenting pointer and array
76 dereferencing operations.
79 The Objective-C and Objective-C++ runtime library.
82 The C++ runtime library.
84 @item maintainer-scripts
85 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
88 The @code{zlib} compression library, used by the Java front end and as
89 part of the Java runtime library.
92 The build system in the top level directory, including how recursion
93 into subdirectories works and how building runtime libraries for
94 multilibs is handled, is documented in a separate manual, included
95 with GNU Binutils. @xref{Top, , GNU configure and build system,
96 configure, The GNU configure and build system}, for details.
99 @section The @file{gcc} Subdirectory
101 The @file{gcc} directory contains many files that are part of the C
102 sources of GCC, other files used as part of the configuration and
103 build process, and subdirectories including documentation and a
104 testsuite. The files that are sources of GCC are documented in a
105 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
108 * Subdirectories:: Subdirectories of @file{gcc}.
109 * Configuration:: The configuration process, and the files it uses.
110 * Build:: The build system in the @file{gcc} directory.
111 * Makefile:: Targets in @file{gcc/Makefile}.
112 * Library Files:: Library source files and headers under @file{gcc/}.
113 * Headers:: Headers installed by GCC.
114 * Documentation:: Building documentation in GCC.
115 * Front End:: Anatomy of a language front end.
116 * Back End:: Anatomy of a target back end.
120 @subsection Subdirectories of @file{gcc}
122 The @file{gcc} directory contains the following subdirectories:
126 Subdirectories for various languages. Directories containing a file
127 @file{config-lang.in} are language subdirectories. The contents of
128 the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C)
129 and @file{objcp} (for Objective-C++) are documented in this manual
130 (@pxref{Passes, , Passes and Files of the Compiler}); those for other
131 languages are not. @xref{Front End, , Anatomy of a Language Front End},
132 for details of the files in these directories.
135 Configuration files for supported architectures and operating
136 systems. @xref{Back End, , Anatomy of a Target Back End}, for
137 details of the files in this directory.
140 Texinfo documentation for GCC, together with automatically generated
141 man pages and support for converting the installation manual to
142 HTML@. @xref{Documentation}.
145 The support for fixing system headers to work with GCC@. See
146 @file{fixinc/README} for more information. The headers fixed by this
147 mechanism are installed in @file{@var{libsubdir}/include}. Along with
148 those headers, @file{README-fixinc} is also installed, as
149 @file{@var{libsubdir}/include/README}.
152 System headers installed by GCC, mainly those required by the C
153 standard of freestanding implementations. @xref{Headers, , Headers
154 Installed by GCC}, for details of when these and other headers are
158 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
159 include it in libc. Properly, this directory should be at top level,
160 parallel to the @file{gcc} directory.
163 Message catalogs with translations of messages produced by GCC into
164 various languages, @file{@var{language}.po}. This directory also
165 contains @file{gcc.pot}, the template for these message catalogues,
166 @file{exgettext}, a wrapper around @command{gettext} to extract the
167 messages from the GCC sources and create @file{gcc.pot}, which is run
168 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
169 which messages should not be extracted.
172 The GCC testsuites (except for those for runtime libraries).
177 @subsection Configuration in the @file{gcc} Directory
179 The @file{gcc} directory is configured with an Autoconf-generated
180 script @file{configure}. The @file{configure} script is generated
181 from @file{configure.ac} and @file{aclocal.m4}. From the files
182 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
183 file @file{config.in}. The file @file{cstamp-h.in} is used as a
187 * Config Fragments:: Scripts used by @file{configure}.
188 * System Config:: The @file{config.build}, @file{config.host}, and
189 @file{config.gcc} files.
190 * Configuration Files:: Files created by running @file{configure}.
193 @node Config Fragments
194 @subsubsection Scripts Used by @file{configure}
196 @file{configure} uses some other scripts to help in its work:
199 @item The standard GNU @file{config.sub} and @file{config.guess}
200 files, kept in the top level directory, are used. FIXME: when is the
201 @file{config.guess} file in the @file{gcc} directory (that just calls
202 the top level one) used?
204 @item The file @file{config.gcc} is used to handle configuration
205 specific to the particular target machine. The file
206 @file{config.build} is used to handle configuration specific to the
207 particular build machine. The file @file{config.host} is used to handle
208 configuration specific to the particular host machine. (In general,
209 these should only be used for features that cannot reasonably be tested in
210 Autoconf feature tests.)
211 @xref{System Config, , The @file{config.build}; @file{config.host};
212 and @file{config.gcc} Files}, for details of the contents of these files.
214 @item Each language subdirectory has a file
215 @file{@var{language}/config-lang.in} that is used for
216 front-end-specific configuration. @xref{Front End Config, , The Front
217 End @file{config-lang.in} File}, for details of this file.
219 @item A helper script @file{configure.frag} is used as part of
220 creating the output of @file{configure}.
224 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
226 The @file{config.build} file contains specific rules for particular systems
227 which GCC is built on. This should be used as rarely as possible, as the
228 behavior of the build system can always be detected by autoconf.
230 The @file{config.host} file contains specific rules for particular systems
231 which GCC will run on. This is rarely needed.
233 The @file{config.gcc} file contains specific rules for particular systems
234 which GCC will generate code for. This is usually needed.
236 Each file has a list of the shell variables it sets, with descriptions, at the
239 FIXME: document the contents of these files, and what variables should
240 be set to control build, host and target configuration.
242 @include configfiles.texi
245 @subsection Build System in the @file{gcc} Directory
247 FIXME: describe the build system, including what is built in what
248 stages. Also list the various source files that are used in the build
249 process but aren't source files of GCC itself and so aren't documented
250 below (@pxref{Passes}).
252 @include makefile.texi
255 @subsection Library Source Files and Headers under the @file{gcc} Directory
257 FIXME: list here, with explanation, all the C source files and headers
258 under the @file{gcc} directory that aren't built into the GCC
259 executable but rather are part of runtime libraries and object files,
260 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
261 Headers Installed by GCC}, for more information about the
262 @file{ginclude} directory.
265 @subsection Headers Installed by GCC
267 In general, GCC expects the system C library to provide most of the
268 headers to be used with it. However, GCC will fix those headers if
269 necessary to make them work with GCC, and will install some headers
270 required of freestanding implementations. These headers are installed
271 in @file{@var{libsubdir}/include}. Headers for non-C runtime
272 libraries are also installed by GCC; these are not documented here.
273 (FIXME: document them somewhere.)
275 Several of the headers GCC installs are in the @file{ginclude}
276 directory. These headers, @file{iso646.h},
277 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
278 are installed in @file{@var{libsubdir}/include},
279 unless the target Makefile fragment (@pxref{Target Fragment})
280 overrides this by setting @code{USER_H}.
282 In addition to these headers and those generated by fixing system
283 headers to work with GCC, some other headers may also be installed in
284 @file{@var{libsubdir}/include}. @file{config.gcc} may set
285 @code{extra_headers}; this specifies additional headers under
286 @file{config} to be installed on some systems.
288 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
289 This is done to cope with command-line options that change the
290 representation of floating point numbers.
292 GCC also installs its own version of @code{<limits.h>}; this is generated
293 from @file{glimits.h}, together with @file{limitx.h} and
294 @file{limity.h} if the system also has its own version of
295 @code{<limits.h>}. (GCC provides its own header because it is
296 required of ISO C freestanding implementations, but needs to include
297 the system header from its own header as well because other standards
298 such as POSIX specify additional values to be defined in
299 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
300 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
301 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
302 needs fixing, @file{syslimits.h} is the fixed copy.
304 GCC can also install @code{<tgmath.h>}. It will do this when
305 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
308 @subsection Building Documentation
310 The main GCC documentation is in the form of manuals in Texinfo
311 format. These are installed in Info format; DVI versions may be
312 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
313 HTML versions by @command{make html}. In addition, some man pages are
314 generated from the Texinfo manuals, there are some other text files
315 with miscellaneous documentation, and runtime libraries have their own
316 documentation outside the @file{gcc} directory. FIXME: document the
317 documentation for runtime libraries somewhere.
320 * Texinfo Manuals:: GCC manuals in Texinfo format.
321 * Man Page Generation:: Generating man pages from Texinfo manuals.
322 * Miscellaneous Docs:: Miscellaneous text files with documentation.
325 @node Texinfo Manuals
326 @subsubsection Texinfo Manuals
328 The manuals for GCC as a whole, and the C and C++ front ends, are in
329 files @file{doc/*.texi}. Other front ends have their own manuals in
330 files @file{@var{language}/*.texi}. Common files
331 @file{doc/include/*.texi} are provided which may be included in
332 multiple manuals; the following files are in @file{doc/include}:
336 The GNU Free Documentation License.
338 The section ``Funding Free Software''.
339 @item gcc-common.texi
340 Common definitions for manuals.
342 The GNU General Public License.
344 A copy of @file{texinfo.tex} known to work with the GCC manuals.
347 DVI-formatted manuals are generated by @samp{make dvi}, which uses
348 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).
349 PDF-formatted manuals are generated by @samp{make pdf}, which uses
350 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML
351 formatted manuals are generated by @command{make html}. Info
352 manuals are generated by @samp{make info} (which is run as part of
353 a bootstrap); this generates the manuals in the source directory,
354 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
355 and they are included in release distributions.
357 Manuals are also provided on the GCC web site, in both HTML and
358 PostScript forms. This is done via the script
359 @file{maintainer-scripts/update_web_docs}. Each manual to be
360 provided online must be listed in the definition of @code{MANUALS} in
361 that file; a file @file{@var{name}.texi} must only appear once in the
362 source tree, and the output manual must have the same name as the
363 source file. (However, other Texinfo files, included in manuals but
364 not themselves the root files of manuals, may have names that appear
365 more than once in the source tree.) The manual file
366 @file{@var{name}.texi} should only include other files in its own
367 directory or in @file{doc/include}. HTML manuals will be generated by
368 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
369 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
370 All Texinfo files that are parts of manuals must
371 be checked into CVS, even if they are generated files, for the
372 generation of online manuals to work.
374 The installation manual, @file{doc/install.texi}, is also provided on
375 the GCC web site. The HTML version is generated by the script
376 @file{doc/install.texi2html}.
378 @node Man Page Generation
379 @subsubsection Man Page Generation
381 Because of user demand, in addition to full Texinfo manuals, man pages
382 are provided which contain extracts from those manuals. These man
383 pages are generated from the Texinfo manuals using
384 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
385 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
386 to @file{gcc.1}, but all the other man pages are generated from
389 Because many systems may not have the necessary tools installed to
390 generate the man pages, they are only generated if the
391 @file{configure} script detects that recent enough tools are
392 installed, and the Makefiles allow generating man pages to fail
393 without aborting the build. Man pages are also included in release
394 distributions. They are generated in the source directory.
396 Magic comments in Texinfo files starting @samp{@@c man} control what
397 parts of a Texinfo file go into a man page. Only a subset of Texinfo
398 is supported by @file{texi2pod.pl}, and it may be necessary to add
399 support for more Texinfo features to this script when generating new
400 man pages. To improve the man page output, some special Texinfo
401 macros are provided in @file{doc/include/gcc-common.texi} which
402 @file{texi2pod.pl} understands:
406 Use in the form @samp{@@table @@gcctabopt} for tables of options,
407 where for printed output the effect of @samp{@@code} is better than
408 that of @samp{@@option} but for man page output a different effect is
411 Use for summary lists of options in manuals.
413 Use at the end of each line inside @samp{@@gccoptlist}. This is
414 necessary to avoid problems with differences in how the
415 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
418 FIXME: describe the @file{texi2pod.pl} input language and magic
419 comments in more detail.
421 @node Miscellaneous Docs
422 @subsubsection Miscellaneous Documentation
424 In addition to the formal documentation that is installed by GCC,
425 there are several other text files with miscellaneous documentation:
429 Notes on GCC's Native Language Support. FIXME: this should be part of
430 this manual rather than a separate file.
432 Notes on the Free Translation Project.
434 The GNU General Public License.
436 The GNU Lesser General Public License.
439 Change log files for various parts of GCC@.
441 Details of a few changes to the GCC front-end interface. FIXME: the
442 information in this file should be part of general documentation of
443 the front-end interface in this manual.
445 Information about new features in old versions of GCC@. (For recent
446 versions, the information is on the GCC web site.)
447 @item README.Portability
448 Information about portability issues when writing code in GCC@. FIXME:
449 why isn't this part of this manual or of the GCC Coding Conventions?
451 A pointer to the GNU Service Directory.
454 FIXME: document such files in subdirectories, at least @file{config},
455 @file{cp}, @file{objc}, @file{testsuite}.
458 @subsection Anatomy of a Language Front End
460 A front end for a language in GCC has the following parts:
464 A directory @file{@var{language}} under @file{gcc} containing source
465 files for that front end. @xref{Front End Directory, , The Front End
466 @file{@var{language}} Directory}, for details.
468 A mention of the language in the list of supported languages in
469 @file{gcc/doc/install.texi}.
471 A mention of the name under which the language's runtime library is
472 recognized by @option{--enable-shared=@var{package}} in the
473 documentation of that option in @file{gcc/doc/install.texi}.
475 A mention of any special prerequisites for building the front end in
476 the documentation of prerequisites in @file{gcc/doc/install.texi}.
478 Details of contributors to that front end in
479 @file{gcc/doc/contrib.texi}. If the details are in that front end's
480 own manual then there should be a link to that manual's list in
483 Information about support for that language in
484 @file{gcc/doc/frontends.texi}.
486 Information about standards for that language, and the front end's
487 support for them, in @file{gcc/doc/standards.texi}. This may be a
488 link to such information in the front end's own manual.
490 Details of source file suffixes for that language and @option{-x
491 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
493 Entries in @code{default_compilers} in @file{gcc.c} for source file
494 suffixes for that language.
496 Preferably testsuites, which may be under @file{gcc/testsuite} or
497 runtime library directories. FIXME: document somewhere how to write
500 Probably a runtime library for the language, outside the @file{gcc}
501 directory. FIXME: document this further.
503 Details of the directories of any runtime libraries in
504 @file{gcc/doc/sourcebuild.texi}.
507 If the front end is added to the official GCC CVS repository, the
508 following are also necessary:
512 At least one Bugzilla component for bugs in that front end and runtime
513 libraries. This category needs to be mentioned in
514 @file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
516 Normally, one or more maintainers of that front end listed in
519 Mentions on the GCC web site in @file{index.html} and
520 @file{frontends.html}, with any relevant links on
521 @file{readings.html}. (Front ends that are not an official part of
522 GCC may also be listed on @file{frontends.html}, with relevant links.)
524 A news item on @file{index.html}, and possibly an announcement on the
525 @email{gcc-announce@@gcc.gnu.org} mailing list.
527 The front end's manuals should be mentioned in
528 @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
529 and the online manuals should be linked to from
530 @file{onlinedocs/index.html}.
532 Any old releases or CVS repositories of the front end, before its
533 inclusion in GCC, should be made available on the GCC FTP site
534 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
536 The release and snapshot script @file{maintainer-scripts/gcc_release}
537 should be updated to generate appropriate tarballs for this front end.
538 The associated @file{maintainer-scripts/snapshot-README} and
539 @file{maintainer-scripts/snapshot-index.html} files should be updated
540 to list the tarballs and diffs for this front end.
542 If this front end includes its own version files that include the
543 current date, @file{maintainer-scripts/update_version} should be
546 @file{CVSROOT/modules} in the GCC CVS repository should be updated.
550 * Front End Directory:: The front end @file{@var{language}} directory.
551 * Front End Config:: The front end @file{config-lang.in} file.
554 @node Front End Directory
555 @subsubsection The Front End @file{@var{language}} Directory
557 A front end @file{@var{language}} directory contains the source files
558 of that front end (but not of any runtime libraries, which should be
559 outside the @file{gcc} directory). This includes documentation, and
560 possibly some subsidiary programs build alongside the front end.
561 Certain files are special and other parts of the compiler depend on
566 This file is required in all language subdirectories. @xref{Front End
567 Config, , The Front End @file{config-lang.in} File}, for details of
570 This file is required in all language subdirectories. It contains
571 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
572 setting of @code{language} in @file{config-lang.in}) for the following
573 values of @code{@var{hook}}, and any other Makefile rules required to
574 build those targets (which may if necessary use other Makefiles
575 specified in @code{outputs} in @file{config-lang.in}, although this is
576 deprecated). It also adds any testsuite targets that can use the
577 standard rule in @file{gcc/Makefile.in} to the variable
584 FIXME: exactly what goes in each of these targets?
586 Build an @command{etags} @file{TAGS} file in the language subdirectory
589 Build info documentation for the front end, in the build directory.
590 This target is only called by @samp{make bootstrap} if a suitable
591 version of @command{makeinfo} is available, so does not need to check
592 for this, and should fail if an error occurs.
594 Build DVI documentation for the front end, in the build directory.
595 This should be done using @code{$(TEXI2DVI)}, with appropriate
596 @option{-I} arguments pointing to directories of included files.
598 Build PDF documentation for the front end, in the build directory.
599 This should be done using @code{$(TEXI2PDF)}, with appropriate
600 @option{-I} arguments pointing to directories of included files.
602 Build HTML documentation for the front end, in the build directory.
604 Build generated man pages for the front end from Texinfo manuals
605 (@pxref{Man Page Generation}), in the build directory. This target
606 is only called if the necessary tools are available, but should ignore
607 errors so as not to stop the build if errors occur; man pages are
608 optional and the tools involved may be installed in a broken way.
610 Install everything that is part of the front end, apart from the
611 compiler executables listed in @code{compilers} in
612 @file{config-lang.in}.
614 Install info documentation for the front end, if it is present in the
615 source directory. This target should have dependencies on info files
616 that should be installed.
618 Install man pages for the front end. This target should ignore
621 Copies its dependencies into the source directory. This generally should
622 be used for generated files such as Bison output files which are not
623 present in CVS, but should be included in any release tarballs. This
624 target will be executed during a bootstrap if
625 @samp{--enable-generated-files-in-srcdir} was specified as a
626 @file{configure} option.
629 Copies its dependencies into the source directory. These targets will be
630 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
631 was specified as a @file{configure} option.
633 Uninstall files installed by installing the compiler. This is
634 currently documented not to be supported, so the hook need not do
639 @itemx maintainer-clean
640 The language parts of the standard GNU
641 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
642 Users, standards, GNU Coding Standards}, for details of the standard
643 targets. For GCC, @code{maintainer-clean} should delete
644 all generated files in the source directory that are not checked into
645 CVS, but should not delete anything checked into CVS@.
649 This file registers the set of switches that the front end accepts on
650 the command line, and their @option{--help} text. @xref{Options}.
652 This file provides entries for @code{default_compilers} in
653 @file{gcc.c} which override the default of giving an error that a
654 compiler for that language is not installed.
655 @item @var{language}-tree.def
656 This file, which need not exist, defines any language-specific tree
660 @node Front End Config
661 @subsubsection The Front End @file{config-lang.in} File
663 Each language subdirectory contains a @file{config-lang.in} file. In
664 addition the main directory contains @file{c-config-lang.in}, which
665 contains limited information for the C language. This file is a shell
666 script that may define some variables describing the language:
670 This definition must be present, and gives the name of the language
671 for some purposes such as arguments to @option{--enable-languages}.
673 If defined, this variable lists (space-separated) language front ends
674 other than C that this front end requires to be enabled (with the
675 names given being their @code{language} settings). For example, the
676 Java front end depends on the C++ front end, so sets
677 @samp{lang_requires=c++}.
678 @item subdir_requires
679 If defined, this variable lists (space-separated) front end directories
680 other than C that this front end requires to be present. For example,
681 the Objective-C++ front end uses source files from the C++ and
682 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
684 If defined, this variable lists (space-separated) targets in the top
685 level @file{Makefile} to build the runtime libraries for this
686 language, such as @code{target-libobjc}.
688 If defined, this variable lists (space-separated) top level
689 directories (parallel to @file{gcc}), apart from the runtime libraries,
690 that should not be configured if this front end is not built.
691 @item build_by_default
692 If defined to @samp{no}, this language front end is not built unless
693 enabled in a @option{--enable-languages} argument. Otherwise, front
694 ends are built by default, subject to any special logic in
695 @file{configure.ac} (as is present to disable the Ada front end if the
696 Ada compiler is not already installed).
698 If defined to @samp{yes}, this front end is built in stage 1 of the
699 bootstrap. This is only relevant to front ends written in their own
702 If defined, a space-separated list of compiler executables that will
703 be run by the driver. The names here will each end
704 with @samp{\$(exeext)}.
706 If defined, a space-separated list of files that should be generated
707 by @file{configure} substituting values in them. This mechanism can
708 be used to create a file @file{@var{language}/Makefile} from
709 @file{@var{language}/Makefile.in}, but this is deprecated, building
710 everything from the single @file{gcc/Makefile} is preferred.
712 If defined, a space-separated list of files that should be scanned by
713 gengtype.c to generate the garbage collection tables and routines for
714 this language. This excludes the files that are common to all front
715 ends. @xref{Type Information}.
720 @subsection Anatomy of a Target Back End
722 A back end for a target architecture in GCC has the following parts:
726 A directory @file{@var{machine}} under @file{gcc/config}, containing a
727 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
728 , Machine Descriptions}), header files @file{@var{machine}.h} and
729 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
730 (@pxref{Target Macros, , Target Description Macros and Functions}),
731 possibly a target Makefile fragment @file{t-@var{machine}}
732 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
733 some other files. The names of these files may be changed from the
734 defaults given by explicit specifications in @file{config.gcc}.
736 If necessary, a file @file{@var{machine}-modes.def} in the
737 @file{@var{machine}} directory, containing additional machine modes to
738 represent condition codes. @xref{Condition Code}, for further details.
740 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
741 directory, containing a list of target-specific options. You can also
742 add other option files using the @code{extra_options} variable in
743 @file{config.gcc}. @xref{Options}.
745 Entries in @file{config.gcc} (@pxref{System Config, , The
746 @file{config.gcc} File}) for the systems with this target
749 Documentation in @file{gcc/doc/invoke.texi} for any command-line
750 options supported by this target (@pxref{Run-time Target, , Run-time
751 Target Specification}). This means both entries in the summary table
752 of options and details of the individual options.
754 Documentation in @file{gcc/doc/extend.texi} for any target-specific
755 attributes supported (@pxref{Target Attributes, , Defining
756 target-specific uses of @code{__attribute__}}), including where the
757 same attribute is already supported on some targets, which are
758 enumerated in the manual.
760 Documentation in @file{gcc/doc/extend.texi} for any target-specific
763 Documentation in @file{gcc/doc/extend.texi} of any target-specific
764 built-in functions supported.
766 Documentation in @file{gcc/doc/extend.texi} of any target-specific
767 format checking styles supported.
769 Documentation in @file{gcc/doc/md.texi} of any target-specific
770 constraint letters (@pxref{Machine Constraints, , Constraints for
771 Particular Machines}).
773 A note in @file{gcc/doc/contrib.texi} under the person or people who
774 contributed the target support.
776 Entries in @file{gcc/doc/install.texi} for all target triplets
777 supported with this target architecture, giving details of any special
778 notes about installation for this target, or saying that there are no
779 special notes if there are none.
781 Possibly other support outside the @file{gcc} directory for runtime
782 libraries. FIXME: reference docs for this. The libstdc++ porting
783 manual needs to be installed as info for this to work, or to be a
784 chapter of this manual.
787 If the back end is added to the official GCC CVS repository, the
788 following are also necessary:
792 An entry for the target architecture in @file{readings.html} on the
793 GCC web site, with any relevant links.
795 Details of the properties of the back end and target architecture in
796 @file{backends.html} on the GCC web site.
798 A news item about the contribution of support for that target
799 architecture, in @file{index.html} on the GCC web site.
801 Normally, one or more maintainers of that target listed in
802 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
803 but it would be unusual to add support for a target that does not have
804 a maintainer when support is added.
810 GCC contains several testsuites to help maintain compiler quality.
811 Most of the runtime libraries and language front ends in GCC have
812 testsuites. Currently only the C language testsuites are documented
813 here; FIXME: document the others.
816 * Test Idioms:: Idioms used in testsuite code.
817 * Test Directives:: Directives used within DejaGnu tests.
818 * Ada Tests:: The Ada language testsuites.
819 * C Tests:: The C language testsuites.
820 * libgcj Tests:: The Java library testsuites.
821 * gcov Testing:: Support for testing gcov.
822 * profopt Testing:: Support for testing profile-directed optimizations.
823 * compat Testing:: Support for testing binary compatibility.
827 @subsection Idioms Used in Testsuite Code
829 In general, C testcases have a trailing @file{-@var{n}.c}, starting
830 with @file{-1.c}, in case other testcases with similar names are added
831 later. If the test is a test of some well-defined feature, it should
832 have a name referring to that feature such as
833 @file{@var{feature}-1.c}. If it does not test a well-defined feature
834 but just happens to exercise a bug somewhere in the compiler, and a
835 bug report has been filed for this bug in the GCC bug database,
836 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
837 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
838 and previously more generally, test cases are named after the date on
839 which they were added. This allows people to tell at a glance whether
840 a test failure is because of a recently found bug that has not yet
841 been fixed, or whether it may be a regression, but does not give any
842 other information about the bug or where discussion of it may be
843 found. Some other language testsuites follow similar conventions.
845 In the @file{gcc.dg} testsuite, it is often necessary to test that an
846 error is indeed a hard error and not just a warning---for example,
847 where it is a constraint violation in the C standard, which must
848 become an error with @option{-pedantic-errors}. The following idiom,
849 where the first line shown is line @var{line} of the file and the line
850 that generates the error, is used for this:
853 /* @{ dg-bogus "warning" "warning in place of error" @} */
854 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
857 It may be necessary to check that an expression is an integer constant
858 expression and has a certain value. To check that @code{@var{E}} has
859 value @code{@var{V}}, an idiom similar to the following is used:
862 char x[((E) == (V) ? 1 : -1)];
865 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
866 assertions about the types of expressions. See, for example,
867 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
868 exact rules for the types of conditional expressions in the C
869 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
871 It is useful to be able to test that optimizations are being made
872 properly. This cannot be done in all cases, but it can be done where
873 the optimization will lead to code being optimized away (for example,
874 where flow analysis or alias analysis should show that certain code
875 cannot be called) or to functions not being called because they have
876 been expanded as built-in functions. Such tests go in
877 @file{gcc.c-torture/execute}. Where code should be optimized away, a
878 call to a nonexistent function such as @code{link_failure ()} may be
879 inserted; a definition
892 will also be needed so that linking still succeeds when the test is
893 run without optimization. When all calls to a built-in function
894 should have been optimized and no calls to the non-built-in version of
895 the function should remain, that function may be defined as
896 @code{static} to call @code{abort ()} (although redeclaring a function
897 as static may not work on all targets).
899 All testcases must be portable. Target-specific testcases must have
900 appropriate code to avoid causing failures on unsupported systems;
901 unfortunately, the mechanisms for this differ by directory.
903 FIXME: discuss non-C testsuites here.
905 @node Test Directives
906 @subsection Directives used within DejaGnu tests
908 Test directives appear within comments in a test source file and begin
909 with @code{dg-}. Some of these are defined within DejaGnu and others
910 are local to the GCC testsuite.
912 The order in which test directives appear in a test can be important:
913 directives local to GCC sometimes override information used by the
914 DejaGnu directives, which know nothing about the GCC directives, so the
915 DejaGnu directives must precede GCC directives.
917 Several test directives include selectors which are usually preceded by
918 the keyword @code{target} or @code{xfail}. A selector is: one or more
919 target triplets, possibly including wildcard characters; a single
920 effective-target keyword; or a logical expression. Depending on the
921 context, the selector specifies whether a test is skipped and reported
922 as unsupported or is expected to fail. Use @samp{*-*-*} to match any
924 Effective-target keywords are defined in @file{target-supports.exp} in
927 A selector expression appears within curly braces and uses a single
928 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An
929 operand is another selector expression, an effective-target keyword,
930 a single target triplet, or a list of target triplets within quotes or
931 curly braces. For example:
934 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
935 @{ target @{ powerpc*-*-* && lp64 @} @}
936 @{ xfail @{ lp64 || vect_no_align @} @}
940 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
941 @var{do-what-keyword} specifies how the test is compiled and whether
942 it is executed. It is one of:
946 Compile with @option{-E} to run only the preprocessor.
948 Compile with @option{-S} to produce an assembly code file.
950 Compile with @option{-c} to produce a relocatable object file.
952 Compile, assemble, and link to produce an executable file.
954 Produce and run an executable file, which is expected to return
958 The default is @code{compile}. That can be overridden for a set of
959 tests by redefining @code{dg-do-what-default} within the @code{.exp}
960 file for those tests.
962 If the directive includes the optional @samp{@{ target @var{selector} @}}
963 then the test is skipped unless the target system is included in the
964 list of target triplets or matches the effective-target keyword.
966 If the directive includes the optional @samp{@{ xfail @var{selector} @}}
967 and the selector is met then the test is expected to fail. For
968 @code{dg-do run}, execution is expected to fail but compilation
971 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
972 This DejaGnu directive provides a list of compiler options, to be used
973 if the target system matches @var{selector}, that replace the default
974 options used for this set of tests.
976 @item @{ dg-add-options @var{feature} ... @}
977 Add any compiler options that are needed to access certain features.
978 This directive does nothing on targets that enable the features by
979 default, or that don't provide them at all. It must come after
980 all @code{dg-options} directives.
982 The supported values of @var{feature} are:
985 The target's C99 runtime (both headers and libraries).
987 @item mips16_attribute
988 @code{mips16} function attributes. Only MIPS targets support this feature,
989 and only then in certain modes.
992 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
993 Skip the test if the test system is included in @var{selector} and if
994 each of the options in @var{include-opts} is in the set of options with
995 which the test would be compiled and if none of the options in
996 @var{exclude-opts} is in the set of options with which the test would be
999 Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
1000 an empty @var{exclude-opts} list.
1002 @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1003 Expect the test to fail if the conditions (which are the same as for
1004 @code{dg-skip-if}) are met.
1006 @item @{ dg-require-@var{support} args @}
1007 Skip the test if the target does not provide the required support;
1008 see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
1009 These directives must appear after any @code{dg-do} directive in the test
1010 and before any @code{dg-additional-sources} directive.
1011 They require at least one argument, which can be an empty string if the
1012 specific procedure does not examine the argument.
1014 @item @{ dg-require-effective-target @var{keyword} @}
1015 Skip the test if the test target, including current multilib flags,
1016 is not covered by the effective-target keyword.
1017 This directive must appear after any @code{dg-do} directive in the test
1018 and before any @code{dg-additional-sources} directive.
1020 @item @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1021 Expect the test executable to return a nonzero exit status if the
1022 conditions (which are the same as for @code{dg-skip-if}) are met.
1024 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1025 This DejaGnu directive appears on a source line that is expected to get
1026 an error message, or else specifies the source line associated with the
1027 message. If there is no message for that line or if the text of that
1028 message is not matched by @var{regexp} then the check fails and
1029 @var{comment} is included in the @code{FAIL} message. The check does
1030 not look for the string @samp{"error"} unless it is part of @var{regexp}.
1032 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1033 This DejaGnu directive appears on a source line that is expected to get
1034 a warning message, or else specifies the source line associated with the
1035 message. If there is no message for that line or if the text of that
1036 message is not matched by @var{regexp} then the check fails and
1037 @var{comment} is included in the @code{FAIL} message. The check does
1038 not look for the string @samp{"warning"} unless it is part of @var{regexp}.
1040 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1041 The line is expected to get a message other than an error or warning.
1042 If there is no message for that line or if the text of that message is
1043 not matched by @var{regexp} then the check fails and @var{comment} is
1044 included in the @code{FAIL} message.
1046 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1047 This DejaGnu directive appears on a source line that should not get a
1048 message matching @var{regexp}, or else specifies the source line
1049 associated with the bogus message. It is usually used with @samp{xfail}
1050 to indicate that the message is a known problem for a particular set of
1053 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1054 This DejaGnu directive indicates that the test is expected to fail due
1055 to compiler messages that are not handled by @samp{dg-error},
1056 @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail}
1057 has the same effect as @samp{target}.
1059 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1060 This DejaGnu directive compares @var{regexp} to the combined output
1061 that the test executable writes to @file{stdout} and @file{stderr}.
1063 @item @{ dg-prune-output @var{regexp} @}
1064 Prune messages matching @var{regexp} from test output.
1066 @item @{ dg-additional-files "@var{filelist}" @}
1067 Specify additional files, other than source files, that must be copied
1068 to the system where the compiler runs.
1070 @item @{ dg-additional-sources "@var{filelist}" @}
1071 Specify additional source files to appear in the compile line
1072 following the main test file.
1074 @item @{ dg-final @{ @var{local-directive} @} @}
1075 This DejaGnu directive is placed within a comment anywhere in the
1076 source file and is processed after the test has been compiled and run.
1077 Multiple @samp{dg-final} commands are processed in the order in which
1078 they appear in the source file.
1080 The GCC testsuite defines the following directives to be used within
1084 @item cleanup-coverage-files
1085 Removes coverage data files generated for this test.
1087 @item cleanup-repo-files
1088 Removes files generated for this test for @option{-frepo}.
1090 @item cleanup-rtl-dump @var{suffix}
1091 Removes RTL dump files generated for this test.
1093 @item cleanup-tree-dump @var{suffix}
1094 Removes tree dump files matching @var{suffix} which were generated for
1097 @item cleanup-saved-temps
1098 Removes files for the current test which were kept for @option{--save-temps}.
1100 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1101 Passes if @var{regexp} matches text in @var{filename}.
1103 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1104 Passes if @var{regexp} does not match text in @var{filename}.
1106 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
1107 Passes if @var{symbol} is defined as a hidden symbol in the test's
1110 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
1111 Passes if @var{symbol} is not defined as a hidden symbol in the test's
1114 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
1115 Passes if @var{regex} is matched exactly @var{num} times in the test's
1118 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
1119 Passes if @var{regex} matches text in the test's assembler output.
1121 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
1122 Passes if @var{regex} does not match text in the test's assembler output.
1124 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
1125 Passes if @var{regex} matches text in the test's demangled assembler output.
1127 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
1128 Passes if @var{regex} does not match text in the test's demangled assembler
1131 @item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
1132 Passes if @var{regex} is found exactly @var{num} times in the dump file
1133 with suffix @var{suffix}.
1135 @item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1136 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
1138 @item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1139 Passes if @var{regex} does not match text in the dump file with suffix
1142 @item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1143 Passes if @var{regex} matches demangled text in the dump file with
1144 suffix @var{suffix}.
1146 @item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1147 Passes if @var{regex} does not match demangled text in the dump file with
1148 suffix @var{suffix}.
1150 @item output-exists [@{ target/xfail @var{selector} @}]
1151 Passes if compiler output file exists.
1153 @item output-exists-not [@{ target/xfail @var{selector} @}]
1154 Passes if compiler output file does not exist.
1156 @item run-gcov @var{sourcefile}
1157 Check line counts in @command{gcov} tests.
1159 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
1160 Check branch and/or call counts, in addition to line counts, in
1161 @command{gcov} tests.
1166 @subsection Ada Language Testsuites
1168 The Ada testsuite includes executable tests from the ACATS 2.5
1169 testsuite, publicly available at
1170 @uref{http://www.adaic.org/compilers/acats/2.5}
1172 These tests are integrated in the GCC testsuite in the
1173 @file{gcc/testsuite/ada/acats} directory, and
1174 enabled automatically when running @code{make check}, assuming
1175 the Ada language has been enabled when configuring GCC@.
1177 You can also run the Ada testsuite independently, using
1178 @code{make check-ada}, or run a subset of the tests by specifying which
1179 chapter to run, e.g.:
1182 $ make check-ada CHAPTERS="c3 c9"
1185 The tests are organized by directory, each directory corresponding to
1186 a chapter of the Ada Reference Manual. So for example, c9 corresponds
1187 to chapter 9, which deals with tasking features of the language.
1189 There is also an extra chapter called @file{gcc} containing a template for
1190 creating new executable tests.
1192 The tests are run using two @command{sh} scripts: @file{run_acats} and
1193 @file{run_all.sh}. To run the tests using a simulator or a cross
1194 target, see the small
1195 customization section at the top of @file{run_all.sh}.
1197 These tests are run using the build tree: they can be run without doing
1198 a @code{make install}.
1201 @subsection C Language Testsuites
1203 GCC contains the following C language testsuites, in the
1204 @file{gcc/testsuite} directory:
1208 This contains tests of particular features of the C compiler, using the
1209 more modern @samp{dg} harness. Correctness tests for various compiler
1210 features should go here if possible.
1212 Magic comments determine whether the file
1213 is preprocessed, compiled, linked or run. In these tests, error and warning
1214 message texts are compared against expected texts or regular expressions
1215 given in comments. These tests are run with the options @samp{-ansi -pedantic}
1216 unless other options are given in the test. Except as noted below they
1217 are not run with multiple optimization options.
1219 This subdirectory contains tests for binary compatibility using
1220 @file{compat.exp}, which in turn uses the language-independent support
1221 (@pxref{compat Testing, , Support for testing binary compatibility}).
1223 This subdirectory contains tests of the preprocessor.
1225 This subdirectory contains tests for debug formats. Tests in this
1226 subdirectory are run for each debug format that the compiler supports.
1228 This subdirectory contains tests of the @option{-Wformat} format
1229 checking. Tests in this directory are run with and without
1231 @item gcc.dg/noncompile
1232 This subdirectory contains tests of code that should not compile and
1233 does not need any special compilation options. They are run with
1234 multiple optimization options, since sometimes invalid code crashes
1235 the compiler with optimization.
1236 @item gcc.dg/special
1237 FIXME: describe this.
1240 This contains particular code fragments which have historically broken easily.
1241 These tests are run with multiple optimization options, so tests for features
1242 which only break at some optimization levels belong here. This also contains
1243 tests to check that certain optimizations occur. It might be worthwhile to
1244 separate the correctness tests cleanly from the code quality tests, but
1245 it hasn't been done yet.
1247 @item gcc.c-torture/compat
1248 FIXME: describe this.
1250 This directory should probably not be used for new tests.
1251 @item gcc.c-torture/compile
1252 This testsuite contains test cases that should compile, but do not
1253 need to link or run. These test cases are compiled with several
1254 different combinations of optimization options. All warnings are
1255 disabled for these test cases, so this directory is not suitable if
1256 you wish to test for the presence or absence of compiler warnings.
1257 While special options can be set, and tests disabled on specific
1258 platforms, by the use of @file{.x} files, mostly these test cases
1259 should not contain platform dependencies. FIXME: discuss how defines
1260 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
1261 @item gcc.c-torture/execute
1262 This testsuite contains test cases that should compile, link and run;
1263 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
1264 @item gcc.c-torture/execute/ieee
1265 This contains tests which are specific to IEEE floating point.
1266 @item gcc.c-torture/unsorted
1267 FIXME: describe this.
1269 This directory should probably not be used for new tests.
1270 @item gcc.c-torture/misc-tests
1271 This directory contains C tests that require special handling. Some
1272 of these tests have individual expect files, and others share
1273 special-purpose expect files:
1276 @item @code{bprob*.c}
1277 Test @option{-fbranch-probabilities} using @file{bprob.exp}, which
1278 in turn uses the generic, language-independent framework
1279 (@pxref{profopt Testing, , Support for testing profile-directed
1283 Test the testsuite itself using @file{dg-test.exp}.
1285 @item @code{gcov*.c}
1286 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
1287 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
1289 @item @code{i386-pf-*.c}
1290 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
1295 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
1296 test cases and magic comments more.
1299 @subsection The Java library testsuites.
1301 Runtime tests are executed via @samp{make check} in the
1302 @file{@var{target}/libjava/testsuite} directory in the build
1303 tree. Additional runtime tests can be checked into this testsuite.
1305 Regression testing of the core packages in libgcj is also covered by the
1306 Mauve testsuite. The @uref{http://sourceware.org/mauve/,,Mauve Project}
1307 develops tests for the Java Class Libraries. These tests are run as part
1308 of libgcj testing by placing the Mauve tree within the libjava testsuite
1309 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
1310 the location of that tree when invoking @samp{make}, as in
1311 @samp{make MAUVEDIR=~/mauve check}.
1313 To detect regressions, a mechanism in @file{mauve.exp} compares the
1314 failures for a test run against the list of expected failures in
1315 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
1316 Update this file when adding new failing tests to Mauve, or when fixing
1317 bugs in libgcj that had caused Mauve test failures.
1319 We encourage developers to contribute test cases to Mauve.
1322 @subsection Support for testing @command{gcov}
1324 Language-independent support for testing @command{gcov}, and for checking
1325 that branch profiling produces expected values, is provided by the
1326 expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures
1327 in @file{gcc.dg.exp} to compile and run the test program. A typical
1328 @command{gcov} test contains the following DejaGnu commands within comments:
1331 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
1332 @{ dg-do run @{ target native @} @}
1333 @{ dg-final @{ run-gcov sourcefile @} @}
1336 Checks of @command{gcov} output can include line counts, branch percentages,
1337 and call return percentages. All of these checks are requested via
1338 commands that appear in comments in the test's source file.
1339 Commands to check line counts are processed by default.
1340 Commands to check branch percentages and call return percentages are
1341 processed if the @command{run-gcov} command has arguments @code{branches}
1342 or @code{calls}, respectively. For example, the following specifies
1343 checking both, as well as passing @option{-b} to @command{gcov}:
1346 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
1349 A line count command appears within a comment on the source line
1350 that is expected to get the specified count and has the form
1351 @code{count(@var{cnt})}. A test should only check line counts for
1352 lines that will get the same count for any architecture.
1354 Commands to check branch percentages (@code{branch}) and call
1355 return percentages (@code{returns}) are very similar to each other.
1356 A beginning command appears on or before the first of a range of
1357 lines that will report the percentage, and the ending command
1358 follows that range of lines. The beginning command can include a
1359 list of percentages, all of which are expected to be found within
1360 the range. A range is terminated by the next command of the same
1361 kind. A command @code{branch(end)} or @code{returns(end)} marks
1362 the end of a range without starting a new one. For example:
1365 if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
1366 /* @r{branch(end)} */
1370 For a call return percentage, the value specified is the
1371 percentage of calls reported to return. For a branch percentage,
1372 the value is either the expected percentage or 100 minus that
1373 value, since the direction of a branch can differ depending on the
1374 target or the optimization level.
1376 Not all branches and calls need to be checked. A test should not
1377 check for branches that might be optimized away or replaced with
1378 predicated instructions. Don't check for calls inserted by the
1379 compiler or ones that might be inlined or optimized away.
1381 A single test can check for combinations of line counts, branch
1382 percentages, and call return percentages. The command to check a
1383 line count must appear on the line that will report that count, but
1384 commands to check branch percentages and call return percentages can
1385 bracket the lines that report them.
1387 @node profopt Testing
1388 @subsection Support for testing profile-directed optimizations
1390 The file @file{profopt.exp} provides language-independent support for
1391 checking correct execution of a test built with profile-directed
1392 optimization. This testing requires that a test program be built and
1393 executed twice. The first time it is compiled to generate profile
1394 data, and the second time it is compiled to use the data that was
1395 generated during the first execution. The second execution is to
1396 verify that the test produces the expected results.
1398 To check that the optimization actually generated better code, a
1399 test can be built and run a third time with normal optimizations to
1400 verify that the performance is better with the profile-directed
1401 optimizations. @file{profopt.exp} has the beginnings of this kind
1404 @file{profopt.exp} provides generic support for profile-directed
1405 optimizations. Each set of tests that uses it provides information
1406 about a specific optimization:
1410 tool being tested, e.g., @command{gcc}
1412 @item profile_option
1413 options used to generate profile data
1415 @item feedback_option
1416 options used to optimize using that profile data
1419 suffix of profile data files
1421 @item PROFOPT_OPTIONS
1422 list of options with which to run each test, similar to the lists for
1426 @node compat Testing
1427 @subsection Support for testing binary compatibility
1429 The file @file{compat.exp} provides language-independent support for
1430 binary compatibility testing. It supports testing interoperability of
1431 two compilers that follow the same ABI, or of multiple sets of
1432 compiler options that should not affect binary compatibility. It is
1433 intended to be used for testsuites that complement ABI testsuites.
1435 A test supported by this framework has three parts, each in a
1436 separate source file: a main program and two pieces that interact
1437 with each other to split up the functionality being tested.
1440 @item @var{testname}_main.@var{suffix}
1441 Contains the main program, which calls a function in file
1442 @file{@var{testname}_x.@var{suffix}}.
1444 @item @var{testname}_x.@var{suffix}
1445 Contains at least one call to a function in
1446 @file{@var{testname}_y.@var{suffix}}.
1448 @item @var{testname}_y.@var{suffix}
1449 Shares data with, or gets arguments from,
1450 @file{@var{testname}_x.@var{suffix}}.
1453 Within each test, the main program and one functional piece are
1454 compiled by the GCC under test. The other piece can be compiled by
1455 an alternate compiler. If no alternate compiler is specified,
1456 then all three source files are all compiled by the GCC under test.
1457 You can specify pairs of sets of compiler options. The first element
1458 of such a pair specifies options used with the GCC under test, and the
1459 second element of the pair specifies options used with the alternate
1460 compiler. Each test is compiled with each pair of options.
1462 @file{compat.exp} defines default pairs of compiler options.
1463 These can be overridden by defining the environment variable
1464 @env{COMPAT_OPTIONS} as:
1467 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
1468 ...[list @{@var{tstn}@} @{@var{altn}@}]]"
1471 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
1472 used by the compiler under test and @var{alti} used by the alternate
1473 compiler. For example, with
1474 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
1475 the test is first built with @option{-g -O0} by the compiler under
1476 test and with @option{-O3} by the alternate compiler. The test is
1477 built a second time using @option{-fpic} by the compiler under test
1478 and @option{-fPIC -O2} by the alternate compiler.
1480 An alternate compiler is specified by defining an environment
1481 variable to be the full pathname of an installed compiler; for C
1482 define @env{ALT_CC_UNDER_TEST}, and for C++ define
1483 @env{ALT_CXX_UNDER_TEST}. These will be written to the
1484 @file{site.exp} file used by DejaGnu. The default is to build each
1485 test with the compiler under test using the first of each pair of
1486 compiler options from @env{COMPAT_OPTIONS}. When
1487 @env{ALT_CC_UNDER_TEST} or
1488 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
1489 the compiler under test but with combinations of the options from
1490 @env{COMPAT_OPTIONS}.
1492 To run only the C++ compatibility suite using the compiler under test
1493 and another version of GCC using specific compiler options, do the
1494 following from @file{@var{objdir}/gcc}:
1499 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
1500 COMPAT_OPTIONS="lists as shown above" \
1502 RUNTESTFLAGS="compat.exp"
1505 A test that fails when the source files are compiled with different
1506 compilers, but passes when the files are compiled with the same
1507 compiler, demonstrates incompatibility of the generated code or
1508 runtime support. A test that fails for the alternate compiler but
1509 passes for the compiler under test probably tests for a bug that was
1510 fixed in the compiler under test but is present in the alternate
1513 The binary compatibility tests support a small number of test framework
1514 commands that appear within comments in a test file.
1518 These commands can be used in @file{@var{testname}_main.@var{suffix}}
1519 to skip the test if specific support is not available on the target.
1522 The specified options are used for compiling this particular source
1523 file, appended to the options from @env{COMPAT_OPTIONS}. When this
1524 command appears in @file{@var{testname}_main.@var{suffix}} the options
1525 are also used to link the test program.
1528 This command can be used in a secondary source file to specify that
1529 compilation is expected to fail for particular options on particular