OSDN Git Service

e4d9afca94da5a49ebce6737da9c2f5f1d785db2
[pf3gnuchains/gcc-fork.git] / gcc / doc / sourcebuild.texi
1 @c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010
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.
5
6 @node Source Tree
7 @chapter Source Tree Structure and Build System
8
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.
13
14 @menu
15 * Configure Terms:: Configuration terminology and history.
16 * Top Level::       The top level source directory.
17 * gcc Directory::   The @file{gcc} subdirectory.
18 @end menu
19
20 @include configterms.texi
21
22 @node Top Level
23 @section Top Level Source Directory
24
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:
29
30 @table @file
31 @item boehm-gc
32 The Boehm conservative garbage collector, used as part of the Java
33 runtime library.
34
35 @item config
36 Autoconf macros and Makefile fragments used throughout the tree.
37
38 @item contrib
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.
42
43 @item fixincludes
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}.
49
50 @item gcc
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.
55
56 @item gnattools
57 Support tools for GNAT.
58
59 @item include
60 Headers for the @code{libiberty} library.
61
62 @item intl
63 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
64 include it in @code{libc}.
65
66 @item libada
67 The Ada runtime library.
68
69 @item libcpp
70 The C preprocessor library.
71
72 @item libdecnumber
73 The Decimal Float support library.
74
75 @item libffi
76 The @code{libffi} library, used as part of the Java runtime library.
77
78 @item libgcc
79 The GCC runtime library.
80
81 @item libgfortran
82 The Fortran runtime library.
83
84 @item libgo
85 The Go runtime library.  The bulk of this library is mirrored from the
86 @uref{http://code.google.com/@/p/@/go, master Go repository}.
87
88 @item libgomp
89 The GNU OpenMP runtime library.
90
91 @item libiberty
92 The @code{libiberty} library, used for portability and for some
93 generally useful data structures and algorithms.  @xref{Top, ,
94 Introduction, libiberty, @sc{gnu} libiberty}, for more information
95 about this library.
96
97 @item libjava
98 The Java runtime library.
99
100 @item libmudflap
101 The @code{libmudflap} library, used for instrumenting pointer and array
102 dereferencing operations.
103
104 @item libobjc
105 The Objective-C and Objective-C++ runtime library.
106
107 @item libssp
108 The Stack protector runtime library.
109
110 @item libstdc++-v3
111 The C++ runtime library.
112
113 @item lto-plugin
114 Plugin used by @command{gold} if link-time optimizations are enabled.
115
116 @item maintainer-scripts
117 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
118
119 @item zlib
120 The @code{zlib} compression library, used by the Java front end, as
121 part of the Java runtime library, and for compressing and uncompressing
122 GCC's intermediate language in LTO object files.
123 @end table
124
125 The build system in the top level directory, including how recursion
126 into subdirectories works and how building runtime libraries for
127 multilibs is handled, is documented in a separate manual, included
128 with GNU Binutils.  @xref{Top, , GNU configure and build system,
129 configure, The GNU configure and build system}, for details.
130
131 @node gcc Directory
132 @section The @file{gcc} Subdirectory
133
134 The @file{gcc} directory contains many files that are part of the C
135 sources of GCC, other files used as part of the configuration and
136 build process, and subdirectories including documentation and a
137 testsuite.  The files that are sources of GCC are documented in a
138 separate chapter.  @xref{Passes, , Passes and Files of the Compiler}.
139
140 @menu
141 * Subdirectories:: Subdirectories of @file{gcc}.
142 * Configuration::  The configuration process, and the files it uses.
143 * Build::          The build system in the @file{gcc} directory.
144 * Makefile::       Targets in @file{gcc/Makefile}.
145 * Library Files::  Library source files and headers under @file{gcc/}.
146 * Headers::        Headers installed by GCC.
147 * Documentation::  Building documentation in GCC.
148 * Front End::      Anatomy of a language front end.
149 * Back End::       Anatomy of a target back end.
150 @end menu
151
152 @node Subdirectories
153 @subsection Subdirectories of @file{gcc}
154
155 The @file{gcc} directory contains the following subdirectories:
156
157 @table @file
158 @item @var{language}
159 Subdirectories for various languages.  Directories containing a file
160 @file{config-lang.in} are language subdirectories.  The contents of
161 the subdirectories @file{cp} (for C++), @file{lto} (for LTO),
162 @file{objc} (for Objective-C) and @file{objcp} (for Objective-C++) are
163 documented in this manual (@pxref{Passes, , Passes and Files of the
164 Compiler}); those for other languages are not.  @xref{Front End, ,
165 Anatomy of a Language Front End}, for details of the files in these
166 directories.
167
168 @item config
169 Configuration files for supported architectures and operating
170 systems.  @xref{Back End, , Anatomy of a Target Back End}, for
171 details of the files in this directory.
172
173 @item doc
174 Texinfo documentation for GCC, together with automatically generated
175 man pages and support for converting the installation manual to
176 HTML@.  @xref{Documentation}.
177
178 @item ginclude
179 System headers installed by GCC, mainly those required by the C
180 standard of freestanding implementations.  @xref{Headers, , Headers
181 Installed by GCC}, for details of when these and other headers are
182 installed.
183
184 @item po
185 Message catalogs with translations of messages produced by GCC into
186 various languages, @file{@var{language}.po}.  This directory also
187 contains @file{gcc.pot}, the template for these message catalogues,
188 @file{exgettext}, a wrapper around @command{gettext} to extract the
189 messages from the GCC sources and create @file{gcc.pot}, which is run
190 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
191 which messages should not be extracted.
192
193 @item testsuite
194 The GCC testsuites (except for those for runtime libraries).
195 @xref{Testsuites}.
196 @end table
197
198 @node Configuration
199 @subsection Configuration in the @file{gcc} Directory
200
201 The @file{gcc} directory is configured with an Autoconf-generated
202 script @file{configure}.  The @file{configure} script is generated
203 from @file{configure.ac} and @file{aclocal.m4}.  From the files
204 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
205 file @file{config.in}.  The file @file{cstamp-h.in} is used as a
206 timestamp.
207
208 @menu
209 * Config Fragments::     Scripts used by @file{configure}.
210 * System Config::        The @file{config.build}, @file{config.host}, and
211                          @file{config.gcc} files.
212 * Configuration Files::  Files created by running @file{configure}.
213 @end menu
214
215 @node Config Fragments
216 @subsubsection Scripts Used by @file{configure}
217
218 @file{configure} uses some other scripts to help in its work:
219
220 @itemize @bullet
221 @item The standard GNU @file{config.sub} and @file{config.guess}
222 files, kept in the top level directory, are used.
223
224 @item The file @file{config.gcc} is used to handle configuration
225 specific to the particular target machine.  The file
226 @file{config.build} is used to handle configuration specific to the
227 particular build machine.  The file @file{config.host} is used to handle
228 configuration specific to the particular host machine.  (In general,
229 these should only be used for features that cannot reasonably be tested in
230 Autoconf feature tests.)
231 @xref{System Config, , The @file{config.build}; @file{config.host};
232 and @file{config.gcc} Files}, for details of the contents of these files.
233
234 @item Each language subdirectory has a file
235 @file{@var{language}/config-lang.in} that is used for
236 front-end-specific configuration.  @xref{Front End Config, , The Front
237 End @file{config-lang.in} File}, for details of this file.
238
239 @item A helper script @file{configure.frag} is used as part of
240 creating the output of @file{configure}.
241 @end itemize
242
243 @node System Config
244 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
245
246 The @file{config.build} file contains specific rules for particular systems
247 which GCC is built on.  This should be used as rarely as possible, as the
248 behavior of the build system can always be detected by autoconf.
249
250 The @file{config.host} file contains specific rules for particular systems
251 which GCC will run on.  This is rarely needed.
252
253 The @file{config.gcc} file contains specific rules for particular systems
254 which GCC will generate code for.  This is usually needed.
255
256 Each file has a list of the shell variables it sets, with descriptions, at the
257 top of the file.
258
259 FIXME: document the contents of these files, and what variables should
260 be set to control build, host and target configuration.
261
262 @include configfiles.texi
263
264 @node Build
265 @subsection Build System in the @file{gcc} Directory
266
267 FIXME: describe the build system, including what is built in what
268 stages.  Also list the various source files that are used in the build
269 process but aren't source files of GCC itself and so aren't documented
270 below (@pxref{Passes}).
271
272 @include makefile.texi
273
274 @node Library Files
275 @subsection Library Source Files and Headers under the @file{gcc} Directory
276
277 FIXME: list here, with explanation, all the C source files and headers
278 under the @file{gcc} directory that aren't built into the GCC
279 executable but rather are part of runtime libraries and object files,
280 such as @file{crtstuff.c} and @file{unwind-dw2.c}.  @xref{Headers, ,
281 Headers Installed by GCC}, for more information about the
282 @file{ginclude} directory.
283
284 @node Headers
285 @subsection Headers Installed by GCC
286
287 In general, GCC expects the system C library to provide most of the
288 headers to be used with it.  However, GCC will fix those headers if
289 necessary to make them work with GCC, and will install some headers
290 required of freestanding implementations.  These headers are installed
291 in @file{@var{libsubdir}/include}.  Headers for non-C runtime
292 libraries are also installed by GCC; these are not documented here.
293 (FIXME: document them somewhere.)
294
295 Several of the headers GCC installs are in the @file{ginclude}
296 directory.  These headers, @file{iso646.h},
297 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
298 are installed in @file{@var{libsubdir}/include},
299 unless the target Makefile fragment (@pxref{Target Fragment})
300 overrides this by setting @code{USER_H}.
301
302 In addition to these headers and those generated by fixing system
303 headers to work with GCC, some other headers may also be installed in
304 @file{@var{libsubdir}/include}.  @file{config.gcc} may set
305 @code{extra_headers}; this specifies additional headers under
306 @file{config} to be installed on some systems.
307
308 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
309 This is done to cope with command-line options that change the
310 representation of floating point numbers.
311
312 GCC also installs its own version of @code{<limits.h>}; this is generated
313 from @file{glimits.h}, together with @file{limitx.h} and
314 @file{limity.h} if the system also has its own version of
315 @code{<limits.h>}.  (GCC provides its own header because it is
316 required of ISO C freestanding implementations, but needs to include
317 the system header from its own header as well because other standards
318 such as POSIX specify additional values to be defined in
319 @code{<limits.h>}.)  The system's @code{<limits.h>} header is used via
320 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
321 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
322 needs fixing, @file{syslimits.h} is the fixed copy.
323
324 GCC can also install @code{<tgmath.h>}.  It will do this when
325 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
326
327 @node Documentation
328 @subsection Building Documentation
329
330 The main GCC documentation is in the form of manuals in Texinfo
331 format.  These are installed in Info format; DVI versions may be
332 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
333 HTML versions by @samp{make html}.  In addition, some man pages are
334 generated from the Texinfo manuals, there are some other text files
335 with miscellaneous documentation, and runtime libraries have their own
336 documentation outside the @file{gcc} directory.  FIXME: document the
337 documentation for runtime libraries somewhere.
338
339 @menu
340 * Texinfo Manuals::      GCC manuals in Texinfo format.
341 * Man Page Generation::  Generating man pages from Texinfo manuals.
342 * Miscellaneous Docs::   Miscellaneous text files with documentation.
343 @end menu
344
345 @node Texinfo Manuals
346 @subsubsection Texinfo Manuals
347
348 The manuals for GCC as a whole, and the C and C++ front ends, are in
349 files @file{doc/*.texi}.  Other front ends have their own manuals in
350 files @file{@var{language}/*.texi}.  Common files
351 @file{doc/include/*.texi} are provided which may be included in
352 multiple manuals; the following files are in @file{doc/include}:
353
354 @table @file
355 @item fdl.texi
356 The GNU Free Documentation License.
357 @item funding.texi
358 The section ``Funding Free Software''.
359 @item gcc-common.texi
360 Common definitions for manuals.
361 @item gpl.texi
362 @itemx gpl_v3.texi
363 The GNU General Public License.
364 @item texinfo.tex
365 A copy of @file{texinfo.tex} known to work with the GCC manuals.
366 @end table
367
368 DVI-formatted manuals are generated by @samp{make dvi}, which uses
369 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  
370 PDF-formatted manuals are generated by @samp{make pdf}, which uses
371 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML
372 formatted manuals are generated by @samp{make html}.  Info
373 manuals are generated by @samp{make info} (which is run as part of
374 a bootstrap); this generates the manuals in the source directory,
375 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
376 and they are included in release distributions.
377
378 Manuals are also provided on the GCC web site, in both HTML and
379 PostScript forms.  This is done via the script
380 @file{maintainer-scripts/update_web_docs_svn}.  Each manual to be
381 provided online must be listed in the definition of @code{MANUALS} in
382 that file; a file @file{@var{name}.texi} must only appear once in the
383 source tree, and the output manual must have the same name as the
384 source file.  (However, other Texinfo files, included in manuals but
385 not themselves the root files of manuals, may have names that appear
386 more than once in the source tree.)  The manual file
387 @file{@var{name}.texi} should only include other files in its own
388 directory or in @file{doc/include}.  HTML manuals will be generated by
389 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
390 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
391 All Texinfo files that are parts of manuals must
392 be version-controlled, even if they are generated files, for the
393 generation of online manuals to work.
394
395 The installation manual, @file{doc/install.texi}, is also provided on
396 the GCC web site.  The HTML version is generated by the script
397 @file{doc/install.texi2html}.
398
399 @node Man Page Generation
400 @subsubsection Man Page Generation
401
402 Because of user demand, in addition to full Texinfo manuals, man pages
403 are provided which contain extracts from those manuals.  These man
404 pages are generated from the Texinfo manuals using
405 @file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for
406 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
407 to @file{gcc.1}, but all the other man pages are generated from
408 Texinfo manuals.)
409
410 Because many systems may not have the necessary tools installed to
411 generate the man pages, they are only generated if the
412 @file{configure} script detects that recent enough tools are
413 installed, and the Makefiles allow generating man pages to fail
414 without aborting the build.  Man pages are also included in release
415 distributions.  They are generated in the source directory.
416
417 Magic comments in Texinfo files starting @samp{@@c man} control what
418 parts of a Texinfo file go into a man page.  Only a subset of Texinfo
419 is supported by @file{texi2pod.pl}, and it may be necessary to add
420 support for more Texinfo features to this script when generating new
421 man pages.  To improve the man page output, some special Texinfo
422 macros are provided in @file{doc/include/gcc-common.texi} which
423 @file{texi2pod.pl} understands:
424
425 @table @code
426 @item @@gcctabopt
427 Use in the form @samp{@@table @@gcctabopt} for tables of options,
428 where for printed output the effect of @samp{@@code} is better than
429 that of @samp{@@option} but for man page output a different effect is
430 wanted.
431 @item @@gccoptlist
432 Use for summary lists of options in manuals.
433 @item @@gol
434 Use at the end of each line inside @samp{@@gccoptlist}.  This is
435 necessary to avoid problems with differences in how the
436 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
437 @end table
438
439 FIXME: describe the @file{texi2pod.pl} input language and magic
440 comments in more detail.
441
442 @node Miscellaneous Docs
443 @subsubsection Miscellaneous Documentation
444
445 In addition to the formal documentation that is installed by GCC,
446 there are several other text files in the @file{gcc} subdirectory
447 with miscellaneous documentation:
448
449 @table @file
450 @item ABOUT-GCC-NLS
451 Notes on GCC's Native Language Support.  FIXME: this should be part of
452 this manual rather than a separate file.
453 @item ABOUT-NLS
454 Notes on the Free Translation Project.
455 @item COPYING
456 @itemx COPYING3
457 The GNU General Public License, Versions 2 and 3.
458 @item COPYING.LIB
459 @itemx COPYING3.LIB
460 The GNU Lesser General Public License, Versions 2.1 and 3.
461 @item *ChangeLog*
462 @itemx */ChangeLog*
463 Change log files for various parts of GCC@.
464 @item LANGUAGES
465 Details of a few changes to the GCC front-end interface.  FIXME: the
466 information in this file should be part of general documentation of
467 the front-end interface in this manual.
468 @item ONEWS
469 Information about new features in old versions of GCC@.  (For recent
470 versions, the information is on the GCC web site.)
471 @item README.Portability
472 Information about portability issues when writing code in GCC@.  FIXME:
473 why isn't this part of this manual or of the GCC Coding Conventions?
474 @end table
475
476 FIXME: document such files in subdirectories, at least @file{config},
477 @file{cp}, @file{objc}, @file{testsuite}.
478
479 @node Front End
480 @subsection Anatomy of a Language Front End
481
482 A front end for a language in GCC has the following parts:
483
484 @itemize @bullet
485 @item
486 A directory @file{@var{language}} under @file{gcc} containing source
487 files for that front end.  @xref{Front End Directory, , The Front End
488 @file{@var{language}} Directory}, for details.
489 @item
490 A mention of the language in the list of supported languages in
491 @file{gcc/doc/install.texi}.
492 @item
493 A mention of the name under which the language's runtime library is
494 recognized by @option{--enable-shared=@var{package}} in the
495 documentation of that option in @file{gcc/doc/install.texi}.
496 @item
497 A mention of any special prerequisites for building the front end in
498 the documentation of prerequisites in @file{gcc/doc/install.texi}.
499 @item
500 Details of contributors to that front end in
501 @file{gcc/doc/contrib.texi}.  If the details are in that front end's
502 own manual then there should be a link to that manual's list in
503 @file{contrib.texi}.
504 @item
505 Information about support for that language in
506 @file{gcc/doc/frontends.texi}.
507 @item
508 Information about standards for that language, and the front end's
509 support for them, in @file{gcc/doc/standards.texi}.  This may be a
510 link to such information in the front end's own manual.
511 @item
512 Details of source file suffixes for that language and @option{-x
513 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
514 @item
515 Entries in @code{default_compilers} in @file{gcc.c} for source file
516 suffixes for that language.
517 @item
518 Preferably testsuites, which may be under @file{gcc/testsuite} or
519 runtime library directories.  FIXME: document somewhere how to write
520 testsuite harnesses.
521 @item
522 Probably a runtime library for the language, outside the @file{gcc}
523 directory.  FIXME: document this further.
524 @item
525 Details of the directories of any runtime libraries in
526 @file{gcc/doc/sourcebuild.texi}.
527 @item
528 Check targets in @file{Makefile.def} for the top-level @file{Makefile}
529 to check just the compiler or the compiler and runtime library for the
530 language.
531 @end itemize
532
533 If the front end is added to the official GCC source repository, the
534 following are also necessary:
535
536 @itemize @bullet
537 @item
538 At least one Bugzilla component for bugs in that front end and runtime
539 libraries.  This category needs to be added to the Bugzilla database.
540 @item
541 Normally, one or more maintainers of that front end listed in
542 @file{MAINTAINERS}.
543 @item
544 Mentions on the GCC web site in @file{index.html} and
545 @file{frontends.html}, with any relevant links on
546 @file{readings.html}.  (Front ends that are not an official part of
547 GCC may also be listed on @file{frontends.html}, with relevant links.)
548 @item
549 A news item on @file{index.html}, and possibly an announcement on the
550 @email{gcc-announce@@gcc.gnu.org} mailing list.
551 @item
552 The front end's manuals should be mentioned in
553 @file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals})
554 and the online manuals should be linked to from
555 @file{onlinedocs/index.html}.
556 @item
557 Any old releases or CVS repositories of the front end, before its
558 inclusion in GCC, should be made available on the GCC FTP site
559 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
560 @item
561 The release and snapshot script @file{maintainer-scripts/gcc_release}
562 should be updated to generate appropriate tarballs for this front end.
563 The associated @file{maintainer-scripts/snapshot-README} and
564 @file{maintainer-scripts/snapshot-index.html} files should be updated
565 to list the tarballs and diffs for this front end.
566 @item
567 If this front end includes its own version files that include the
568 current date, @file{maintainer-scripts/update_version} should be
569 updated accordingly.
570 @end itemize
571
572 @menu
573 * Front End Directory::  The front end @file{@var{language}} directory.
574 * Front End Config::     The front end @file{config-lang.in} file.
575 * Front End Makefile::   The front end @file{Make-lang.in} file.
576 @end menu
577
578 @node Front End Directory
579 @subsubsection The Front End @file{@var{language}} Directory
580
581 A front end @file{@var{language}} directory contains the source files
582 of that front end (but not of any runtime libraries, which should be
583 outside the @file{gcc} directory).  This includes documentation, and
584 possibly some subsidiary programs built alongside the front end.
585 Certain files are special and other parts of the compiler depend on
586 their names:
587
588 @table @file
589 @item config-lang.in
590 This file is required in all language subdirectories.  @xref{Front End
591 Config, , The Front End @file{config-lang.in} File}, for details of
592 its contents
593 @item Make-lang.in
594 This file is required in all language subdirectories.  @xref{Front End
595 Makefile, , The Front End @file{Make-lang.in} File}, for details of its
596 contents.
597 @item lang.opt
598 This file registers the set of switches that the front end accepts on
599 the command line, and their @option{--help} text.  @xref{Options}.
600 @item lang-specs.h
601 This file provides entries for @code{default_compilers} in
602 @file{gcc.c} which override the default of giving an error that a
603 compiler for that language is not installed.
604 @item @var{language}-tree.def
605 This file, which need not exist, defines any language-specific tree
606 codes.
607 @end table
608
609 @node Front End Config
610 @subsubsection The Front End @file{config-lang.in} File
611
612 Each language subdirectory contains a @file{config-lang.in} file.  In
613 addition the main directory contains @file{c-config-lang.in}, which
614 contains limited information for the C language.  This file is a shell
615 script that may define some variables describing the language:
616
617 @table @code
618 @item language
619 This definition must be present, and gives the name of the language
620 for some purposes such as arguments to @option{--enable-languages}.
621 @item lang_requires
622 If defined, this variable lists (space-separated) language front ends
623 other than C that this front end requires to be enabled (with the
624 names given being their @code{language} settings).  For example, the
625 Java front end depends on the C++ front end, so sets
626 @samp{lang_requires=c++}.
627 @item subdir_requires
628 If defined, this variable lists (space-separated) front end directories
629 other than C that this front end requires to be present.  For example,
630 the Objective-C++ front end uses source files from the C++ and
631 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
632 @item target_libs
633 If defined, this variable lists (space-separated) targets in the top
634 level @file{Makefile} to build the runtime libraries for this
635 language, such as @code{target-libobjc}.
636 @item lang_dirs
637 If defined, this variable lists (space-separated) top level
638 directories (parallel to @file{gcc}), apart from the runtime libraries,
639 that should not be configured if this front end is not built.
640 @item build_by_default
641 If defined to @samp{no}, this language front end is not built unless
642 enabled in a @option{--enable-languages} argument.  Otherwise, front
643 ends are built by default, subject to any special logic in
644 @file{configure.ac} (as is present to disable the Ada front end if the
645 Ada compiler is not already installed).
646 @item boot_language
647 If defined to @samp{yes}, this front end is built in stage1 of the
648 bootstrap.  This is only relevant to front ends written in their own
649 languages.
650 @item compilers
651 If defined, a space-separated list of compiler executables that will
652 be run by the driver.  The names here will each end
653 with @samp{\$(exeext)}.
654 @item outputs
655 If defined, a space-separated list of files that should be generated
656 by @file{configure} substituting values in them.  This mechanism can
657 be used to create a file @file{@var{language}/Makefile} from
658 @file{@var{language}/Makefile.in}, but this is deprecated, building
659 everything from the single @file{gcc/Makefile} is preferred.
660 @item gtfiles
661 If defined, a space-separated list of files that should be scanned by
662 @file{gengtype.c} to generate the garbage collection tables and routines for
663 this language.  This excludes the files that are common to all front
664 ends.  @xref{Type Information}.
665
666 @end table
667
668 @node Front End Makefile
669 @subsubsection The Front End @file{Make-lang.in} File
670
671 Each language subdirectory contains a @file{Make-lang.in} file.  It contains
672 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
673 setting of @code{language} in @file{config-lang.in}) for the following
674 values of @code{@var{hook}}, and any other Makefile rules required to
675 build those targets (which may if necessary use other Makefiles
676 specified in @code{outputs} in @file{config-lang.in}, although this is
677 deprecated).  It also adds any testsuite targets that can use the
678 standard rule in @file{gcc/Makefile.in} to the variable
679 @code{lang_checks}.
680
681 @table @code
682 @itemx all.cross
683 @itemx start.encap
684 @itemx rest.encap
685 FIXME: exactly what goes in each of these targets?
686 @item tags
687 Build an @command{etags} @file{TAGS} file in the language subdirectory
688 in the source tree.
689 @item info
690 Build info documentation for the front end, in the build directory.
691 This target is only called by @samp{make bootstrap} if a suitable
692 version of @command{makeinfo} is available, so does not need to check
693 for this, and should fail if an error occurs.
694 @item dvi
695 Build DVI documentation for the front end, in the build directory.
696 This should be done using @code{$(TEXI2DVI)}, with appropriate
697 @option{-I} arguments pointing to directories of included files.
698 @item pdf
699 Build PDF documentation for the front end, in the build directory.
700 This should be done using @code{$(TEXI2PDF)}, with appropriate
701 @option{-I} arguments pointing to directories of included files.
702 @item html
703 Build HTML documentation for the front end, in the build directory.
704 @item man
705 Build generated man pages for the front end from Texinfo manuals
706 (@pxref{Man Page Generation}), in the build directory.  This target
707 is only called if the necessary tools are available, but should ignore
708 errors so as not to stop the build if errors occur; man pages are
709 optional and the tools involved may be installed in a broken way.
710 @item install-common
711 Install everything that is part of the front end, apart from the
712 compiler executables listed in @code{compilers} in
713 @file{config-lang.in}.
714 @item install-info
715 Install info documentation for the front end, if it is present in the
716 source directory.  This target should have dependencies on info files
717 that should be installed.
718 @item install-man
719 Install man pages for the front end.  This target should ignore
720 errors.
721 @item install-plugin
722 Install headers needed for plugins.
723 @item srcextra
724 Copies its dependencies into the source directory.  This generally should
725 be used for generated files such as Bison output files which are not
726 version-controlled, but should be included in any release tarballs.  This
727 target will be executed during a bootstrap if
728 @samp{--enable-generated-files-in-srcdir} was specified as a
729 @file{configure} option.
730 @item srcinfo
731 @itemx srcman
732 Copies its dependencies into the source directory.  These targets will be
733 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
734 was specified as a @file{configure} option.
735 @item uninstall
736 Uninstall files installed by installing the compiler.  This is
737 currently documented not to be supported, so the hook need not do
738 anything.
739 @item mostlyclean
740 @itemx clean
741 @itemx distclean
742 @itemx maintainer-clean
743 The language parts of the standard GNU
744 @samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for
745 Users, standards, GNU Coding Standards}, for details of the standard
746 targets.  For GCC, @code{maintainer-clean} should delete
747 all generated files in the source directory that are not version-controlled,
748 but should not delete anything that is.
749 @end table
750
751 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
752 to a list of host object files that are used by that language.
753
754 @node Back End
755 @subsection Anatomy of a Target Back End
756
757 A back end for a target architecture in GCC has the following parts:
758
759 @itemize @bullet
760 @item
761 A directory @file{@var{machine}} under @file{gcc/config}, containing a
762 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
763 , Machine Descriptions}), header files @file{@var{machine}.h} and
764 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
765 (@pxref{Target Macros, , Target Description Macros and Functions}),
766 possibly a target Makefile fragment @file{t-@var{machine}}
767 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
768 some other files.  The names of these files may be changed from the
769 defaults given by explicit specifications in @file{config.gcc}.
770 @item
771 If necessary, a file @file{@var{machine}-modes.def} in the
772 @file{@var{machine}} directory, containing additional machine modes to
773 represent condition codes.  @xref{Condition Code}, for further details.
774 @item
775 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
776 directory, containing a list of target-specific options.  You can also
777 add other option files using the @code{extra_options} variable in
778 @file{config.gcc}.  @xref{Options}.
779 @item
780 Entries in @file{config.gcc} (@pxref{System Config, , The
781 @file{config.gcc} File}) for the systems with this target
782 architecture.
783 @item
784 Documentation in @file{gcc/doc/invoke.texi} for any command-line
785 options supported by this target (@pxref{Run-time Target, , Run-time
786 Target Specification}).  This means both entries in the summary table
787 of options and details of the individual options.
788 @item
789 Documentation in @file{gcc/doc/extend.texi} for any target-specific
790 attributes supported (@pxref{Target Attributes, , Defining
791 target-specific uses of @code{__attribute__}}), including where the
792 same attribute is already supported on some targets, which are
793 enumerated in the manual.
794 @item
795 Documentation in @file{gcc/doc/extend.texi} for any target-specific
796 pragmas supported.
797 @item
798 Documentation in @file{gcc/doc/extend.texi} of any target-specific
799 built-in functions supported.
800 @item
801 Documentation in @file{gcc/doc/extend.texi} of any target-specific
802 format checking styles supported.
803 @item
804 Documentation in @file{gcc/doc/md.texi} of any target-specific
805 constraint letters (@pxref{Machine Constraints, , Constraints for
806 Particular Machines}).
807 @item
808 A note in @file{gcc/doc/contrib.texi} under the person or people who
809 contributed the target support.
810 @item
811 Entries in @file{gcc/doc/install.texi} for all target triplets
812 supported with this target architecture, giving details of any special
813 notes about installation for this target, or saying that there are no
814 special notes if there are none.
815 @item
816 Possibly other support outside the @file{gcc} directory for runtime
817 libraries.  FIXME: reference docs for this.  The @code{libstdc++} porting
818 manual needs to be installed as info for this to work, or to be a
819 chapter of this manual.
820 @end itemize
821
822 If the back end is added to the official GCC source repository, the
823 following are also necessary:
824
825 @itemize @bullet
826 @item
827 An entry for the target architecture in @file{readings.html} on the
828 GCC web site, with any relevant links.
829 @item
830 Details of the properties of the back end and target architecture in
831 @file{backends.html} on the GCC web site.
832 @item
833 A news item about the contribution of support for that target
834 architecture, in @file{index.html} on the GCC web site.
835 @item
836 Normally, one or more maintainers of that target listed in
837 @file{MAINTAINERS}.  Some existing architectures may be unmaintained,
838 but it would be unusual to add support for a target that does not have
839 a maintainer when support is added.
840 @end itemize
841
842 @node Testsuites
843 @chapter Testsuites
844
845 GCC contains several testsuites to help maintain compiler quality.
846 Most of the runtime libraries and language front ends in GCC have
847 testsuites.  Currently only the C language testsuites are documented
848 here; FIXME: document the others.
849
850 @menu
851 * Test Idioms::     Idioms used in testsuite code.
852 * Test Directives:: Directives used within DejaGnu tests.
853 * Ada Tests::       The Ada language testsuites.
854 * C Tests::         The C language testsuites.
855 * libgcj Tests::    The Java library testsuites.
856 * LTO Testing::     Support for testing link-time optimizations.
857 * gcov Testing::    Support for testing gcov.
858 * profopt Testing:: Support for testing profile-directed optimizations.
859 * compat Testing::  Support for testing binary compatibility.
860 * Torture Tests::   Support for torture testing using multiple options.
861 @end menu
862
863 @node Test Idioms
864 @section Idioms Used in Testsuite Code
865
866 In general, C testcases have a trailing @file{-@var{n}.c}, starting
867 with @file{-1.c}, in case other testcases with similar names are added
868 later.  If the test is a test of some well-defined feature, it should
869 have a name referring to that feature such as
870 @file{@var{feature}-1.c}.  If it does not test a well-defined feature
871 but just happens to exercise a bug somewhere in the compiler, and a
872 bug report has been filed for this bug in the GCC bug database,
873 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
874 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
875 and previously more generally, test cases are named after the date on
876 which they were added.  This allows people to tell at a glance whether
877 a test failure is because of a recently found bug that has not yet
878 been fixed, or whether it may be a regression, but does not give any
879 other information about the bug or where discussion of it may be
880 found.  Some other language testsuites follow similar conventions.
881
882 In the @file{gcc.dg} testsuite, it is often necessary to test that an
883 error is indeed a hard error and not just a warning---for example,
884 where it is a constraint violation in the C standard, which must
885 become an error with @option{-pedantic-errors}.  The following idiom,
886 where the first line shown is line @var{line} of the file and the line
887 that generates the error, is used for this:
888
889 @smallexample
890 /* @{ dg-bogus "warning" "warning in place of error" @} */
891 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
892 @end smallexample
893
894 It may be necessary to check that an expression is an integer constant
895 expression and has a certain value.  To check that @code{@var{E}} has
896 value @code{@var{V}}, an idiom similar to the following is used:
897
898 @smallexample
899 char x[((E) == (V) ? 1 : -1)];
900 @end smallexample
901
902 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
903 assertions about the types of expressions.  See, for example,
904 @file{gcc.dg/c99-condexpr-1.c}.  The more subtle uses depend on the
905 exact rules for the types of conditional expressions in the C
906 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
907
908 It is useful to be able to test that optimizations are being made
909 properly.  This cannot be done in all cases, but it can be done where
910 the optimization will lead to code being optimized away (for example,
911 where flow analysis or alias analysis should show that certain code
912 cannot be called) or to functions not being called because they have
913 been expanded as built-in functions.  Such tests go in
914 @file{gcc.c-torture/execute}.  Where code should be optimized away, a
915 call to a nonexistent function such as @code{link_failure ()} may be
916 inserted; a definition
917
918 @smallexample
919 #ifndef __OPTIMIZE__
920 void
921 link_failure (void)
922 @{
923   abort ();
924 @}
925 #endif
926 @end smallexample
927
928 @noindent
929 will also be needed so that linking still succeeds when the test is
930 run without optimization.  When all calls to a built-in function
931 should have been optimized and no calls to the non-built-in version of
932 the function should remain, that function may be defined as
933 @code{static} to call @code{abort ()} (although redeclaring a function
934 as static may not work on all targets).
935
936 All testcases must be portable.  Target-specific testcases must have
937 appropriate code to avoid causing failures on unsupported systems;
938 unfortunately, the mechanisms for this differ by directory.
939
940 FIXME: discuss non-C testsuites here.
941
942 @node Test Directives
943 @section Directives used within DejaGnu tests
944
945 @menu
946 * Directives::  Syntax and descriptions of test directives.
947 * Selectors:: Selecting targets to which a test applies.
948 * Effective-Target Keywords:: Keywords describing target attributes.
949 * Add Options:: Features for @code{dg-add-options}
950 * Require Support:: Variants of @code{dg-require-@var{support}}
951 * Final Actions:: Commands for use in @code{dg-final}
952 @end menu
953
954 @node Directives
955 @subsection Syntax and Descriptions of test directives
956
957 Test directives appear within comments in a test source file and begin
958 with @code{dg-}.  Some of these are defined within DejaGnu and others
959 are local to the GCC testsuite.
960
961 The order in which test directives appear in a test can be important:
962 directives local to GCC sometimes override information used by the
963 DejaGnu directives, which know nothing about the GCC directives, so the
964 DejaGnu directives must precede GCC directives.
965
966 Several test directives include selectors (@pxref{Selectors, , })
967 which are usually preceded by the keyword @code{target} or @code{xfail}.
968
969 @subsubsection Specify how to build the test
970
971 @table @code
972 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
973 @var{do-what-keyword} specifies how the test is compiled and whether
974 it is executed.  It is one of:
975
976 @table @code
977 @item preprocess
978 Compile with @option{-E} to run only the preprocessor.
979 @item compile
980 Compile with @option{-S} to produce an assembly code file.
981 @item assemble
982 Compile with @option{-c} to produce a relocatable object file.
983 @item link
984 Compile, assemble, and link to produce an executable file.
985 @item run
986 Produce and run an executable file, which is expected to return
987 an exit code of 0.
988 @end table
989
990 The default is @code{compile}.  That can be overridden for a set of
991 tests by redefining @code{dg-do-what-default} within the @code{.exp}
992 file for those tests.
993
994 If the directive includes the optional @samp{@{ target @var{selector} @}}
995 then the test is skipped unless the target system matches the
996 @var{selector}.
997
998 If @var{do-what-keyword} is @code{run} and the directive includes
999 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
1000 then the test is expected to fail.  The @code{xfail} clause is ignored
1001 for other values of @var{do-what-keyword}; those tests can use
1002 directive @code{dg-xfail-if}.
1003 @end table
1004
1005 @subsubsection Specify additional compiler options
1006
1007 @table @code
1008 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
1009 This DejaGnu directive provides a list of compiler options, to be used
1010 if the target system matches @var{selector}, that replace the default
1011 options used for this set of tests.
1012
1013 @item @{ dg-add-options @var{feature} @dots{} @}
1014 Add any compiler options that are needed to access certain features.
1015 This directive does nothing on targets that enable the features by
1016 default, or that don't provide them at all.  It must come after
1017 all @code{dg-options} directives.
1018 For supported values of @var{feature} see @ref{Add Options, ,}.
1019 @end table
1020
1021 @subsubsection Modify the test timeout value
1022
1023 The normal timeout limit, in seconds, is found by searching the
1024 following in order:
1025
1026 @itemize @bullet
1027 @item the value defined by an earlier @code{dg-timeout} directive in
1028 the test
1029
1030 @item variable @var{tool_timeout} defined by the set of tests
1031
1032 @item @var{gcc},@var{timeout} set in the target board
1033
1034 @item 300
1035 @end itemize
1036
1037 @table @code
1038 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
1039 Set the time limit for the compilation and for the execution of the test
1040 to the specified number of seconds.
1041
1042 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
1043 Multiply the normal time limit for compilation and execution of the test
1044 by the specified floating-point factor.
1045 @end table
1046
1047 @subsubsection Skip a test for some targets
1048
1049 @table @code
1050 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1051 Arguments @var{include-opts} and @var{exclude-opts} are lists in which
1052 each element is a string of zero or more GCC options.
1053 Skip the test if all of the following conditions are met:
1054 @itemize @bullet
1055 @item the test system is included in @var{selector}
1056
1057 @item for at least one of the option strings in @var{include-opts},
1058 every option from that string is in the set of options with which
1059 the test would be compiled; use @samp{"*"} for an @var{include-opts} list
1060 that matches any options; that is the default if @var{include-opts} is
1061 not specified
1062
1063 @item for each of the option strings in @var{exclude-opts}, at least one
1064 option from that string is not in the set of options with which the test
1065 would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
1066 that is the default if @var{exclude-opts} is not specified
1067 @end itemize
1068
1069 For example, to skip a test if option @code{-Os} is present:
1070
1071 @smallexample
1072 /* @{ dg-skip-if "" @{ *-*-* @}  @{ "-Os" @} @{ "" @} @} */
1073 @end smallexample
1074
1075 To skip a test if both options @code{-O2} and @code{-g} are present:
1076
1077 @smallexample
1078 /* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2 -g" @} @{ "" @} @} */
1079 @end smallexample
1080
1081 To skip a test if either @code{-O2} or @code{-O3} is present:
1082
1083 @smallexample
1084 /* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2" "-O3" @} @{ "" @} @} */
1085 @end smallexample
1086
1087 To skip a test unless option @code{-Os} is present:
1088
1089 @smallexample
1090 /* @{ dg-skip-if "" @{ *-*-* @}  @{ "*" @} @{ "-Os" @} @} */
1091 @end smallexample
1092
1093 To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
1094 but not if @code{-fpic} is also present:
1095
1096 @smallexample
1097 /* @{ dg-skip-if "" @{ *-*-* @}  @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
1098 @end smallexample
1099
1100 @item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @}
1101 Skip the test if the test target, including current multilib flags,
1102 is not covered by the effective-target keyword.
1103 If the directive includes the optional @samp{@{ @var{selector} @}}
1104 then the effective-target test is only performed if the target system
1105 matches the @var{selector}.
1106 This directive must appear after any @code{dg-do} directive in the test
1107 and before any @code{dg-additional-sources} directive.
1108 @xref{Effective-Target Keywords, , }.
1109
1110 @item @{ dg-require-@var{support} args @}
1111 Skip the test if the target does not provide the required support.
1112 These directives must appear after any @code{dg-do} directive in the test
1113 and before any @code{dg-additional-sources} directive.
1114 They require at least one argument, which can be an empty string if the
1115 specific procedure does not examine the argument.
1116 @xref{Require Support, , }, for a complete list of these directives.
1117 @end table
1118
1119 @subsubsection Expect a test to fail for some targets
1120
1121 @table @code
1122 @item  @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1123 Expect the test to fail if the conditions (which are the same as for
1124 @code{dg-skip-if}) are met.  This does not affect the execute step.
1125
1126 @item  @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
1127 Expect the execute step of a test to fail if the conditions (which are
1128 the same as for @code{dg-skip-if}) are met.
1129 @end table
1130
1131 @subsubsection Expect the test executable to fail
1132
1133 @table @code
1134 @item  @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @}
1135 Expect the test executable to return a nonzero exit status if the
1136 conditions (which are the same as for @code{dg-skip-if}) are met.
1137 @end table
1138
1139 @subsubsection Verify compiler messages
1140
1141 @table @code
1142 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1143 This DejaGnu directive appears on a source line that is expected to get
1144 an error message, or else specifies the source line associated with the
1145 message.  If there is no message for that line or if the text of that
1146 message is not matched by @var{regexp} then the check fails and
1147 @var{comment} is included in the @code{FAIL} message.  The check does
1148 not look for the string @samp{error} unless it is part of @var{regexp}.
1149
1150 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1151 This DejaGnu directive appears on a source line that is expected to get
1152 a warning message, or else specifies the source line associated with the
1153 message.  If there is no message for that line or if the text of that
1154 message is not matched by @var{regexp} then the check fails and
1155 @var{comment} is included in the @code{FAIL} message.  The check does
1156 not look for the string @samp{warning} unless it is part of @var{regexp}.
1157
1158 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1159 The line is expected to get a message other than an error or warning.
1160 If there is no message for that line or if the text of that message is
1161 not matched by @var{regexp} then the check fails and @var{comment} is
1162 included in the @code{FAIL} message.
1163
1164 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1165 This DejaGnu directive appears on a source line that should not get a
1166 message matching @var{regexp}, or else specifies the source line
1167 associated with the bogus message.  It is usually used with @samp{xfail}
1168 to indicate that the message is a known problem for a particular set of
1169 targets.
1170
1171 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1172 This DejaGnu directive indicates that the test is expected to fail due
1173 to compiler messages that are not handled by @samp{dg-error},
1174 @samp{dg-warning} or @samp{dg-bogus}.  For this directive @samp{xfail}
1175 has the same effect as @samp{target}.
1176
1177 @item @{ dg-prune-output @var{regexp} @}
1178 Prune messages matching @var{regexp} from the test output.
1179 @end table
1180
1181 @subsubsection Verify output of the test executable
1182
1183 @table @code
1184 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1185 This DejaGnu directive compares @var{regexp} to the combined output
1186 that the test executable writes to @file{stdout} and @file{stderr}.
1187 @end table
1188
1189 @subsubsection Specify additional files for a test
1190
1191 @table @code
1192 @item @{ dg-additional-files "@var{filelist}" @}
1193 Specify additional files, other than source files, that must be copied
1194 to the system where the compiler runs.
1195
1196 @item @{ dg-additional-sources "@var{filelist}" @}
1197 Specify additional source files to appear in the compile line
1198 following the main test file.
1199 @end table
1200
1201 @subsubsection Add checks at the end of a test
1202
1203 @table @code
1204 @item @{ dg-final @{ @var{local-directive} @} @}
1205 This DejaGnu directive is placed within a comment anywhere in the
1206 source file and is processed after the test has been compiled and run.
1207 Multiple @samp{dg-final} commands are processed in the order in which
1208 they appear in the source file.  @xref{Final Actions, , }, for a list
1209 of directives that can be used within @code{dg-final}.
1210 @end table
1211
1212 @node Selectors
1213 @subsection Selecting targets to which a test applies
1214
1215 Several test directives include @var{selector}s to limit the targets
1216 for which a test is run or to declare that a test is expected to fail
1217 on particular targets.
1218
1219 A selector is:
1220 @itemize @bullet
1221 @item one or more target triplets, possibly including wildcard characters
1222 @item a single effective-target keyword (@pxref{Effective-Target Keywords})
1223 @item a logical expression
1224 @end itemize
1225
1226 Depending on the
1227 context, the selector specifies whether a test is skipped and reported
1228 as unsupported or is expected to fail.  Use @samp{*-*-*} to match any
1229 target.
1230
1231 A selector expression appears within curly braces and uses a single
1232 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}.  An
1233 operand is another selector expression, an effective-target keyword,
1234 a single target triplet, or a list of target triplets within quotes or
1235 curly braces.  For example:
1236
1237 @smallexample
1238 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
1239 @{ target @{ powerpc*-*-* && lp64 @} @}
1240 @{ xfail @{ lp64 || vect_no_align @} @}
1241 @end smallexample
1242
1243 @node Effective-Target Keywords
1244 @subsection Keywords describing target attributes
1245
1246 Effective-target keywords identify sets of targets that support
1247 particular functionality.  They are used to limit tests to be run only
1248 for particular targets, or to specify that particular sets of targets
1249 are expected to fail some tests.
1250
1251 Effective-target keywords are defined in @file{lib/target-supports.exp} in
1252 the GCC testsuite, with the exception of those that are documented as
1253 being local to a particular test directory.
1254
1255 The @samp{effective target} takes into account all of the compiler options
1256 with which the test will be compiled, including the multilib options.
1257 By convention, keywords ending in @code{_nocache} can also include options
1258 specified for the particular test in an earlier @code{dg-options} or
1259 @code{dg-add-options} directive.
1260
1261 @subsubsection Data type sizes
1262
1263 @table @code
1264 @item ilp32
1265 Target has 32-bit @code{int}, @code{long}, and pointers.
1266
1267 @item lp64
1268 Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
1269
1270 @item llp64
1271 Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
1272 and pointers.
1273
1274 @item double64
1275 Target has 64-bit @code{double}.
1276
1277 @item double64plus
1278 Target has @code{double} that is 64 bits or longer.
1279
1280 @item int32plus
1281 Target has @code{int} that is at 32 bits or longer.
1282
1283 @item int16
1284 Target has @code{int} that is 16 bits or shorter.
1285
1286 @item large_double
1287 Target supports @code{double} that is longer than @code{float}.
1288
1289 @item large_long_double
1290 Target supports @code{long double} that is longer than @code{double}.
1291
1292 @item ptr32plus
1293 Target has pointers that are 32 bits or longer.
1294
1295 @item size32plus
1296 Target supports array and structure sizes that are 32 bits or longer.
1297
1298 @item 4byte_wchar_t
1299 Target has @code{wchar_t} that is at least 4 bytes.
1300 @end table
1301
1302 @subsubsection Fortran-specific attributes
1303
1304 @table @code
1305 @item fortran_integer_16
1306 Target supports Fortran @code{integer} that is 16 bytes or longer.
1307
1308 @item fortran_large_int
1309 Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
1310
1311 @item fortran_large_real
1312 Target supports Fortran @code{real} kinds larger than @code{real(8)}.
1313 @end table
1314
1315 @subsubsection Vector-specific attributes
1316
1317 @table @code
1318 @item vect_condition
1319 Target supports vector conditional operations.
1320
1321 @item vect_double
1322 Target supports hardware vectors of @code{double}.
1323
1324 @item vect_float
1325 Target supports hardware vectors of @code{float}.
1326
1327 @item vect_int
1328 Target supports hardware vectors of @code{int}.
1329
1330 @item vect_long
1331 Target supports hardware vectors of @code{long}.
1332
1333 @item vect_long_long
1334 Target supports hardware vectors of @code{long long}.
1335
1336 @item vect_aligned_arrays
1337 Target aligns arrays to vector alignment boundary.
1338
1339 @item vect_hw_misalign
1340 Target supports a vector misalign access.
1341
1342 @item vect_no_align
1343 Target does not support a vector alignment mechanism.
1344
1345 @item vect_no_int_max
1346 Target does not support a vector max instruction on @code{int}.
1347
1348 @item vect_no_int_add
1349 Target does not support a vector add instruction on @code{int}.
1350
1351 @item vect_no_bitwise
1352 Target does not support vector bitwise instructions.
1353
1354 @item vect_char_mult
1355 Target supports @code{vector char} multiplication.
1356
1357 @item vect_short_mult
1358 Target supports @code{vector short} multiplication.
1359
1360 @item vect_int_mult
1361 Target supports @code{vector int} multiplication.
1362
1363 @item vect_extract_even_odd
1364 Target supports vector even/odd element extraction.
1365
1366 @item vect_extract_even_odd_wide
1367 Target supports vector even/odd element extraction of vectors with elements
1368 @code{SImode} or larger.
1369
1370 @item vect_interleave
1371 Target supports vector interleaving.
1372
1373 @item vect_strided
1374 Target supports vector interleaving and extract even/odd.
1375
1376 @item vect_strided_wide
1377 Target supports vector interleaving and extract even/odd for wide
1378 element types.
1379
1380 @item vect_perm
1381 Target supports vector permutation.
1382
1383 @item vect_shift
1384 Target supports a hardware vector shift operation.
1385
1386 @item vect_widen_sum_hi_to_si
1387 Target supports a vector widening summation of @code{short} operands
1388 into @code{int} results, or can promote (unpack) from @code{short}
1389 to @code{int}.
1390
1391 @item vect_widen_sum_qi_to_hi
1392 Target supports a vector widening summation of @code{char} operands
1393 into @code{short} results, or can promote (unpack) from @code{char}
1394 to @code{short}.
1395
1396 @item vect_widen_sum_qi_to_si
1397 Target supports a vector widening summation of @code{char} operands
1398 into @code{int} results.
1399
1400 @item vect_widen_mult_qi_to_hi
1401 Target supports a vector widening multiplication of @code{char} operands
1402 into @code{short} results, or can promote (unpack) from @code{char} to
1403 @code{short} and perform non-widening multiplication of @code{short}.
1404
1405 @item vect_widen_mult_hi_to_si
1406 Target supports a vector widening multiplication of @code{short} operands
1407 into @code{int} results, or can promote (unpack) from @code{short} to
1408 @code{int} and perform non-widening multiplication of @code{int}.
1409
1410 @item vect_sdot_qi
1411 Target supports a vector dot-product of @code{signed char}.
1412
1413 @item vect_udot_qi
1414 Target supports a vector dot-product of @code{unsigned char}.
1415
1416 @item vect_sdot_hi
1417 Target supports a vector dot-product of @code{signed short}.
1418
1419 @item vect_udot_hi
1420 Target supports a vector dot-product of @code{unsigned short}.
1421
1422 @item vect_pack_trunc
1423 Target supports a vector demotion (packing) of @code{short} to @code{char}
1424 and from @code{int} to @code{short} using modulo arithmetic.
1425
1426 @item vect_unpack
1427 Target supports a vector promotion (unpacking) of @code{char} to @code{short}
1428 and from @code{char} to @code{int}.
1429
1430 @item vect_intfloat_cvt
1431 Target supports conversion from @code{signed int} to @code{float}.
1432
1433 @item vect_uintfloat_cvt
1434 Target supports conversion from @code{unsigned int} to @code{float}.
1435
1436 @item vect_floatint_cvt
1437 Target supports conversion from @code{float} to @code{signed int}.
1438
1439 @item vect_floatuint_cvt
1440 Target supports conversion from @code{float} to @code{unsigned int}.
1441 @end table
1442
1443 @subsubsection Thread Local Storage attributes
1444
1445 @table @code
1446 @item tls
1447 Target supports thread-local storage.
1448
1449 @item tls_native
1450 Target supports native (rather than emulated) thread-local storage.
1451
1452 @item tls_runtime
1453 Test system supports executing TLS executables.
1454 @end table
1455
1456 @subsubsection Decimal floating point attributes
1457
1458 @table @code
1459 @item dfp
1460 Targets supports compiling decimal floating point extension to C.
1461
1462 @item dfp_nocache
1463 Including the options used to compile this particular test, the
1464 target supports compiling decimal floating point extension to C.
1465
1466 @item dfprt
1467 Test system can execute decimal floating point tests.
1468
1469 @item dfprt_nocache
1470 Including the options used to compile this particular test, the
1471 test system can execute decimal floating point tests.
1472
1473 @item hard_dfp
1474 Target generates decimal floating point instructions with current options.
1475 @end table
1476
1477 @subsubsection ARM-specific attributes
1478
1479 @table @code
1480 @item arm32
1481 ARM target generates 32-bit code.
1482
1483 @item arm_eabi
1484 ARM target adheres to the ABI for the ARM Architecture.
1485
1486 @item arm_hard_vfp_ok
1487 ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
1488 Some multilibs may be incompatible with these options.
1489
1490 @item arm_iwmmxt_ok
1491 ARM target supports @code{-mcpu=iwmmxt}.
1492 Some multilibs may be incompatible with this option.
1493
1494 @item arm_neon
1495 ARM target supports generating NEON instructions.
1496
1497 @item arm_neon_hw
1498 Test system supports executing NEON instructions.
1499
1500 @item arm_neon_ok
1501 @anchor{arm_neon_ok}
1502 ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
1503 options.  Some multilibs may be incompatible with these options.
1504
1505 @item arm_neon_fp16_ok
1506 @anchor{arm_neon_fp16_ok}
1507 ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
1508 options.  Some multilibs may be incompatible with these options.
1509
1510 @item arm_thumb1_ok
1511 ARM target generates Thumb-1 code for @code{-mthumb}.
1512
1513 @item arm_thumb2_ok
1514 ARM target generates Thumb-2 code for @code{-mthumb}.
1515
1516 @item arm_vfp_ok
1517 ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
1518 Some multilibs may be incompatible with these options.
1519 @end table
1520
1521 @subsubsection MIPS-specific attributes
1522
1523 @table @code
1524 @item mips64
1525 MIPS target supports 64-bit instructions.
1526
1527 @item nomips16
1528 MIPS target does not produce MIPS16 code.
1529
1530 @item mips16_attribute
1531 MIPS target can generate MIPS16 code.
1532
1533 @item mips_loongson
1534 MIPS target is a Loongson-2E or -2F target using an ABI that supports
1535 the Loongson vector modes.
1536
1537 @item mips_newabi_large_long_double
1538 MIPS target supports @code{long double} larger than @code{double}
1539 when using the new ABI.
1540
1541 @item mpaired_single
1542 MIPS target supports @code{-mpaired-single}.
1543 @end table
1544
1545 @subsubsection PowerPC-specific attributes
1546
1547 @table @code
1548 @item powerpc64
1549 Test system supports executing 64-bit instructions.
1550
1551 @item powerpc_altivec
1552 PowerPC target supports AltiVec.
1553
1554 @item powerpc_altivec_ok
1555 PowerPC target supports @code{-maltivec}.
1556
1557 @item powerpc_fprs
1558 PowerPC target supports floating-point registers.
1559
1560 @item powerpc_hard_double
1561 PowerPC target supports hardware double-precision floating-point.
1562
1563 @item powerpc_ppu_ok
1564 PowerPC target supports @code{-mcpu=cell}.
1565
1566 @item powerpc_spe
1567 PowerPC target supports PowerPC SPE.
1568
1569 @item powerpc_spe_nocache
1570 Including the options used to compile this particular test, the
1571 PowerPC target supports PowerPC SPE.
1572
1573 @item powerpc_spu
1574 PowerPC target supports PowerPC SPU.
1575
1576 @item spu_auto_overlay
1577 SPU target has toolchain that supports automatic overlay generation.
1578
1579 @item powerpc_vsx_ok
1580 PowerPC target supports @code{-mvsx}.
1581
1582 @item powerpc_405_nocache
1583 Including the options used to compile this particular test, the
1584 PowerPC target supports PowerPC 405.
1585
1586 @item vmx_hw
1587 PowerPC target supports executing AltiVec instructions.
1588 @end table
1589
1590 @subsubsection Other hardware attributes
1591
1592 @table @code
1593 @item avx
1594 Target supports compiling AVX instructions.
1595
1596 @item cell_hw
1597 Test system can execute AltiVec and Cell PPU instructions.
1598
1599 @item coldfire_fpu
1600 Target uses a ColdFire FPU.
1601
1602 @item hard_float
1603 Target supports FPU instructions.
1604
1605 @item sse
1606 Target supports compiling @code{sse} instructions.
1607
1608 @item sse_runtime
1609 Target supports the execution of @code{sse} instructions.
1610
1611 @item sse2
1612 Target supports compiling @code{sse2} instructions.
1613
1614 @item sse2_runtime
1615 Target supports the execution of @code{sse2} instructions.
1616
1617 @item sync_char_short
1618 Target supports atomic operations on @code{char} and @code{short}.
1619
1620 @item sync_int_long
1621 Target supports atomic operations on @code{int} and @code{long}.
1622
1623 @item ultrasparc_hw
1624 Test environment appears to run executables on a simulator that
1625 accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
1626 or @code{EM_SPARCV9} executables.
1627
1628 @item vect_cmdline_needed
1629 Target requires a command line argument to enable a SIMD instruction set.
1630 @end table
1631
1632 @subsubsection Environment attributes
1633
1634 @table @code
1635 @item c
1636 The language for the compiler under test is C.
1637
1638 @item c++
1639 The language for the compiler under test is C++.
1640
1641 @item c99_runtime
1642 Target provides a full C99 runtime.
1643
1644 @item correct_iso_cpp_string_wchar_protos
1645 Target @code{string.h} and @code{wchar.h} headers provide C++ required
1646 overloads for @code{strchr} etc. functions.
1647
1648 @item dummy_wcsftime
1649 Target uses a dummy @code{wcsftime} function that always returns zero.
1650
1651 @item fd_truncate
1652 Target can truncate a file from a file descriptor, as used by
1653 @file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or
1654 @code{chsize}.
1655
1656 @item freestanding
1657 Target is @samp{freestanding} as defined in section 4 of the C99 standard.
1658 Effectively, it is a target which supports no extra headers or libraries
1659 other than what is considered essential.
1660
1661 @item init_priority
1662 Target supports constructors with initialization priority arguments.
1663
1664 @item inttypes_types
1665 Target has the basic signed and unsigned types in @code{inttypes.h}.
1666 This is for tests that GCC's notions of these types agree with those
1667 in the header, as some systems have only @code{inttypes.h}.
1668
1669 @item lax_strtofp
1670 Target might have errors of a few ULP in string to floating-point
1671 conversion functions and overflow is not always detected correctly by
1672 those functions.
1673
1674 @item newlib
1675 Target supports Newlib.
1676
1677 @item pow10
1678 Target provides @code{pow10} function.
1679
1680 @item pthread
1681 Target can compile using @code{pthread.h} with no errors or warnings.
1682
1683 @item pthread_h
1684 Target has @code{pthread.h}.
1685
1686 @item run_expensive_tests
1687 Expensive testcases (usually those that consume excessive amounts of CPU
1688 time) should be run on this target.  This can be enabled by setting the
1689 @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
1690
1691 @item simulator
1692 Test system runs executables on a simulator (i.e. slowly) rather than
1693 hardware (i.e. fast).
1694
1695 @item stdint_types
1696 Target has the basic signed and unsigned C types in @code{stdint.h}.
1697 This will be obsolete when GCC ensures a working @code{stdint.h} for
1698 all targets.
1699
1700 @item trampolines
1701 Target supports trampolines.
1702
1703 @item uclibc
1704 Target supports uClibc.
1705
1706 @item unwrapped
1707 Target does not use a status wrapper.
1708
1709 @item vxworks_kernel
1710 Target is a VxWorks kernel.
1711
1712 @item vxworks_rtp
1713 Target is a VxWorks RTP.
1714
1715 @item wchar
1716 Target supports wide characters.
1717 @end table
1718
1719 @subsubsection Other attributes
1720
1721 @table @code
1722 @item automatic_stack_alignment
1723 Target supports automatic stack alignment.
1724
1725 @item cxa_atexit
1726 Target uses @code{__cxa_atexit}.
1727
1728 @item default_packed
1729 Target has packed layout of structure members by default.
1730
1731 @item fgraphite
1732 Target supports Graphite optimizations.
1733
1734 @item fixed_point
1735 Target supports fixed-point extension to C.
1736
1737 @item fopenmp
1738 Target supports OpenMP via @option{-fopenmp}.
1739
1740 @item fpic
1741 Target supports @option{-fpic} and @option{-fPIC}.
1742
1743 @item freorder
1744 Target supports @option{-freorder-blocks-and-partition}.
1745
1746 @item fstack_protector
1747 Target supports @option{-fstack-protector}.
1748
1749 @item gas
1750 Target uses GNU @command{as}.
1751
1752 @item gc_sections
1753 Target supports @option{--gc-sections}.
1754
1755 @item keeps_null_pointer_checks
1756 Target keeps null pointer checks, either due to the use of
1757 @option{-fno-delete-null-pointer-checks} or hardwired into the target.
1758
1759 @item lto
1760 Compiler has been configured to support link-time optimization (LTO).
1761
1762 @item named_sections
1763 Target supports named sections.
1764
1765 @item natural_alignment_32
1766 Target uses natural alignment (aligned to type size) for types of
1767 32 bits or less.
1768
1769 @item target_natural_alignment_64
1770 Target uses natural alignment (aligned to type size) for types of
1771 64 bits or less.
1772
1773 @item nonpic
1774 Target does not generate PIC by default.
1775
1776 @item pcc_bitfield_type_matters
1777 Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
1778
1779 @item pe_aligned_commons
1780 Target supports @option{-mpe-aligned-commons}.
1781
1782 @item section_anchors
1783 Target supports section anchors.
1784
1785 @item short_enums
1786 Target defaults to short enums.
1787
1788 @item static
1789 Target supports @option{-static}.
1790
1791 @item static_libgfortran
1792 Target supports statically linking @samp{libgfortran}.
1793
1794 @item string_merging
1795 Target supports merging string constants at link time.
1796
1797 @item ucn
1798 Target supports compiling and assembling UCN.
1799
1800 @item ucn_nocache
1801 Including the options used to compile this particular test, the
1802 target supports compiling and assembling UCN.
1803
1804 @item unaligned_stack
1805 Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
1806 or equal to the required vector alignment.
1807
1808 @item vector_alignment_reachable
1809 Vector alignment is reachable for types of 32 bits or less.
1810
1811 @item vector_alignment_reachable_for_64bit
1812 Vector alignment is reachable for types of 64 bits or less.
1813
1814 @item wchar_t_char16_t_compatible
1815 Target supports @code{wchar_t} that is compatible with @code{char16_t}.
1816
1817 @item wchar_t_char32_t_compatible
1818 Target supports @code{wchar_t} that is compatible with @code{char32_t}.
1819 @end table
1820
1821 @subsubsection Local to tests in @code{gcc.target/i386}
1822
1823 @table @code
1824 @item 3dnow
1825 Target supports compiling @code{3dnow} instructions.
1826
1827 @item aes
1828 Target supports compiling @code{aes} instructions.
1829
1830 @item fma4
1831 Target supports compiling @code{fma4} instructions.
1832
1833 @item ms_hook_prologue
1834 Target supports attribute @code{ms_hook_prologue}.
1835
1836 @item pclmul
1837 Target supports compiling @code{pclmul} instructions.
1838
1839 @item sse3
1840 Target supports compiling @code{sse3} instructions.
1841
1842 @item sse4
1843 Target supports compiling @code{sse4} instructions.
1844
1845 @item sse4a
1846 Target supports compiling @code{sse4a} instructions.
1847
1848 @item ssse3
1849 Target supports compiling @code{ssse3} instructions.
1850
1851 @item vaes
1852 Target supports compiling @code{vaes} instructions.
1853
1854 @item vpclmul
1855 Target supports compiling @code{vpclmul} instructions.
1856
1857 @item xop
1858 Target supports compiling @code{xop} instructions.
1859 @end table
1860
1861 @subsubsection Local to tests in @code{gcc.target/spu/ea}
1862
1863 @table @code
1864 @item ealib
1865 Target @code{__ea} library functions are available.
1866 @end table
1867
1868 @subsubsection Local to tests in @code{gcc.test-framework}
1869
1870 @table @code
1871 @item no
1872 Always returns 0.
1873
1874 @item yes
1875 Always returns 1.
1876 @end table
1877
1878 @node Add Options
1879 @subsection Features for @code{dg-add-options}
1880
1881 The supported values of @var{feature} for directive @code{dg-add-options}
1882 are:
1883
1884 @table @code
1885 @item arm_neon
1886 NEON support.  Only ARM targets support this feature, and only then
1887 in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
1888 keyword}.
1889
1890 @item arm_neon_fp16
1891 NEON and half-precision floating point support.  Only ARM targets
1892 support this feature, and only then in certain modes; see
1893 the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}.
1894
1895 @item bind_pic_locally
1896 Add the target-specific flags needed to enable functions to bind
1897 locally when using pic/PIC passes in the testsuite.
1898
1899 @item c99_runtime
1900 Add the target-specific flags needed to access the C99 runtime.
1901
1902 @item ieee
1903 Add the target-specific flags needed to enable full IEEE
1904 compliance mode.
1905
1906 @item mips16_attribute
1907 @code{mips16} function attributes.
1908 Only MIPS targets support this feature, and only then in certain modes.
1909
1910 @item tls
1911 Add the target-specific flags needed to use thread-local storage.
1912 @end table
1913
1914 @node Require Support
1915 @subsection Variants of @code{dg-require-@var{support}}
1916
1917 A few of the @code{dg-require} directives take arguments.
1918
1919 @table @code
1920 @item dg-require-iconv @var{codeset}
1921 Skip the test if the target does not support iconv.  @var{codeset} is
1922 the codeset to convert to.
1923
1924 @item dg-require-profiling @var{profopt}
1925 Skip the test if the target does not support profiling with option
1926 @var{profopt}.
1927
1928 @item dg-require-visibility @var{vis}
1929 Skip the test if the target does not support the @code{visibility} attribute.
1930 If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
1931 checked, for @code{visibility("@var{vis}")} otherwise.
1932 @end table
1933
1934 The original @code{dg-require} directives were defined before there
1935 was support for effective-target keywords.  The directives that do not
1936 take arguments could be replaced with effective-target keywords.
1937
1938 @table @code
1939 @item dg-require-alias ""
1940 Skip the test if the target does not support the @samp{alias} attribute.
1941
1942 @item dg-require-compat-dfp ""
1943 Skip this test unless both compilers in a @file{compat} testsuite
1944 support decimal floating point.
1945
1946 @item dg-require-cxa-atexit ""
1947 Skip the test if the target does not support @code{__cxa_atexit}.
1948 This is equivalent to @code{dg-require-effective-target cxa_atexit}.
1949
1950 @item dg-require-dll ""
1951 Skip the test if the target does not support DLL attributes.
1952
1953 @item dg-require-fork ""
1954 Skip the test if the target does not support @code{fork}.
1955
1956 @item dg-require-gc-sections ""
1957 Skip the test if the target's linker does not support the
1958 @code{--gc-sections} flags.
1959 This is equivalent to @code{dg-require-effective-target gc-sections}.
1960
1961 @item dg-require-host-local ""
1962 Skip the test if the host is remote, rather than the same as the build
1963 system.  Some tests are incompatible with DejaGnu's handling of remote
1964 hosts, which involves copying the source file to the host and compiling
1965 it with a relative path and "@code{-o a.out}".
1966
1967 @item dg-require-mkfifo ""
1968 Skip the test if the target does not support @code{mkfifo}.
1969
1970 @item dg-require-named-sections ""
1971 Skip the test is the target does not support named sections.
1972 This is equivalent to @code{dg-require-effective-target named_sections}.
1973
1974 @item dg-require-weak ""
1975 Skip the test if the target does not support weak symbols.
1976
1977 @item dg-require-weak-override ""
1978 Skip the test if the target does not support overriding weak symbols.
1979 @end table
1980
1981 @node Final Actions
1982 @subsection Commands for use in @code{dg-final}
1983
1984 The GCC testsuite defines the following directives to be used within
1985 @code{dg-final}.
1986
1987 @subsubsection Scan a particular file
1988
1989 @table @code
1990 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1991 Passes if @var{regexp} matches text in @var{filename}.
1992 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1993 Passes if @var{regexp} does not match text in @var{filename}.
1994 @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
1995 Passes if @var{regexp} matches in Fortran module @var{module}.
1996 @end table
1997
1998 @subsubsection Scan the assembly output
1999
2000 @table @code
2001 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
2002 Passes if @var{regex} matches text in the test's assembler output.
2003
2004 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
2005 Passes if @var{regex} does not match text in the test's assembler output.
2006
2007 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
2008 Passes if @var{regex} is matched exactly @var{num} times in the test's
2009 assembler output.
2010
2011 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
2012 Passes if @var{regex} matches text in the test's demangled assembler output.
2013
2014 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
2015 Passes if @var{regex} does not match text in the test's demangled assembler
2016 output.
2017
2018 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2019 Passes if @var{symbol} is defined as a hidden symbol in the test's
2020 assembly output.
2021
2022 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
2023 Passes if @var{symbol} is not defined as a hidden symbol in the test's
2024 assembly output.
2025 @end table
2026
2027 @subsubsection Scan optimization dump files
2028
2029 These commands are available for @var{kind} of @code{tree}, @code{rtl},
2030 and @code{ipa}.
2031
2032 @table @code
2033 @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2034 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
2035
2036 @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2037 Passes if @var{regex} does not match text in the dump file with suffix
2038 @var{suffix}.
2039
2040 @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
2041 Passes if @var{regex} is found exactly @var{num} times in the dump file
2042 with suffix @var{suffix}.
2043
2044 @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2045 Passes if @var{regex} matches demangled text in the dump file with
2046 suffix @var{suffix}.
2047
2048 @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
2049 Passes if @var{regex} does not match demangled text in the dump file with
2050 suffix @var{suffix}.
2051 @end table
2052
2053 @subsubsection Verify that an output files exists or not
2054
2055 @table @code
2056 @item output-exists [@{ target/xfail @var{selector} @}]
2057 Passes if compiler output file exists.
2058
2059 @item output-exists-not [@{ target/xfail @var{selector} @}]
2060 Passes if compiler output file does not exist.
2061 @end table
2062
2063 @subsubsection Check for LTO tests
2064
2065 @table @code
2066 @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
2067 Passes if the pattern is present in the final executable.
2068 @end table
2069
2070 @subsubsection Checks for @command{gcov} tests
2071
2072 @table @code
2073 @item run-gcov @var{sourcefile}
2074 Check line counts in @command{gcov} tests.
2075
2076 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
2077 Check branch and/or call counts, in addition to line counts, in
2078 @command{gcov} tests.
2079 @end table
2080
2081 @subsubsection Clean up generated test files
2082
2083 @table @code
2084 @item cleanup-coverage-files
2085 Removes coverage data files generated for this test.
2086
2087 @item cleanup-ipa-dump @var{suffix}
2088 Removes IPA dump files generated for this test.
2089
2090 @item cleanup-modules
2091 Removes Fortran module files generated for this test.
2092
2093 @item cleanup-profile-file
2094 Removes profiling files generated for this test.
2095
2096 @item cleanup-repo-files
2097 Removes files generated for this test for @option{-frepo}.
2098
2099 @item cleanup-rtl-dump @var{suffix}
2100 Removes RTL dump files generated for this test.
2101
2102 @item cleanup-saved-temps
2103 Removes files for the current test which were kept for @option{-save-temps}.
2104
2105 @item cleanup-tree-dump @var{suffix}
2106 Removes tree dump files matching @var{suffix} which were generated for
2107 this test.
2108 @end table
2109
2110 @node Ada Tests
2111 @section Ada Language Testsuites
2112
2113 The Ada testsuite includes executable tests from the ACATS 2.5
2114 testsuite, publicly available at
2115 @uref{http://www.adaic.org/compilers/acats/2.5}.
2116
2117 These tests are integrated in the GCC testsuite in the
2118 @file{ada/acats} directory, and
2119 enabled automatically when running @code{make check}, assuming
2120 the Ada language has been enabled when configuring GCC@.
2121
2122 You can also run the Ada testsuite independently, using
2123 @code{make check-ada}, or run a subset of the tests by specifying which
2124 chapter to run, e.g.:
2125
2126 @smallexample
2127 $ make check-ada CHAPTERS="c3 c9"
2128 @end smallexample
2129
2130 The tests are organized by directory, each directory corresponding to
2131 a chapter of the Ada Reference Manual.  So for example, @file{c9} corresponds
2132 to chapter 9, which deals with tasking features of the language.
2133
2134 There is also an extra chapter called @file{gcc} containing a template for
2135 creating new executable tests, although this is deprecated in favor of
2136 the @file{gnat.dg} testsuite.
2137
2138 The tests are run using two @command{sh} scripts: @file{run_acats} and
2139 @file{run_all.sh}.  To run the tests using a simulator or a cross
2140 target, see the small
2141 customization section at the top of @file{run_all.sh}.
2142
2143 These tests are run using the build tree: they can be run without doing
2144 a @code{make install}.
2145
2146 @node C Tests
2147 @section C Language Testsuites
2148
2149 GCC contains the following C language testsuites, in the
2150 @file{gcc/testsuite} directory:
2151
2152 @table @file
2153 @item gcc.dg
2154 This contains tests of particular features of the C compiler, using the
2155 more modern @samp{dg} harness.  Correctness tests for various compiler
2156 features should go here if possible.
2157
2158 Magic comments determine whether the file
2159 is preprocessed, compiled, linked or run.  In these tests, error and warning
2160 message texts are compared against expected texts or regular expressions
2161 given in comments.  These tests are run with the options @samp{-ansi -pedantic}
2162 unless other options are given in the test.  Except as noted below they
2163 are not run with multiple optimization options.
2164 @item gcc.dg/compat
2165 This subdirectory contains tests for binary compatibility using
2166 @file{lib/compat.exp}, which in turn uses the language-independent support
2167 (@pxref{compat Testing, , Support for testing binary compatibility}).
2168 @item gcc.dg/cpp
2169 This subdirectory contains tests of the preprocessor.
2170 @item gcc.dg/debug
2171 This subdirectory contains tests for debug formats.  Tests in this
2172 subdirectory are run for each debug format that the compiler supports.
2173 @item gcc.dg/format
2174 This subdirectory contains tests of the @option{-Wformat} format
2175 checking.  Tests in this directory are run with and without
2176 @option{-DWIDE}.
2177 @item gcc.dg/noncompile
2178 This subdirectory contains tests of code that should not compile and
2179 does not need any special compilation options.  They are run with
2180 multiple optimization options, since sometimes invalid code crashes
2181 the compiler with optimization.
2182 @item gcc.dg/special
2183 FIXME: describe this.
2184
2185 @item gcc.c-torture
2186 This contains particular code fragments which have historically broken easily.
2187 These tests are run with multiple optimization options, so tests for features
2188 which only break at some optimization levels belong here.  This also contains
2189 tests to check that certain optimizations occur.  It might be worthwhile to
2190 separate the correctness tests cleanly from the code quality tests, but
2191 it hasn't been done yet.
2192
2193 @item gcc.c-torture/compat
2194 FIXME: describe this.
2195
2196 This directory should probably not be used for new tests.
2197 @item gcc.c-torture/compile
2198 This testsuite contains test cases that should compile, but do not
2199 need to link or run.  These test cases are compiled with several
2200 different combinations of optimization options.  All warnings are
2201 disabled for these test cases, so this directory is not suitable if
2202 you wish to test for the presence or absence of compiler warnings.
2203 While special options can be set, and tests disabled on specific
2204 platforms, by the use of @file{.x} files, mostly these test cases
2205 should not contain platform dependencies.  FIXME: discuss how defines
2206 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
2207 @item gcc.c-torture/execute
2208 This testsuite contains test cases that should compile, link and run;
2209 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
2210 @item gcc.c-torture/execute/ieee
2211 This contains tests which are specific to IEEE floating point.
2212 @item gcc.c-torture/unsorted
2213 FIXME: describe this.
2214
2215 This directory should probably not be used for new tests.
2216 @item gcc.misc-tests
2217 This directory contains C tests that require special handling.  Some
2218 of these tests have individual expect files, and others share
2219 special-purpose expect files:
2220
2221 @table @file
2222 @item @code{bprob*.c}
2223 Test @option{-fbranch-probabilities} using
2224 @file{gcc.misc-tests/bprob.exp}, which
2225 in turn uses the generic, language-independent framework
2226 (@pxref{profopt Testing, , Support for testing profile-directed
2227 optimizations}).
2228
2229 @item @code{gcov*.c}
2230 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
2231 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
2232
2233 @item @code{i386-pf-*.c}
2234 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
2235 @end table
2236
2237 @item gcc.test-framework
2238 @table @file
2239 @item @code{dg-*.c}
2240 Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}.
2241 @end table
2242
2243 @end table
2244
2245 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
2246 test cases and magic comments more.
2247
2248 @node libgcj Tests
2249 @section The Java library testsuites.
2250
2251 Runtime tests are executed via @samp{make check} in the
2252 @file{@var{target}/libjava/testsuite} directory in the build
2253 tree.  Additional runtime tests can be checked into this testsuite.
2254
2255 Regression testing of the core packages in libgcj is also covered by the
2256 Mauve testsuite.  The @uref{http://sourceware.org/mauve/,,Mauve Project}
2257 develops tests for the Java Class Libraries.  These tests are run as part
2258 of libgcj testing by placing the Mauve tree within the libjava testsuite
2259 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
2260 the location of that tree when invoking @samp{make}, as in
2261 @samp{make MAUVEDIR=~/mauve check}.
2262
2263 To detect regressions, a mechanism in @file{mauve.exp} compares the
2264 failures for a test run against the list of expected failures in
2265 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
2266 Update this file when adding new failing tests to Mauve, or when fixing
2267 bugs in libgcj that had caused Mauve test failures.
2268
2269 We encourage developers to contribute test cases to Mauve.
2270
2271 @node LTO Testing
2272 @section Support for testing link-time optimizations
2273
2274 Tests for link-time optimizations usually require multiple source files
2275 that are compiled separately, perhaps with different sets of options.
2276 There are several special-purpose test directives used for these tests.
2277
2278 @table @code
2279 @item @{ dg-lto-do @var{do-what-keyword} @}
2280 @var{do-what-keyword} specifies how the test is compiled and whether
2281 it is executed.  It is one of:
2282
2283 @table @code
2284 @item assemble
2285 Compile with @option{-c} to produce a relocatable object file.
2286 @item link
2287 Compile, assemble, and link to produce an executable file.
2288 @item run
2289 Produce and run an executable file, which is expected to return
2290 an exit code of 0.
2291 @end table
2292
2293 The default is @code{assemble}.  That can be overridden for a set of
2294 tests by redefining @code{dg-do-what-default} within the @code{.exp}
2295 file for those tests.
2296
2297 Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
2298 @samp{target} or @samp{xfail} list.  Use @code{dg-skip-if},
2299 @code{dg-xfail-if}, or @code{dg-xfail-run-if}.
2300
2301 @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
2302 This directive provides a list of one or more sets of compiler options
2303 to override @var{LTO_OPTIONS}.  Each test will be compiled and run with
2304 each of these sets of options.
2305
2306 @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
2307 This directive adds @var{options} to the linker options used.
2308
2309 @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
2310 This directive removes @var{options} from the set of linker options used.
2311 @end table
2312
2313 @node gcov Testing
2314 @section Support for testing @command{gcov}
2315
2316 Language-independent support for testing @command{gcov}, and for checking
2317 that branch profiling produces expected values, is provided by the
2318 expect file @file{lib/gcov.exp}.  @command{gcov} tests also rely on procedures
2319 in @file{lib/gcc-dg.exp} to compile and run the test program.  A typical
2320 @command{gcov} test contains the following DejaGnu commands within comments:
2321
2322 @smallexample
2323 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
2324 @{ dg-do run @{ target native @} @}
2325 @{ dg-final @{ run-gcov sourcefile @} @}
2326 @end smallexample
2327
2328 Checks of @command{gcov} output can include line counts, branch percentages,
2329 and call return percentages.  All of these checks are requested via
2330 commands that appear in comments in the test's source file.
2331 Commands to check line counts are processed by default.
2332 Commands to check branch percentages and call return percentages are
2333 processed if the @command{run-gcov} command has arguments @code{branches}
2334 or @code{calls}, respectively.  For example, the following specifies
2335 checking both, as well as passing @option{-b} to @command{gcov}:
2336
2337 @smallexample
2338 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
2339 @end smallexample
2340
2341 A line count command appears within a comment on the source line
2342 that is expected to get the specified count and has the form
2343 @code{count(@var{cnt})}.  A test should only check line counts for
2344 lines that will get the same count for any architecture.
2345
2346 Commands to check branch percentages (@code{branch}) and call
2347 return percentages (@code{returns}) are very similar to each other.
2348 A beginning command appears on or before the first of a range of
2349 lines that will report the percentage, and the ending command
2350 follows that range of lines.  The beginning command can include a
2351 list of percentages, all of which are expected to be found within
2352 the range.  A range is terminated by the next command of the same
2353 kind.  A command @code{branch(end)} or @code{returns(end)} marks
2354 the end of a range without starting a new one.  For example:
2355
2356 @smallexample
2357 if (i > 10 && j > i && j < 20)  /* @r{branch(27 50 75)} */
2358                                 /* @r{branch(end)} */
2359   foo (i, j);
2360 @end smallexample
2361
2362 For a call return percentage, the value specified is the
2363 percentage of calls reported to return.  For a branch percentage,
2364 the value is either the expected percentage or 100 minus that
2365 value, since the direction of a branch can differ depending on the
2366 target or the optimization level.
2367
2368 Not all branches and calls need to be checked.  A test should not
2369 check for branches that might be optimized away or replaced with
2370 predicated instructions.  Don't check for calls inserted by the
2371 compiler or ones that might be inlined or optimized away.
2372
2373 A single test can check for combinations of line counts, branch
2374 percentages, and call return percentages.  The command to check a
2375 line count must appear on the line that will report that count, but
2376 commands to check branch percentages and call return percentages can
2377 bracket the lines that report them.
2378
2379 @node profopt Testing
2380 @section Support for testing profile-directed optimizations
2381
2382 The file @file{profopt.exp} provides language-independent support for
2383 checking correct execution of a test built with profile-directed
2384 optimization.  This testing requires that a test program be built and
2385 executed twice.  The first time it is compiled to generate profile
2386 data, and the second time it is compiled to use the data that was
2387 generated during the first execution.  The second execution is to
2388 verify that the test produces the expected results.
2389
2390 To check that the optimization actually generated better code, a
2391 test can be built and run a third time with normal optimizations to
2392 verify that the performance is better with the profile-directed
2393 optimizations.  @file{profopt.exp} has the beginnings of this kind
2394 of support.
2395
2396 @file{profopt.exp} provides generic support for profile-directed
2397 optimizations.  Each set of tests that uses it provides information
2398 about a specific optimization:
2399
2400 @table @code
2401 @item tool
2402 tool being tested, e.g., @command{gcc}
2403
2404 @item profile_option
2405 options used to generate profile data
2406
2407 @item feedback_option
2408 options used to optimize using that profile data
2409
2410 @item prof_ext
2411 suffix of profile data files
2412
2413 @item PROFOPT_OPTIONS
2414 list of options with which to run each test, similar to the lists for
2415 torture tests
2416
2417 @item @{ dg-final-generate @{ @var{local-directive} @} @}
2418 This directive is similar to @code{dg-final}, but the
2419 @var{local-directive} is run after the generation of profile data.
2420
2421 @item @{ dg-final-use @{ @var{local-directive} @} @}
2422 The @var{local-directive} is run after the profile data have been
2423 used.
2424 @end table
2425
2426 @node compat Testing
2427 @section Support for testing binary compatibility
2428
2429 The file @file{compat.exp} provides language-independent support for
2430 binary compatibility testing.  It supports testing interoperability of
2431 two compilers that follow the same ABI, or of multiple sets of
2432 compiler options that should not affect binary compatibility.  It is
2433 intended to be used for testsuites that complement ABI testsuites.
2434
2435 A test supported by this framework has three parts, each in a
2436 separate source file: a main program and two pieces that interact
2437 with each other to split up the functionality being tested.
2438
2439 @table @file
2440 @item @var{testname}_main.@var{suffix}
2441 Contains the main program, which calls a function in file
2442 @file{@var{testname}_x.@var{suffix}}.
2443
2444 @item @var{testname}_x.@var{suffix}
2445 Contains at least one call to a function in
2446 @file{@var{testname}_y.@var{suffix}}.
2447
2448 @item @var{testname}_y.@var{suffix}
2449 Shares data with, or gets arguments from,
2450 @file{@var{testname}_x.@var{suffix}}.
2451 @end table
2452
2453 Within each test, the main program and one functional piece are
2454 compiled by the GCC under test.  The other piece can be compiled by
2455 an alternate compiler.  If no alternate compiler is specified,
2456 then all three source files are all compiled by the GCC under test.
2457 You can specify pairs of sets of compiler options.  The first element
2458 of such a pair specifies options used with the GCC under test, and the
2459 second element of the pair specifies options used with the alternate
2460 compiler.  Each test is compiled with each pair of options.
2461
2462 @file{compat.exp} defines default pairs of compiler options.
2463 These can be overridden by defining the environment variable
2464 @env{COMPAT_OPTIONS} as:
2465
2466 @smallexample
2467 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
2468   @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
2469 @end smallexample
2470
2471 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
2472 used by the compiler under test and @var{alti} used by the alternate
2473 compiler.  For example, with
2474 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
2475 the test is first built with @option{-g -O0} by the compiler under
2476 test and with @option{-O3} by the alternate compiler.  The test is
2477 built a second time using @option{-fpic} by the compiler under test
2478 and @option{-fPIC -O2} by the alternate compiler.
2479
2480 An alternate compiler is specified by defining an environment
2481 variable to be the full pathname of an installed compiler; for C
2482 define @env{ALT_CC_UNDER_TEST}, and for C++ define
2483 @env{ALT_CXX_UNDER_TEST}.  These will be written to the
2484 @file{site.exp} file used by DejaGnu.  The default is to build each
2485 test with the compiler under test using the first of each pair of
2486 compiler options from @env{COMPAT_OPTIONS}.  When
2487 @env{ALT_CC_UNDER_TEST} or
2488 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
2489 the compiler under test but with combinations of the options from
2490 @env{COMPAT_OPTIONS}.
2491
2492 To run only the C++ compatibility suite using the compiler under test
2493 and another version of GCC using specific compiler options, do the
2494 following from @file{@var{objdir}/gcc}:
2495
2496 @smallexample
2497 rm site.exp
2498 make -k \
2499   ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
2500   COMPAT_OPTIONS="@var{lists as shown above}" \
2501   check-c++ \
2502   RUNTESTFLAGS="compat.exp"
2503 @end smallexample
2504
2505 A test that fails when the source files are compiled with different
2506 compilers, but passes when the files are compiled with the same
2507 compiler, demonstrates incompatibility of the generated code or
2508 runtime support.  A test that fails for the alternate compiler but
2509 passes for the compiler under test probably tests for a bug that was
2510 fixed in the compiler under test but is present in the alternate
2511 compiler.
2512
2513 The binary compatibility tests support a small number of test framework
2514 commands that appear within comments in a test file.
2515
2516 @table @code
2517 @item dg-require-*
2518 These commands can be used in @file{@var{testname}_main.@var{suffix}}
2519 to skip the test if specific support is not available on the target.
2520
2521 @item dg-options
2522 The specified options are used for compiling this particular source
2523 file, appended to the options from @env{COMPAT_OPTIONS}.  When this
2524 command appears in @file{@var{testname}_main.@var{suffix}} the options
2525 are also used to link the test program.
2526
2527 @item dg-xfail-if
2528 This command can be used in a secondary source file to specify that
2529 compilation is expected to fail for particular options on particular
2530 targets.
2531 @end table
2532
2533 @node Torture Tests
2534 @section Support for torture testing using multiple options
2535
2536 Throughout the compiler testsuite there are several directories whose
2537 tests are run multiple times, each with a different set of options.
2538 These are known as torture tests.
2539 @file{lib/torture-options.exp} defines procedures to
2540 set up these lists:
2541
2542 @table @code
2543 @item torture-init
2544 Initialize use of torture lists.
2545 @item set-torture-options
2546 Set lists of torture options to use for tests with and without loops.
2547 Optionally combine a set of torture options with a set of other
2548 options, as is done with Objective-C runtime options.
2549 @item torture-finish
2550 Finalize use of torture lists.
2551 @end table
2552
2553 The @file{.exp} file for a set of tests that use torture options must
2554 include calls to these three procedures if:
2555
2556 @itemize @bullet
2557 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
2558
2559 @item It calls @var{$@{tool@}}@code{-torture} or
2560 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
2561 @code{fortran}, or @code{objc}.
2562
2563 @item It calls @code{dg-pch}.
2564 @end itemize
2565
2566 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
2567 to call the torture procedures if the tests should use the list in
2568 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
2569
2570 Most uses of torture options can override the default lists by defining
2571 @var{TORTURE_OPTIONS} or add to the default list by defining
2572 @var{ADDITIONAL_TORTURE_OPTIONS}.  Define these in a @file{.dejagnurc}
2573 file or add them to the @file{site.exp} file; for example
2574
2575 @smallexample
2576 set ADDITIONAL_TORTURE_OPTIONS  [list \
2577   @{ -O2 -ftree-loop-linear @} \
2578   @{ -O2 -fpeel-loops @} ]
2579 @end smallexample