OSDN Git Service

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