OSDN Git Service

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