OSDN Git Service

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