OSDN Git Service

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