OSDN Git Service

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