OSDN Git Service

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