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 Fortran runtime library.
57 The @code{libffi} library, used as part of the Java runtime library.
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
66 The Java runtime library.
69 The Objective-C runtime library.
72 The C++ runtime library.
74 @item maintainer-scripts
75 Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
78 The @code{zlib} compression library, used by the Java front end and as
79 part of the Java runtime library.
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.
89 @section The @file{gcc} Subdirectory
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}.
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.
110 @subsection Subdirectories of @file{gcc}
112 The @file{gcc} directory contains the following subdirectories:
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.
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.
130 Texinfo documentation for GCC, together with automatically generated
131 man pages and support for converting the installation manual to
132 HTML@. @xref{Documentation}.
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}.
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
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.
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 @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
159 which messages should not be extracted.
162 The GCC test suites (except for those for runtime libraries).
167 @subsection Configuration in the @file{gcc} Directory
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
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}.
182 @node Config Fragments
183 @subsubsection Scripts Used by @file{configure}
185 @file{configure} uses some other scripts to help in its work:
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?
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.
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.
204 @item A helper script @file{configure.frag} is used as part of
205 creating the output of @file{configure}.
209 @subsubsection The @file{config.gcc} File
211 FIXME: document the contents of this file, and what variables should
212 be set to control build, host and target configuration.
214 @include configfiles.texi
217 @subsection Build System in the @file{gcc} Directory
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}).
224 @include makefile.texi
227 @subsection Library Source Files and Headers under the @file{gcc} Directory
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.
237 @subsection Headers Installed by GCC
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.)
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}.
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.
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.
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.
277 @subsection Building Documentation
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 @command{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.
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.
293 @node Texinfo Manuals
294 @subsubsection Texinfo Manuals
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}:
304 The GNU Free Documentation License.
306 The section ``Funding Free Software''.
307 @item gcc-common.texi
308 Common definitions for manuals.
310 The GNU General Public License.
312 A copy of @file{texinfo.tex} known to work with the GCC manuals.
315 DVI formatted manuals are generated by @command{make dvi}, which uses
316 @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
317 manuals are generated by @command{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.
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 @command{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.
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}.
342 @node Man Page Generation
343 @subsubsection Man Page Generation
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
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.
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:
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
375 Use for summary lists of options in manuals.
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.
382 FIXME: describe the @file{texi2pod.pl} input language and magic
383 comments in more detail.
385 @node Miscellaneous Docs
386 @subsubsection Miscellaneous Documentation
388 In addition to the formal documentation that is installed by GCC,
389 there are several other text files with miscellaneous documentation:
393 Notes on GCC's Native Language Support. FIXME: this should be part of
394 this manual rather than a separate file.
396 Notes on the Free Translation Project.
398 The GNU General Public License.
400 The GNU Lesser General Public License.
403 Change log files for various parts of GCC@.
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.
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?
415 A pointer to the GNU Service Directory.
418 FIXME: document such files in subdirectories, at least @file{config},
419 @file{cp}, @file{objc}, @file{testsuite}.
422 @subsection Anatomy of a Language Front End
424 A front end for a language in GCC has the following parts:
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.
432 A mention of the language in the list of supported languages in
433 @file{gcc/doc/install.texi}.
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
440 Information about support for that language in
441 @file{gcc/doc/frontends.texi}.
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.
447 Details of source file suffixes for that language and @option{-x
448 @var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
450 Entries in @code{default_compilers} in @file{gcc.c} for source file
451 suffixes for that language.
453 Preferably test suites, which may be under @file{gcc/testsuite} or
454 runtime library directories. FIXME: document somewhere how to write
455 test suite harnesses.
457 Probably a runtime library for the language, outside the @file{gcc}
458 directory. FIXME: document this further.
460 Details of the directories of any runtime libraries in
461 @file{gcc/doc/sourcebuild.texi}.
464 If the front end is added to the official GCC CVS repository, the
465 following are also necessary:
469 At least one GNATS category for bugs in that front end and runtime
470 libraries. This category needs to be mentioned in
471 @file{gcc/gccbug.in}, and in @file{gnats.html} on the GCC web site, as
472 well as being added to the GNATS database.
474 Normally, one or more maintainers of that front end listed in
477 Mentions on the GCC web site in @file{index.html} and
478 @file{frontends.html}, with any relevant links on
479 @file{readings.html}. (Front ends that are not an official part of
480 GCC may also be listed on @file{frontends.html}, with relevant links.)
482 A news item on @file{index.html}, and possibly an announcement on the
483 @email{gcc-announce@@gcc.gnu.org} mailing list.
485 The front end's manuals should be mentioned in
486 @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
487 and the online manuals should be linked to from
488 @file{onlinedocs/index.html}.
490 Any old releases or CVS repositories of the front end, before its
491 inclusion in GCC, should be made available on the GCC FTP site
492 @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
494 The release and snapshot script @file{maintainer-scripts/gcc_release}
495 should be updated to generate appropriate tarballs for this front end.
496 The associated @file{maintainer-scripts/snapshot-README} and
497 @file{maintainer-scripts/snapshot-index.html} files should be updated
498 to list the tarballs and diffs for this front end.
500 If this front end includes its own version files that include the
501 current date, @file{maintainer-scripts/update_version} should be
504 @file{CVSROOT/modules} in the GCC CVS repository should be updated.
508 * Front End Directory:: The front end @file{@var{language}} directory.
509 * Front End Config:: The front end @file{config-lang.in} file.
512 @node Front End Directory
513 @subsubsection The Front End @file{@var{language}} Directory
515 A front end @file{@var{language}} directory contains the source files
516 of that front end (but not of any runtime libraries, which should be
517 outside the @file{gcc} directory). This includes documentation, and
518 possibly some subsidiary programs build alongside the front end.
519 Certain files are special and other parts of the compiler depend on
524 This file is required in all language subdirectories. @xref{Front End
525 Config, , The Front End @file{config-lang.in} File}, for details of
528 This file is required in all language subdirectories. It contains
529 targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
530 setting of @code{language} in @file{config-lang.in}) for the following
531 values of @code{@var{hook}}, and any other Makefile rules required to
532 build those targets (which may if necessary use other Makefiles
533 specified in @code{outputs} in @file{config-lang.in}, although this is
541 FIXME: exactly what goes in each of these targets?
543 Build info documentation for the front end, in the source directory.
544 This target is only called by @command{make bootstrap} if a suitable
545 version of @command{makeinfo} is available, so does not need to check
546 for this, and should fail if an error occurs.
548 Build DVI documentation for the front end, in the build directory.
549 This should be done using @code{$(TEXI2DVI)}, with appropriate
550 @option{-I} arguments pointing to directories of included files.
551 @item generated-manpages
552 Build generated man pages for the front end from Texinfo manuals
553 (@pxref{Man Page Generation}), in the source directory. This target
554 is only called if the necessary tools are available, but should ignore
555 errors so as not to stop the build if errors occur; man pages are
556 optional and the tools involved may be installed in a broken way.
558 FIXME: what is this target for?
560 Install everything that is part of the front end, apart from the
561 compiler executables listed in @code{compilers} in
562 @file{config-lang.in} that are installed in @file{@var{libsubdir}} by
563 the main @file{Makefile}.
565 Install info documentation for the front end, if it is present in the
566 source directory. (It may not be present if a suitable version of
567 @command{makeinfo} was not installed.) This target should run the
568 command @command{install-info} to update the info directory, but
569 should ignore errors when running that command.
571 Install man pages for the front end. This target should ignore
574 Uninstall files installed by installing the compiler. This is
575 currently documented not to be supported, so the hook need not do
581 @itemx maintainer-clean
582 Except for @code{extraclean}, the language parts of the standard GNU
583 @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
584 Users, standards, GNU Coding Standards}, for details of the standard
585 targets. @code{extraclean} does @code{distclean} and also deletes
586 anything likely to be found in the source directory that shouldn't be
587 in the distribution. For GCC, @code{maintainer-clean} should delete
588 all generated files in the source directory that are not checked into
589 CVS, but should not delete anything checked into CVS@.
594 Move to the stage directory files not included in @code{stagestuff} in
595 @file{config-lang.in} or otherwise moved by the main @file{Makefile}.
599 This file provides entries for @code{documented_lang_options} in
600 @file{toplev.c} describing command-line options the front end accepts
601 for @option{--help} output.
603 This file provides entries for @code{default_compilers} in
604 @file{gcc.c} which override the default of giving an error that a
605 compiler for that language is not installed.
606 @item @var{language}-tree.def
607 This file, which need not exist, defines any language-specific tree
611 @node Front End Config
612 @subsubsection The Front End @file{config-lang.in} File
614 Each language subdirectory contains a @file{config-lang.in} file. In
615 addition the main directory contains @file{c-config-lang.in}, which
616 contains limited information for the C language. This file is a shell
617 script that may define some variables describing the language:
621 This definition must be present, and gives the name of the language
622 for some purposes such as arguments to @option{--enable-languages}.
624 If defined, this variable lists (space-separated) language front ends
625 other than C that this front end requires to be enabled (with the
626 names given being their @code{language} settings). For example, the
627 Java front end depends on the C++ front end, so sets
628 @samp{lang_requires=c++}.
630 If defined, this variable lists (space-separated) targets in the top
631 level @file{Makefile} to build the runtime libraries for this
632 language, such as @code{target-libobjc}.
634 If defined, this variable lists (space-separated) top level
635 directories (parallel to @file{gcc}), apart from the runtime libraries,
636 that should not be configured if this front end is not built.
637 @item build_by_default
638 If defined to @samp{no}, this language front end is not built unless
639 enabled in a @option{--enable-languages} argument. Otherwise, front
640 ends are built by default, subject to any special logic in
641 @file{configure.in} (as is present to disable the Ada front end if the
642 Ada compiler is not already installed).
644 If defined to @samp{yes}, this front end is built in stage 1 of the
645 bootstrap. This is only relevant to front ends written in their own
648 If defined, a space-separated list of compiler executables that should
649 be installed in @file{@var{libsubdir}}. The names here will each end
650 with @samp{\$(exeext)}.
652 If defined, a space-separated list of files that should be moved to
653 the @file{stage@var{n}} directories in each stage of bootstrap.
655 If defined, a space-separated list of files that should be generated
656 by @file{configure} substituting values in them. This mechanism can
657 be used to create a file @file{@var{language}/Makefile} from
658 @file{@var{language}/Makefile.in}, but this is deprecated, building
659 everything from the single @file{gcc/Makefile} is preferred.
661 If defined, a space-separated list of files that should be scanned by
662 gengtype.c to generate the garbage collection tables and routines for
663 this language. This excludes the files that are common to all front
664 ends. @xref{Type Information}.
669 @subsection Anatomy of a Target Back End
671 A back end for a target architecture in GCC has the following parts:
675 A directory @file{@var{machine}} under @file{gcc/config}, containing a
676 machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
677 , Machine Descriptions}), header files @file{@var{machine}.h} and
678 @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
679 (@pxref{Target Macros, , Target Description Macros and Functions}),
680 possibly a target Makefile fragment @file{t-@var{machine}}
681 (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
682 some other files. The names of these files may be changed from the
683 defaults given by explicit specifications in @file{config.gcc}.
685 If necessary, a file @file{@var{machine}-modes.def} in the
686 @file{@var{machine}} directory, containing additional machine modes to
687 represent condition codes. @xref{Condition Code}, for further details.
689 Entries in @file{config.gcc} (@pxref{System Config, , The
690 @file{config.gcc} File}) for the systems with this target
693 Documentation in @file{gcc/doc/invoke.texi} for any command-line
694 options supported by this target (@pxref{Run-time Target, , Run-time
695 Target Specification}). This means both entries in the summary table
696 of options and details of the individual options.
698 Documentation in @file{gcc/doc/extend.texi} for any target-specific
699 attributes supported (@pxref{Target Attributes, , Defining
700 target-specific uses of @code{__attribute__}}), including where the
701 same attribute is already supported on some targets, which are
702 enumerated in the manual.
704 Documentation in @file{gcc/doc/extend.texi} for any target-specific
707 Documentation in @file{gcc/doc/extend.texi} of any target-specific
708 built-in functions supported.
710 Documentation in @file{gcc/doc/md.texi} of any target-specific
711 constraint letters (@pxref{Machine Constraints, , Constraints for
712 Particular Machines}).
714 A note in @file{gcc/doc/contrib.texi} under the person or people who
715 contributed the target support.
717 Entries in @file{gcc/doc/install.texi} for all target triplets
718 supported with this target architecture, giving details of any special
719 notes about installation for this target, or saying that there are no
720 special notes if there are none.
722 Possibly other support outside the @file{gcc} directory for runtime
723 libraries. FIXME: reference docs for this. The libstdc++ porting
724 manual needs to be installed as info for this to work, or to be a
725 chapter of this manual.
728 If the back end is added to the official GCC CVS repository, the
729 following are also necessary:
733 An entry for the target architecture in @file{readings.html} on the
734 GCC web site, with any relevant links.
736 A news item about the contribution of support for that target
737 architecture, in @file{index.html} on the GCC web site.
739 Normally, one or more maintainers of that target listed in
740 @file{MAINTAINERS}. Some existing architectures may be unmaintained,
741 but it would be unusual to add support for a target that does not have
742 a maintainer when support is added.
748 GCC contains several test suites to help maintain compiler quality.
749 Most of the runtime libraries and language front ends in GCC have test
750 suites. Currently only the C language test suites are documented
751 here; FIXME: document the others.
754 * Test Idioms:: Idioms used in test suite code.
755 * C Tests:: The C language test suites.
756 * libgcj Tests:: The Java library test suites.
760 @subsection Idioms Used in Test Suite Code
762 In the @file{gcc.c-torture} test suites, test cases are commonly named
763 after the date on which they were added. This allows people to tell
764 at a glance whether a test failure is because of a recently found bug
765 that has not yet been fixed, or whether it may be a regression. In
766 other test suites, more descriptive names are used. In general C test
767 cases have a trailing @file{-@var{n}.c}, starting with @file{-1.c}, in
768 case other test cases with similar names are added later.
770 Test cases should use @code{abort ()} to indicate failure and
771 @code{exit (0)} for success; on some targets these may be redefined to
772 indicate failure and success in other ways.
774 In the @file{gcc.dg} test suite, it is often necessary to test that an
775 error is indeed a hard error and not just a warning---for example,
776 where it is a constraint violation in the C standard, which must
777 become an error with @option{-pedantic-errors}. The following idiom,
778 where the first line shown is line @var{line} of the file and the line
779 that generates the error, is used for this:
782 /* @{ dg-bogus "warning" "warning in place of error" @} */
783 /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
786 It may be necessary to check that an expression is an integer constant
787 expression and has a certain value. To check that @code{@var{E}} has
788 value @code{@var{V}}, an idiom similar to the following is used:
791 char x[((E) == (V) ? 1 : -1)];
794 In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
795 assertions about the types of expressions. See, for example,
796 @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the
797 exact rules for the types of conditional expressions in the C
798 standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.
800 It is useful to be able to test that optimizations are being made
801 properly. This cannot be done in all cases, but it can be done where
802 the optimization will lead to code being optimized away (for example,
803 where flow analysis or alias analysis should show that certain code
804 cannot be called) or to functions not being called because they have
805 been expanded as built-in functions. Such tests go in
806 @file{gcc.c-torture/execute}. Where code should be optimized away, a
807 call to a nonexistent function such as @code{link_failure ()} may be
808 inserted; a definition
821 will also be needed so that linking still succeeds when the test is
822 run without optimization. When all calls to a built-in function
823 should have been optimized and no calls to the non-built-in version of
824 the function should remain, that function may be defined as
825 @code{static} to call @code{abort ()} (although redeclaring a function
826 as static may not work on all targets).
828 All testcases must be portable. Target-specific testcases must have
829 appropriate code to avoid causing failures on unsupported systems;
830 unfortunately, the mechanisms for this differ by directory.
832 FIXME: discuss non-C test suites here.
835 @subsection C Language Test Suites
837 GCC contains the following C language test suites, in the
838 @file{gcc/testsuite} directory:
842 This contains tests of particular features of the C compiler, using the
843 more modern @samp{dg} harness. Correctness tests for various compiler
844 features should go here if possible.
846 Magic comments determine whether the file
847 is preprocessed, compiled, linked or run. In these tests, error and warning
848 message texts are compared against expected texts or regular expressions
849 given in comments. These tests are run with the options @samp{-ansi -pedantic}
850 unless other options are given in the test. Except as noted below they
851 are not run with multiple optimization options.
853 This subdirectory contains tests of the preprocessor.
855 This subdirectory contains tests for debug formats. Tests in this
856 subdirectory are run for each debug format that the compiler supports.
858 This subdirectory contains tests of the @option{-Wformat} format
859 checking. Tests in this directory are run with and without
861 @item gcc.dg/noncompile
862 This subdirectory contains tests of code that should not compile and
863 does not need any special compilation options. They are run with
864 multiple optimization options, since sometimes invalid code crashes
865 the compiler with optimization.
867 FIXME: describe this.
870 This contains particular code fragments which have historically broken easily.
871 These tests are run with multiple optimization options, so tests for features
872 which only break at some optimization levels belong here. This also contains
873 tests to check that certain optimizations occur. It might be worthwhile to
874 separate the correctness tests cleanly from the code quality tests, but
875 it hasn't been done yet.
877 @item gcc.c-torture/compat
878 FIXME: describe this.
880 This directory should probably not be used for new tests.
881 @item gcc.c-torture/compile
882 This test suite contains test cases that should compile, but do not
883 need to link or run. These test cases are compiled with several
884 different combinations of optimization options. All warnings are
885 disabled for these test cases, so this directory is not suitable if
886 you wish to test for the presence or absence of compiler warnings.
887 While special options can be set, and tests disabled on specific
888 platforms, by the use of @file{.x} files, mostly these test cases
889 should not contain platform dependencies. FIXME: discuss how defines
890 such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
891 @item gcc.c-torture/execute
892 This test suite contains test cases that should compile, link and run;
893 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
894 @item gcc.c-torture/execute/ieee
895 This contains tests which are specific to IEEE floating point.
896 @item gcc.c-torture/unsorted
897 FIXME: describe this.
899 This directory should probably not be used for new tests.
900 @item gcc.c-torture/misc-tests
901 FIXME: describe this, when it should be used for new tests and when it
905 FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
906 test cases and magic comments more.
909 @subsection The Java library test suites.
911 Runtime tests are executed via @samp{make check} from the @samp{testsuite}
912 directory of the libjava hierarchy in the build tree. Additional runtime
913 tests can be checked into this testsuite.
915 Regression testing of the core packages in libgcj is also covered by the
916 Mauve test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project}
917 develops tests for the Java Class Libraries. These tests are run as part
918 of libgcj testing by placing the Mauve tree within the libjava testsuite
919 sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
920 the location of that tree when invoking @samp{make}, as in
921 @samp{make MAUVEDIR=~/mauve check}.
923 To detect regressions, a mechanism in @file{mauve.exp} compares the
924 failures for a test run against the list of expected failures in
925 @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
926 Update this file when adding new failing tests to Mauve, or when fixing
927 bugs in libgcj that had caused Mauve test failures.
929 The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,,
930 Jacks} project provides a test suite for Java compilers that can be used
931 to test changes that affect the GCJ front end. This test suite is run as
932 part of Java testing by placing the Jacks tree within the the libjava
933 testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}.
935 We encourage developers to contribute test cases to Mauve and Jacks.