OSDN Git Service

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