| @c Copyright (C) 2002 Free Software Foundation, Inc. |
| @c This is part of the GCC manual. |
| @c For copying conditions, see the file gcc.texi. |
| |
| @node Source Tree |
| @chapter Source Tree Structure and Build System |
| |
| This chapter describes the structure of the GCC source tree, and how |
| GCC is built. The user documentation for building and installing GCC |
| is in a separate manual (@uref{http://gcc.gnu.org/install/}), with |
| which it is presumed that you are familiar. |
| |
| @menu |
| * Configure Terms:: Configuration terminology and history. |
| * Top Level:: The top level source directory. |
| * gcc Directory:: The @file{gcc} subdirectory. |
| * Test Suites:: The GCC test suites. |
| @end menu |
| |
| @include configterms.texi |
| |
| @node Top Level |
| @section Top Level Source Directory |
| |
| The top level source directory in a GCC distribution contains several |
| files and directories that are shared with other software |
| distributions such as that of GNU Binutils. It also contains several |
| subdirectories that contain parts of GCC and its runtime libraries: |
| |
| @table @file |
| @item boehm-gc |
| The Boehm conservative garbage collector, used as part of the Java |
| runtime library. |
| |
| @item contrib |
| Contributed scripts that may be found useful in conjunction with GCC@. |
| One of these, @file{contrib/texi2pod.pl}, is used to generate man |
| pages from Texinfo manuals as part of the GCC build process. |
| |
| @item fastjar |
| An implementation of the @command{jar} command, used with the Java |
| front end. |
| |
| @item gcc |
| The main sources of GCC itself (except for runtime libraries), |
| including optimizers, support for different target architectures, |
| language front ends, and test suites. @xref{gcc Directory, , The |
| @file{gcc} Subdirectory}, for details. |
| |
| @item include |
| Headers for the @code{libiberty} library. |
| |
| @item libchill |
| The CHILL runtime library. |
| |
| @item libf2c |
| The Fortran runtime library. |
| |
| @item libffi |
| The @code{libffi} library, used as part of the Java runtime library. |
| |
| @item libiberty |
| The @code{libibery} library, used for portability and for some |
| generally useful data structures and algorithms. @xref{Top, , |
| Introduction, libiberty, @sc{gnu} libiberty}, for more information |
| about this library. |
| |
| @item libjava |
| The Java runtime library. |
| |
| @item libobjc |
| The Objective-C runtime library. |
| |
| @item libstdc++-v3 |
| The C++ runtime library. |
| |
| @item maintainer-scripts |
| Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. |
| |
| @item zlib |
| The @code{zlib} compression library, used by the Java front end and as |
| part of the Java runtime library. |
| @end table |
| |
| The build system in the top level directory, including how recursion |
| into subdirectories works and how building runtime libraries for |
| multilibs is handled, is documented in a separate manual, included |
| with GNU Binutils. @xref{Top, , GNU configure and build system, |
| configure, The GNU configure and build system}, for details. |
| |
| @node gcc Directory |
| @section The @file{gcc} Subdirectory |
| |
| The @file{gcc} directory contains many files that are part of the C |
| sources of GCC, other files used as part of the configuration and |
| build process, and subdirectories including documentation and a |
| test suite. The files that are sources of GCC are documented in a |
| separate chapter. @xref{Passes, , Passes and Files of the Compiler}. |
| |
| @menu |
| * Subdirectories:: Subdirectories of @file{gcc}. |
| * Configuration:: The configuration process, and the files it uses. |
| * Build:: The build system in the @file{gcc} directory. |
| * Makefile:: Targets in @file{gcc/Makefile}. |
| * Library Files:: Library source files and headers under @file{gcc/}. |
| * Headers:: Headers installed by GCC. |
| * Documentation:: Building documentation in GCC. |
| * Front End:: Anatomy of a language front end. |
| * Back End:: Anatomy of a target back end. |
| @end menu |
| |
| @node Subdirectories |
| @subsection Subdirectories of @file{gcc} |
| |
| The @file{gcc} directory contains the following subdirectories: |
| |
| @table @file |
| @item @var{language} |
| Subdirectories for various languages. Directories containing a file |
| @file{config-lang.in} are language subdirectories. The contents of |
| the subdirectories @file{cp} (for C++) and @file{objc} (for |
| Objective-C) are documented in this manual (@pxref{Passes, , Passes |
| and Files of the Compiler}); those for other languages are not. |
| @xref{Front End, , Anatomy of a Language Front End}, for details of |
| the files in these directories. |
| |
| @item config |
| Configuration files for supported architectures and operating |
| systems. @xref{Back End, , Anatomy of a Target Back End}, for |
| details of the files in thie directory. |
| |
| @item doc |
| Texinfo documentation for GCC, together with automatically generated |
| man pages and support for converting the installation manual to |
| HTML@. @xref{Documentation}. |
| |
| @item fixinc |
| The support for fixing system headers to work with GCC@. See |
| @file{fixinc/README} for more information. The headers fixed by this |
| mechanism are installed in @file{@var{libsubdir}/include}. Along with |
| those headers, @file{README-fixinc} is also installed, as |
| @file{@var{libsubdir}/include/README}. |
| |
| @item ginclude |
| System headers installed by GCC, mainly those required by the C |
| standard of freestanding implementations. @xref{Headers, , Headers |
| Installed by GCC}, for details of when these and other headers are |
| installed. |
| |
| @item intl |
| GNU @code{libintl}, from GNU @code{gettext}, for systems which do not |
| include it in libc. Properly, this directory should be at top level, |
| parallel to the @file{gcc} directory. |
| |
| @item po |
| Message catalogs with translations of messages produced by GCC into |
| various languages, @file{@var{language}.po}. This directory also |
| contains @file{gcc.pot}, the template for these message catalogues, |
| @file{exgettext}, a wrapper around @command{gettext} to extract the |
| messages from the GCC sources and create @file{gcc.pot}, which is run |
| by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from |
| which messages should not be extracted. |
| |
| @item testsuite |
| The GCC test suites (except for those for runtime libraries). |
| @xref{Test Suites}. |
| @end table |
| |
| @node Configuration |
| @subsection Configuration in the @file{gcc} Directory |
| |
| The @file{gcc} directory is configured with an Autoconf-generated |
| script @file{configure}. The @file{configure} script is generated |
| from @file{configure.in} and @file{aclocal.m4}. From the files |
| @file{configure.in} and @file{acconfig.h}, Autoheader generates the |
| file @file{config.in}. The file @file{cstamp-h.in} is used as a |
| timestamp. |
| |
| @menu |
| * Config Fragments:: Scripts used by @file{configure}. |
| * System Config:: The @file{config.gcc} file. |
| * Configuration Files:: Files created by running @file{configure}. |
| @end menu |
| |
| @node Config Fragments |
| @subsubsection Scripts Used by @file{configure} |
| |
| @file{configure} uses some other scripts to help in its work: |
| |
| @itemize @bullet |
| @item The standard GNU @file{config.sub} and @file{config.guess} |
| files, kept in the top level directory, are used. FIXME: when is the |
| @file{config.guess} file in the @file{gcc} directory (that just calls |
| the top level one) used? |
| |
| @item The file @file{config.gcc} is used to handle configuration |
| specific to the particular build, host or target machine. (In |
| general, this should only be used for features that cannot reasonably |
| be tested in Autoconf feature tests.) @xref{System Config, , The |
| @file{config.gcc} File}, for details of the contents of this file. |
| |
| @item Each language subdirectory has a file |
| @file{@var{language}/config-lang.in} that is used for |
| front-end-specific configuration. @xref{Front End Config, , The Front |
| End @file{config-lang.in} File}, for details of this file. |
| |
| @item A helper script @file{configure.frag} is used as part of |
| creating the output of @file{configure}. |
| @end itemize |
| |
| @node System Config |
| @subsubsection The @file{config.gcc} File |
| |
| FIXME: document the contents of this file, and what variables should |
| be set to control build, host and target configuration. |
| |
| @include configfiles.texi |
| |
| @node Build |
| @subsection Build System in the @file{gcc} Directory |
| |
| FIXME: describe the build system, including what is built in what |
| stages. Also list the various source files that are used in the build |
| process but aren't source files of GCC itself and so aren't documented |
| below (@pxref{Passes}). |
| |
| @include makefile.texi |
| |
| @node Library Files |
| @subsection Library Source Files and Headers under the @file{gcc} Directory |
| |
| FIXME: list here, with explanation, all the C source files and headers |
| under the @file{gcc} directory that aren't built into the GCC |
| executable but rather are part of runtime libraries and object files, |
| such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , |
| Headers Installed by GCC}, for more information about the |
| @file{ginclude} directory. |
| |
| @node Headers |
| @subsection Headers Installed by GCC |
| |
| In general, GCC expects the system C library to provide most of the |
| headers to be used with it. However, GCC will fix those headers if |
| necessary to make them work with GCC, and will install some headers |
| required of freestanding implementations. These headers are installed |
| in @file{@var{libsubdir}/include}. Headers for non-C runtime |
| libraries are also installed by GCC; these are not documented here. |
| (FIXME: document them somewhere.) |
| |
| Several of the headers GCC installs are in the @file{ginclude} |
| directory. These headers, @file{iso646.h}, |
| @file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and |
| @file{varargs.h}, are installed in @file{@var{libsubdir}/include}, |
| unless the target Makefile fragment (@pxref{Target Fragment}) |
| overrides this by setting @code{USER_H}. |
| |
| In addition to these headers and those generated by fixing system |
| headers to work with GCC, some other headers may also be installed in |
| @file{@var{libsubdir}/include}. @file{config.gcc} may set |
| @code{extra_headers}; this specifies additional headers under |
| @file{config} to be installed on some systems. GCC normally installs |
| a @code{<float.h>} file; these are kept as |
| @file{config/float-@var{format}.h}, where @var{format} is specified by |
| a @code{float_format} setting in @file{config.gcc}, and a setting |
| @samp{float_format=none} disables installation of this header. GCC |
| also installs its own version of @code{<limits.h>}; this is generated |
| from @file{glimits.h}, together with @file{limitx.h} and |
| @file{limity.h} if the system also has its own version of |
| @code{<limits.h>}. (GCC provides its own header because it is |
| required of ISO C freestanding implementations, but needs to include |
| the system header from its own header as well because other standards |
| such as POSIX specify additional values to be defined in |
| @code{<limits.h>}.) The system's @code{<limits.h>} header is used via |
| @file{@var{libsubdir}/include/syslimits.h}, which is copied from |
| @file{gsyslimits.h} if it does not need fixing to work with GCC; if it |
| needs fixing, @file{syslimits.h} is the fixed copy. |
| |
| @node Documentation |
| @subsection Building Documentation |
| |
| The main GCC documentation is in the form of manuals in Texinfo |
| format. These are installed in Info format, and DVI versions may be |
| generated by @command{make dvi}. In addition, some man pages are |
| generated from the Texinfo manuals, there are some other text files |
| with miscellaneous documentation, and runtime libraries have their own |
| documentation outside the @file{gcc} directory. FIXME: document the |
| documentation for runtime libraries somewhere. |
| |
| @menu |
| * Texinfo Manuals:: GCC manuals in Texinfo format. |
| * Man Page Generation:: Generating man pages from Texinfo manuals. |
| * Miscellaneous Docs:: Miscellaneous text files with documentation. |
| @end menu |
| |
| @node Texinfo Manuals |
| @subsubsection Texinfo Manuals |
| |
| The manuals for GCC as a whole, and the C and C++ front ends, are in |
| files @file{doc/*.texi}. Other front ends have their own manuals in |
| files @file{@var{language}/*.texi}. Common files |
| @file{doc/include/*.texi} are provided which may be included in |
| multiple manuals; the following files are in @file{doc/include}: |
| |
| @table @file |
| @item fdl.texi |
| The GNU Free Documentation License. |
| @item funding.texi |
| The section ``Funding Free Software''. |
| @item gcc-common.texi |
| Common definitions for manuals. |
| @item gpl.texi |
| The GNU General Public License. |
| @item texinfo.tex |
| A copy of @file{texinfo.tex} known to work with the GCC manuals. |
| @end table |
| |
| DVI formatted manuals are generated by @command{make dvi}, which uses |
| @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info |
| manuals are generated by @command{make info} (which is run as part of |
| a bootstrap); this generates the manuals in the source directory, |
| using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, |
| and they are included in release distributions. |
| |
| Manuals are also provided on the GCC web site, in both HTML and |
| PostScript forms. This is done via the script |
| @file{maintainer-scripts/update_web_docs}. Each manual to be |
| provided online must be listed in the definition of @code{MANUALS} in |
| that file; a file @file{@var{name}.texi} must only appear once in the |
| source tree, and the output manual must have the same name as the |
| source file. (However, other Texinfo files, included in manuals but |
| not themselves the root files of manuals, may have names that appear |
| more than once in the source tree.) The manual file |
| @file{@var{name}.texi} should only include other files in its own |
| directory or in @file{doc/include}. HTML manuals will be generated by |
| @command{makeinfo --html} and PostScript manuals by @command{texi2dvi} |
| and @command{dvips}. All Texinfo files that are parts of manuals must |
| be checked into CVS, even if they are generated files, for the |
| generation of online manuals to work. |
| |
| The installation manual, @file{doc/install.texi}, is also provided on |
| the GCC web site. The HTML version is generated by the script |
| @file{doc/install.texi2html}. |
| |
| @node Man Page Generation |
| @subsubsection Man Page Generation |
| |
| Because of user demand, in addition to full Texinfo manuals, man pages |
| are provided which contain extracts from those manuals. These man |
| pages are generated from the Texinfo manuals using |
| @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for |
| @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference |
| to @file{gcc.1}, but all the other man pages are generated from |
| Texinfo manuals.) |
| |
| Because many systems may not have the necessary tools installed to |
| generate the man pages, they are only generated if the |
| @file{configure} script detects that recent enough tools are |
| installed, and the Makefiles allow generating man pages to fail |
| without aborting the build. Man pages are also included in release |
| distributions. They are generated in the source directory. |
| |
| Magic comments in Texinfo files starting @samp{@@c man} control what |
| parts of a Texinfo file go into a man page. Only a subset of Texinfo |
| is supported by @file{texi2pod.pl}, and it may be necessary to add |
| support for more Texinfo features to this script when generating new |
| man pages. To improve the man page output, some special Texinfo |
| macros are provided in @file{doc/include/gcc-common.texi} which |
| @file{texi2pod.pl} understands: |
| |
| @table @code |
| @item @@gcctabopt |
| Use in the form @samp{@@table @@gcctabopt} for tables of options, |
| where for printed output the effect of @samp{@@code} is better than |
| that of @samp{@@option} but for man page output a different effect is |
| wanted. |
| @item @@gccoptlist |
| Use for summary lists of options in manuals. |
| @item @@gol |
| Use at the end of each line inside @samp{@@gccoptlist}. This is |
| necessary to avoid problems with differences in how the |
| @samp{@@gccoptlist} macro is handled by different Texinfo formatters. |
| @end table |
| |
| FIXME: describe the @file{texi2pod.pl} input language and magic |
| comments in more detail. |
| |
| @node Miscellaneous Docs |
| @subsubsection Miscellaneous Documentation |
| |
| In addition to the formal documentation that is installed by GCC, |
| there are several other text files with miscellaneous documentation: |
| |
| @table @file |
| @item ABOUT-GCC-NLS |
| Notes on GCC's Native Language Support. FIXME: this should be part of |
| this manual rather than a separate file. |
| @item ABOUT-NLS |
| Notes on the Free Translation Project. |
| @item COPYING |
| The GNU General Public License. |
| @item COPYING.LIB |
| The GNU Lesser General Public License. |
| @item *ChangeLog* |
| @itemx */ChangeLog* |
| Change log files for various parts of GCC@. |
| @item LANGUAGES |
| Details of a few changes to the GCC front-end interface. FIXME: the |
| information in this file should be part of general documentation of |
| the front-end interface in this manual. |
| @item ONEWS |
| Information about new features in old versions of GCC@. (For recent |
| versions, the information is on the GCC web site.) |
| @item README.Portability |
| Information about portability issues when writing code in GCC@. FIXME: |
| why isn't this part of this manual or of the GCC Coding Conventions? |
| @item SERVICE |
| A pointer to the GNU Service Directory. |
| @end table |
| |
| FIXME: document such files in subdirectories, at least @file{config}, |
| @file{cp}, @file{objc}, @file{testsuite}. |
| |
| @node Front End |
| @subsection Anatomy of a Language Front End |
| |
| A front end for a language in GCC has the following parts: |
| |
| @itemize @bullet |
| @item |
| A directory @file{@var{language}} under @file{gcc} containing source |
| files for that front end. @xref{Front End Directory, , The Front End |
| @file{@var{language}} Directory}, for details. |
| @item |
| A mention of the language in the list of supported languages in |
| @file{gcc/doc/install.texi}. |
| @item |
| Details of contributors to that front end in |
| @file{gcc/doc/contrib.texi}. If the details are in that front end's |
| own manual then there should be a link to that manual's list in |
| @file{contrib.texi}. |
| @item |
| Information about support for that language in |
| @file{gcc/doc/frontends.texi}. |
| @item |
| Information about standards for that language, and the front end's |
| support for them, in @file{gcc/doc/standards.texi}. This may be a |
| link to such information in the front end's own manual. |
| @item |
| Details of source file suffixes for that language and @option{-x |
| @var{lang}} options supported, in @file{gcc/doc/invoke.texi}. |
| @item |
| Entries in @code{default_compilers} in @file{gcc.c} for source file |
| suffixes for that language. |
| @item |
| Preferably test suites, which may be under @file{gcc/testsuite} or |
| runtime library directories. FIXME: document somewhere how to write |
| test suite harnesses. |
| @item |
| Probably a runtime library for the language, outside the @file{gcc} |
| directory. FIXME: document this further. |
| @item |
| Details of the directories of any runtime libraries in |
| @file{gcc/doc/sourcebuild.texi}. |
| @end itemize |
| |
| If the front end is added to the official GCC CVS repository, the |
| following are also necessary: |
| |
| @itemize @bullet |
| @item |
| At least one GNATS category for bugs in that front end and runtime |
| libraries. This category needs to be mentioned in |
| @file{gcc/gccbug.in}, and in @file{gnats.html} on the GCC web site, as |
| well as being added to the GNATS database. |
| @item |
| Normally, one or more maintainers of that front end listed in |
| @file{MAINTAINERS}. |
| @item |
| Mentions on the GCC web site in @file{index.html} and |
| @file{frontends.html}, with any relevant links on |
| @file{readings.html}. (Front ends that are not an official part of |
| GCC may also be listed on @file{frontends.html}, with relevant links.) |
| @item |
| A news item on @file{index.html}, and possibly an announcement on the |
| @email{gcc-announce@@gcc.gnu.org} mailing list. |
| @item |
| The front end's manuals should be mentioned in |
| @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals}) |
| and the online manuals should be linked to from |
| @file{onlinedocs/index.html}. |
| @item |
| Any old releases or CVS repositories of the front end, before its |
| inclusion in GCC, should be made available on the GCC FTP site |
| @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. |
| @item |
| The release and snapshot script @file{maintainer-scripts/gcc_release} |
| should be updated to generate appropriate tarballs for this front end. |
| @item |
| If this front end includes its own version files that include the |
| current date, @file{maintainer-scripts/update_version} should be |
| updated accordingly. |
| @item |
| @file{CVSROOT/modules} in the GCC CVS repository should be updated. |
| @end itemize |
| |
| @menu |
| * Front End Directory:: The front end @file{@var{language}} directory. |
| * Front End Config:: The front end @file{config-lang.in} file. |
| @end menu |
| |
| @node Front End Directory |
| @subsubsection The Front End @file{@var{language}} Directory |
| |
| A front end @file{@var{language}} directory contains the source files |
| of that front end (but not of any runtime libraries, which should be |
| outside the @file{gcc} directory). This includes documentation, and |
| possibly some subsidiary programs build alongside the front end. |
| Certain files are special and other parts of the compiler depend on |
| their names: |
| |
| @table @file |
| @item config-lang.in |
| This file is required in all language subdirectories. @xref{Front End |
| Config, , The Front End @file{config-lang.in} File}, for details of |
| its contents |
| @item Make-lang.in |
| This file is required in all language subdirectories. It contains |
| targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the |
| setting of @code{language} in @file{config-lang.in}) for the following |
| values of @code{@var{hook}}, and any other Makefile rules required to |
| build those targets (which may if necessary use other Makefiles |
| specified in @code{outputs} in @file{config-lang.in}, although this is |
| deprecated). |
| |
| @table @code |
| @item all.build |
| @itemx all.cross |
| @itemx start.encap |
| @itemx rest.encap |
| FIXME: exactly what goes in each of these targets? |
| @item info |
| Build info documentation for the front end, in the source directory. |
| This target is only called by @command{make bootstrap} if a suitable |
| version of @command{makeinfo} is available, so does not need to check |
| for this, and should fail if an error occurs. |
| @item dvi |
| Build DVI documentation for the front end, in the build directory. |
| This should be done using @code{$(TEXI2DVI)}, with appropriate |
| @option{-I} arguments pointing to directories of included files. |
| @item generated-manpages |
| Build generated man pages for the front end from Texinfo manuals |
| (@pxref{Man Page Generation}), in the source directory. This target |
| is only called if the necessary tools are available, but should ignore |
| errors so as not to stop the build if errors occur; man pages are |
| optional and the tools involved may be installed in a broken way. |
| @item install-normal |
| FIXME: what is this target for? |
| @item install-common |
| Install everything that is part of the front end, apart from the |
| compiler executables listed in @code{compilers} in |
| @file{config-lang.in} that are installed in @file{@var{libsubdir}} by |
| the main @file{Makefile}. |
| @item install-info |
| Install info documentation for the front end, if it is present in the |
| source directory. (It may not be present if a suitable version of |
| @command{makeinfo} was not installed.) This target should run the |
| command @command{install-info} to update the info directory, but |
| should ignore errors when running that command. |
| @item install-man |
| Install man pages for the front end. This target should ignore |
| errors. |
| @item uninstall |
| Uninstall files installed by installing the compiler. This is |
| currently documented not to be supported, so the hook need not do |
| anything. |
| @item mostlyclean |
| @itemx clean |
| @itemx distclean |
| @itemx extraclean |
| @itemx maintainer-clean |
| Except for @code{extraclean}, the language parts of the standard GNU |
| @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for |
| Users, standards, GNU Coding Standards}, for details of the standard |
| targets. @code{extraclean} does @code{distclean} and also deletes |
| anything likely to be found in the source directory that shouldn't be |
| in the distribution. For GCC, @code{maintainer-clean} should delete |
| all generated files in the source directory that are not checked into |
| CVS, but should not delete anything checked into CVS@. |
| @item stage1 |
| @itemx stage2 |
| @itemx stage3 |
| @itemx stage4 |
| Move to the stage directory files not included in @code{stagestuff} in |
| @file{config-lang.in} or otherwise moved by the main @file{Makefile}. |
| @end table |
| |
| @item lang-options.h |
| This file provides entries for @code{documented_lang_options} in |
| @file{toplev.c} describing command-line options the front end accepts |
| for @option{--help} output. |
| @item lang-specs.h |
| This file provides entries for @code{default_compilers} in |
| @file{gcc.c} which override the default of giving an error that a |
| compiler for that language is not installed. |
| @item @var{language}-tree.def |
| This file, which need not exist, defines any language-specific tree |
| codes. |
| @end table |
| |
| @node Front End Config |
| @subsubsection The Front End @file{config-lang.in} File |
| |
| Each language subdirectory contains a @file{config-lang.in} file. |
| This file is a shell script that may define some variables describing |
| the language: |
| |
| @table @code |
| @item language |
| This definition must be present, and gives the name of the language |
| for some purposes such as arguments to @option{--enable-languages}. |
| @item lang_requires |
| If defined, this variable lists (space-separated) language front ends |
| other than C that this front end requires to be enabled (with the |
| names given being their @code{language} settings). For example, the |
| Java front end depends on the C++ front end, so sets |
| @samp{lang_requires=c++}. |
| @item target_libs |
| If defined, this variable lists (space-separated) targets in the top |
| level @file{Makefile} to build the runtime libraries for this |
| language, such as @code{target-libobjc}. |
| @item lang_dirs |
| If defined, this variable lists (space-separated) top level |
| directories (parallel to @file{gcc}), apart from the runtime libraries, |
| that should not be configured if this front end is not built. |
| @item build_by_default |
| If defined to @samp{no}, this language front end is not built unless |
| enabled in a @option{--enable-languages} argument. Otherwise, front |
| ends are built by default, subject to any special logic in |
| @file{configure.in} (as is present to disable the Ada front end if the |
| Ada compiler is not already installed). |
| @item boot_language |
| If defined to @samp{yes}, this front end is built in stage 1 of the |
| bootstrap. This is only relevant to front ends written in their own |
| languages. |
| @item compilers |
| If defined, a space-separated list of compiler executables that should |
| be installed in @file{@var{libsubdir}}. The names here will each end |
| with @samp{\$(exeext)}. |
| @item stagestuff |
| If defined, a space-separated list of files that should be moved to |
| the @file{stage@var{n}} directories in each stage of bootstrap. |
| @item outputs |
| If defined, a space-separated list of files that should be generated |
| by @file{configure} substituting values in them. This mechanism can |
| be used to create a file @file{@var{language}/Makefile} from |
| @file{@var{language}/Makefile.in}, but this is deprecated, building |
| everything from the single @file{gcc/Makefile} is preferred. |
| @end table |
| |
| @node Back End |
| @subsection Anatomy of a Target Back End |
| |
| A back end for a target architecture in GCC has the following parts: |
| |
| @itemize @bullet |
| @item |
| A directory @file{@var{machine}} under @file{gcc/config}, containing a |
| machine description @file{@var{machine}.md} file (@pxref{Machine Desc, |
| , Machine Descriptions}), header files @file{@var{machine}.h} and |
| @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} |
| (@pxref{Target Macros, , Target Description Macros and Functions}), |
| possibly a target Makefile fragment @file{t-@var{machine}} |
| (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe |
| some other files. The names of these files may be changed from the |
| defaults given by explicit specifications in @file{config.gcc}. |
| @item |
| Entries in @file{config.gcc} (@pxref{System Config, , The |
| @file{config.gcc} File}) for the systems with this target |
| architecture. |
| @item |
| Documentation in @file{gcc/doc/invoke.texi} for any command-line |
| options supported by this target (@pxref{Run-time Target, , Run-time |
| Target Specification}). This means both entries in the summary table |
| of options and details of the individual options. |
| @item |
| Documentation in @file{gcc/doc/extend.texi} for any target-specific |
| attributes supported (@pxref{Target Attributes, , Defining |
| target-specific uses of @code{__attribute__}}), including where the |
| same attribute is already supported on some targets, which are |
| enumerated in the manual. |
| @item |
| Documentation in @file{gcc/doc/extend.texi} for any target-specific |
| pragmas supported. |
| @item |
| Documentation in @file{gcc/doc/extend.texi} of any target-specific |
| built-in functions supported. |
| @item |
| Documentation in @file{gcc/doc/md.texi} of any target-specific |
| constraint letters (@pxref{Machine Constraints, , Constraints for |
| Particular Machines}). |
| @item |
| A note in @file{gcc/doc/contrib.texi} under the person or people who |
| contributed the target support. |
| @item |
| Entries in @file{gcc/doc/install.texi} for all target triplets |
| supported with this target architecture, giving details of any special |
| notes about installation for this target, or saying that there are no |
| special notes if there are none. |
| @item |
| Possibly other support outside the @file{gcc} directory for runtime |
| libraries. FIXME: reference docs for this. The libstdc++ porting |
| manual needs to be installed as info for this to work, or to be a |
| chapter of this manual. |
| @end itemize |
| |
| If the back end is added to the official GCC CVS repository, the |
| following are also necessary: |
| |
| @itemize @bullet |
| @item |
| An entry for the target architecture in @file{readings.html} on the |
| GCC web site, with any relevant links. |
| @item |
| A news item about the contribution of support for that target |
| architecture, in @file{index.html} on the GCC web site. |
| @item |
| Normally, one or more maintainers of that target listed in |
| @file{MAINTAINERS}. Some existing architectures may be unmaintained, |
| but it would be unusual to add support for a target that does not have |
| a maintainer when support is added. |
| @end itemize |
| |
| @node Test Suites |
| @section Test Suites |
| |
| GCC contains several test suites to help maintain compiler quality. |
| Most of the runtime libraries and language front ends in GCC have test |
| suites. Currently only the C language test suites are documented |
| here; FIXME: document the others. |
| |
| @menu |
| * Test Idioms:: Idioms used in test suite code. |
| * C Tests:: The C language test suites. |
| @end menu |
| |
| @node Test Idioms |
| @subsection Idioms Used in Test Suite Code |
| |
| In the @file{gcc.c-torture} test suites, test cases are commonly named |
| after the date on which they were added. This allows people to tell |
| at a glance whether a test failure is because of a recently found bug |
| that has not yet been fixed, or whether it may be a regression. In |
| other test suites, more descriptive names are used. In general C test |
| cases have a trailing @file{-@var{n}.c}, starting with @file{-1.c}, in |
| case other test cases with similar names are added later. |
| |
| Test cases should use @code{abort ()} to indicate failure and |
| @code{exit (0)} for success; on some targets these may be redefined to |
| indicate failure and success in other ways. |
| |
| In the @file{gcc.dg} test suite, it is often necessary to test that an |
| error is indeed a hard error and not just a warning---for example, |
| where it is a constraint violation in the C standard, which must |
| become an error with @option{-pedantic-errors}. The following idiom, |
| where the first line shown is line @var{line} of the file and the line |
| that generates the error, is used for this: |
| |
| @smallexample |
| /* @{ dg-bogus "warning" "warning in place of error" @} */ |
| /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ |
| @end smallexample |
| |
| It may be necessary to check that an expression is an integer constant |
| expression and has a certain value. To check that @code{@var{E}} has |
| value @code{@var{V}}, an idiom similar to the following is used: |
| |
| @smallexample |
| char x[((E) == (V) ? 1 : -1)]; |
| @end smallexample |
| |
| In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make |
| assertions about the types of expressions. See, for example, |
| @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the |
| exact rules for the types of conditional expressions in the C |
| standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. |
| |
| It is useful to be able to test that optimizations are being made |
| properly. This cannot be done in all cases, but it can be done where |
| the optimization will lead to code being optimized away (for example, |
| where flow analysis or alias analysis should show that certain code |
| cannot be called) or to functions not being called because they have |
| been expanded as built-in functions. Such tests go in |
| @file{gcc.c-torture/execute}. Where code should be optimized away, a |
| call to a nonexistent function such as @code{link_failure ()} may be |
| inserted; a definition |
| |
| @smallexample |
| #ifndef __OPTIMIZE__ |
| void |
| link_failure (void) |
| @{ |
| abort (); |
| @} |
| #endif |
| @end smallexample |
| |
| @noindent |
| will also be needed so that linking still succeeds when the test is |
| run without optimization. When all calls to a built-in function |
| should have been optimized and no calls to the non-built-in version of |
| the function should remain, that function may be defined as |
| @code{static} to call @code{abort ()} (although redeclaring a function |
| as static may not work on all targets). |
| |
| FIXME: discuss non-C test suites here. |
| |
| @node C Tests |
| @subsection C Language Test Suites |
| |
| GCC contains the following C language test suites, in the |
| @file{gcc/testsuite} directory: |
| |
| @table @file |
| @item gcc.c-torture/compat |
| FIXME: describe this. |
| |
| This directory should probably not be used for new tests. |
| @item gcc.c-torture/compile |
| This test suite contains test cases that should compile, but do not |
| need to link or run. These test cases are compiled with several |
| different combinations of optimization options. All warnings are |
| disabled for these test cases, so this directory is not suitable if |
| you wish to test for the presence or absence of compiler warnings. |
| While special options can be set, and tests disabled on specific |
| platforms, by the use of @file{.x} files, mostly these test cases |
| should not contain platform dependencies. FIXME: discuss how defines |
| such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. |
| @item gcc.c-torture/execute |
| This test suite contains test cases that should compile, link and run; |
| otherwise the same comments as for @file{gcc.c-torture/compile} apply. |
| @item gcc.c-torture/unsorted |
| FIXME: describe this. |
| |
| This directory should probably not be used for new tests. |
| @item gcc.dg |
| This test suite contains tests using the more modern @samp{dg} harness. |
| Magic comments determine whether the file is preprocessed, compiled, |
| linked or run. In these tests, error and warning message texts are |
| compared against expected texts or regular expressions given in |
| comments. These tests are run with the options @samp{-ansi -pedantic} |
| unless other options are given in the test. Except as noted below they |
| are not run with multiple optimization options. |
| @item gcc.dg/cpp |
| This subdirectory contains tests of the preprocessor. |
| @item gcc.dg/debug |
| This subdirectory contains tests for debug formats. Tests in this |
| subdirectory are run for each debug format that the compiler supports. |
| @item gcc.dg/format |
| This subdirectory contains tests of the @option{-Wformat} format |
| checking. Tests in this directory are run with and without |
| @option{-DWIDE}. |
| @item gcc.dg/noncompile |
| This subdirectory contains tests of code that should not compile and |
| does not need any special compilation options. They are run with |
| multiple optimization options, since sometimes invalid code crashes |
| the compiler with optimization. |
| @item gcc.dg/special |
| FIXME: describe this. |
| @item gcc.c-torture/misc-tests |
| FIXME: describe this, when it should be used for new tests and when it |
| shouldn't. |
| @end table |
| |
| FIXME: merge in @file{testsuite/README.gcc} and discuss the format of |
| test cases and magic comments more. |