1 @c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Source Tree Structure and Build System
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.
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.
20 @include configterms.texi
23 @section Top Level Source Directory
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:
32 The Boehm conservative garbage collector, used as part of the Java
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.
41 An implementation of the @command{jar} command, used with the Java
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.
51 Headers for the @code{libiberty} library.
54 The Ada runtime library.
57 The @code{libbanshee} library, used for Andersen-style points-to analysis.
60 The Fortran 77 runtime library.
63 The Fortran runtime library.
66 The @code{libffi} library, used as part of the Java runtime library.
69 The @code{libiberty} library, used for portability and for some
70 generally useful data structures and algorithms. @xref{Top, ,
71 Introduction, libiberty, @sc{gnu} libiberty}, for more information
75 The Java runtime library.
78 The @code{libmudflap} library, used for instrumenting pointer and array
79 dereferencing operations.
82 The Objective-C runtime library.
85 The C++ runtime library.
87 @item maintainer-scripts
88 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
91 The @code{zlib} compression library, used by the Java front end and as
92 part of the Java runtime library.
95 The build system in the top level directory, including how recursion
96 into subdirectories works and how building runtime libraries for
97 multilibs is handled, is documented in a separate manual, included
98 with GNU Binutils. @xref{Top, , GNU configure and build system,
99 configure, The GNU configure and build system}, for details.
102 @section The @file{gcc} Subdirectory
104 The @file{gcc} directory contains many files that are part of the C
105 sources of GCC, other files used as part of the configuration and
106 build process, and subdirectories including documentation and a
107 test suite. The files that are sources of GCC are documented in a
108 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
111 * Subdirectories:: Subdirectories of @file{gcc}.
112 * Configuration:: The configuration process, and the files it uses.
113 * Build:: The build system in the @file{gcc} directory.
114 * Makefile:: Targets in @file{gcc/Makefile}.
115 * Library Files:: Library source files and headers under @file{gcc/}.
116 * Headers:: Headers installed by GCC.
117 * Documentation:: Building documentation in GCC.
118 * Front End:: Anatomy of a language front end.
119 * Back End:: Anatomy of a target back end.
123 @subsection Subdirectories of @file{gcc}
125 The @file{gcc} directory contains the following subdirectories:
129 Subdirectories for various languages. Directories containing a file
130 @file{config-lang.in} are language subdirectories. The contents of
131 the subdirectories @file{cp} (for C++) and @file{objc} (for
132 Objective-C) are documented in this manual (@pxref{Passes, , Passes
133 and Files of the Compiler}); those for other languages are not.
134 @xref{Front End, , Anatomy of a Language Front End}, for details of
135 the files in these directories.
138 Configuration files for supported architectures and operating
139 systems. @xref{Back End, , Anatomy of a Target Back End}, for
140 details of the files in this directory.
143 Texinfo documentation for GCC, together with automatically generated
144 man pages and support for converting the installation manual to
145 HTML@. @xref{Documentation}.
148 The support for fixing system headers to work with GCC@. See
149 @file{fixinc/README} for more information. The headers fixed by this
150 mechanism are installed in @file{@var{libsubdir}/include}. Along with
151 those headers, @file{README-fixinc} is also installed, as
152 @file{@var{libsubdir}/include/README}.
155 System headers installed by GCC, mainly those required by the C
156 standard of freestanding implementations. @xref{Headers, , Headers
157 Installed by GCC}, for details of when these and other headers are
161 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
162 include it in libc. Properly, this directory should be at top level,
163 parallel to the @file{gcc} directory.
166 Message catalogs with translations of messages produced by GCC into
167 various languages, @file{@var{language}.po}. This directory also
168 contains @file{gcc.pot}, the template for these message catalogues,
169 @file{exgettext}, a wrapper around @command{gettext} to extract the
170 messages from the GCC sources and create @file{gcc.pot}, which is run
171 by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
172 which messages should not be extracted.
175 The GCC test suites (except for those for runtime libraries).
180 @subsection Configuration in the @file{gcc} Directory
182 The @file{gcc} directory is configured with an Autoconf-generated
183 script @file{configure}. The @file{configure} script is generated
184 from @file{configure.ac} and @file{aclocal.m4}. From the files
185 @file{configure.ac} and @file{acconfig.h}, Autoheader generates the
186 file @file{config.in}. The file @file{cstamp-h.in} is used as a
190 * Config Fragments:: Scripts used by @file{configure}.
191 * System Config:: The @file{config.build}, @file{config.host}, and
192 @file{config.gcc} files.
193 * Configuration Files:: Files created by running @file{configure}.
196 @node Config Fragments
197 @subsubsection Scripts Used by @file{configure}
199 @file{configure} uses some other scripts to help in its work:
202 @item The standard GNU @file{config.sub} and @file{config.guess}
203 files, kept in the top level directory, are used. FIXME: when is the
204 @file{config.guess} file in the @file{gcc} directory (that just calls
205 the top level one) used?
207 @item The file @file{config.gcc} is used to handle configuration
208 specific to the particular target machine. The file
209 @file{config.build} is used to handle configuration specific to the
210 particular build machine. The file @file{config.host} is used to handle
211 configuration specific to the particular host machine. (In general,
212 these should only be used for features that cannot reasonably be tested in
213 Autoconf feature tests.)
214 @xref{System Config, , The @file{config.build}, @file{config.host},
215 and @file{config.gcc} Files}, for details of the contents of these files.
217 @item Each language subdirectory has a file
218 @file{@var{language}/config-lang.in} that is used for
219 front-end-specific configuration. @xref{Front End Config, , The Front
220 End @file{config-lang.in} File}, for details of this file.
222 @item A helper script @file{configure.frag} is used as part of
223 creating the output of @file{configure}.
227 @subsubsection The @file{config.build}, @file{config.host}, and @file{config.gcc} Files
229 The @file{config.build} file contains specific rules for particular systems
230 which GCC is built on. This should be used as rarely as possible, as the
231 behavior of the build system can always be detected by autoconf.
233 The @file{config.host} file contains specific rules for particular systems
234 which GCC will run on. This is rarely needed.
236 The @file{config.gcc} file contains specific rules for particular systems
237 which GCC will generate code for. This is usually needed.
239 Each file has a list of the shell variables it sets, with descriptions, at the
242 FIXME: document the contents of these files, and what variables should
243 be set to control build, host and target configuration.
245 @include configfiles.texi
248 @subsection Build System in the @file{gcc} Directory
250 FIXME: describe the build system, including what is built in what
251 stages. Also list the various source files that are used in the build
252 process but aren't source files of GCC itself and so aren't documented
253 below (@pxref{Passes}).
255 @include makefile.texi
258 @subsection Library Source Files and Headers under the @file{gcc} Directory
260 FIXME: list here, with explanation, all the C source files and headers
261 under the @file{gcc} directory that aren't built into the GCC
262 executable but rather are part of runtime libraries and object files,
263 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
264 Headers Installed by GCC}, for more information about the
265 @file{ginclude} directory.
268 @subsection Headers Installed by GCC
270 In general, GCC expects the system C library to provide most of the
271 headers to be used with it. However, GCC will fix those headers if
272 necessary to make them work with GCC, and will install some headers
273 required of freestanding implementations. These headers are installed
274 in @file{@var{libsubdir}/include}. Headers for non-C runtime
275 libraries are also installed by GCC; these are not documented here.
276 (FIXME: document them somewhere.)
278 Several of the headers GCC installs are in the @file{ginclude}
279 directory. These headers, @file{iso646.h},
280 @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
281 are installed in @file{@var{libsubdir}/include},
282 unless the target Makefile fragment (@pxref{Target Fragment})
283 overrides this by setting @code{USER_H}.
285 In addition to these headers and those generated by fixing system
286 headers to work with GCC, some other headers may also be installed in
287 @file{@var{libsubdir}/include}. @file{config.gcc} may set
288 @code{extra_headers}; this specifies additional headers under
289 @file{config} to be installed on some systems.
291 GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
292 This is done to cope with command-line options that change the
293 representation of floating point numbers.
295 GCC also installs its own version of @code{<limits.h>}; this is generated
296 from @file{glimits.h}, together with @file{limitx.h} and
297 @file{limity.h} if the system also has its own version of
298 @code{<limits.h>}. (GCC provides its own header because it is
299 required of ISO C freestanding implementations, but needs to include
300 the system header from its own header as well because other standards
301 such as POSIX specify additional values to be defined in
302 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
303 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
304 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
305 needs fixing, @file{syslimits.h} is the fixed copy.
308 @subsection Building Documentation
310 The main GCC documentation is in the form of manuals in Texinfo
311 format. These are installed in Info format, and DVI versions may be
312 generated by @samp{make dvi}. In addition, some man pages are
313 generated from the Texinfo manuals, there are some other text files
314 with miscellaneous documentation, and runtime libraries have their own
315 documentation outside the @file{gcc} directory. FIXME: document the
316 documentation for runtime libraries somewhere.
319 * Texinfo Manuals:: GCC manuals in Texinfo format.
320 * Man Page Generation:: Generating man pages from Texinfo manuals.
321 * Miscellaneous Docs:: Miscellaneous text files with documentation.
324 @node Texinfo Manuals
325 @subsubsection Texinfo Manuals
327 The manuals for GCC as a whole, and the C and C++ front ends, are in
328 files @file{doc/*.texi}. Other front ends have their own manuals in
329 files @file{@var{language}/*.texi}. Common files
330 @file{doc/include/*.texi} are provided which may be included in
331 multiple manuals; the following files are in @file{doc/include}:
335 The GNU Free Documentation License.
337 The section ``Funding Free Software''.
338 @item gcc-common.texi
339 Common definitions for manuals.
341 The GNU General Public License.
343 A copy of @file{texinfo.tex} known to work with the GCC manuals.
346 DVI formatted manuals are generated by @samp{make dvi}, which uses
347 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
348 manuals are generated by @samp{make info} (which is run as part of
349 a bootstrap); this generates the manuals in the source directory,
350 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
351 and they are included in release distributions.
353 Manuals are also provided on the GCC web site, in both HTML and
354 PostScript forms. This is done via the script
355 @file{maintainer-scripts/update_web_docs}. Each manual to be
356 provided online must be listed in the definition of @code{MANUALS} in
357 that file; a file @file{@var{name}.texi} must only appear once in the
358 source tree, and the output manual must have the same name as the
359 source file. (However, other Texinfo files, included in manuals but
360 not themselves the root files of manuals, may have names that appear
361 more than once in the source tree.) The manual file
362 @file{@var{name}.texi} should only include other files in its own
363 directory or in @file{doc/include}. HTML manuals will be generated by
364 @samp{makeinfo --html} and PostScript manuals by @command{texi2dvi}
365 and @command{dvips}. All Texinfo files that are parts of manuals must
366 be checked into CVS, even if they are generated files, for the
367 generation of online manuals to work.
369 The installation manual, @file{doc/install.texi}, is also provided on
370 the GCC web site. The HTML version is generated by the script
371 @file{doc/install.texi2html}.
373 @node Man Page Generation
374 @subsubsection Man Page Generation
376 Because of user demand, in addition to full Texinfo manuals, man pages
377 are provided which contain extracts from those manuals. These man
378 pages are generated from the Texinfo manuals using
379 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
380 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
381 to @file{gcc.1}, but all the other man pages are generated from
384 Because many systems may not have the necessary tools installed to
385 generate the man pages, they are only generated if the
386 @file{configure} script detects that recent enough tools are
387 installed, and the Makefiles allow generating man pages to fail
388 without aborting the build. Man pages are also included in release
389 distributions. They are generated in the source directory.
391 Magic comments in Texinfo files starting @samp{@@c man} control what
392 parts of a Texinfo file go into a man page. Only a subset of Texinfo
393 is supported by @file{texi2pod.pl}, and it may be necessary to add
394 support for more Texinfo features to this script when generating new
395 man pages. To improve the man page output, some special Texinfo
396 macros are provided in @file{doc/include/gcc-common.texi} which
397 @file{texi2pod.pl} understands:
401 Use in the form @samp{@@table @@gcctabopt} for tables of options,
402 where for printed output the effect of @samp{@@code} is better than
403 that of @samp{@@option} but for man page output a different effect is
406 Use for summary lists of options in manuals.
408 Use at the end of each line inside @samp{@@gccoptlist}. This is
409 necessary to avoid problems with differences in how the
410 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
413 FIXME: describe the @file{texi2pod.pl} input language and magic
414 comments in more detail.
416 @node Miscellaneous Docs
417 @subsubsection Miscellaneous Documentation
419 In addition to the formal documentation that is installed by GCC,
420 there are several other text files with miscellaneous documentation:
424 Notes on GCC's Native Language Support. FIXME: this should be part of
425 this manual rather than a separate file.
427 Notes on the Free Translation Project.
429 The GNU General Public License.
431 The GNU Lesser General Public License.
434 Change log files for various parts of GCC@.
436 Details of a few changes to the GCC front-end interface. FIXME: the
437 information in this file should be part of general documentation of
438 the front-end interface in this manual.
440 Information about new features in old versions of GCC@. (For recent
441 versions, the information is on the GCC web site.)
442 @item README.Portability
443 Information about portability issues when writing code in GCC@. FIXME:
444 why isn't this part of this manual or of the GCC Coding Conventions?
446 A pointer to the GNU Service Directory.
449 FIXME: document such files in subdirectories, at least @file{config},
450 @file{cp}, @file{objc}, @file{testsuite}.
453 @subsection Anatomy of a Language Front End
455 A front end for a language in GCC has the following parts:
459 A directory @file{@var{language}} under @file{gcc} containing source
460 files for that front end. @xref{Front End Directory, , The Front End
461 @file{@var{language}} Directory}, for details.
463 A mention of the language in the list of supported languages in
464 @file{gcc/doc/install.texi}.
466 Details of contributors to that front end in
467 @file{gcc/doc/contrib.texi}. If the details are in that front end's
468 own manual then there should be a link to that manual's list in
471 Information about support for that language in
472 @file{gcc/doc/frontends.texi}.
474 Information about standards for that language, and the front end's
475 support for them, in @file{gcc/doc/standards.texi}. This may be a
476 link to such information in the front end's own manual.
478 Details of source file suffixes for that language and @option{-x
479 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
481 Entries in @code{default_compilers} in @file{gcc.c} for source file
482 suffixes for that language.
484 Preferably test suites, which may be under @file{gcc/testsuite} or
485 runtime library directories. FIXME: document somewhere how to write
486 test suite harnesses.
488 Probably a runtime library for the language, outside the @file{gcc}
489 directory. FIXME: document this further.
491 Details of the directories of any runtime libraries in
492 @file{gcc/doc/sourcebuild.texi}.
495 If the front end is added to the official GCC CVS repository, the
496 following are also necessary:
500 At least one Bugzilla component for bugs in that front end and runtime
501 libraries. This category needs to be mentioned in
502 @file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
504 Normally, one or more maintainers of that front end listed in
507 Mentions on the GCC web site in @file{index.html} and
508 @file{frontends.html}, with any relevant links on
509 @file{readings.html}. (Front ends that are not an official part of
510 GCC may also be listed on @file{frontends.html}, with relevant links.)
512 A news item on @file{index.html}, and possibly an announcement on the
513 @email{gcc-announce@@gcc.gnu.org} mailing list.
515 The front end's manuals should be mentioned in
516 @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
517 and the online manuals should be linked to from
518 @file{onlinedocs/index.html}.
520 Any old releases or CVS repositories of the front end, before its
521 inclusion in GCC, should be made available on the GCC FTP site
522 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
524 The release and snapshot script @file{maintainer-scripts/gcc_release}
525 should be updated to generate appropriate tarballs for this front end.
526 The associated @file{maintainer-scripts/snapshot-README} and
527 @file{maintainer-scripts/snapshot-index.html} files should be updated
528 to list the tarballs and diffs for this front end.
530 If this front end includes its own version files that include the
531 current date, @file{maintainer-scripts/update_version} should be
534 @file{CVSROOT/modules} in the GCC CVS repository should be updated.
538 * Front End Directory:: The front end @file{@var{language}} directory.
539 * Front End Config:: The front end @file{config-lang.in} file.
542 @node Front End Directory
543 @subsubsection The Front End @file{@var{language}} Directory
545 A front end @file{@var{language}} directory contains the source files
546 of that front end (but not of any runtime libraries, which should be
547 outside the @file{gcc} directory). This includes documentation, and
548 possibly some subsidiary programs build alongside the front end.
549 Certain files are special and other parts of the compiler depend on
554 This file is required in all language subdirectories. @xref{Front End
555 Config, , The Front End @file{config-lang.in} File}, for details of
558 This file is required in all language subdirectories. It contains
559 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
560 setting of @code{language} in @file{config-lang.in}) for the following
561 values of @code{@var{hook}}, and any other Makefile rules required to
562 build those targets (which may if necessary use other Makefiles
563 specified in @code{outputs} in @file{config-lang.in}, although this is
564 deprecated). Some hooks are defined by using a double-colon rule for
565 @code{@var{hook}}, rather than by using a target of form
566 @code{@var{lang}.@var{hook}}. These hooks are called ``double-colon
567 hooks'' below. It also adds any testsuite targets that can use the
568 standard rule in @file{gcc/Makefile.in} to the variable
576 FIXME: exactly what goes in each of these targets?
578 Build an @command{etags} @file{TAGS} file in the language subdirectory
581 Build info documentation for the front end, in the build directory.
582 This target is only called by @samp{make bootstrap} if a suitable
583 version of @command{makeinfo} is available, so does not need to check
584 for this, and should fail if an error occurs.
586 Build DVI documentation for the front end, in the build directory.
587 This should be done using @code{$(TEXI2DVI)}, with appropriate
588 @option{-I} arguments pointing to directories of included files.
589 This hook is a double-colon hook.
591 Build generated man pages for the front end from Texinfo manuals
592 (@pxref{Man Page Generation}), in the build directory. This target
593 is only called if the necessary tools are available, but should ignore
594 errors so as not to stop the build if errors occur; man pages are
595 optional and the tools involved may be installed in a broken way.
597 FIXME: what is this target for?
599 Install everything that is part of the front end, apart from the
600 compiler executables listed in @code{compilers} in
601 @file{config-lang.in}.
603 Install info documentation for the front end, if it is present in the
604 source directory. This target should have dependencies on info files
605 that should be installed. This hook is a double-colon hook.
607 Install man pages for the front end. This target should ignore
610 Copies its dependencies into the source directory. This generally should
611 be used for generated files such as @file{gcc/c-parse.c} which are not
612 present in CVS, but should be included in any release tarballs. This
613 target will be executed during a bootstrap if
614 @samp{--enable-generated-files-in-srcdir} was specified as a
615 @file{configure} option.
618 Copies its dependencies into the source directory. These targets will be
619 executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
620 was specified as a @file{configure} option.
622 Uninstall files installed by installing the compiler. This is
623 currently documented not to be supported, so the hook need not do
628 @itemx maintainer-clean
629 The language parts of the standard GNU
630 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
631 Users, standards, GNU Coding Standards}, for details of the standard
632 targets. For GCC, @code{maintainer-clean} should delete
633 all generated files in the source directory that are not checked into
634 CVS, but should not delete anything checked into CVS@.
641 Move to the stage directory files not included in @code{stagestuff} in
642 @file{config-lang.in} or otherwise moved by the main @file{Makefile}.
646 This file registers the set of switches that the front end accepts on
647 the command line, and their --help text. The file format is
648 documented in the file @file{c.opt}. These files are processed by the
649 script @file{opts.sh}.
651 This file provides entries for @code{default_compilers} in
652 @file{gcc.c} which override the default of giving an error that a
653 compiler for that language is not installed.
654 @item @var{language}-tree.def
655 This file, which need not exist, defines any language-specific tree
659 @node Front End Config
660 @subsubsection The Front End @file{config-lang.in} File
662 Each language subdirectory contains a @file{config-lang.in} file. In
663 addition the main directory contains @file{c-config-lang.in}, which
664 contains limited information for the C language. This file is a shell
665 script that may define some variables describing the language:
669 This definition must be present, and gives the name of the language
670 for some purposes such as arguments to @option{--enable-languages}.
672 If defined, this variable lists (space-separated) language front ends
673 other than C that this front end requires to be enabled (with the
674 names given being their @code{language} settings). For example, the
675 Java front end depends on the C++ front end, so sets
676 @samp{lang_requires=c++}.
678 If defined, this variable lists (space-separated) targets in the top
679 level @file{Makefile} to build the runtime libraries for this
680 language, such as @code{target-libobjc}.
682 If defined, this variable lists (space-separated) top level
683 directories (parallel to @file{gcc}), apart from the runtime libraries,
684 that should not be configured if this front end is not built.
685 @item build_by_default
686 If defined to @samp{no}, this language front end is not built unless
687 enabled in a @option{--enable-languages} argument. Otherwise, front
688 ends are built by default, subject to any special logic in
689 @file{configure.ac} (as is present to disable the Ada front end if the
690 Ada compiler is not already installed).
692 If defined to @samp{yes}, this front end is built in stage 1 of the
693 bootstrap. This is only relevant to front ends written in their own
696 If defined, a space-separated list of compiler executables that will
697 be run by the driver. The names here will each end
698 with @samp{\$(exeext)}.
700 If defined, a space-separated list of files that should be moved to
701 the @file{stage@var{n}} directories in each stage of bootstrap.
703 If defined, a space-separated list of files that should be generated
704 by @file{configure} substituting values in them. This mechanism can
705 be used to create a file @file{@var{language}/Makefile} from
706 @file{@var{language}/Makefile.in}, but this is deprecated, building
707 everything from the single @file{gcc/Makefile} is preferred.
709 If defined, a space-separated list of files that should be scanned by
710 gengtype.c to generate the garbage collection tables and routines for
711 this language. This excludes the files that are common to all front
712 ends. @xref{Type Information}.
714 If defined to @samp{yes}, this frontend requires the GMP library.
715 Enables configure tests for GMP, which set @code{GMPLIBS} and
716 @code{GMPINC} appropriately.
721 @subsection Anatomy of a Target Back End
723 A back end for a target architecture in GCC has the following parts:
727 A directory @file{@var{machine}} under @file{gcc/config}, containing a
728 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
729 , Machine Descriptions}), header files @file{@var{machine}.h} and
730 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
731 (@pxref{Target Macros, , Target Description Macros and Functions}),
732 possibly a target Makefile fragment @file{t-@var{machine}}
733 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
734 some other files. The names of these files may be changed from the
735 defaults given by explicit specifications in @file{config.gcc}.
737 If necessary, a file @file{@var{machine}-modes.def} in the
738 @file{@var{machine}} directory, containing additional machine modes to
739 represent condition codes. @xref{Condition Code}, for further details.
741 Entries in @file{config.gcc} (@pxref{System Config, , The
742 @file{config.gcc} File}) for the systems with this target
745 Documentation in @file{gcc/doc/invoke.texi} for any command-line
746 options supported by this target (@pxref{Run-time Target, , Run-time
747 Target Specification}). This means both entries in the summary table
748 of options and details of the individual options.
750 Documentation in @file{gcc/doc/extend.texi} for any target-specific
751 attributes supported (@pxref{Target Attributes, , Defining
752 target-specific uses of @code{__attribute__}}), including where the
753 same attribute is already supported on some targets, which are
754 enumerated in the manual.
756 Documentation in @file{gcc/doc/extend.texi} for any target-specific
759 Documentation in @file{gcc/doc/extend.texi} of any target-specific
760 built-in functions supported.
762 Documentation in @file{gcc/doc/md.texi} of any target-specific
763 constraint letters (@pxref{Machine Constraints, , Constraints for
764 Particular Machines}).
766 A note in @file{gcc/doc/contrib.texi} under the person or people who
767 contributed the target support.
769 Entries in @file{gcc/doc/install.texi} for all target triplets
770 supported with this target architecture, giving details of any special
771 notes about installation for this target, or saying that there are no
772 special notes if there are none.
774 Possibly other support outside the @file{gcc} directory for runtime
775 libraries. FIXME: reference docs for this. The libstdc++ porting
776 manual needs to be installed as info for this to work, or to be a
777 chapter of this manual.
780 If the back end is added to the official GCC CVS repository, the
781 following are also necessary:
785 An entry for the target architecture in @file{readings.html} on the
786 GCC web site, with any relevant links.
788 Details of the properties of the back end and target architecture in
789 @file{backends.html} on the GCC web site.
791 A news item about the contribution of support for that target
792 architecture, in @file{index.html} on the GCC web site.
794 Normally, one or more maintainers of that target listed in
795 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
796 but it would be unusual to add support for a target that does not have
797 a maintainer when support is added.
803 GCC contains several test suites to help maintain compiler quality.
804 Most of the runtime libraries and language front ends in GCC have test
805 suites. Currently only the C language test suites are documented
806 here; FIXME: document the others.
809 * Test Idioms:: Idioms used in test suite code.
810 * Ada Tests:: The Ada language test suites.
811 * C Tests:: The C language test suites.
812 * libgcj Tests:: The Java library test suites.
813 * gcov Testing:: Support for testing gcov.
814 * profopt Testing:: Support for testing profile-directed optimizations.
815 * compat Testing:: Support for testing binary compatibility.
819 @subsection Idioms Used in Test Suite Code
821 In general C testcases have a trailing @file{-@var{n}.c}, starting
822 with @file{-1.c}, in case other testcases with similar names are added
823 later. If the test is a test of some well-defined feature, it should
824 have a name referring to that feature such as
825 @file{@var{feature}-1.c}. If it does not test a well-defined feature
826 but just happens to exercise a bug somewhere in the compiler, and a
827 bug report has been filed for this bug in the GCC bug database,
828 @file{pr@var{bug-number}-1.c} is the appropriate form of name.
829 Otherwise (for miscellaneous bugs not filed in the GCC bug database),
830 and previously more generally, test cases are named after the date on
831 which they were added. This allows people to tell at a glance whether
832 a test failure is because of a recently found bug that has not yet
833 been fixed, or whether it may be a regression, but does not give any
834 other information about the bug or where discussion of it may be
835 found. Some other language testsuites follow similar conventions.
837 In the @file{gcc.dg} test suite, it is often necessary to test that an
838 error is indeed a hard error and not just a warning---for example,
839 where it is a constraint violation in the C standard, which must
840 become an error with @option{-pedantic-errors}. The following idiom,
841 where the first line shown is line @var{line} of the file and the line
842 that generates the error, is used for this:
845 /* @{ dg-bogus "warning" "warning in place of error" @} */
846 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
849 It may be necessary to check that an expression is an integer constant
850 expression and has a certain value. To check that @code{@var{E}} has
851 value @code{@var{V}}, an idiom similar to the following is used:
854 char x[((E) == (V) ? 1 : -1)];
857 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
858 assertions about the types of expressions. See, for example,
859 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
860 exact rules for the types of conditional expressions in the C
861 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
863 It is useful to be able to test that optimizations are being made
864 properly. This cannot be done in all cases, but it can be done where
865 the optimization will lead to code being optimized away (for example,
866 where flow analysis or alias analysis should show that certain code
867 cannot be called) or to functions not being called because they have
868 been expanded as built-in functions. Such tests go in
869 @file{gcc.c-torture/execute}. Where code should be optimized away, a
870 call to a nonexistent function such as @code{link_failure ()} may be
871 inserted; a definition
884 will also be needed so that linking still succeeds when the test is
885 run without optimization. When all calls to a built-in function
886 should have been optimized and no calls to the non-built-in version of
887 the function should remain, that function may be defined as
888 @code{static} to call @code{abort ()} (although redeclaring a function
889 as static may not work on all targets).
891 All testcases must be portable. Target-specific testcases must have
892 appropriate code to avoid causing failures on unsupported systems;
893 unfortunately, the mechanisms for this differ by directory.
895 FIXME: discuss non-C test suites here.
898 @subsection Ada Language Test Suites
900 The Ada test suite includes executable tests from the ACATS 2.5 test
901 suite, publicly available at @uref{http://www.adaic.org/compilers/acats/2.5}
903 These tests are integrated in the GCC test suite in the
904 @file{gcc/testsuite/ada/acats} directory, and
905 enabled automatically when running @code{make check}, assuming
906 the Ada language has been enabled when configuring GCC.
908 You can also run the Ada test suite independently, using
909 @code{make check-ada}, or run a subset of the tests by specifying which
913 $ make check-ada CHAPTERS="c3 c9"
916 The tests are organized by directory, each directory corresponding to
917 a chapter of the Ada Reference Manual. So for example, c9 corresponds
918 to chapter 9, which deals with tasking features of the language.
920 There is also an extra chapter called @file{gcc} containing a template for
921 creating new executable tests.
923 The tests are run using two 'sh' scripts: run_acats and run_all.sh
924 To run the tests using a simulator or a cross target, see the small
925 customization section at the top of run_all.sh
927 These tests are run using the build tree: they can be run without doing
928 a @code{make install}.
931 @subsection C Language Test Suites
933 GCC contains the following C language test suites, in the
934 @file{gcc/testsuite} directory:
938 This contains tests of particular features of the C compiler, using the
939 more modern @samp{dg} harness. Correctness tests for various compiler
940 features should go here if possible.
942 Magic comments determine whether the file
943 is preprocessed, compiled, linked or run. In these tests, error and warning
944 message texts are compared against expected texts or regular expressions
945 given in comments. These tests are run with the options @samp{-ansi -pedantic}
946 unless other options are given in the test. Except as noted below they
947 are not run with multiple optimization options.
949 This subdirectory contains tests for binary compatibility using
950 @file{compat.exp}, which in turn uses the language-independent support
951 (@pxref{compat Testing, , Support for testing binary compatibility}).
953 This subdirectory contains tests of the preprocessor.
955 This subdirectory contains tests for debug formats. Tests in this
956 subdirectory are run for each debug format that the compiler supports.
958 This subdirectory contains tests of the @option{-Wformat} format
959 checking. Tests in this directory are run with and without
961 @item gcc.dg/noncompile
962 This subdirectory contains tests of code that should not compile and
963 does not need any special compilation options. They are run with
964 multiple optimization options, since sometimes invalid code crashes
965 the compiler with optimization.
967 FIXME: describe this.
970 This contains particular code fragments which have historically broken easily.
971 These tests are run with multiple optimization options, so tests for features
972 which only break at some optimization levels belong here. This also contains
973 tests to check that certain optimizations occur. It might be worthwhile to
974 separate the correctness tests cleanly from the code quality tests, but
975 it hasn't been done yet.
977 @item gcc.c-torture/compat
978 FIXME: describe this.
980 This directory should probably not be used for new tests.
981 @item gcc.c-torture/compile
982 This test suite contains test cases that should compile, but do not
983 need to link or run. These test cases are compiled with several
984 different combinations of optimization options. All warnings are
985 disabled for these test cases, so this directory is not suitable if
986 you wish to test for the presence or absence of compiler warnings.
987 While special options can be set, and tests disabled on specific
988 platforms, by the use of @file{.x} files, mostly these test cases
989 should not contain platform dependencies. FIXME: discuss how defines
990 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
991 @item gcc.c-torture/execute
992 This test suite contains test cases that should compile, link and run;
993 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
994 @item gcc.c-torture/execute/ieee
995 This contains tests which are specific to IEEE floating point.
996 @item gcc.c-torture/unsorted
997 FIXME: describe this.
999 This directory should probably not be used for new tests.
1000 @item gcc.c-torture/misc-tests
1001 This directory contains C tests that require special handling. Some
1002 of these tests have individual expect files, and others share
1003 special-purpose expect files:
1006 @item @code{bprob*.c}
1007 Test @option{-fbranch-probabilities} using @file{bprob.exp}, which
1008 in turn uses the generic, language-independent framework
1009 (@pxref{profopt Testing, , Support for testing profile-directed
1013 Test the testsuite itself using @file{dg-test.exp}.
1015 @item @code{gcov*.c}
1016 Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
1017 language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
1019 @item @code{i386-pf-*.c}
1020 Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
1025 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
1026 test cases and magic comments more.
1029 @subsection The Java library test suites.
1031 Runtime tests are executed via @samp{make check} in the
1032 @file{@var{target}/libjava/testsuite} directory in the build
1033 tree. Additional runtime tests can be checked into this testsuite.
1035 Regression testing of the core packages in libgcj is also covered by the
1036 Mauve test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project}
1037 develops tests for the Java Class Libraries. These tests are run as part
1038 of libgcj testing by placing the Mauve tree within the libjava testsuite
1039 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
1040 the location of that tree when invoking @samp{make}, as in
1041 @samp{make MAUVEDIR=~/mauve check}.
1043 To detect regressions, a mechanism in @file{mauve.exp} compares the
1044 failures for a test run against the list of expected failures in
1045 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
1046 Update this file when adding new failing tests to Mauve, or when fixing
1047 bugs in libgcj that had caused Mauve test failures.
1049 The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,,
1050 Jacks} project provides a test suite for Java compilers that can be used
1051 to test changes that affect the GCJ front end. This test suite is run as
1052 part of Java testing by placing the Jacks tree within the the libjava
1053 testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}.
1055 We encourage developers to contribute test cases to Mauve and Jacks.
1058 @subsection Support for testing @command{gcov}
1060 Language-independent support for testing @command{gcov}, and for checking
1061 that branch profiling produces expected values, is provided by the
1062 expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures
1063 in @file{gcc.dg.exp} to compile and run the test program. A typical
1064 @command{gcov} test contains the following DejaGNU commands within comments:
1067 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
1068 @{ dg-do run @{ target native @} @}
1069 @{ dg-final @{ run-gcov sourcefile @} @}
1072 Checks of @command{gcov} output can include line counts, branch percentages,
1073 and call return percentages. All of these checks are requested via
1074 commands that appear in comments in the test's source file.
1075 Commands to check line counts are processed by default.
1076 Commands to check branch percentages and call return percentages are
1077 processed if the @command{run-gcov} command has arguments @code{branches}
1078 or @code{calls}, respectively. For example, the following specifies
1079 checking both, as well as passing @code{-b} to @command{gcov}:
1082 @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
1085 A line count command appears within a comment on the source line
1086 that is expected to get the specified count and has the form
1087 @code{count(@var{cnt})}. A test should only check line counts for
1088 lines that will get the same count for any architecture.
1090 Commands to check branch percentages (@code{branch}) and call
1091 return percentages (@code{returns}) are very similar to each other.
1092 A beginning command appears on or before the first of a range of
1093 lines that will report the percentage, and the ending command
1094 follows that range of lines. The beginning command can include a
1095 list of percentages, all of which are expected to be found within
1096 the range. A range is terminated by the next command of the same
1097 kind. A command @code{branch(end)} or @code{returns(end)} marks
1098 the end of a range without starting a new one. For example:
1101 if (i > 10 && j > i && j < 20) /* branch(27 50 75) */
1106 For a call return percentage, the value specified is the
1107 percentage of calls reported to return. For a branch percentage,
1108 the value is either the expected percentage or 100 minus that
1109 value, since the direction of a branch can differ depending on the
1110 target or the optimization level.
1112 Not all branches and calls need to be checked. A test should not
1113 check for branches that might be optimized away or replaced with
1114 predicated instructions. Don't check for calls inserted by the
1115 compiler or ones that might be inlined or optimized away.
1117 A single test can check for combinations of line counts, branch
1118 percentages, and call return percentages. The command to check a
1119 line count must appear on the line that will report that count, but
1120 commands to check branch percentages and call return percentages can
1121 bracket the lines that report them.
1123 @node profopt Testing
1124 @subsection Support for testing profile-directed optimizations
1126 The file @file{profopt.exp} provides language-independent support for
1127 checking correct execution of a test built with profile-directed
1128 optimization. This testing requires that a test program be built and
1129 executed twice. The first time it is compiled to generate profile
1130 data, and the second time it is compiled to use the data that was
1131 generated during the first execution. The second execution is to
1132 verify that the test produces the expected results.
1134 To check that the optimization actually generated better code, a
1135 test can be built and run a third time with normal optimizations to
1136 verify that the performance is better with the profile-directed
1137 optimizations. @file{profopt.exp} has the beginnings of this kind
1140 @file{profopt.exp} provides generic support for profile-directed
1141 optimizations. Each set of tests that uses it provides information
1142 about a specific optimization:
1146 tool being tested, e.g., @command{gcc}
1148 @item profile_option
1149 options used to generate profile data
1151 @item feedback_option
1152 options used to optimize using that profile data
1155 suffix of profile data files
1157 @item PROFOPT_OPTIONS
1158 list of options with which to run each test, similar to the lists for
1162 @node compat Testing
1163 @subsection Support for testing binary compatibility
1165 The file @file{compat.exp} provides language-independent support for
1166 binary compatibility testing. It supports testing interoperability
1167 of two compilers that follow the same ABI, or of multiple sets of
1168 compiler options that should not affect binary compatibility.
1169 It is intended to be used for test suites that complement ABI test
1172 A test supported by this framework has three parts, each in a
1173 separate source file: a main program and two pieces that interact
1174 with each other to split up the functionality being tested.
1177 @item @var{testname}_main.@var{suffix}
1178 Contains the main program, which calls a function in file
1179 @file{@var{testname}_x.@var{suffix}}.
1181 @item @var{testname}_x.@var{suffix}
1182 Contains at least one call to a function in
1183 @file{@var{testname}_y.@var{suffix}}.
1185 @item @var{testname}_y.@var{suffix}
1186 Shares data with, or gets arguments from,
1187 @file{@var{testname}_x.@var{suffix}}.
1190 Within each test, the main program and one functional piece are
1191 compiled by the GCC under test. The other piece can be compiled by
1192 an alternate compiler. If no alternate compiler is specified,
1193 then all three source files are all compiled by the GCC under test.
1194 It's also possible to specify a pair of lists of compiler options,
1195 one list for each compiler, so that each test will be compiled with
1196 each pair of options.
1198 @file{compat.exp} defines default pairs of compiler options.
1199 These can be overridden by defining the environment variable
1200 @env{COMPAT_OPTIONS} as:
1203 COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
1204 ...[list @{@var{tstn}@} @{@var{altn}@}]]"
1207 where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
1208 used by the compiler under test and @var{alti} used by the alternate
1209 compiler. For example, with
1210 @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
1211 the test is first built with @code{-g -O0} by the compiler under
1212 test and with @code{-O3} by the alternate compiler. The test is
1213 built a second time using @code{-fpic} by the compiler under test
1214 and @code{-fPIC -O2} by the alternate compiler.
1216 An alternate compiler is specified by defining an environment
1217 variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full
1218 pathname of an installed compiler. That will be written to the
1219 @file{site.exp} file used by DejaGNU. The default is to build each
1220 test with the compiler under test using the first of each pair of
1221 compiler options from @env{COMPAT_OPTIONS}. When
1222 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
1223 the compiler under test but with combinations of the options from
1224 @env{COMPAT_OPTIONS}.
1226 To run only the C++ compatibility suite using the compiler under test
1227 and another version of GCC using specific compiler options, do the
1228 following from @file{@var{objdir}/gcc}:
1233 ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
1234 COMPAT_OPTIONS="lists as shown above" \
1236 RUNTESTFLAGS="compat.exp"
1239 A test that fails when the source files are compiled with different
1240 compilers, but passes when the files are compiled with the same
1241 compiler, demonstrates incompatibility of the generated code or
1242 runtime support. A test that fails for the alternate compiler but
1243 passes for the compiler under test probably tests for a bug that was
1244 fixed in the compiler under test but is present in the alternate