1 @c Copyright (C) 2002 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 CHILL runtime library.
57 The Fortran runtime library.
60 The @code{libffi} library, used as part of the Java runtime library.
63 The @code{libibery} library, used for portability and for some
64 generally useful data structures and algorithms. @xref{Top, ,
65 Introduction, libiberty, @sc{gnu} libiberty}, for more information
69 The Java runtime library.
72 The Objective-C runtime library.
75 The C++ runtime library.
77 @item maintainer-scripts
78 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
81 The @code{zlib} compression library, used by the Java front end and as
82 part of the Java runtime library.
85 The build system in the top level directory, including how recursion
86 into subdirectories works and how building runtime libraries for
87 multilibs is handled, is documented in a separate manual, included
88 with GNU Binutils. @xref{Top, , GNU configure and build system,
89 configure, The GNU configure and build system}, for details.
92 @section The @file{gcc} Subdirectory
94 The @file{gcc} directory contains many files that are part of the C
95 sources of GCC, other files used as part of the configuration and
96 build process, and subdirectories including documentation and a
97 test suite. The files that are sources of GCC are documented in a
98 separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
101 * Subdirectories:: Subdirectories of @file{gcc}.
102 * Configuration:: The configuration process, and the files it uses.
103 * Build:: The build system in the @file{gcc} directory.
104 * Makefile:: Targets in @file{gcc/Makefile}.
105 * Library Files:: Library source files and headers under @file{gcc/}.
106 * Headers:: Headers installed by GCC.
107 * Documentation:: Building documentation in GCC.
108 * Front End:: Anatomy of a language front end.
109 * Back End:: Anatomy of a target back end.
113 @subsection Subdirectories of @file{gcc}
115 The @file{gcc} directory contains the following subdirectories:
119 Subdirectories for various languages. Directories containing a file
120 @file{config-lang.in} are language subdirectories. The contents of
121 the subdirectories @file{cp} (for C++) and @file{objc} (for
122 Objective-C) are documented in this manual (@pxref{Passes, , Passes
123 and Files of the Compiler}); those for other languages are not.
124 @xref{Front End, , Anatomy of a Language Front End}, for details of
125 the files in these directories.
128 Configuration files for supported architectures and operating
129 systems. @xref{Back End, , Anatomy of a Target Back End}, for
130 details of the files in thie directory.
133 Texinfo documentation for GCC, together with automatically generated
134 man pages and support for converting the installation manual to
135 HTML@. @xref{Documentation}.
138 The support for fixing system headers to work with GCC@. See
139 @file{fixinc/README} for more information. The headers fixed by this
140 mechanism are installed in @file{@var{libsubdir}/include}. Along with
141 those headers, @file{README-fixinc} is also installed, as
142 @file{@var{libsubdir}/include/README}.
145 System headers installed by GCC, mainly those required by the C
146 standard of freestanding implementations. @xref{Headers, , Headers
147 Installed by GCC}, for details of when these and other headers are
151 GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
152 include it in libc. Properly, this directory should be at top level,
153 parallel to the @file{gcc} directory.
156 Message catalogs with translations of messages produced by GCC into
157 various languages, @file{@var{language}.po}. This directory also
158 contains @file{gcc.pot}, the template for these message catalogues,
159 @file{exgettext}, a wrapper around @command{gettext} to extract the
160 messages from the GCC sources and create @file{gcc.pot}, which is run
161 by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
162 which messages should not be extracted.
165 The GCC test suites (except for those for runtime libraries).
170 @subsection Configuration in the @file{gcc} Directory
172 The @file{gcc} directory is configured with an Autoconf-generated
173 script @file{configure}. The @file{configure} script is generated
174 from @file{configure.in} and @file{aclocal.m4}. From the files
175 @file{configure.in} and @file{acconfig.h}, Autoheader generates the
176 file @file{config.in}. The file @file{cstamp-h.in} is used as a
180 * Config Fragments:: Scripts used by @file{configure}.
181 * System Config:: The @file{config.gcc} file.
182 * Configuration Files:: Files created by running @file{configure}.
185 @node Config Fragments
186 @subsubsection Scripts Used by @file{configure}
188 @file{configure} uses some other scripts to help in its work:
191 @item The standard GNU @file{config.sub} and @file{config.guess}
192 files, kept in the top level directory, are used. FIXME: when is the
193 @file{config.guess} file in the @file{gcc} directory (that just calls
194 the top level one) used?
196 @item The file @file{config.gcc} is used to handle configuration
197 specific to the particular build, host or target machine. (In
198 general, this should only be used for features that cannot reasonably
199 be tested in Autoconf feature tests.) @xref{System Config, , The
200 @file{config.gcc} File}, for details of the contents of this file.
202 @item Each language subdirectory has a file
203 @file{@var{language}/config-lang.in} that is used for
204 front-end-specific configuration. @xref{Front End Config, , The Front
205 End @file{config-lang.in} File}, for details of this file.
207 @item A helper script @file{configure.frag} is used as part of
208 creating the output of @file{configure}.
212 @subsubsection The @file{config.gcc} File
214 FIXME: document the contents of this file, and what variables should
215 be set to control build, host and target configuration.
217 @include configfiles.texi
220 @subsection Build System in the @file{gcc} Directory
222 FIXME: describe the build system, including what is built in what
223 stages. Also list the various source files that are used in the build
224 process but aren't source files of GCC itself and so aren't documented
225 below (@pxref{Passes}).
227 @include makefile.texi
230 @subsection Library Source Files and Headers under the @file{gcc} Directory
232 FIXME: list here, with explanation, all the C source files and headers
233 under the @file{gcc} directory that aren't built into the GCC
234 executable but rather are part of runtime libraries and object files,
235 such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
236 Headers Installed by GCC}, for more information about the
237 @file{ginclude} directory.
240 @subsection Headers Installed by GCC
242 In general, GCC expects the system C library to provide most of the
243 headers to be used with it. However, GCC will fix those headers if
244 necessary to make them work with GCC, and will install some headers
245 required of freestanding implementations. These headers are installed
246 in @file{@var{libsubdir}/include}. Headers for non-C runtime
247 libraries are also installed by GCC; these are not documented here.
248 (FIXME: document them somewhere.)
250 Several of the headers GCC installs are in the @file{ginclude}
251 directory. These headers, @file{iso646.h},
252 @file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and
253 @file{varargs.h}, are installed in @file{@var{libsubdir}/include},
254 unless the target Makefile fragment (@pxref{Target Fragment})
255 overrides this by setting @code{USER_H}.
257 In addition to these headers and those generated by fixing system
258 headers to work with GCC, some other headers may also be installed in
259 @file{@var{libsubdir}/include}. @file{config.gcc} may set
260 @code{extra_headers}; this specifies additional headers under
261 @file{config} to be installed on some systems. GCC normally installs
262 a @code{<float.h>} file; these are kept as
263 @file{config/float-@var{format}.h}, where @var{format} is specified by
264 a @code{float_format} setting in @file{config.gcc}, and a setting
265 @samp{float_format=none} disables installation of this header. GCC
266 also installs its own version of @code{<limits.h>}; this is generated
267 from @file{glimits.h}, together with @file{limitx.h} and
268 @file{limity.h} if the system also has its own version of
269 @code{<limits.h>}. (GCC provides its own header because it is
270 required of ISO C freestanding implementations, but needs to include
271 the system header from its own header as well because other standards
272 such as POSIX specify additional values to be defined in
273 @code{<limits.h>}.) The system's @code{<limits.h>} header is used via
274 @file{@var{libsubdir}/include/syslimits.h}, which is copied from
275 @file{gsyslimits.h} if it does not need fixing to work with GCC; if it
276 needs fixing, @file{syslimits.h} is the fixed copy.
279 @subsection Building Documentation
281 The main GCC documentation is in the form of manuals in Texinfo
282 format. These are installed in Info format, and DVI versions may be
283 generated by @command{make dvi}. In addition, some man pages are
284 generated from the Texinfo manuals, there are some other text files
285 with miscellaneous documentation, and runtime libraries have their own
286 documentation outside the @file{gcc} directory. FIXME: document the
287 documentation for runtime libraries somewhere.
290 * Texinfo Manuals:: GCC manuals in Texinfo format.
291 * Man Page Generation:: Generating man pages from Texinfo manuals.
292 * Miscellaneous Docs:: Miscellaneous text files with documentation.
295 @node Texinfo Manuals
296 @subsubsection Texinfo Manuals
298 The manuals for GCC as a whole, and the C and C++ front ends, are in
299 files @file{doc/*.texi}. Other front ends have their own manuals in
300 files @file{@var{language}/*.texi}. Common files
301 @file{doc/include/*.texi} are provided which may be included in
302 multiple manuals; the following files are in @file{doc/include}:
306 The GNU Free Documentation License.
308 The section ``Funding Free Software''.
309 @item gcc-common.texi
310 Common definitions for manuals.
312 The GNU General Public License.
314 A copy of @file{texinfo.tex} known to work with the GCC manuals.
317 DVI formatted manuals are generated by @command{make dvi}, which uses
318 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
319 manuals are generated by @command{make info} (which is run as part of
320 a bootstrap); this generates the manuals in the source directory,
321 using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
322 and they are included in release distributions.
324 Manuals are also provided on the GCC web site, in both HTML and
325 PostScript forms. This is done via the script
326 @file{maintainer-scripts/update_web_docs}. Each manual to be
327 provided online must be listed in the definition of @code{MANUALS} in
328 that file; a file @file{@var{name}.texi} must only appear once in the
329 source tree, and the output manual must have the same name as the
330 source file. (However, other Texinfo files, included in manuals but
331 not themselves the root files of manuals, may have names that appear
332 more than once in the source tree.) The manual file
333 @file{@var{name}.texi} should only include other files in its own
334 directory or in @file{doc/include}. HTML manuals will be generated by
335 @command{makeinfo --html} and PostScript manuals by @command{texi2dvi}
336 and @command{dvips}. All Texinfo files that are parts of manuals must
337 be checked into CVS, even if they are generated files, for the
338 generation of online manuals to work.
340 The installation manual, @file{doc/install.texi}, is also provided on
341 the GCC web site. The HTML version is generated by the script
342 @file{doc/install.texi2html}.
344 @node Man Page Generation
345 @subsubsection Man Page Generation
347 Because of user demand, in addition to full Texinfo manuals, man pages
348 are provided which contain extracts from those manuals. These man
349 pages are generated from the Texinfo manuals using
350 @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
351 @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
352 to @file{gcc.1}, but all the other man pages are generated from
355 Because many systems may not have the necessary tools installed to
356 generate the man pages, they are only generated if the
357 @file{configure} script detects that recent enough tools are
358 installed, and the Makefiles allow generating man pages to fail
359 without aborting the build. Man pages are also included in release
360 distributions. They are generated in the source directory.
362 Magic comments in Texinfo files starting @samp{@@c man} control what
363 parts of a Texinfo file go into a man page. Only a subset of Texinfo
364 is supported by @file{texi2pod.pl}, and it may be necessary to add
365 support for more Texinfo features to this script when generating new
366 man pages. To improve the man page output, some special Texinfo
367 macros are provided in @file{doc/include/gcc-common.texi} which
368 @file{texi2pod.pl} understands:
372 Use in the form @samp{@@table @@gcctabopt} for tables of options,
373 where for printed output the effect of @samp{@@code} is better than
374 that of @samp{@@option} but for man page output a different effect is
377 Use for summary lists of options in manuals.
379 Use at the end of each line inside @samp{@@gccoptlist}. This is
380 necessary to avoid problems with differences in how the
381 @samp{@@gccoptlist} macro is handled by different Texinfo formatters.
384 FIXME: describe the @file{texi2pod.pl} input language and magic
385 comments in more detail.
387 @node Miscellaneous Docs
388 @subsubsection Miscellaneous Documentation
390 In addition to the formal documentation that is installed by GCC,
391 there are several other text files with miscellaneous documentation:
395 Notes on GCC's Native Language Support. FIXME: this should be part of
396 this manual rather than a separate file.
398 Notes on the Free Translation Project.
400 The GNU General Public License.
402 The GNU Lesser General Public License.
405 Change log files for various parts of GCC@.
407 Details of a few changes to the GCC front-end interface. FIXME: the
408 information in this file should be part of general documentation of
409 the front-end interface in this manual.
411 Information about new features in old versions of GCC@. (For recent
412 versions, the information is on the GCC web site.)
413 @item README.Portability
414 Information about portability issues when writing code in GCC@. FIXME:
415 why isn't this part of this manual or of the GCC Coding Conventions?
417 A pointer to the GNU Service Directory.
420 FIXME: document such files in subdirectories, at least @file{config},
421 @file{cp}, @file{objc}, @file{testsuite}.
424 @subsection Anatomy of a Language Front End
426 A front end for a language in GCC has the following parts:
430 A directory @file{@var{language}} under @file{gcc} containing source
431 files for that front end. @xref{Front End Directory, , The Front End
432 @file{@var{language}} Directory}, for details.
434 A mention of the language in the list of supported languages in
435 @file{gcc/doc/install.texi}.
437 Details of contributors to that front end in
438 @file{gcc/doc/contrib.texi}. If the details are in that front end's
439 own manual then there should be a link to that manual's list in
442 Information about support for that language in
443 @file{gcc/doc/frontends.texi}.
445 Information about standards for that language, and the front end's
446 support for them, in @file{gcc/doc/standards.texi}. This may be a
447 link to such information in the front end's own manual.
449 Details of source file suffixes for that language and @option{-x
450 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
452 Entries in @code{default_compilers} in @file{gcc.c} for source file
453 suffixes for that language.
455 Preferably test suites, which may be under @file{gcc/testsuite} or
456 runtime library directories. FIXME: document somewhere how to write
457 test suite harnesses.
459 Probably a runtime library for the language, outside the @file{gcc}
460 directory. FIXME: document this further.
462 Details of the directories of any runtime libraries in
463 @file{gcc/doc/sourcebuild.texi}.
466 If the front end is added to the official GCC CVS repository, the
467 following are also necessary:
471 At least one GNATS category for bugs in that front end and runtime
472 libraries. This category needs to be mentioned in
473 @file{gcc/gccbug.in}, and in @file{gnats.html} on the GCC web site, as
474 well as being added to the GNATS database.
476 Normally, one or more maintainers of that front end listed in
479 Mentions on the GCC web site in @file{index.html} and
480 @file{frontends.html}, with any relevant links on
481 @file{readings.html}. (Front ends that are not an official part of
482 GCC may also be listed on @file{frontends.html}, with relevant links.)
484 A news item on @file{index.html}, and possibly an announcement on the
485 @email{gcc-announce@@gcc.gnu.org} mailing list.
487 The front end's manuals should be mentioned in
488 @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
489 and the online manuals should be linked to from
490 @file{onlinedocs/index.html}.
492 Any old releases or CVS repositories of the front end, before its
493 inclusion in GCC, should be made available on the GCC FTP site
494 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
496 The release and snapshot script @file{maintainer-scripts/gcc_release}
497 should be updated to generate appropriate tarballs for this front end.
499 If this front end includes its own version files that include the
500 current date, @file{maintainer-scripts/update_version} should be
503 @file{CVSROOT/modules} in the GCC CVS repository should be updated.
507 * Front End Directory:: The front end @file{@var{language}} directory.
508 * Front End Config:: The front end @file{config-lang.in} file.
511 @node Front End Directory
512 @subsubsection The Front End @file{@var{language}} Directory
514 A front end @file{@var{language}} directory contains the source files
515 of that front end (but not of any runtime libraries, which should be
516 outside the @file{gcc} directory). This includes documentation, and
517 possibly some subsidiary programs build alongside the front end.
518 Certain files are special and other parts of the compiler depend on
523 This file is required in all language subdirectories. @xref{Front End
524 Config, , The Front End @file{config-lang.in} File}, for details of
527 This file is required in all language subdirectories. It contains
528 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
529 setting of @code{language} in @file{config-lang.in}) for the following
530 values of @code{@var{hook}}, and any other Makefile rules required to
531 build those targets (which may if necessary use other Makefiles
532 specified in @code{outputs} in @file{config-lang.in}, although this is
540 FIXME: exactly what goes in each of these targets?
542 Build info documentation for the front end, in the source directory.
543 This target is only called by @command{make bootstrap} if a suitable
544 version of @command{makeinfo} is available, so does not need to check
545 for this, and should fail if an error occurs.
547 Build DVI documentation for the front end, in the build directory.
548 This should be done using @code{$(TEXI2DVI)}, with appropriate
549 @option{-I} arguments pointing to directories of included files.
550 @item generated-manpages
551 Build generated man pages for the front end from Texinfo manuals
552 (@pxref{Man Page Generation}), in the source directory. This target
553 is only called if the necessary tools are available, but should ignore
554 errors so as not to stop the build if errors occur; man pages are
555 optional and the tools involved may be installed in a broken way.
557 FIXME: what is this target for?
559 Install everything that is part of the front end, apart from the
560 compiler executables listed in @code{compilers} in
561 @file{config-lang.in} that are installed in @file{@var{libsubdir}} by
562 the main @file{Makefile}.
564 Install info documentation for the front end, if it is present in the
565 source directory. (It may not be present if a suitable version of
566 @command{makeinfo} was not installed.) This target should run the
567 command @command{install-info} to update the info directory, but
568 should ignore errors when running that command.
570 Install man pages for the front end. This target should ignore
573 Uninstall files installed by installing the compiler. This is
574 currently documented not to be supported, so the hook need not do
580 @itemx maintainer-clean
581 Except for @code{extraclean}, the language parts of the standard GNU
582 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
583 Users, standards, GNU Coding Standards}, for details of the standard
584 targets. @code{extraclean} does @code{distclean} and also deletes
585 anything likely to be found in the source directory that shouldn't be
586 in the distribution. For GCC, @code{maintainer-clean} should delete
587 all generated files in the source directory that are not checked into
588 CVS, but should not delete anything checked into CVS@.
593 Move to the stage directory files not included in @code{stagestuff} in
594 @file{config-lang.in} or otherwise moved by the main @file{Makefile}.
598 This file provides entries for @code{documented_lang_options} in
599 @file{toplev.c} describing command-line options the front end accepts
600 for @option{--help} output.
602 This file provides entries for @code{default_compilers} in
603 @file{gcc.c} which override the default of giving an error that a
604 compiler for that language is not installed.
605 @item @var{language}-tree.def
606 This file, which need not exist, defines any language-specific tree
610 @node Front End Config
611 @subsubsection The Front End @file{config-lang.in} File
613 Each language subdirectory contains a @file{config-lang.in} file.
614 This file is a shell script that may define some variables describing
619 This definition must be present, and gives the name of the language
620 for some purposes such as arguments to @option{--enable-languages}.
622 If defined, this variable lists (space-separated) language front ends
623 other than C that this front end requires to be enabled (with the
624 names given being their @code{language} settings). For example, the
625 Java front end depends on the C++ front end, so sets
626 @samp{lang_requires=c++}.
628 If defined, this variable lists (space-separated) targets in the top
629 level @file{Makefile} to build the runtime libraries for this
630 language, such as @code{target-libobjc}.
632 If defined, this variable lists (space-separated) top level
633 directories (parallel to @file{gcc}), apart from the runtime libraries,
634 that should not be configured if this front end is not built.
635 @item build_by_default
636 If defined to @samp{no}, this language front end is not built unless
637 enabled in a @option{--enable-languages} argument. Otherwise, front
638 ends are built by default, subject to any special logic in
639 @file{configure.in} (as is present to disable the Ada front end if the
640 Ada compiler is not already installed).
642 If defined to @samp{yes}, this front end is built in stage 1 of the
643 bootstrap. This is only relevant to front ends written in their own
646 If defined, a space-separated list of compiler executables that should
647 be installed in @file{@var{libsubdir}}. The names here will each end
648 with @samp{\$(exeext)}.
650 If defined, a space-separated list of files that should be moved to
651 the @file{stage@var{n}} directories in each stage of bootstrap.
653 If defined, a space-separated list of files that should be generated
654 by @file{configure} substituting values in them. This mechanism can
655 be used to create a file @file{@var{language}/Makefile} from
656 @file{@var{language}/Makefile.in}, but this is deprecated, building
657 everything from the single @file{gcc/Makefile} is preferred.
661 @subsection Anatomy of a Target Back End
663 A back end for a target architecture in GCC has the following parts:
667 A directory @file{@var{machine}} under @file{gcc/config}, containing a
668 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
669 , Machine Descriptions}), header files @file{@var{machine}.h} and
670 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
671 (@pxref{Target Macros, , Target Description Macros and Functions}),
672 possibly a target Makefile fragment @file{t-@var{machine}}
673 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
674 some other files. The names of these files may be changed from the
675 defaults given by explicit specifications in @file{config.gcc}.
677 Entries in @file{config.gcc} (@pxref{System Config, , The
678 @file{config.gcc} File}) for the systems with this target
681 Documentation in @file{gcc/doc/invoke.texi} for any command-line
682 options supported by this target (@pxref{Run-time Target, , Run-time
683 Target Specification}). This means both entries in the summary table
684 of options and details of the individual options.
686 Documentation in @file{gcc/doc/extend.texi} for any target-specific
687 attributes supported (@pxref{Target Attributes, , Defining
688 target-specific uses of @code{__attribute__}}), including where the
689 same attribute is already supported on some targets, which are
690 enumerated in the manual.
692 Documentation in @file{gcc/doc/extend.texi} for any target-specific
695 Documentation in @file{gcc/doc/extend.texi} of any target-specific
696 built-in functions supported.
698 Documentation in @file{gcc/doc/md.texi} of any target-specific
699 constraint letters (@pxref{Machine Constraints, , Constraints for
700 Particular Machines}).
702 A note in @file{gcc/doc/contrib.texi} under the person or people who
703 contributed the target support.
705 Entries in @file{gcc/doc/install.texi} for all target triplets
706 supported with this target architecture, giving details of any special
707 notes about installation for this target, or saying that there are no
708 special notes if there are none.
710 Possibly other support outside the @file{gcc} directory for runtime
711 libraries. FIXME: reference docs for this. The libstdc++ porting
712 manual needs to be installed as info for this to work, or to be a
713 chapter of this manual.
716 If the back end is added to the official GCC CVS repository, the
717 following are also necessary:
721 An entry for the target architecture in @file{readings.html} on the
722 GCC web site, with any relevant links.
724 A news item about the contribution of support for that target
725 architecture, in @file{index.html} on the GCC web site.
727 Normally, one or more maintainers of that target listed in
728 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
729 but it would be unusual to add support for a target that does not have
730 a maintainer when support is added.
736 GCC contains several test suites to help maintain compiler quality.
737 Most of the runtime libraries and language front ends in GCC have test
738 suites. Currently only the C language test suites are documented
739 here; FIXME: document the others.
742 * Test Idioms:: Idioms used in test suite code.
743 * C Tests:: The C language test suites.
747 @subsection Idioms Used in Test Suite Code
749 In the @file{gcc.c-torture} test suites, test cases are commonly named
750 after the date on which they were added. This allows people to tell
751 at a glance whether a test failure is because of a recently found bug
752 that has not yet been fixed, or whether it may be a regression. In
753 other test suites, more descriptive names are used. In general C test
754 cases have a trailing @file{-@var{n}.c}, starting with @file{-1.c}, in
755 case other test cases with similar names are added later.
757 Test cases should use @code{abort ()} to indicate failure and
758 @code{exit (0)} for success; on some targets these may be redefined to
759 indicate failure and success in other ways.
761 In the @file{gcc.dg} test suite, it is often necessary to test that an
762 error is indeed a hard error and not just a warning---for example,
763 where it is a constraint violation in the C standard, which must
764 become an error with @option{-pedantic-errors}. The following idiom,
765 where the first line shown is line @var{line} of the file and the line
766 that generates the error, is used for this:
769 /* @{ dg-bogus "warning" "warning in place of error" @} */
770 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
773 It may be necessary to check that an expression is an integer constant
774 expression and has a certain value. To check that @code{@var{E}} has
775 value @code{@var{V}}, an idiom similar to the following is used:
778 char x[((E) == (V) ? 1 : -1)];
781 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
782 assertions about the types of expressions. See, for example,
783 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
784 exact rules for the types of conditional expressions in the C
785 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
787 It is useful to be able to test that optimizations are being made
788 properly. This cannot be done in all cases, but it can be done where
789 the optimization will lead to code being optimized away (for example,
790 where flow analysis or alias analysis should show that certain code
791 cannot be called) or to functions not being called because they have
792 been expanded as built-in functions. Such tests go in
793 @file{gcc.c-torture/execute}. Where code should be optimized away, a
794 call to a nonexistent function such as @code{link_failure ()} may be
795 inserted; a definition
808 will also be needed so that linking still succeeds when the test is
809 run without optimization. When all calls to a built-in function
810 should have been optimized and no calls to the non-built-in version of
811 the function should remain, that function may be defined as
812 @code{static} to call @code{abort ()} (although redeclaring a function
813 as static may not work on all targets).
815 FIXME: discuss non-C test suites here.
818 @subsection C Language Test Suites
820 GCC contains the following C language test suites, in the
821 @file{gcc/testsuite} directory:
824 @item gcc.c-torture/compat
825 FIXME: describe this.
827 This directory should probably not be used for new tests.
828 @item gcc.c-torture/compile
829 This test suite contains test cases that should compile, but do not
830 need to link or run. These test cases are compiled with several
831 different combinations of optimization options. All warnings are
832 disabled for these test cases, so this directory is not suitable if
833 you wish to test for the presence or absence of compiler warnings.
834 While special options can be set, and tests disabled on specific
835 platforms, by the use of @file{.x} files, mostly these test cases
836 should not contain platform dependencies. FIXME: discuss how defines
837 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
838 @item gcc.c-torture/execute
839 This test suite contains test cases that should compile, link and run;
840 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
841 @item gcc.c-torture/unsorted
842 FIXME: describe this.
844 This directory should probably not be used for new tests.
846 This test suite contains tests using the more modern @samp{dg}
847 harness. Magic comments determine whether the file is preprocessed,
848 compiled, linked or run. In these tests, error and warning message
849 texts are compared against expected texts or regular expressions given
850 in comments. These tests are run with the options @samp{-ansi
851 -pedantic} unless other options are given in the test. Except for the
852 @file{noncompile} subdirectory, they are not run with multiple
853 optimization options.
855 This subdirectory contains tests of the preprocessor.
857 This subdirectory contains tests of the @option{-Wformat} format
858 checking. Tests in this directory are run with and without
860 @item gcc.dg/noncompile
861 This subdirectory contains tests of code that should not compile and
862 does not need any special compilation options. They are run with
863 multiple optimization options, since sometimes invalid code crashes
864 the compiler with optimization.
866 FIXME: describe this.
867 @item gcc.c-torture/misc-tests
868 FIXME: describe this, when it should be used for new tests and when it
872 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
873 test cases and magic comments more.