binutils221: Fix missing section start/end label generation
[dragonfly.git] / contrib / gcc-4.4 / gcc / doc / sourcebuild.texi
1 @c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
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 * Testsuites::      The GCC testsuites.
19 @end menu
20
21 @include configterms.texi
22
23 @node Top Level
24 @section Top Level Source Directory
25
26 The top level source directory in a GCC distribution contains several
27 files and directories that are shared with other software
28 distributions such as that of GNU Binutils.  It also contains several
29 subdirectories that contain parts of GCC and its runtime libraries:
30
31 @table @file
32 @item boehm-gc
33 The Boehm conservative garbage collector, used as part of the Java
34 runtime library.
35
36 @item contrib
37 Contributed scripts that may be found useful in conjunction with GCC@.
38 One of these, @file{contrib/texi2pod.pl}, is used to generate man
39 pages from Texinfo manuals as part of the GCC build process.
40
41 @item fastjar
42 An implementation of the @command{jar} command, used with the Java
43 front end.
44
45 @item fixincludes
46 The support for fixing system headers to work with GCC@.  See
47 @file{fixincludes/README} for more information.  The headers fixed by
48 this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
49 Along with those headers, @file{README-fixinc} is also installed, as
50 @file{@var{libsubdir}/include-fixed/README}.
51
52 @item gcc
53 The main sources of GCC itself (except for runtime libraries),
54 including optimizers, support for different target architectures,
55 language front ends, and testsuites.  @xref{gcc Directory, , The
56 @file{gcc} Subdirectory}, for details.
57
58 @item include
59 Headers for the @code{libiberty} library.
60
61 @item intl
62 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
63 include it in libc.
64
65 @item libada
66 The Ada runtime library.
67
68 @item libcpp
69 The C preprocessor library.
70
71 @item libgfortran
72 The Fortran runtime library.
73
74 @item libffi
75 The @code{libffi} library, used as part of the Java runtime library.
76
77 @item libiberty
78 The @code{libiberty} library, used for portability and for some
79 generally useful data structures and algorithms.  @xref{Top, ,
80 Introduction, libiberty, @sc{gnu} libiberty}, for more information
81 about this library.
82
83 @item libjava
84 The Java runtime library.
85
86 @item libmudflap
87 The @code{libmudflap} library, used for instrumenting pointer and array
88 dereferencing operations.
89
90 @item libobjc
91 The Objective-C and Objective-C++ runtime library.
92
93 @item libstdc++-v3
94 The C++ runtime library.
95
96 @item maintainer-scripts
97 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
98
99 @item zlib
100 The @code{zlib} compression library, used by the Java front end and as
101 part of the Java runtime library.
102 @end table
103
104 The build system in the top level directory, including how recursion
105 into subdirectories works and how building runtime libraries for
106 multilibs is handled, is documented in a separate manual, included
107 with GNU Binutils.  @xref{Top, , GNU configure and build system,
108 configure, The GNU configure and build system}, for details.
109
110 @node gcc Directory
111 @section The @file{gcc} Subdirectory
112
113 The @file{gcc} directory contains many files that are part of the C
114 sources of GCC, other files used as part of the configuration and
115 build process, and subdirectories including documentation and a
116 testsuite.  The files that are sources of GCC are documented in a
117 separate chapter.  @xref{Passes, , Passes and Files of the Compiler}.
118
119 @menu
120 * Subdirectories:: Subdirectories of @file{gcc}.
121 * Configuration::  The configuration process, and the files it uses.
122 * Build::          The build system in the @file{gcc} directory.
123 * Makefile::       Targets in @file{gcc/Makefile}.
124 * Library Files::  Library source files and headers under @file{gcc/}.
125 * Headers::        Headers installed by GCC.
126 * Documentation::  Building documentation in GCC.
127 * Front End::      Anatomy of a language front end.
128 * Back End::       Anatomy of a target back end.
129 @end menu
130
131 @node Subdirectories
132 @subsection Subdirectories of @file{gcc}
133
134 The @file{gcc} directory contains the following subdirectories:
135
136 @table @file
137 @item @var{language}
138 Subdirectories for various languages.  Directories containing a file
139 @file{config-lang.in} are language subdirectories.  The contents of
140 the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C)
141 and @file{objcp} (for Objective-C++) are documented in this manual
142 (@pxref{Passes, , Passes and Files of the Compiler}); those for other
143 languages are not.  @xref{Front End, , Anatomy of a Language Front End},
144 for details of the files in these directories.
145
146 @item config
147 Configuration files for supported architectures and operating
148 systems.  @xref{Back End, , Anatomy of a Target Back End}, for
149 details of the files in this directory.
150
151 @item doc
152 Texinfo documentation for GCC, together with automatically generated
153 man pages and support for converting the installation manual to
154 HTML@.  @xref{Documentation}.
155
156 @item ginclude
157 System headers installed by GCC, mainly those required by the C
158 standard of freestanding implementations.  @xref{Headers, , Headers
159 Installed by GCC}, for details of when these and other headers are
160 installed.
161
162 @item po
163 Message catalogs with translations of messages produced by GCC into
164 various languages, @file{@var{language}.po}.  This directory also
165 contains @file{gcc.pot}, the template for these message catalogues,
166 @file{exgettext}, a wrapper around @command{gettext} to extract the
167 messages from the GCC sources and create @file{gcc.pot}, which is run
168 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
169 which messages should not be extracted.
170
171 @item testsuite
172 The GCC testsuites (except for those for runtime libraries).
173 @xref{Testsuites}.
174 @end table
175
176 @node Configuration
177 @subsection Configuration in the @file{gcc} Directory
178
179 The @file{gcc} directory is configured with an Autoconf-generated
180 script @file{configure}.  The @file{configure} script is generated
181 from @file{configure.ac} and @file{aclocal.m4}.  From the files
182 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
183 file @file{config.in}.  The file @file{cstamp-h.in} is used as a
184 timestamp.
185
186 @menu
187 * Config Fragments::     Scripts used by @file{configure}.
188 * System Config::        The @file{config.build}, @file{config.host}, and
189                          @file{config.gcc} files.
190 * Configuration Files::  Files created by running @file{configure}.
191 @end menu
192
193 @node Config Fragments
194 @subsubsection Scripts Used by @file{configure}
195
196 @file{configure} uses some other scripts to help in its work:
197
198 @itemize @bullet
199 @item The standard GNU @file{config.sub} and @file{config.guess}
200 files, kept in the top level directory, are used.
201
202 @item The file @file{config.gcc} is used to handle configuration
203 specific to the particular target machine.  The file
204 @file{config.build} is used to handle configuration specific to the
205 particular build machine.  The file @file{config.host} is used to handle
206 configuration specific to the particular host machine.  (In general,
207 these should only be used for features that cannot reasonably be tested in
208 Autoconf feature tests.)
209 @xref{System Config, , The @file{config.build}; @file{config.host};
210 and @file{config.gcc} Files}, for details of the contents of these files.
211
212 @item Each language subdirectory has a file
213 @file{@var{language}/config-lang.in} that is used for
214 front-end-specific configuration.  @xref{Front End Config, , The Front
215 End @file{config-lang.in} File}, for details of this file.
216
217 @item A helper script @file{configure.frag} is used as part of
218 creating the output of @file{configure}.
219 @end itemize
220
221 @node System Config
222 @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
223
224 The @file{config.build} file contains specific rules for particular systems
225 which GCC is built on.  This should be used as rarely as possible, as the
226 behavior of the build system can always be detected by autoconf.
227
228 The @file{config.host} file contains specific rules for particular systems
229 which GCC will run on.  This is rarely needed.
230
231 The @file{config.gcc} file contains specific rules for particular systems
232 which GCC will generate code for.  This is usually needed.
233
234 Each file has a list of the shell variables it sets, with descriptions, at the
235 top of the file.
236
237 FIXME: document the contents of these files, and what variables should
238 be set to control build, host and target configuration.
239
240 @include configfiles.texi
241
242 @node Build
243 @subsection Build System in the @file{gcc} Directory
244
245 FIXME: describe the build system, including what is built in what
246 stages.  Also list the various source files that are used in the build
247 process but aren't source files of GCC itself and so aren't documented
248 below (@pxref{Passes}).
249
250 @include makefile.texi
251
252 @node Library Files
253 @subsection Library Source Files and Headers under the @file{gcc} Directory
254
255 FIXME: list here, with explanation, all the C source files and headers
256 under the @file{gcc} directory that aren't built into the GCC
257 executable but rather are part of runtime libraries and object files,
258 such as @file{crtstuff.c} and @file{unwind-dw2.c}.  @xref{Headers, ,
259 Headers Installed by GCC}, for more information about the
260 @file{ginclude} directory.
261
262 @node Headers
263 @subsection Headers Installed by GCC
264
265 In general, GCC expects the system C library to provide most of the
266 headers to be used with it.  However, GCC will fix those headers if
267 necessary to make them work with GCC, and will install some headers
268 required of freestanding implementations.  These headers are installed
269 in @file{@var{libsubdir}/include}.  Headers for non-C runtime
270 libraries are also installed by GCC; these are not documented here.
271 (FIXME: document them somewhere.)
272
273 Several of the headers GCC installs are in the @file{ginclude}
274 directory.  These headers, @file{iso646.h},
275 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
276 are installed in @file{@var{libsubdir}/include},
277 unless the target Makefile fragment (@pxref{Target Fragment})
278 overrides this by setting @code{USER_H}.
279
280 In addition to these headers and those generated by fixing system
281 headers to work with GCC, some other headers may also be installed in
282 @file{@var{libsubdir}/include}.  @file{config.gcc} may set
283 @code{extra_headers}; this specifies additional headers under
284 @file{config} to be installed on some systems.
285
286 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
287 This is done to cope with command-line options that change the
288 representation of floating point numbers.
289
290 GCC also installs its own version of @code{<limits.h>}; this is generated
291 from @file{glimits.h}, together with @file{limitx.h} and
292 @file{limity.h} if the system also has its own version of
293 @code{<limits.h>}.  (GCC provides its own header because it is
294 required of ISO C freestanding implementations, but needs to include
295 the system header from its own header as well because other standards
296 such as POSIX specify additional values to be defined in
297 @code{<limits.h>}.)  The system's @code{<limits.h>} header is used via
298 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
299 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
300 needs fixing, @file{syslimits.h} is the fixed copy.
301
302 GCC can also install @code{<tgmath.h>}.  It will do this when
303 @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
304
305 @node Documentation
306 @subsection Building Documentation
307
308 The main GCC documentation is in the form of manuals in Texinfo
309 format.  These are installed in Info format; DVI versions may be
310 generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
311 HTML versions by @command{make html}.  In addition, some man pages are
312 generated from the Texinfo manuals, there are some other text files
313 with miscellaneous documentation, and runtime libraries have their own
314 documentation outside the @file{gcc} directory.  FIXME: document the
315 documentation for runtime libraries somewhere.
316
317 @menu
318 * Texinfo Manuals::      GCC manuals in Texinfo format.
319 * Man Page Generation::  Generating man pages from Texinfo manuals.
320 * Miscellaneous Docs::   Miscellaneous text files with documentation.
321 @end menu
322
323 @node Texinfo Manuals
324 @subsubsection Texinfo Manuals
325
326 The manuals for GCC as a whole, and the C and C++ front ends, are in
327 files @file{doc/*.texi}.  Other front ends have their own manuals in
328 files @file{@var{language}/*.texi}.  Common files
329 @file{doc/include/*.texi} are provided which may be included in
330 multiple manuals; the following files are in @file{doc/include}:
331
332 @table @file
333 @item fdl.texi
334 The GNU Free Documentation License.
335 @item funding.texi
336 The section ``Funding Free Software''.
337 @item gcc-common.texi
338 Common definitions for manuals.
339 @item gpl.texi
340 @itemx gpl_v3.texi
341 The GNU General Public License.
342 @item texinfo.tex
343 A copy of @file{texinfo.tex} known to work with the GCC manuals.
344 @end table
345
346 DVI-formatted manuals are generated by @samp{make dvi}, which uses
347 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  
348 PDF-formatted manuals are generated by @samp{make pdf}, which uses
349 @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML
350 formatted manuals are generated by @command{make html}.  Info
351 manuals are generated by @samp{make info} (which is run as part of
352 a bootstrap); this generates the manuals in the source directory,
353 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
354 and they are included in release distributions.
355
356 Manuals are also provided on the GCC web site, in both HTML and
357 PostScript forms.  This is done via the script
358 @file{maintainer-scripts/update_web_docs}.  Each manual to be
359 provided online must be listed in the definition of @code{MANUALS} in
360 that file; a file @file{@var{name}.texi} must only appear once in the
361 source tree, and the output manual must have the same name as the
362 source file.  (However, other Texinfo files, included in manuals but
363 not themselves the root files of manuals, may have names that appear
364 more than once in the source tree.)  The manual file
365 @file{@var{name}.texi} should only include other files in its own
366 directory or in @file{doc/include}.  HTML manuals will be generated by
367 @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
368 and @command{dvips}, and PDF manuals by @command{texi2pdf}.
369 All Texinfo files that are parts of manuals must
370 be checked into SVN, even if they are generated files, for the
371 generation of online manuals to work.
372
373 The installation manual, @file{doc/install.texi}, is also provided on
374 the GCC web site.  The HTML version is generated by the script
375 @file{doc/install.texi2html}.
376
377 @node Man Page Generation
378 @subsubsection Man Page Generation
379
380 Because of user demand, in addition to full Texinfo manuals, man pages
381 are provided which contain extracts from those manuals.  These man
382 pages are generated from the Texinfo manuals using
383 @file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for
384 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
385 to @file{gcc.1}, but all the other man pages are generated from
386 Texinfo manuals.)
387
388 Because many systems may not have the necessary tools installed to
389 generate the man pages, they are only generated if the
390 @file{configure} script detects that recent enough tools are
391 installed, and the Makefiles allow generating man pages to fail
392 without aborting the build.  Man pages are also included in release
393 distributions.  They are generated in the source directory.
394
395 Magic comments in Texinfo files starting @samp{@@c man} control what
396 parts of a Texinfo file go into a man page.  Only a subset of Texinfo
397 is supported by @file{texi2pod.pl}, and it may be necessary to add
398 support for more Texinfo features to this script when generating new
399 man pages.  To improve the man page output, some special Texinfo
400 macros are provided in @file{doc/include/gcc-common.texi} which
401 @file{texi2pod.pl} understands:
402
403 @table @code
404 @item @@gcctabopt
405 Use in the form @samp{@@table @@gcctabopt} for tables of options,
406 where for printed output the effect of @samp{@@code} is better than
407 that of @samp{@@option} but for man page output a different effect is
408 wanted.
409 @item @@gccoptlist
410 Use for summary lists of options in manuals.
411 @item @@gol
412 Use at the end of each line inside @samp{@@gccoptlist}.  This is
413 necessary to avoid problems with differences in how the
414 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
415 @end table
416
417 FIXME: describe the @file{texi2pod.pl} input language and magic
418 comments in more detail.
419
420 @node Miscellaneous Docs
421 @subsubsection Miscellaneous Documentation
422
423 In addition to the formal documentation that is installed by GCC,
424 there are several other text files with miscellaneous documentation:
425
426 @table @file
427 @item ABOUT-GCC-NLS
428 Notes on GCC's Native Language Support.  FIXME: this should be part of
429 this manual rather than a separate file.
430 @item ABOUT-NLS
431 Notes on the Free Translation Project.
432 @item COPYING
433 The GNU General Public License.
434 @item COPYING.LIB
435 The GNU Lesser General Public License.
436 @item *ChangeLog*
437 @itemx */ChangeLog*
438 Change log files for various parts of GCC@.
439 @item LANGUAGES
440 Details of a few changes to the GCC front-end interface.  FIXME: the
441 information in this file should be part of general documentation of
442 the front-end interface in this manual.
443 @item ONEWS
444 Information about new features in old versions of GCC@.  (For recent
445 versions, the information is on the GCC web site.)
446 @item README.Portability
447 Information about portability issues when writing code in GCC@.  FIXME:
448 why isn't this part of this manual or of the GCC Coding Conventions?
449 @end table
450
451 FIXME: document such files in subdirectories, at least @file{config},
452 @file{cp}, @file{objc}, @file{testsuite}.
453
454 @node Front End
455 @subsection Anatomy of a Language Front End
456
457 A front end for a language in GCC has the following parts:
458
459 @itemize @bullet
460 @item
461 A directory @file{@var{language}} under @file{gcc} containing source
462 files for that front end.  @xref{Front End Directory, , The Front End
463 @file{@var{language}} Directory}, for details.
464 @item
465 A mention of the language in the list of supported languages in
466 @file{gcc/doc/install.texi}.
467 @item
468 A mention of the name under which the language's runtime library is
469 recognized by @option{--enable-shared=@var{package}} in the
470 documentation of that option in @file{gcc/doc/install.texi}.
471 @item
472 A mention of any special prerequisites for building the front end in
473 the documentation of prerequisites in @file{gcc/doc/install.texi}.
474 @item
475 Details of contributors to that front end in
476 @file{gcc/doc/contrib.texi}.  If the details are in that front end's
477 own manual then there should be a link to that manual's list in
478 @file{contrib.texi}.
479 @item
480 Information about support for that language in
481 @file{gcc/doc/frontends.texi}.
482 @item
483 Information about standards for that language, and the front end's
484 support for them, in @file{gcc/doc/standards.texi}.  This may be a
485 link to such information in the front end's own manual.
486 @item
487 Details of source file suffixes for that language and @option{-x
488 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
489 @item
490 Entries in @code{default_compilers} in @file{gcc.c} for source file
491 suffixes for that language.
492 @item
493 Preferably testsuites, which may be under @file{gcc/testsuite} or
494 runtime library directories.  FIXME: document somewhere how to write
495 testsuite harnesses.
496 @item
497 Probably a runtime library for the language, outside the @file{gcc}
498 directory.  FIXME: document this further.
499 @item
500 Details of the directories of any runtime libraries in
501 @file{gcc/doc/sourcebuild.texi}.
502 @end itemize
503
504 If the front end is added to the official GCC source repository, the
505 following are also necessary:
506
507 @itemize @bullet
508 @item
509 At least one Bugzilla component for bugs in that front end and runtime
510 libraries.  This category needs to be mentioned in
511 @file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
512 @item
513 Normally, one or more maintainers of that front end listed in
514 @file{MAINTAINERS}.
515 @item
516 Mentions on the GCC web site in @file{index.html} and
517 @file{frontends.html}, with any relevant links on
518 @file{readings.html}.  (Front ends that are not an official part of
519 GCC may also be listed on @file{frontends.html}, with relevant links.)
520 @item
521 A news item on @file{index.html}, and possibly an announcement on the
522 @email{gcc-announce@@gcc.gnu.org} mailing list.
523 @item
524 The front end's manuals should be mentioned in
525 @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
526 and the online manuals should be linked to from
527 @file{onlinedocs/index.html}.
528 @item
529 Any old releases or CVS repositories of the front end, before its
530 inclusion in GCC, should be made available on the GCC FTP site
531 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
532 @item
533 The release and snapshot script @file{maintainer-scripts/gcc_release}
534 should be updated to generate appropriate tarballs for this front end.
535 The associated @file{maintainer-scripts/snapshot-README} and
536 @file{maintainer-scripts/snapshot-index.html} files should be updated
537 to list the tarballs and diffs for this front end.
538 @item
539 If this front end includes its own version files that include the
540 current date, @file{maintainer-scripts/update_version} should be
541 updated accordingly.
542 @end itemize
543
544 @menu
545 * Front End Directory::  The front end @file{@var{language}} directory.
546 * Front End Config::     The front end @file{config-lang.in} file.
547 @end menu
548
549 @node Front End Directory
550 @subsubsection The Front End @file{@var{language}} Directory
551
552 A front end @file{@var{language}} directory contains the source files
553 of that front end (but not of any runtime libraries, which should be
554 outside the @file{gcc} directory).  This includes documentation, and
555 possibly some subsidiary programs build alongside the front end.
556 Certain files are special and other parts of the compiler depend on
557 their names:
558
559 @table @file
560 @item config-lang.in
561 This file is required in all language subdirectories.  @xref{Front End
562 Config, , The Front End @file{config-lang.in} File}, for details of
563 its contents
564 @item Make-lang.in
565 This file is required in all language subdirectories.  It contains
566 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
567 setting of @code{language} in @file{config-lang.in}) for the following
568 values of @code{@var{hook}}, and any other Makefile rules required to
569 build those targets (which may if necessary use other Makefiles
570 specified in @code{outputs} in @file{config-lang.in}, although this is
571 deprecated).  It also adds any testsuite targets that can use the
572 standard rule in @file{gcc/Makefile.in} to the variable
573 @code{lang_checks}.
574
575 @table @code
576 @itemx all.cross
577 @itemx start.encap
578 @itemx rest.encap
579 FIXME: exactly what goes in each of these targets?
580 @item tags
581 Build an @command{etags} @file{TAGS} file in the language subdirectory
582 in the source tree.
583 @item info
584 Build info documentation for the front end, in the build directory.
585 This target is only called by @samp{make bootstrap} if a suitable
586 version of @command{makeinfo} is available, so does not need to check
587 for this, and should fail if an error occurs.
588 @item dvi
589 Build DVI documentation for the front end, in the build directory.
590 This should be done using @code{$(TEXI2DVI)}, with appropriate
591 @option{-I} arguments pointing to directories of included files.
592 @item pdf
593 Build PDF documentation for the front end, in the build directory.
594 This should be done using @code{$(TEXI2PDF)}, with appropriate
595 @option{-I} arguments pointing to directories of included files.
596 @item html
597 Build HTML documentation for the front end, in the build directory.
598 @item man
599 Build generated man pages for the front end from Texinfo manuals
600 (@pxref{Man Page Generation}), in the build directory.  This target
601 is only called if the necessary tools are available, but should ignore
602 errors so as not to stop the build if errors occur; man pages are
603 optional and the tools involved may be installed in a broken way.
604 @item install-common
605 Install everything that is part of the front end, apart from the
606 compiler executables listed in @code{compilers} in
607 @file{config-lang.in}.
608 @item install-info
609 Install info documentation for the front end, if it is present in the
610 source directory.  This target should have dependencies on info files
611 that should be installed.
612 @item install-man
613 Install man pages for the front end.  This target should ignore
614 errors.
615 @item srcextra
616 Copies its dependencies into the source directory.  This generally should
617 be used for generated files such as Bison output files which are not
618 present in CVS, but should be included in any release tarballs.  This
619 target will be executed during a bootstrap if
620 @samp{--enable-generated-files-in-srcdir} was specified as a
621 @file{configure} option.
622 @item srcinfo
623 @itemx srcman
624 Copies its dependencies into the source directory.  These targets will be
625 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
626 was specified as a @file{configure} option.
627 @item uninstall
628 Uninstall files installed by installing the compiler.  This is
629 currently documented not to be supported, so the hook need not do
630 anything.
631 @item mostlyclean
632 @itemx clean
633 @itemx distclean
634 @itemx maintainer-clean
635 The language parts of the standard GNU
636 @samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for
637 Users, standards, GNU Coding Standards}, for details of the standard
638 targets.  For GCC, @code{maintainer-clean} should delete
639 all generated files in the source directory that are not checked into
640 CVS, but should not delete anything checked into CVS@.
641 @end table
642
643 @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
644 to a list of host object files that are used by that language.
645
646 @item lang.opt
647 This file registers the set of switches that the front end accepts on
648 the command line, and their @option{--help} text.  @xref{Options}.
649 @item lang-specs.h
650 This file provides entries for @code{default_compilers} in
651 @file{gcc.c} which override the default of giving an error that a
652 compiler for that language is not installed.
653 @item @var{language}-tree.def
654 This file, which need not exist, defines any language-specific tree
655 codes.
656 @end table
657
658 @node Front End Config
659 @subsubsection The Front End @file{config-lang.in} File
660
661 Each language subdirectory contains a @file{config-lang.in} file.  In
662 addition the main directory contains @file{c-config-lang.in}, which
663 contains limited information for the C language.  This file is a shell
664 script that may define some variables describing the language:
665
666 @table @code
667 @item language
668 This definition must be present, and gives the name of the language
669 for some purposes such as arguments to @option{--enable-languages}.
670 @item lang_requires
671 If defined, this variable lists (space-separated) language front ends
672 other than C that this front end requires to be enabled (with the
673 names given being their @code{language} settings).  For example, the
674 Java front end depends on the C++ front end, so sets
675 @samp{lang_requires=c++}.
676 @item subdir_requires
677 If defined, this variable lists (space-separated) front end directories
678 other than C that this front end requires to be present.  For example,
679 the Objective-C++ front end uses source files from the C++ and
680 Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
681 @item target_libs
682 If defined, this variable lists (space-separated) targets in the top
683 level @file{Makefile} to build the runtime libraries for this
684 language, such as @code{target-libobjc}.
685 @item lang_dirs
686 If defined, this variable lists (space-separated) top level
687 directories (parallel to @file{gcc}), apart from the runtime libraries,
688 that should not be configured if this front end is not built.
689 @item build_by_default
690 If defined to @samp{no}, this language front end is not built unless
691 enabled in a @option{--enable-languages} argument.  Otherwise, front
692 ends are built by default, subject to any special logic in
693 @file{configure.ac} (as is present to disable the Ada front end if the
694 Ada compiler is not already installed).
695 @item boot_language
696 If defined to @samp{yes}, this front end is built in stage 1 of the
697 bootstrap.  This is only relevant to front ends written in their own
698 languages.
699 @item compilers
700 If defined, a space-separated list of compiler executables that will
701 be run by the driver.  The names here will each end
702 with @samp{\$(exeext)}.
703 @item outputs
704 If defined, a space-separated list of files that should be generated
705 by @file{configure} substituting values in them.  This mechanism can
706 be used to create a file @file{@var{language}/Makefile} from
707 @file{@var{language}/Makefile.in}, but this is deprecated, building
708 everything from the single @file{gcc/Makefile} is preferred.
709 @item gtfiles
710 If defined, a space-separated list of files that should be scanned by
711 gengtype.c to generate the garbage collection tables and routines for
712 this language.  This excludes the files that are common to all front
713 ends.  @xref{Type Information}.
714
715 @end table
716
717 @node Back End
718 @subsection Anatomy of a Target Back End
719
720 A back end for a target architecture in GCC has the following parts:
721
722 @itemize @bullet
723 @item
724 A directory @file{@var{machine}} under @file{gcc/config}, containing a
725 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
726 , Machine Descriptions}), header files @file{@var{machine}.h} and
727 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
728 (@pxref{Target Macros, , Target Description Macros and Functions}),
729 possibly a target Makefile fragment @file{t-@var{machine}}
730 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
731 some other files.  The names of these files may be changed from the
732 defaults given by explicit specifications in @file{config.gcc}.
733 @item
734 If necessary, a file @file{@var{machine}-modes.def} in the
735 @file{@var{machine}} directory, containing additional machine modes to
736 represent condition codes.  @xref{Condition Code}, for further details.
737 @item
738 An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
739 directory, containing a list of target-specific options.  You can also
740 add other option files using the @code{extra_options} variable in
741 @file{config.gcc}.  @xref{Options}.
742 @item
743 Entries in @file{config.gcc} (@pxref{System Config, , The
744 @file{config.gcc} File}) for the systems with this target
745 architecture.
746 @item
747 Documentation in @file{gcc/doc/invoke.texi} for any command-line
748 options supported by this target (@pxref{Run-time Target, , Run-time
749 Target Specification}).  This means both entries in the summary table
750 of options and details of the individual options.
751 @item
752 Documentation in @file{gcc/doc/extend.texi} for any target-specific
753 attributes supported (@pxref{Target Attributes, , Defining
754 target-specific uses of @code{__attribute__}}), including where the
755 same attribute is already supported on some targets, which are
756 enumerated in the manual.
757 @item
758 Documentation in @file{gcc/doc/extend.texi} for any target-specific
759 pragmas supported.
760 @item
761 Documentation in @file{gcc/doc/extend.texi} of any target-specific
762 built-in functions supported.
763 @item
764 Documentation in @file{gcc/doc/extend.texi} of any target-specific
765 format checking styles supported.
766 @item
767 Documentation in @file{gcc/doc/md.texi} of any target-specific
768 constraint letters (@pxref{Machine Constraints, , Constraints for
769 Particular Machines}).
770 @item
771 A note in @file{gcc/doc/contrib.texi} under the person or people who
772 contributed the target support.
773 @item
774 Entries in @file{gcc/doc/install.texi} for all target triplets
775 supported with this target architecture, giving details of any special
776 notes about installation for this target, or saying that there are no
777 special notes if there are none.
778 @item
779 Possibly other support outside the @file{gcc} directory for runtime
780 libraries.  FIXME: reference docs for this.  The libstdc++ porting
781 manual needs to be installed as info for this to work, or to be a
782 chapter of this manual.
783 @end itemize
784
785 If the back end is added to the official GCC source repository, the
786 following are also necessary:
787
788 @itemize @bullet
789 @item
790 An entry for the target architecture in @file{readings.html} on the
791 GCC web site, with any relevant links.
792 @item
793 Details of the properties of the back end and target architecture in
794 @file{backends.html} on the GCC web site.
795 @item
796 A news item about the contribution of support for that target
797 architecture, in @file{index.html} on the GCC web site.
798 @item
799 Normally, one or more maintainers of that target listed in
800 @file{MAINTAINERS}.  Some existing architectures may be unmaintained,
801 but it would be unusual to add support for a target that does not have
802 a maintainer when support is added.
803 @end itemize
804
805 @node Testsuites
806 @section Testsuites
807
808 GCC contains several testsuites to help maintain compiler quality.
809 Most of the runtime libraries and language front ends in GCC have
810 testsuites.  Currently only the C language testsuites are documented
811 here; FIXME: document the others.
812
813 @menu
814 * Test Idioms::     Idioms used in testsuite code.
815 * Test Directives:: Directives used within DejaGnu tests.
816 * Ada Tests::       The Ada language testsuites.
817 * C Tests::         The C language testsuites.
818 * libgcj Tests::    The Java library testsuites.
819 * gcov Testing::    Support for testing gcov.
820 * profopt Testing:: Support for testing profile-directed optimizations.
821 * compat Testing::  Support for testing binary compatibility.
822 * Torture Tests::   Support for torture testing using multiple options.
823 @end menu
824
825 @node Test Idioms
826 @subsection Idioms Used in Testsuite Code
827
828 In general, C testcases have a trailing @file{-@var{n}.c}, starting
829 with @file{-1.c}, in case other testcases with similar names are added
830 later.  If the test is a test of some well-defined feature, it should
831 have a name referring to that feature such as
832 @file{@var{feature}-1.c}.  If it does not test a well-defined feature
833 but just happens to exercise a bug somewhere in the compiler, and a
834 bug report has been filed for this bug in the GCC bug database,
835 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
836 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
837 and previously more generally, test cases are named after the date on
838 which they were added.  This allows people to tell at a glance whether
839 a test failure is because of a recently found bug that has not yet
840 been fixed, or whether it may be a regression, but does not give any
841 other information about the bug or where discussion of it may be
842 found.  Some other language testsuites follow similar conventions.
843
844 In the @file{gcc.dg} testsuite, it is often necessary to test that an
845 error is indeed a hard error and not just a warning---for example,
846 where it is a constraint violation in the C standard, which must
847 become an error with @option{-pedantic-errors}.  The following idiom,
848 where the first line shown is line @var{line} of the file and the line
849 that generates the error, is used for this:
850
851 @smallexample
852 /* @{ dg-bogus "warning" "warning in place of error" @} */
853 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
854 @end smallexample
855
856 It may be necessary to check that an expression is an integer constant
857 expression and has a certain value.  To check that @code{@var{E}} has
858 value @code{@var{V}}, an idiom similar to the following is used:
859
860 @smallexample
861 char x[((E) == (V) ? 1 : -1)];
862 @end smallexample
863
864 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
865 assertions about the types of expressions.  See, for example,
866 @file{gcc.dg/c99-condexpr-1.c}.  The more subtle uses depend on the
867 exact rules for the types of conditional expressions in the C
868 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
869
870 It is useful to be able to test that optimizations are being made
871 properly.  This cannot be done in all cases, but it can be done where
872 the optimization will lead to code being optimized away (for example,
873 where flow analysis or alias analysis should show that certain code
874 cannot be called) or to functions not being called because they have
875 been expanded as built-in functions.  Such tests go in
876 @file{gcc.c-torture/execute}.  Where code should be optimized away, a
877 call to a nonexistent function such as @code{link_failure ()} may be
878 inserted; a definition
879
880 @smallexample
881 #ifndef __OPTIMIZE__
882 void
883 link_failure (void)
884 @{
885   abort ();
886 @}
887 #endif
888 @end smallexample
889
890 @noindent
891 will also be needed so that linking still succeeds when the test is
892 run without optimization.  When all calls to a built-in function
893 should have been optimized and no calls to the non-built-in version of
894 the function should remain, that function may be defined as
895 @code{static} to call @code{abort ()} (although redeclaring a function
896 as static may not work on all targets).
897
898 All testcases must be portable.  Target-specific testcases must have
899 appropriate code to avoid causing failures on unsupported systems;
900 unfortunately, the mechanisms for this differ by directory.
901
902 FIXME: discuss non-C testsuites here.
903
904 @node Test Directives
905 @subsection Directives used within DejaGnu tests
906
907 Test directives appear within comments in a test source file and begin
908 with @code{dg-}.  Some of these are defined within DejaGnu and others
909 are local to the GCC testsuite.
910
911 The order in which test directives appear in a test can be important:
912 directives local to GCC sometimes override information used by the
913 DejaGnu directives, which know nothing about the GCC directives, so the
914 DejaGnu directives must precede GCC directives.
915
916 Several test directives include selectors which are usually preceded by
917 the keyword @code{target} or @code{xfail}.  A selector is: one or more
918 target triplets, possibly including wildcard characters; a single
919 effective-target keyword; or a logical expression.  Depending on the
920 context, the selector specifies whether a test is skipped and reported
921 as unsupported or is expected to fail.  Use @samp{*-*-*} to match any
922 target.
923 Effective-target keywords are defined in @file{target-supports.exp} in
924 the GCC testsuite.
925
926 A selector expression appears within curly braces and uses a single
927 logical operator: one of @samp{!}, @samp{&&}, or @samp{||}.  An
928 operand is another selector expression, an effective-target keyword,
929 a single target triplet, or a list of target triplets within quotes or
930 curly braces.  For example:
931
932 @smallexample
933 @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
934 @{ target @{ powerpc*-*-* && lp64 @} @}
935 @{ xfail @{ lp64 || vect_no_align @} @}
936 @end smallexample
937
938 @table @code
939 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
940 @var{do-what-keyword} specifies how the test is compiled and whether
941 it is executed.  It is one of:
942
943 @table @code
944 @item preprocess
945 Compile with @option{-E} to run only the preprocessor.
946 @item compile
947 Compile with @option{-S} to produce an assembly code file.
948 @item assemble
949 Compile with @option{-c} to produce a relocatable object file.
950 @item link
951 Compile, assemble, and link to produce an executable file.
952 @item run
953 Produce and run an executable file, which is expected to return
954 an exit code of 0.
955 @end table
956
957 The default is @code{compile}.  That can be overridden for a set of
958 tests by redefining @code{dg-do-what-default} within the @code{.exp}
959 file for those tests.
960
961 If the directive includes the optional @samp{@{ target @var{selector} @}}
962 then the test is skipped unless the target system is included in the
963 list of target triplets or matches the effective-target keyword.
964
965 If @samp{do-what-keyword} is @code{run} and the directive includes
966 the optional @samp{@{ xfail @var{selector} @}} and the selector is met
967 then the test is expected to fail.  The @code{xfail} clause is ignored
968 for other values of @samp{do-what-keyword}; those tests can use
969 directive @code{dg-xfail-if}.
970
971 @item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
972 This DejaGnu directive provides a list of compiler options, to be used
973 if the target system matches @var{selector}, that replace the default
974 options used for this set of tests.
975
976 @item @{ dg-add-options @var{feature} @dots{} @}
977 Add any compiler options that are needed to access certain features.
978 This directive does nothing on targets that enable the features by
979 default, or that don't provide them at all.  It must come after
980 all @code{dg-options} directives.
981
982 The supported values of @var{feature} are:
983 @table @code
984 @item c99_runtime
985 The target's C99 runtime (both headers and libraries).
986
987 @item mips16_attribute
988 @code{mips16} function attributes.  Only MIPS targets support this feature,
989 and only then in certain modes.
990 @end table
991
992 @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
993 Set the time limit for the compilation and for the execution of the test
994 to the specified number of seconds.
995
996 @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
997 Multiply the normal time limit for compilation and execution of the test
998 by the specified floating-point factor.  The normal timeout limit, in
999 seconds, is found by searching the following in order:
1000
1001 @itemize @bullet
1002 @item the value defined by an earlier @code{dg-timeout} directive in
1003 the test
1004
1005 @item variable @var{tool_timeout} defined by the set of tests
1006
1007 @item @var{gcc},@var{timeout} set in the target board
1008
1009 @item 300
1010 @end itemize
1011
1012 @item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1013 Skip the test if the test system is included in @var{selector} and if
1014 each of the options in @var{include-opts} is in the set of options with
1015 which the test would be compiled and if none of the options in
1016 @var{exclude-opts} is in the set of options with which the test would be
1017 compiled.
1018
1019 Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
1020 an empty @var{exclude-opts} list.
1021
1022 @item  @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1023 Expect the test to fail if the conditions (which are the same as for
1024 @code{dg-skip-if}) are met.  This does not affect the execute step.
1025
1026 @item  @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1027 Expect the execute step of a test to fail if the conditions (which are
1028 the same as for @code{dg-skip-if}) and @code{dg-xfail-if}) are met.
1029
1030 @item @{ dg-require-@var{support} args @}
1031 Skip the test if the target does not provide the required support;
1032 see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
1033 These directives must appear after any @code{dg-do} directive in the test
1034 and before any @code{dg-additional-sources} directive.
1035 They require at least one argument, which can be an empty string if the
1036 specific procedure does not examine the argument.
1037
1038 @item @{ dg-require-effective-target @var{keyword} @}
1039 Skip the test if the test target, including current multilib flags,
1040 is not covered by the effective-target keyword.
1041 This directive must appear after any @code{dg-do} directive in the test
1042 and before any @code{dg-additional-sources} directive.
1043
1044 @item  @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
1045 Expect the test executable to return a nonzero exit status if the
1046 conditions (which are the same as for @code{dg-skip-if}) are met.
1047
1048 @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1049 This DejaGnu directive appears on a source line that is expected to get
1050 an error message, or else specifies the source line associated with the
1051 message.  If there is no message for that line or if the text of that
1052 message is not matched by @var{regexp} then the check fails and
1053 @var{comment} is included in the @code{FAIL} message.  The check does
1054 not look for the string @samp{"error"} unless it is part of @var{regexp}.
1055
1056 @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1057 This DejaGnu directive appears on a source line that is expected to get
1058 a warning message, or else specifies the source line associated with the
1059 message.  If there is no message for that line or if the text of that
1060 message is not matched by @var{regexp} then the check fails and
1061 @var{comment} is included in the @code{FAIL} message.  The check does
1062 not look for the string @samp{"warning"} unless it is part of @var{regexp}.
1063
1064 @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1065 The line is expected to get a message other than an error or warning.
1066 If there is no message for that line or if the text of that message is
1067 not matched by @var{regexp} then the check fails and @var{comment} is
1068 included in the @code{FAIL} message.
1069
1070 @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
1071 This DejaGnu directive appears on a source line that should not get a
1072 message matching @var{regexp}, or else specifies the source line
1073 associated with the bogus message.  It is usually used with @samp{xfail}
1074 to indicate that the message is a known problem for a particular set of
1075 targets.
1076
1077 @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
1078 This DejaGnu directive indicates that the test is expected to fail due
1079 to compiler messages that are not handled by @samp{dg-error},
1080 @samp{dg-warning} or @samp{dg-bogus}.  For this directive @samp{xfail}
1081 has the same effect as @samp{target}.
1082
1083 @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
1084 This DejaGnu directive compares @var{regexp} to the combined output
1085 that the test executable writes to @file{stdout} and @file{stderr}.
1086
1087 @item @{ dg-prune-output @var{regexp} @}
1088 Prune messages matching @var{regexp} from test output.
1089
1090 @item @{ dg-additional-files "@var{filelist}" @}
1091 Specify additional files, other than source files, that must be copied
1092 to the system where the compiler runs.
1093
1094 @item @{ dg-additional-sources "@var{filelist}" @}
1095 Specify additional source files to appear in the compile line
1096 following the main test file.
1097
1098 @item @{ dg-final @{ @var{local-directive} @} @}
1099 This DejaGnu directive is placed within a comment anywhere in the
1100 source file and is processed after the test has been compiled and run.
1101 Multiple @samp{dg-final} commands are processed in the order in which
1102 they appear in the source file.
1103
1104 The GCC testsuite defines the following directives to be used within
1105 @code{dg-final}.
1106
1107 @table @code
1108 @item cleanup-coverage-files
1109 Removes coverage data files generated for this test.
1110
1111 @item cleanup-repo-files
1112 Removes files generated for this test for @option{-frepo}.
1113
1114 @item cleanup-rtl-dump @var{suffix}
1115 Removes RTL dump files generated for this test.
1116
1117 @item cleanup-tree-dump @var{suffix}
1118 Removes tree dump files matching @var{suffix} which were generated for
1119 this test.
1120
1121 @item cleanup-saved-temps
1122 Removes files for the current test which were kept for @option{--save-temps}.
1123
1124 @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1125 Passes if @var{regexp} matches text in @var{filename}.
1126
1127 @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
1128 Passes if @var{regexp} does not match text in @var{filename}.
1129
1130 @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
1131 Passes if @var{symbol} is defined as a hidden symbol in the test's
1132 assembly output.
1133
1134 @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
1135 Passes if @var{symbol} is not defined as a hidden symbol in the test's
1136 assembly output.
1137
1138 @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
1139 Passes if @var{regex} is matched exactly @var{num} times in the test's
1140 assembler output.
1141
1142 @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
1143 Passes if @var{regex} matches text in the test's assembler output.
1144
1145 @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
1146 Passes if @var{regex} does not match text in the test's assembler output.
1147
1148 @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
1149 Passes if @var{regex} matches text in the test's demangled assembler output.
1150
1151 @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
1152 Passes if @var{regex} does not match text in the test's demangled assembler
1153 output.
1154
1155 @item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
1156 Passes if @var{regex} is found exactly @var{num} times in the dump file
1157 with suffix @var{suffix}.
1158
1159 @item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1160 Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
1161
1162 @item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1163 Passes if @var{regex} does not match text in the dump file with suffix
1164 @var{suffix}.
1165
1166 @item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1167 Passes if @var{regex} matches demangled text in the dump file with
1168 suffix @var{suffix}.
1169
1170 @item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
1171 Passes if @var{regex} does not match demangled text in the dump file with
1172 suffix @var{suffix}.
1173
1174 @item output-exists [@{ target/xfail @var{selector} @}]
1175 Passes if compiler output file exists.
1176
1177 @item output-exists-not [@{ target/xfail @var{selector} @}]
1178 Passes if compiler output file does not exist.
1179
1180 @item run-gcov @var{sourcefile}
1181 Check line counts in @command{gcov} tests.
1182
1183 @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
1184 Check branch and/or call counts, in addition to line counts, in
1185 @command{gcov} tests.
1186 @end table
1187 @end table
1188
1189 @node Ada Tests
1190 @subsection Ada Language Testsuites
1191
1192 The Ada testsuite includes executable tests from the ACATS 2.5
1193 testsuite, publicly available at
1194 @uref{http://www.adaic.org/compilers/acats/2.5}
1195
1196 These tests are integrated in the GCC testsuite in the
1197 @file{gcc/testsuite/ada/acats} directory, and
1198 enabled automatically when running @code{make check}, assuming
1199 the Ada language has been enabled when configuring GCC@.
1200
1201 You can also run the Ada testsuite independently, using
1202 @code{make check-ada}, or run a subset of the tests by specifying which
1203 chapter to run, e.g.:
1204
1205 @smallexample
1206 $ make check-ada CHAPTERS="c3 c9"
1207 @end smallexample
1208
1209 The tests are organized by directory, each directory corresponding to
1210 a chapter of the Ada Reference Manual.  So for example, c9 corresponds
1211 to chapter 9, which deals with tasking features of the language.
1212
1213 There is also an extra chapter called @file{gcc} containing a template for
1214 creating new executable tests.
1215
1216 The tests are run using two @command{sh} scripts: @file{run_acats} and
1217 @file{run_all.sh}.  To run the tests using a simulator or a cross
1218 target, see the small
1219 customization section at the top of @file{run_all.sh}.
1220
1221 These tests are run using the build tree: they can be run without doing
1222 a @code{make install}.
1223
1224 @node C Tests
1225 @subsection C Language Testsuites
1226
1227 GCC contains the following C language testsuites, in the
1228 @file{gcc/testsuite} directory:
1229
1230 @table @file
1231 @item gcc.dg
1232 This contains tests of particular features of the C compiler, using the
1233 more modern @samp{dg} harness.  Correctness tests for various compiler
1234 features should go here if possible.
1235
1236 Magic comments determine whether the file
1237 is preprocessed, compiled, linked or run.  In these tests, error and warning
1238 message texts are compared against expected texts or regular expressions
1239 given in comments.  These tests are run with the options @samp{-ansi -pedantic}
1240 unless other options are given in the test.  Except as noted below they
1241 are not run with multiple optimization options.
1242 @item gcc.dg/compat
1243 This subdirectory contains tests for binary compatibility using
1244 @file{compat.exp}, which in turn uses the language-independent support
1245 (@pxref{compat Testing, , Support for testing binary compatibility}).
1246 @item gcc.dg/cpp
1247 This subdirectory contains tests of the preprocessor.
1248 @item gcc.dg/debug
1249 This subdirectory contains tests for debug formats.  Tests in this
1250 subdirectory are run for each debug format that the compiler supports.
1251 @item gcc.dg/format
1252 This subdirectory contains tests of the @option{-Wformat} format
1253 checking.  Tests in this directory are run with and without
1254 @option{-DWIDE}.
1255 @item gcc.dg/noncompile
1256 This subdirectory contains tests of code that should not compile and
1257 does not need any special compilation options.  They are run with
1258 multiple optimization options, since sometimes invalid code crashes
1259 the compiler with optimization.
1260 @item gcc.dg/special
1261 FIXME: describe this.
1262
1263 @item gcc.c-torture
1264 This contains particular code fragments which have historically broken easily.
1265 These tests are run with multiple optimization options, so tests for features
1266 which only break at some optimization levels belong here.  This also contains
1267 tests to check that certain optimizations occur.  It might be worthwhile to
1268 separate the correctness tests cleanly from the code quality tests, but
1269 it hasn't been done yet.
1270
1271 @item gcc.c-torture/compat
1272 FIXME: describe this.
1273
1274 This directory should probably not be used for new tests.
1275 @item gcc.c-torture/compile
1276 This testsuite contains test cases that should compile, but do not
1277 need to link or run.  These test cases are compiled with several
1278 different combinations of optimization options.  All warnings are
1279 disabled for these test cases, so this directory is not suitable if
1280 you wish to test for the presence or absence of compiler warnings.
1281 While special options can be set, and tests disabled on specific
1282 platforms, by the use of @file{.x} files, mostly these test cases
1283 should not contain platform dependencies.  FIXME: discuss how defines
1284 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
1285 @item gcc.c-torture/execute
1286 This testsuite contains test cases that should compile, link and run;
1287 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
1288 @item gcc.c-torture/execute/ieee
1289 This contains tests which are specific to IEEE floating point.
1290 @item gcc.c-torture/unsorted
1291 FIXME: describe this.
1292
1293 This directory should probably not be used for new tests.
1294 @item gcc.c-torture/misc-tests
1295 This directory contains C tests that require special handling.  Some
1296 of these tests have individual expect files, and others share
1297 special-purpose expect files:
1298
1299 @table @file
1300 @item @code{bprob*.c}
1301 Test @option{-fbranch-probabilities} using @file{bprob.exp}, which
1302 in turn uses the generic, language-independent framework
1303 (@pxref{profopt Testing, , Support for testing profile-directed
1304 optimizations}).
1305
1306 @item @code{dg-*.c}
1307 Test the testsuite itself using @file{dg-test.exp}.
1308
1309 @item @code{gcov*.c}
1310 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
1311 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
1312
1313 @item @code{i386-pf-*.c}
1314 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
1315 @end table
1316
1317 @end table
1318
1319 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
1320 test cases and magic comments more.
1321
1322 @node libgcj Tests
1323 @subsection The Java library testsuites.
1324
1325 Runtime tests are executed via @samp{make check} in the
1326 @file{@var{target}/libjava/testsuite} directory in the build
1327 tree.  Additional runtime tests can be checked into this testsuite.
1328
1329 Regression testing of the core packages in libgcj is also covered by the
1330 Mauve testsuite.  The @uref{http://sourceware.org/mauve/,,Mauve Project}
1331 develops tests for the Java Class Libraries.  These tests are run as part
1332 of libgcj testing by placing the Mauve tree within the libjava testsuite
1333 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
1334 the location of that tree when invoking @samp{make}, as in
1335 @samp{make MAUVEDIR=~/mauve check}.
1336
1337 To detect regressions, a mechanism in @file{mauve.exp} compares the
1338 failures for a test run against the list of expected failures in
1339 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
1340 Update this file when adding new failing tests to Mauve, or when fixing
1341 bugs in libgcj that had caused Mauve test failures.
1342
1343 We encourage developers to contribute test cases to Mauve.
1344
1345 @node gcov Testing
1346 @subsection Support for testing @command{gcov}
1347
1348 Language-independent support for testing @command{gcov}, and for checking
1349 that branch profiling produces expected values, is provided by the
1350 expect file @file{gcov.exp}.  @command{gcov} tests also rely on procedures
1351 in @file{gcc.dg.exp} to compile and run the test program.  A typical
1352 @command{gcov} test contains the following DejaGnu commands within comments:
1353
1354 @smallexample
1355 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
1356 @{ dg-do run @{ target native @} @}
1357 @{ dg-final @{ run-gcov sourcefile @} @}
1358 @end smallexample
1359
1360 Checks of @command{gcov} output can include line counts, branch percentages,
1361 and call return percentages.  All of these checks are requested via
1362 commands that appear in comments in the test's source file.
1363 Commands to check line counts are processed by default.
1364 Commands to check branch percentages and call return percentages are
1365 processed if the @command{run-gcov} command has arguments @code{branches}
1366 or @code{calls}, respectively.  For example, the following specifies
1367 checking both, as well as passing @option{-b} to @command{gcov}:
1368
1369 @smallexample
1370 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
1371 @end smallexample
1372
1373 A line count command appears within a comment on the source line
1374 that is expected to get the specified count and has the form
1375 @code{count(@var{cnt})}.  A test should only check line counts for
1376 lines that will get the same count for any architecture.
1377
1378 Commands to check branch percentages (@code{branch}) and call
1379 return percentages (@code{returns}) are very similar to each other.
1380 A beginning command appears on or before the first of a range of
1381 lines that will report the percentage, and the ending command
1382 follows that range of lines.  The beginning command can include a
1383 list of percentages, all of which are expected to be found within
1384 the range.  A range is terminated by the next command of the same
1385 kind.  A command @code{branch(end)} or @code{returns(end)} marks
1386 the end of a range without starting a new one.  For example:
1387
1388 @smallexample
1389 if (i > 10 && j > i && j < 20)  /* @r{branch(27 50 75)} */
1390                                 /* @r{branch(end)} */
1391   foo (i, j);
1392 @end smallexample
1393
1394 For a call return percentage, the value specified is the
1395 percentage of calls reported to return.  For a branch percentage,
1396 the value is either the expected percentage or 100 minus that
1397 value, since the direction of a branch can differ depending on the
1398 target or the optimization level.
1399
1400 Not all branches and calls need to be checked.  A test should not
1401 check for branches that might be optimized away or replaced with
1402 predicated instructions.  Don't check for calls inserted by the
1403 compiler or ones that might be inlined or optimized away.
1404
1405 A single test can check for combinations of line counts, branch
1406 percentages, and call return percentages.  The command to check a
1407 line count must appear on the line that will report that count, but
1408 commands to check branch percentages and call return percentages can
1409 bracket the lines that report them.
1410
1411 @node profopt Testing
1412 @subsection Support for testing profile-directed optimizations
1413
1414 The file @file{profopt.exp} provides language-independent support for
1415 checking correct execution of a test built with profile-directed
1416 optimization.  This testing requires that a test program be built and
1417 executed twice.  The first time it is compiled to generate profile
1418 data, and the second time it is compiled to use the data that was
1419 generated during the first execution.  The second execution is to
1420 verify that the test produces the expected results.
1421
1422 To check that the optimization actually generated better code, a
1423 test can be built and run a third time with normal optimizations to
1424 verify that the performance is better with the profile-directed
1425 optimizations.  @file{profopt.exp} has the beginnings of this kind
1426 of support.
1427
1428 @file{profopt.exp} provides generic support for profile-directed
1429 optimizations.  Each set of tests that uses it provides information
1430 about a specific optimization:
1431
1432 @table @code
1433 @item tool
1434 tool being tested, e.g., @command{gcc}
1435
1436 @item profile_option
1437 options used to generate profile data
1438
1439 @item feedback_option
1440 options used to optimize using that profile data
1441
1442 @item prof_ext
1443 suffix of profile data files
1444
1445 @item PROFOPT_OPTIONS
1446 list of options with which to run each test, similar to the lists for
1447 torture tests
1448 @end table
1449
1450 @node compat Testing
1451 @subsection Support for testing binary compatibility
1452
1453 The file @file{compat.exp} provides language-independent support for
1454 binary compatibility testing.  It supports testing interoperability of
1455 two compilers that follow the same ABI, or of multiple sets of
1456 compiler options that should not affect binary compatibility.  It is
1457 intended to be used for testsuites that complement ABI testsuites.
1458
1459 A test supported by this framework has three parts, each in a
1460 separate source file: a main program and two pieces that interact
1461 with each other to split up the functionality being tested.
1462
1463 @table @file
1464 @item @var{testname}_main.@var{suffix}
1465 Contains the main program, which calls a function in file
1466 @file{@var{testname}_x.@var{suffix}}.
1467
1468 @item @var{testname}_x.@var{suffix}
1469 Contains at least one call to a function in
1470 @file{@var{testname}_y.@var{suffix}}.
1471
1472 @item @var{testname}_y.@var{suffix}
1473 Shares data with, or gets arguments from,
1474 @file{@var{testname}_x.@var{suffix}}.
1475 @end table
1476
1477 Within each test, the main program and one functional piece are
1478 compiled by the GCC under test.  The other piece can be compiled by
1479 an alternate compiler.  If no alternate compiler is specified,
1480 then all three source files are all compiled by the GCC under test.
1481 You can specify pairs of sets of compiler options.  The first element
1482 of such a pair specifies options used with the GCC under test, and the
1483 second element of the pair specifies options used with the alternate
1484 compiler.  Each test is compiled with each pair of options.
1485
1486 @file{compat.exp} defines default pairs of compiler options.
1487 These can be overridden by defining the environment variable
1488 @env{COMPAT_OPTIONS} as:
1489
1490 @smallexample
1491 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
1492   @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
1493 @end smallexample
1494
1495 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
1496 used by the compiler under test and @var{alti} used by the alternate
1497 compiler.  For example, with
1498 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
1499 the test is first built with @option{-g -O0} by the compiler under
1500 test and with @option{-O3} by the alternate compiler.  The test is
1501 built a second time using @option{-fpic} by the compiler under test
1502 and @option{-fPIC -O2} by the alternate compiler.
1503
1504 An alternate compiler is specified by defining an environment
1505 variable to be the full pathname of an installed compiler; for C
1506 define @env{ALT_CC_UNDER_TEST}, and for C++ define
1507 @env{ALT_CXX_UNDER_TEST}.  These will be written to the
1508 @file{site.exp} file used by DejaGnu.  The default is to build each
1509 test with the compiler under test using the first of each pair of
1510 compiler options from @env{COMPAT_OPTIONS}.  When
1511 @env{ALT_CC_UNDER_TEST} or
1512 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
1513 the compiler under test but with combinations of the options from
1514 @env{COMPAT_OPTIONS}.
1515
1516 To run only the C++ compatibility suite using the compiler under test
1517 and another version of GCC using specific compiler options, do the
1518 following from @file{@var{objdir}/gcc}:
1519
1520 @smallexample
1521 rm site.exp
1522 make -k \
1523   ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
1524   COMPAT_OPTIONS="lists as shown above" \
1525   check-c++ \
1526   RUNTESTFLAGS="compat.exp"
1527 @end smallexample
1528
1529 A test that fails when the source files are compiled with different
1530 compilers, but passes when the files are compiled with the same
1531 compiler, demonstrates incompatibility of the generated code or
1532 runtime support.  A test that fails for the alternate compiler but
1533 passes for the compiler under test probably tests for a bug that was
1534 fixed in the compiler under test but is present in the alternate
1535 compiler.
1536
1537 The binary compatibility tests support a small number of test framework
1538 commands that appear within comments in a test file.
1539
1540 @table @code
1541 @item dg-require-*
1542 These commands can be used in @file{@var{testname}_main.@var{suffix}}
1543 to skip the test if specific support is not available on the target.
1544
1545 @item dg-options
1546 The specified options are used for compiling this particular source
1547 file, appended to the options from @env{COMPAT_OPTIONS}.  When this
1548 command appears in @file{@var{testname}_main.@var{suffix}} the options
1549 are also used to link the test program.
1550
1551 @item dg-xfail-if
1552 This command can be used in a secondary source file to specify that
1553 compilation is expected to fail for particular options on particular
1554 targets.
1555 @end table
1556
1557 @node Torture Tests
1558 @subsection Support for torture testing using multiple options
1559
1560 Throughout the compiler testsuite there are several directories whose
1561 tests are run multiple times, each with a different set of options.
1562 These are known as torture tests.
1563 @file{gcc/testsuite/lib/torture-options.exp} defines procedures to
1564 set up these lists:
1565
1566 @table @code
1567 @item torture-init
1568 Initialize use of torture lists.
1569 @item set-torture-options
1570 Set lists of torture options to use for tests with and without loops.
1571 Optionally combine a set of torture options with a set of other
1572 options, as is done with Objective-C runtime options.
1573 @item torture-finish
1574 Finalize use of torture lists.
1575 @end table
1576
1577 The @file{.exp} file for a set of tests that use torture options must
1578 include calls to these three procedures if:
1579
1580 @itemize @bullet
1581 @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
1582
1583 @item It calls @var{$@{tool@}}@code{-torture} or
1584 @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
1585 @code{fortran}, or @code{objc}.
1586
1587 @item It calls @code{dg-pch}.
1588 @end itemize
1589
1590 It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
1591 to call the torture procedures if the tests should use the list in
1592 @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
1593
1594 Most uses of torture options can override the default lists by defining
1595 @var{TORTURE_OPTIONS} or add to the default list by defining
1596 @var{ADDITIONAL_TORTURE_OPTIONS}.  Define these in a @file{.dejagnurc}
1597 file or add them to the @file{site.exp} file; for example
1598
1599 @smallexample
1600 set ADDITIONAL_TORTURE_OPTIONS  [list \
1601   @{ -O2 -ftree-loop-linear @} \
1602   @{ -O2 -fpeel-loops @} ]
1603 @end smallexample