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.
4
5@node Source Tree
6@chapter Source Tree Structure and Build System
7
8This chapter describes the structure of the GCC source tree, and how
9GCC is built. The user documentation for building and installing GCC
10is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
11which it is presumed that you are familiar.
12
13@menu
14* Configure Terms:: Configuration terminology and history.
15* Top Level:: The top level source directory.
16* gcc Directory:: The @file{gcc} subdirectory.
17* Test Suites:: The GCC test suites.
18@end menu
19
20@include configterms.texi
21
22@node Top Level
23@section Top Level Source Directory
24
25The top level source directory in a GCC distribution contains several
26files and directories that are shared with other software
27distributions such as that of GNU Binutils. It also contains several
28subdirectories that contain parts of GCC and its runtime libraries:
29
30@table @file
31@item boehm-gc
32The Boehm conservative garbage collector, used as part of the Java
33runtime library.
34
35@item contrib
36Contributed scripts that may be found useful in conjunction with GCC@.
37One of these, @file{contrib/texi2pod.pl}, is used to generate man
38pages from Texinfo manuals as part of the GCC build process.
39
40@item fastjar
41An implementation of the @command{jar} command, used with the Java
42front end.
43
44@item gcc
45The main sources of GCC itself (except for runtime libraries),
46including optimizers, support for different target architectures,
47language front ends, and test suites. @xref{gcc Directory, , The
48@file{gcc} Subdirectory}, for details.
49
50@item include
51Headers for the @code{libiberty} library.
52
53@item libf2c
54The Fortran runtime library.
55
56@item libffi
57The @code{libffi} library, used as part of the Java runtime library.
58
59@item libiberty
60The @code{libiberty} library, used for portability and for some
61generally useful data structures and algorithms. @xref{Top, ,
62Introduction, libiberty, @sc{gnu} libiberty}, for more information
63about this library.
64
65@item libjava
66The Java runtime library.
67
68@item libobjc
69The Objective-C runtime library.
70
71@item libstdc++-v3
72The C++ runtime library.
73
74@item maintainer-scripts
75Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
76
77@item zlib
78The @code{zlib} compression library, used by the Java front end and as
79part of the Java runtime library.
80@end table
81
82The build system in the top level directory, including how recursion
83into subdirectories works and how building runtime libraries for
84multilibs is handled, is documented in a separate manual, included
85with GNU Binutils. @xref{Top, , GNU configure and build system,
86configure, The GNU configure and build system}, for details.
87
88@node gcc Directory
89@section The @file{gcc} Subdirectory
90
91The @file{gcc} directory contains many files that are part of the C
92sources of GCC, other files used as part of the configuration and
93build process, and subdirectories including documentation and a
94test suite. The files that are sources of GCC are documented in a
95separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
96
97@menu
98* Subdirectories:: Subdirectories of @file{gcc}.
99* Configuration:: The configuration process, and the files it uses.
100* Build:: The build system in the @file{gcc} directory.
101* Makefile:: Targets in @file{gcc/Makefile}.
102* Library Files:: Library source files and headers under @file{gcc/}.
103* Headers:: Headers installed by GCC.
104* Documentation:: Building documentation in GCC.
105* Front End:: Anatomy of a language front end.
106* Back End:: Anatomy of a target back end.
107@end menu
108
109@node Subdirectories
110@subsection Subdirectories of @file{gcc}
111
112The @file{gcc} directory contains the following subdirectories:
113
114@table @file
115@item @var{language}
116Subdirectories for various languages. Directories containing a file
117@file{config-lang.in} are language subdirectories. The contents of
118the subdirectories @file{cp} (for C++) and @file{objc} (for
119Objective-C) are documented in this manual (@pxref{Passes, , Passes
120and Files of the Compiler}); those for other languages are not.
121@xref{Front End, , Anatomy of a Language Front End}, for details of
122the files in these directories.
123
124@item config
125Configuration files for supported architectures and operating
126systems. @xref{Back End, , Anatomy of a Target Back End}, for
127details of the files in thie directory.
128
129@item doc
130Texinfo documentation for GCC, together with automatically generated
131man pages and support for converting the installation manual to
132HTML@. @xref{Documentation}.
133
134@item fixinc
135The support for fixing system headers to work with GCC@. See
136@file{fixinc/README} for more information. The headers fixed by this
137mechanism are installed in @file{@var{libsubdir}/include}. Along with
138those headers, @file{README-fixinc} is also installed, as
139@file{@var{libsubdir}/include/README}.
140
141@item ginclude
142System headers installed by GCC, mainly those required by the C
143standard of freestanding implementations. @xref{Headers, , Headers
144Installed by GCC}, for details of when these and other headers are
145installed.
146
147@item intl
148GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
149include it in libc. Properly, this directory should be at top level,
150parallel to the @file{gcc} directory.
151
152@item po
153Message catalogs with translations of messages produced by GCC into
154various languages, @file{@var{language}.po}. This directory also
155contains @file{gcc.pot}, the template for these message catalogues,
156@file{exgettext}, a wrapper around @command{gettext} to extract the
157messages from the GCC sources and create @file{gcc.pot}, which is run
158by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
159which messages should not be extracted.
160
161@item testsuite
162The GCC test suites (except for those for runtime libraries).
163@xref{Test Suites}.
164@end table
165
166@node Configuration
167@subsection Configuration in the @file{gcc} Directory
168
169The @file{gcc} directory is configured with an Autoconf-generated
170script @file{configure}. The @file{configure} script is generated
171from @file{configure.in} and @file{aclocal.m4}. From the files
172@file{configure.in} and @file{acconfig.h}, Autoheader generates the
173file @file{config.in}. The file @file{cstamp-h.in} is used as a
174timestamp.
175
176@menu
177* Config Fragments:: Scripts used by @file{configure}.
178* System Config:: The @file{config.gcc} file.
179* Configuration Files:: Files created by running @file{configure}.
180@end menu
181
182@node Config Fragments
183@subsubsection Scripts Used by @file{configure}
184
185@file{configure} uses some other scripts to help in its work:
186
187@itemize @bullet
188@item The standard GNU @file{config.sub} and @file{config.guess}
189files, 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
191the top level one) used?
192
193@item The file @file{config.gcc} is used to handle configuration
194specific to the particular build, host or target machine. (In
195general, this should only be used for features that cannot reasonably
196be tested in Autoconf feature tests.) @xref{System Config, , The
197@file{config.gcc} File}, for details of the contents of this file.
198
199@item Each language subdirectory has a file
200@file{@var{language}/config-lang.in} that is used for
201front-end-specific configuration. @xref{Front End Config, , The Front
202End @file{config-lang.in} File}, for details of this file.
203
204@item A helper script @file{configure.frag} is used as part of
205creating the output of @file{configure}.
206@end itemize
207
208@node System Config
209@subsubsection The @file{config.gcc} File
210
211FIXME: document the contents of this file, and what variables should
212be set to control build, host and target configuration.
213
214@include configfiles.texi
215
216@node Build
217@subsection Build System in the @file{gcc} Directory
218
219FIXME: describe the build system, including what is built in what
220stages. Also list the various source files that are used in the build
221process but aren't source files of GCC itself and so aren't documented
222below (@pxref{Passes}).
223
224@include makefile.texi
225
226@node Library Files
227@subsection Library Source Files and Headers under the @file{gcc} Directory
228
229FIXME: list here, with explanation, all the C source files and headers
230under the @file{gcc} directory that aren't built into the GCC
231executable but rather are part of runtime libraries and object files,
232such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
233Headers Installed by GCC}, for more information about the
234@file{ginclude} directory.
235
236@node Headers
237@subsection Headers Installed by GCC
238
239In general, GCC expects the system C library to provide most of the
240headers to be used with it. However, GCC will fix those headers if
241necessary to make them work with GCC, and will install some headers
242required of freestanding implementations. These headers are installed
243in @file{@var{libsubdir}/include}. Headers for non-C runtime
244libraries are also installed by GCC; these are not documented here.
245(FIXME: document them somewhere.)
246
247Several of the headers GCC installs are in the @file{ginclude}
248directory. These headers, @file{iso646.h},
249@file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and
250@file{varargs.h}, are installed in @file{@var{libsubdir}/include},
251unless the target Makefile fragment (@pxref{Target Fragment})
252overrides this by setting @code{USER_H}.
253
254In addition to these headers and those generated by fixing system
255headers 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. GCC normally installs
259a @code{<float.h>} file; these are kept as
260@file{config/float-@var{format}.h}, where @var{format} is specified by
261a @code{float_format} setting in @file{config.gcc}, and a setting
262@samp{float_format=none} disables installation of this header. GCC
263also installs its own version of @code{<limits.h>}; this is generated
264from @file{glimits.h}, together with @file{limitx.h} and
265@file{limity.h} if the system also has its own version of
266@code{<limits.h>}. (GCC provides its own header because it is
267required of ISO C freestanding implementations, but needs to include
268the system header from its own header as well because other standards
269such as POSIX specify additional values to be defined in
270@code{<limits.h>}.) The system's @code{<limits.h>} header is used via
271@file{@var{libsubdir}/include/syslimits.h}, which is copied from
272@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
273needs fixing, @file{syslimits.h} is the fixed copy.
274
275@node Documentation
276@subsection Building Documentation
277
278The main GCC documentation is in the form of manuals in Texinfo
279format. These are installed in Info format, and DVI versions may be
280generated by @command{make dvi}. In addition, some man pages are
281generated from the Texinfo manuals, there are some other text files
282with miscellaneous documentation, and runtime libraries have their own
283documentation outside the @file{gcc} directory. FIXME: document the
284documentation for runtime libraries somewhere.
285
286@menu
287* Texinfo Manuals:: GCC manuals in Texinfo format.
288* Man Page Generation:: Generating man pages from Texinfo manuals.
289* Miscellaneous Docs:: Miscellaneous text files with documentation.
290@end menu
291
292@node Texinfo Manuals
293@subsubsection Texinfo Manuals
294
295The manuals for GCC as a whole, and the C and C++ front ends, are in
296files @file{doc/*.texi}. Other front ends have their own manuals in
297files @file{@var{language}/*.texi}. Common files
298@file{doc/include/*.texi} are provided which may be included in
299multiple manuals; the following files are in @file{doc/include}:
300
301@table @file
302@item fdl.texi
303The GNU Free Documentation License.
304@item funding.texi
305The section ``Funding Free Software''.
306@item gcc-common.texi
307Common definitions for manuals.
308@item gpl.texi
309The GNU General Public License.
310@item texinfo.tex
311A copy of @file{texinfo.tex} known to work with the GCC manuals.
312@end table
313
314DVI formatted manuals are generated by @command{make dvi}, which uses
315@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
316manuals are generated by @command{make info} (which is run as part of
317a bootstrap); this generates the manuals in the source directory,
318using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
319and they are included in release distributions.
320
321Manuals are also provided on the GCC web site, in both HTML and
322PostScript forms. This is done via the script
323@file{maintainer-scripts/update_web_docs}. Each manual to be
324provided online must be listed in the definition of @code{MANUALS} in
325that file; a file @file{@var{name}.texi} must only appear once in the
326source tree, and the output manual must have the same name as the
327source file. (However, other Texinfo files, included in manuals but
328not themselves the root files of manuals, may have names that appear
329more than once in the source tree.) The manual file
330@file{@var{name}.texi} should only include other files in its own
331directory or in @file{doc/include}. HTML manuals will be generated by
332@command{makeinfo --html} and PostScript manuals by @command{texi2dvi}
333and @command{dvips}. All Texinfo files that are parts of manuals must
334be checked into CVS, even if they are generated files, for the
335generation of online manuals to work.
336
337The installation manual, @file{doc/install.texi}, is also provided on
338the GCC web site. The HTML version is generated by the script
339@file{doc/install.texi2html}.
340
341@node Man Page Generation
342@subsubsection Man Page Generation
343
344Because of user demand, in addition to full Texinfo manuals, man pages
345are provided which contain extracts from those manuals. These man
346pages are generated from the Texinfo manuals using
347@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
348@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
349to @file{gcc.1}, but all the other man pages are generated from
350Texinfo manuals.)
351
352Because many systems may not have the necessary tools installed to
353generate the man pages, they are only generated if the
354@file{configure} script detects that recent enough tools are
355installed, and the Makefiles allow generating man pages to fail
356without aborting the build. Man pages are also included in release
357distributions. They are generated in the source directory.
358
359Magic comments in Texinfo files starting @samp{@@c man} control what
360parts of a Texinfo file go into a man page. Only a subset of Texinfo
361is supported by @file{texi2pod.pl}, and it may be necessary to add
362support for more Texinfo features to this script when generating new
363man pages. To improve the man page output, some special Texinfo
364macros are provided in @file{doc/include/gcc-common.texi} which
365@file{texi2pod.pl} understands:
366
367@table @code
368@item @@gcctabopt
369Use in the form @samp{@@table @@gcctabopt} for tables of options,
370where for printed output the effect of @samp{@@code} is better than
371that of @samp{@@option} but for man page output a different effect is
372wanted.
373@item @@gccoptlist
374Use for summary lists of options in manuals.
375@item @@gol
376Use at the end of each line inside @samp{@@gccoptlist}. This is
377necessary to avoid problems with differences in how the
378@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
379@end table
380
381FIXME: describe the @file{texi2pod.pl} input language and magic
382comments in more detail.
383
384@node Miscellaneous Docs
385@subsubsection Miscellaneous Documentation
386
387In addition to the formal documentation that is installed by GCC,
388there are several other text files with miscellaneous documentation:
389
390@table @file
391@item ABOUT-GCC-NLS
392Notes on GCC's Native Language Support. FIXME: this should be part of
393this manual rather than a separate file.
394@item ABOUT-NLS
395Notes on the Free Translation Project.
396@item COPYING
397The GNU General Public License.
398@item COPYING.LIB
399The GNU Lesser General Public License.
400@item *ChangeLog*
401@itemx */ChangeLog*
402Change log files for various parts of GCC@.
403@item LANGUAGES
404Details of a few changes to the GCC front-end interface. FIXME: the
405information in this file should be part of general documentation of
406the front-end interface in this manual.
407@item ONEWS
408Information about new features in old versions of GCC@. (For recent
409versions, the information is on the GCC web site.)
410@item README.Portability
411Information about portability issues when writing code in GCC@. FIXME:
412why isn't this part of this manual or of the GCC Coding Conventions?
413@item SERVICE
414A pointer to the GNU Service Directory.
415@end table
416
417FIXME: document such files in subdirectories, at least @file{config},
418@file{cp}, @file{objc}, @file{testsuite}.
419
420@node Front End
421@subsection Anatomy of a Language Front End
422
423A front end for a language in GCC has the following parts:
424
425@itemize @bullet
426@item
427A directory @file{@var{language}} under @file{gcc} containing source
428files for that front end. @xref{Front End Directory, , The Front End
429@file{@var{language}} Directory}, for details.
430@item
431A mention of the language in the list of supported languages in
432@file{gcc/doc/install.texi}.
433@item
434Details of contributors to that front end in
435@file{gcc/doc/contrib.texi}. If the details are in that front end's
436own manual then there should be a link to that manual's list in
437@file{contrib.texi}.
438@item
439Information about support for that language in
440@file{gcc/doc/frontends.texi}.
441@item
442Information about standards for that language, and the front end's
443support for them, in @file{gcc/doc/standards.texi}. This may be a
444link to such information in the front end's own manual.
445@item
446Details of source file suffixes for that language and @option{-x
447@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
448@item
449Entries in @code{default_compilers} in @file{gcc.c} for source file
450suffixes for that language.
451@item
452Preferably test suites, which may be under @file{gcc/testsuite} or
453runtime library directories. FIXME: document somewhere how to write
454test suite harnesses.
455@item
456Probably a runtime library for the language, outside the @file{gcc}
457directory. FIXME: document this further.
458@item
459Details of the directories of any runtime libraries in
460@file{gcc/doc/sourcebuild.texi}.
461@end itemize
462
463If the front end is added to the official GCC CVS repository, the
464following are also necessary:
465
466@itemize @bullet
467@item
468At least one GNATS category for bugs in that front end and runtime
469libraries. This category needs to be mentioned in
470@file{gcc/gccbug.in}, and in @file{gnats.html} on the GCC web site, as
471well as being added to the GNATS database.
472@item
473Normally, one or more maintainers of that front end listed in
474@file{MAINTAINERS}.
475@item
476Mentions on the GCC web site in @file{index.html} and
477@file{frontends.html}, with any relevant links on
478@file{readings.html}. (Front ends that are not an official part of
479GCC may also be listed on @file{frontends.html}, with relevant links.)
480@item
481A news item on @file{index.html}, and possibly an announcement on the
482@email{gcc-announce@@gcc.gnu.org} mailing list.
483@item
484The front end's manuals should be mentioned in
485@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
486and the online manuals should be linked to from
487@file{onlinedocs/index.html}.
488@item
489Any old releases or CVS repositories of the front end, before its
490inclusion in GCC, should be made available on the GCC FTP site
491@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
492@item
493The release and snapshot script @file{maintainer-scripts/gcc_release}
494should be updated to generate appropriate tarballs for this front end.
495@item
496If this front end includes its own version files that include the
497current date, @file{maintainer-scripts/update_version} should be
498updated accordingly.
499@item
500@file{CVSROOT/modules} in the GCC CVS repository should be updated.
501@end itemize
502
503@menu
504* Front End Directory:: The front end @file{@var{language}} directory.
505* Front End Config:: The front end @file{config-lang.in} file.
506@end menu
507
508@node Front End Directory
509@subsubsection The Front End @file{@var{language}} Directory
510
511A front end @file{@var{language}} directory contains the source files
512of that front end (but not of any runtime libraries, which should be
513outside the @file{gcc} directory). This includes documentation, and
514possibly some subsidiary programs build alongside the front end.
515Certain files are special and other parts of the compiler depend on
516their names:
517
518@table @file
519@item config-lang.in
520This file is required in all language subdirectories. @xref{Front End
521Config, , The Front End @file{config-lang.in} File}, for details of
522its contents
523@item Make-lang.in
524This file is required in all language subdirectories. It contains
525targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
526setting of @code{language} in @file{config-lang.in}) for the following
527values of @code{@var{hook}}, and any other Makefile rules required to
528build those targets (which may if necessary use other Makefiles
529specified in @code{outputs} in @file{config-lang.in}, although this is
530deprecated).
531
532@table @code
533@item all.build
534@itemx all.cross
535@itemx start.encap
536@itemx rest.encap
537FIXME: exactly what goes in each of these targets?
538@item info
539Build info documentation for the front end, in the source directory.
540This target is only called by @command{make bootstrap} if a suitable
541version of @command{makeinfo} is available, so does not need to check
542for this, and should fail if an error occurs.
543@item dvi
544Build DVI documentation for the front end, in the build directory.
545This should be done using @code{$(TEXI2DVI)}, with appropriate
546@option{-I} arguments pointing to directories of included files.
547@item generated-manpages
548Build generated man pages for the front end from Texinfo manuals
549(@pxref{Man Page Generation}), in the source directory. This target
550is only called if the necessary tools are available, but should ignore
551errors so as not to stop the build if errors occur; man pages are
552optional and the tools involved may be installed in a broken way.
553@item install-normal
554FIXME: what is this target for?
555@item install-common
556Install everything that is part of the front end, apart from the
557compiler executables listed in @code{compilers} in
558@file{config-lang.in} that are installed in @file{@var{libsubdir}} by
559the main @file{Makefile}.
560@item install-info
561Install info documentation for the front end, if it is present in the
562source directory. (It may not be present if a suitable version of
563@command{makeinfo} was not installed.) This target should run the
564command @command{install-info} to update the info directory, but
565should ignore errors when running that command.
566@item install-man
567Install man pages for the front end. This target should ignore
568errors.
569@item uninstall
570Uninstall files installed by installing the compiler. This is
571currently documented not to be supported, so the hook need not do
572anything.
573@item mostlyclean
574@itemx clean
575@itemx distclean
576@itemx extraclean
577@itemx maintainer-clean
578Except for @code{extraclean}, the language parts of the standard GNU
579@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
580Users, standards, GNU Coding Standards}, for details of the standard
581targets. @code{extraclean} does @code{distclean} and also deletes
582anything likely to be found in the source directory that shouldn't be
583in the distribution. For GCC, @code{maintainer-clean} should delete
584all generated files in the source directory that are not checked into
585CVS, but should not delete anything checked into CVS@.
586@item stage1
587@itemx stage2
588@itemx stage3
589@itemx stage4
590Move to the stage directory files not included in @code{stagestuff} in
591@file{config-lang.in} or otherwise moved by the main @file{Makefile}.
592@end table
593
594@item lang-options.h
595This file provides entries for @code{documented_lang_options} in
596@file{toplev.c} describing command-line options the front end accepts
597for @option{--help} output.
598@item lang-specs.h
599This file provides entries for @code{default_compilers} in
600@file{gcc.c} which override the default of giving an error that a
601compiler for that language is not installed.
602@item @var{language}-tree.def
603This file, which need not exist, defines any language-specific tree
604codes.
605@end table
606
607@node Front End Config
608@subsubsection The Front End @file{config-lang.in} File
609
610Each language subdirectory contains a @file{config-lang.in} file.
611This file is a shell script that may define some variables describing
612the language:
613
614@table @code
615@item language
616This definition must be present, and gives the name of the language
617for some purposes such as arguments to @option{--enable-languages}.
618@item lang_requires
619If defined, this variable lists (space-separated) language front ends
620other than C that this front end requires to be enabled (with the
621names given being their @code{language} settings). For example, the
622Java front end depends on the C++ front end, so sets
623@samp{lang_requires=c++}.
624@item target_libs
625If defined, this variable lists (space-separated) targets in the top
626level @file{Makefile} to build the runtime libraries for this
627language, such as @code{target-libobjc}.
628@item lang_dirs
629If defined, this variable lists (space-separated) top level
630directories (parallel to @file{gcc}), apart from the runtime libraries,
631that should not be configured if this front end is not built.
632@item build_by_default
633If defined to @samp{no}, this language front end is not built unless
634enabled in a @option{--enable-languages} argument. Otherwise, front
635ends are built by default, subject to any special logic in
636@file{configure.in} (as is present to disable the Ada front end if the
637Ada compiler is not already installed).
638@item boot_language
639If defined to @samp{yes}, this front end is built in stage 1 of the
640bootstrap. This is only relevant to front ends written in their own
641languages.
642@item compilers
643If defined, a space-separated list of compiler executables that should
644be installed in @file{@var{libsubdir}}. The names here will each end
645with @samp{\$(exeext)}.
646@item stagestuff
647If defined, a space-separated list of files that should be moved to
648the @file{stage@var{n}} directories in each stage of bootstrap.
649@item outputs
650If defined, a space-separated list of files that should be generated
651by @file{configure} substituting values in them. This mechanism can
652be used to create a file @file{@var{language}/Makefile} from
653@file{@var{language}/Makefile.in}, but this is deprecated, building
654everything from the single @file{gcc/Makefile} is preferred.
655@end table
656
657@node Back End
658@subsection Anatomy of a Target Back End
659
660A back end for a target architecture in GCC has the following parts:
661
662@itemize @bullet
663@item
664A directory @file{@var{machine}} under @file{gcc/config}, containing a
665machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
666, Machine Descriptions}), header files @file{@var{machine}.h} and
667@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
668(@pxref{Target Macros, , Target Description Macros and Functions}),
669possibly a target Makefile fragment @file{t-@var{machine}}
670(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
671some other files. The names of these files may be changed from the
672defaults given by explicit specifications in @file{config.gcc}.
673@item
674Entries in @file{config.gcc} (@pxref{System Config, , The
675@file{config.gcc} File}) for the systems with this target
676architecture.
677@item
678Documentation in @file{gcc/doc/invoke.texi} for any command-line
679options supported by this target (@pxref{Run-time Target, , Run-time
680Target Specification}). This means both entries in the summary table
681of options and details of the individual options.
682@item
683Documentation in @file{gcc/doc/extend.texi} for any target-specific
684attributes supported (@pxref{Target Attributes, , Defining
685target-specific uses of @code{__attribute__}}), including where the
686same attribute is already supported on some targets, which are
687enumerated in the manual.
688@item
689Documentation in @file{gcc/doc/extend.texi} for any target-specific
690pragmas supported.
691@item
692Documentation in @file{gcc/doc/extend.texi} of any target-specific
693built-in functions supported.
694@item
695Documentation in @file{gcc/doc/md.texi} of any target-specific
696constraint letters (@pxref{Machine Constraints, , Constraints for
697Particular Machines}).
698@item
699A note in @file{gcc/doc/contrib.texi} under the person or people who
700contributed the target support.
701@item
702Entries in @file{gcc/doc/install.texi} for all target triplets
703supported with this target architecture, giving details of any special
704notes about installation for this target, or saying that there are no
705special notes if there are none.
706@item
707Possibly other support outside the @file{gcc} directory for runtime
708libraries. FIXME: reference docs for this. The libstdc++ porting
709manual needs to be installed as info for this to work, or to be a
710chapter of this manual.
711@end itemize
712
713If the back end is added to the official GCC CVS repository, the
714following are also necessary:
715
716@itemize @bullet
717@item
718An entry for the target architecture in @file{readings.html} on the
719GCC web site, with any relevant links.
720@item
721A news item about the contribution of support for that target
722architecture, in @file{index.html} on the GCC web site.
723@item
724Normally, one or more maintainers of that target listed in
725@file{MAINTAINERS}. Some existing architectures may be unmaintained,
726but it would be unusual to add support for a target that does not have
727a maintainer when support is added.
728@end itemize
729
730@node Test Suites
731@section Test Suites
732
733GCC contains several test suites to help maintain compiler quality.
734Most of the runtime libraries and language front ends in GCC have test
735suites. Currently only the C language test suites are documented
736here; FIXME: document the others.
737
738@menu
739* Test Idioms:: Idioms used in test suite code.
740* C Tests:: The C language test suites.
| 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.
4
5@node Source Tree
6@chapter Source Tree Structure and Build System
7
8This chapter describes the structure of the GCC source tree, and how
9GCC is built. The user documentation for building and installing GCC
10is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
11which it is presumed that you are familiar.
12
13@menu
14* Configure Terms:: Configuration terminology and history.
15* Top Level:: The top level source directory.
16* gcc Directory:: The @file{gcc} subdirectory.
17* Test Suites:: The GCC test suites.
18@end menu
19
20@include configterms.texi
21
22@node Top Level
23@section Top Level Source Directory
24
25The top level source directory in a GCC distribution contains several
26files and directories that are shared with other software
27distributions such as that of GNU Binutils. It also contains several
28subdirectories that contain parts of GCC and its runtime libraries:
29
30@table @file
31@item boehm-gc
32The Boehm conservative garbage collector, used as part of the Java
33runtime library.
34
35@item contrib
36Contributed scripts that may be found useful in conjunction with GCC@.
37One of these, @file{contrib/texi2pod.pl}, is used to generate man
38pages from Texinfo manuals as part of the GCC build process.
39
40@item fastjar
41An implementation of the @command{jar} command, used with the Java
42front end.
43
44@item gcc
45The main sources of GCC itself (except for runtime libraries),
46including optimizers, support for different target architectures,
47language front ends, and test suites. @xref{gcc Directory, , The
48@file{gcc} Subdirectory}, for details.
49
50@item include
51Headers for the @code{libiberty} library.
52
53@item libf2c
54The Fortran runtime library.
55
56@item libffi
57The @code{libffi} library, used as part of the Java runtime library.
58
59@item libiberty
60The @code{libiberty} library, used for portability and for some
61generally useful data structures and algorithms. @xref{Top, ,
62Introduction, libiberty, @sc{gnu} libiberty}, for more information
63about this library.
64
65@item libjava
66The Java runtime library.
67
68@item libobjc
69The Objective-C runtime library.
70
71@item libstdc++-v3
72The C++ runtime library.
73
74@item maintainer-scripts
75Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
76
77@item zlib
78The @code{zlib} compression library, used by the Java front end and as
79part of the Java runtime library.
80@end table
81
82The build system in the top level directory, including how recursion
83into subdirectories works and how building runtime libraries for
84multilibs is handled, is documented in a separate manual, included
85with GNU Binutils. @xref{Top, , GNU configure and build system,
86configure, The GNU configure and build system}, for details.
87
88@node gcc Directory
89@section The @file{gcc} Subdirectory
90
91The @file{gcc} directory contains many files that are part of the C
92sources of GCC, other files used as part of the configuration and
93build process, and subdirectories including documentation and a
94test suite. The files that are sources of GCC are documented in a
95separate chapter. @xref{Passes, , Passes and Files of the Compiler}.
96
97@menu
98* Subdirectories:: Subdirectories of @file{gcc}.
99* Configuration:: The configuration process, and the files it uses.
100* Build:: The build system in the @file{gcc} directory.
101* Makefile:: Targets in @file{gcc/Makefile}.
102* Library Files:: Library source files and headers under @file{gcc/}.
103* Headers:: Headers installed by GCC.
104* Documentation:: Building documentation in GCC.
105* Front End:: Anatomy of a language front end.
106* Back End:: Anatomy of a target back end.
107@end menu
108
109@node Subdirectories
110@subsection Subdirectories of @file{gcc}
111
112The @file{gcc} directory contains the following subdirectories:
113
114@table @file
115@item @var{language}
116Subdirectories for various languages. Directories containing a file
117@file{config-lang.in} are language subdirectories. The contents of
118the subdirectories @file{cp} (for C++) and @file{objc} (for
119Objective-C) are documented in this manual (@pxref{Passes, , Passes
120and Files of the Compiler}); those for other languages are not.
121@xref{Front End, , Anatomy of a Language Front End}, for details of
122the files in these directories.
123
124@item config
125Configuration files for supported architectures and operating
126systems. @xref{Back End, , Anatomy of a Target Back End}, for
127details of the files in thie directory.
128
129@item doc
130Texinfo documentation for GCC, together with automatically generated
131man pages and support for converting the installation manual to
132HTML@. @xref{Documentation}.
133
134@item fixinc
135The support for fixing system headers to work with GCC@. See
136@file{fixinc/README} for more information. The headers fixed by this
137mechanism are installed in @file{@var{libsubdir}/include}. Along with
138those headers, @file{README-fixinc} is also installed, as
139@file{@var{libsubdir}/include/README}.
140
141@item ginclude
142System headers installed by GCC, mainly those required by the C
143standard of freestanding implementations. @xref{Headers, , Headers
144Installed by GCC}, for details of when these and other headers are
145installed.
146
147@item intl
148GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
149include it in libc. Properly, this directory should be at top level,
150parallel to the @file{gcc} directory.
151
152@item po
153Message catalogs with translations of messages produced by GCC into
154various languages, @file{@var{language}.po}. This directory also
155contains @file{gcc.pot}, the template for these message catalogues,
156@file{exgettext}, a wrapper around @command{gettext} to extract the
157messages from the GCC sources and create @file{gcc.pot}, which is run
158by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
159which messages should not be extracted.
160
161@item testsuite
162The GCC test suites (except for those for runtime libraries).
163@xref{Test Suites}.
164@end table
165
166@node Configuration
167@subsection Configuration in the @file{gcc} Directory
168
169The @file{gcc} directory is configured with an Autoconf-generated
170script @file{configure}. The @file{configure} script is generated
171from @file{configure.in} and @file{aclocal.m4}. From the files
172@file{configure.in} and @file{acconfig.h}, Autoheader generates the
173file @file{config.in}. The file @file{cstamp-h.in} is used as a
174timestamp.
175
176@menu
177* Config Fragments:: Scripts used by @file{configure}.
178* System Config:: The @file{config.gcc} file.
179* Configuration Files:: Files created by running @file{configure}.
180@end menu
181
182@node Config Fragments
183@subsubsection Scripts Used by @file{configure}
184
185@file{configure} uses some other scripts to help in its work:
186
187@itemize @bullet
188@item The standard GNU @file{config.sub} and @file{config.guess}
189files, 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
191the top level one) used?
192
193@item The file @file{config.gcc} is used to handle configuration
194specific to the particular build, host or target machine. (In
195general, this should only be used for features that cannot reasonably
196be tested in Autoconf feature tests.) @xref{System Config, , The
197@file{config.gcc} File}, for details of the contents of this file.
198
199@item Each language subdirectory has a file
200@file{@var{language}/config-lang.in} that is used for
201front-end-specific configuration. @xref{Front End Config, , The Front
202End @file{config-lang.in} File}, for details of this file.
203
204@item A helper script @file{configure.frag} is used as part of
205creating the output of @file{configure}.
206@end itemize
207
208@node System Config
209@subsubsection The @file{config.gcc} File
210
211FIXME: document the contents of this file, and what variables should
212be set to control build, host and target configuration.
213
214@include configfiles.texi
215
216@node Build
217@subsection Build System in the @file{gcc} Directory
218
219FIXME: describe the build system, including what is built in what
220stages. Also list the various source files that are used in the build
221process but aren't source files of GCC itself and so aren't documented
222below (@pxref{Passes}).
223
224@include makefile.texi
225
226@node Library Files
227@subsection Library Source Files and Headers under the @file{gcc} Directory
228
229FIXME: list here, with explanation, all the C source files and headers
230under the @file{gcc} directory that aren't built into the GCC
231executable but rather are part of runtime libraries and object files,
232such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, ,
233Headers Installed by GCC}, for more information about the
234@file{ginclude} directory.
235
236@node Headers
237@subsection Headers Installed by GCC
238
239In general, GCC expects the system C library to provide most of the
240headers to be used with it. However, GCC will fix those headers if
241necessary to make them work with GCC, and will install some headers
242required of freestanding implementations. These headers are installed
243in @file{@var{libsubdir}/include}. Headers for non-C runtime
244libraries are also installed by GCC; these are not documented here.
245(FIXME: document them somewhere.)
246
247Several of the headers GCC installs are in the @file{ginclude}
248directory. These headers, @file{iso646.h},
249@file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and
250@file{varargs.h}, are installed in @file{@var{libsubdir}/include},
251unless the target Makefile fragment (@pxref{Target Fragment})
252overrides this by setting @code{USER_H}.
253
254In addition to these headers and those generated by fixing system
255headers 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. GCC normally installs
259a @code{<float.h>} file; these are kept as
260@file{config/float-@var{format}.h}, where @var{format} is specified by
261a @code{float_format} setting in @file{config.gcc}, and a setting
262@samp{float_format=none} disables installation of this header. GCC
263also installs its own version of @code{<limits.h>}; this is generated
264from @file{glimits.h}, together with @file{limitx.h} and
265@file{limity.h} if the system also has its own version of
266@code{<limits.h>}. (GCC provides its own header because it is
267required of ISO C freestanding implementations, but needs to include
268the system header from its own header as well because other standards
269such as POSIX specify additional values to be defined in
270@code{<limits.h>}.) The system's @code{<limits.h>} header is used via
271@file{@var{libsubdir}/include/syslimits.h}, which is copied from
272@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
273needs fixing, @file{syslimits.h} is the fixed copy.
274
275@node Documentation
276@subsection Building Documentation
277
278The main GCC documentation is in the form of manuals in Texinfo
279format. These are installed in Info format, and DVI versions may be
280generated by @command{make dvi}. In addition, some man pages are
281generated from the Texinfo manuals, there are some other text files
282with miscellaneous documentation, and runtime libraries have their own
283documentation outside the @file{gcc} directory. FIXME: document the
284documentation for runtime libraries somewhere.
285
286@menu
287* Texinfo Manuals:: GCC manuals in Texinfo format.
288* Man Page Generation:: Generating man pages from Texinfo manuals.
289* Miscellaneous Docs:: Miscellaneous text files with documentation.
290@end menu
291
292@node Texinfo Manuals
293@subsubsection Texinfo Manuals
294
295The manuals for GCC as a whole, and the C and C++ front ends, are in
296files @file{doc/*.texi}. Other front ends have their own manuals in
297files @file{@var{language}/*.texi}. Common files
298@file{doc/include/*.texi} are provided which may be included in
299multiple manuals; the following files are in @file{doc/include}:
300
301@table @file
302@item fdl.texi
303The GNU Free Documentation License.
304@item funding.texi
305The section ``Funding Free Software''.
306@item gcc-common.texi
307Common definitions for manuals.
308@item gpl.texi
309The GNU General Public License.
310@item texinfo.tex
311A copy of @file{texinfo.tex} known to work with the GCC manuals.
312@end table
313
314DVI formatted manuals are generated by @command{make dvi}, which uses
315@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
316manuals are generated by @command{make info} (which is run as part of
317a bootstrap); this generates the manuals in the source directory,
318using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
319and they are included in release distributions.
320
321Manuals are also provided on the GCC web site, in both HTML and
322PostScript forms. This is done via the script
323@file{maintainer-scripts/update_web_docs}. Each manual to be
324provided online must be listed in the definition of @code{MANUALS} in
325that file; a file @file{@var{name}.texi} must only appear once in the
326source tree, and the output manual must have the same name as the
327source file. (However, other Texinfo files, included in manuals but
328not themselves the root files of manuals, may have names that appear
329more than once in the source tree.) The manual file
330@file{@var{name}.texi} should only include other files in its own
331directory or in @file{doc/include}. HTML manuals will be generated by
332@command{makeinfo --html} and PostScript manuals by @command{texi2dvi}
333and @command{dvips}. All Texinfo files that are parts of manuals must
334be checked into CVS, even if they are generated files, for the
335generation of online manuals to work.
336
337The installation manual, @file{doc/install.texi}, is also provided on
338the GCC web site. The HTML version is generated by the script
339@file{doc/install.texi2html}.
340
341@node Man Page Generation
342@subsubsection Man Page Generation
343
344Because of user demand, in addition to full Texinfo manuals, man pages
345are provided which contain extracts from those manuals. These man
346pages are generated from the Texinfo manuals using
347@file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for
348@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
349to @file{gcc.1}, but all the other man pages are generated from
350Texinfo manuals.)
351
352Because many systems may not have the necessary tools installed to
353generate the man pages, they are only generated if the
354@file{configure} script detects that recent enough tools are
355installed, and the Makefiles allow generating man pages to fail
356without aborting the build. Man pages are also included in release
357distributions. They are generated in the source directory.
358
359Magic comments in Texinfo files starting @samp{@@c man} control what
360parts of a Texinfo file go into a man page. Only a subset of Texinfo
361is supported by @file{texi2pod.pl}, and it may be necessary to add
362support for more Texinfo features to this script when generating new
363man pages. To improve the man page output, some special Texinfo
364macros are provided in @file{doc/include/gcc-common.texi} which
365@file{texi2pod.pl} understands:
366
367@table @code
368@item @@gcctabopt
369Use in the form @samp{@@table @@gcctabopt} for tables of options,
370where for printed output the effect of @samp{@@code} is better than
371that of @samp{@@option} but for man page output a different effect is
372wanted.
373@item @@gccoptlist
374Use for summary lists of options in manuals.
375@item @@gol
376Use at the end of each line inside @samp{@@gccoptlist}. This is
377necessary to avoid problems with differences in how the
378@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
379@end table
380
381FIXME: describe the @file{texi2pod.pl} input language and magic
382comments in more detail.
383
384@node Miscellaneous Docs
385@subsubsection Miscellaneous Documentation
386
387In addition to the formal documentation that is installed by GCC,
388there are several other text files with miscellaneous documentation:
389
390@table @file
391@item ABOUT-GCC-NLS
392Notes on GCC's Native Language Support. FIXME: this should be part of
393this manual rather than a separate file.
394@item ABOUT-NLS
395Notes on the Free Translation Project.
396@item COPYING
397The GNU General Public License.
398@item COPYING.LIB
399The GNU Lesser General Public License.
400@item *ChangeLog*
401@itemx */ChangeLog*
402Change log files for various parts of GCC@.
403@item LANGUAGES
404Details of a few changes to the GCC front-end interface. FIXME: the
405information in this file should be part of general documentation of
406the front-end interface in this manual.
407@item ONEWS
408Information about new features in old versions of GCC@. (For recent
409versions, the information is on the GCC web site.)
410@item README.Portability
411Information about portability issues when writing code in GCC@. FIXME:
412why isn't this part of this manual or of the GCC Coding Conventions?
413@item SERVICE
414A pointer to the GNU Service Directory.
415@end table
416
417FIXME: document such files in subdirectories, at least @file{config},
418@file{cp}, @file{objc}, @file{testsuite}.
419
420@node Front End
421@subsection Anatomy of a Language Front End
422
423A front end for a language in GCC has the following parts:
424
425@itemize @bullet
426@item
427A directory @file{@var{language}} under @file{gcc} containing source
428files for that front end. @xref{Front End Directory, , The Front End
429@file{@var{language}} Directory}, for details.
430@item
431A mention of the language in the list of supported languages in
432@file{gcc/doc/install.texi}.
433@item
434Details of contributors to that front end in
435@file{gcc/doc/contrib.texi}. If the details are in that front end's
436own manual then there should be a link to that manual's list in
437@file{contrib.texi}.
438@item
439Information about support for that language in
440@file{gcc/doc/frontends.texi}.
441@item
442Information about standards for that language, and the front end's
443support for them, in @file{gcc/doc/standards.texi}. This may be a
444link to such information in the front end's own manual.
445@item
446Details of source file suffixes for that language and @option{-x
447@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
448@item
449Entries in @code{default_compilers} in @file{gcc.c} for source file
450suffixes for that language.
451@item
452Preferably test suites, which may be under @file{gcc/testsuite} or
453runtime library directories. FIXME: document somewhere how to write
454test suite harnesses.
455@item
456Probably a runtime library for the language, outside the @file{gcc}
457directory. FIXME: document this further.
458@item
459Details of the directories of any runtime libraries in
460@file{gcc/doc/sourcebuild.texi}.
461@end itemize
462
463If the front end is added to the official GCC CVS repository, the
464following are also necessary:
465
466@itemize @bullet
467@item
468At least one GNATS category for bugs in that front end and runtime
469libraries. This category needs to be mentioned in
470@file{gcc/gccbug.in}, and in @file{gnats.html} on the GCC web site, as
471well as being added to the GNATS database.
472@item
473Normally, one or more maintainers of that front end listed in
474@file{MAINTAINERS}.
475@item
476Mentions on the GCC web site in @file{index.html} and
477@file{frontends.html}, with any relevant links on
478@file{readings.html}. (Front ends that are not an official part of
479GCC may also be listed on @file{frontends.html}, with relevant links.)
480@item
481A news item on @file{index.html}, and possibly an announcement on the
482@email{gcc-announce@@gcc.gnu.org} mailing list.
483@item
484The front end's manuals should be mentioned in
485@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
486and the online manuals should be linked to from
487@file{onlinedocs/index.html}.
488@item
489Any old releases or CVS repositories of the front end, before its
490inclusion in GCC, should be made available on the GCC FTP site
491@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
492@item
493The release and snapshot script @file{maintainer-scripts/gcc_release}
494should be updated to generate appropriate tarballs for this front end.
495@item
496If this front end includes its own version files that include the
497current date, @file{maintainer-scripts/update_version} should be
498updated accordingly.
499@item
500@file{CVSROOT/modules} in the GCC CVS repository should be updated.
501@end itemize
502
503@menu
504* Front End Directory:: The front end @file{@var{language}} directory.
505* Front End Config:: The front end @file{config-lang.in} file.
506@end menu
507
508@node Front End Directory
509@subsubsection The Front End @file{@var{language}} Directory
510
511A front end @file{@var{language}} directory contains the source files
512of that front end (but not of any runtime libraries, which should be
513outside the @file{gcc} directory). This includes documentation, and
514possibly some subsidiary programs build alongside the front end.
515Certain files are special and other parts of the compiler depend on
516their names:
517
518@table @file
519@item config-lang.in
520This file is required in all language subdirectories. @xref{Front End
521Config, , The Front End @file{config-lang.in} File}, for details of
522its contents
523@item Make-lang.in
524This file is required in all language subdirectories. It contains
525targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
526setting of @code{language} in @file{config-lang.in}) for the following
527values of @code{@var{hook}}, and any other Makefile rules required to
528build those targets (which may if necessary use other Makefiles
529specified in @code{outputs} in @file{config-lang.in}, although this is
530deprecated).
531
532@table @code
533@item all.build
534@itemx all.cross
535@itemx start.encap
536@itemx rest.encap
537FIXME: exactly what goes in each of these targets?
538@item info
539Build info documentation for the front end, in the source directory.
540This target is only called by @command{make bootstrap} if a suitable
541version of @command{makeinfo} is available, so does not need to check
542for this, and should fail if an error occurs.
543@item dvi
544Build DVI documentation for the front end, in the build directory.
545This should be done using @code{$(TEXI2DVI)}, with appropriate
546@option{-I} arguments pointing to directories of included files.
547@item generated-manpages
548Build generated man pages for the front end from Texinfo manuals
549(@pxref{Man Page Generation}), in the source directory. This target
550is only called if the necessary tools are available, but should ignore
551errors so as not to stop the build if errors occur; man pages are
552optional and the tools involved may be installed in a broken way.
553@item install-normal
554FIXME: what is this target for?
555@item install-common
556Install everything that is part of the front end, apart from the
557compiler executables listed in @code{compilers} in
558@file{config-lang.in} that are installed in @file{@var{libsubdir}} by
559the main @file{Makefile}.
560@item install-info
561Install info documentation for the front end, if it is present in the
562source directory. (It may not be present if a suitable version of
563@command{makeinfo} was not installed.) This target should run the
564command @command{install-info} to update the info directory, but
565should ignore errors when running that command.
566@item install-man
567Install man pages for the front end. This target should ignore
568errors.
569@item uninstall
570Uninstall files installed by installing the compiler. This is
571currently documented not to be supported, so the hook need not do
572anything.
573@item mostlyclean
574@itemx clean
575@itemx distclean
576@itemx extraclean
577@itemx maintainer-clean
578Except for @code{extraclean}, the language parts of the standard GNU
579@samp{*clean} targets. @xref{Standard Targets, , Standard Targets for
580Users, standards, GNU Coding Standards}, for details of the standard
581targets. @code{extraclean} does @code{distclean} and also deletes
582anything likely to be found in the source directory that shouldn't be
583in the distribution. For GCC, @code{maintainer-clean} should delete
584all generated files in the source directory that are not checked into
585CVS, but should not delete anything checked into CVS@.
586@item stage1
587@itemx stage2
588@itemx stage3
589@itemx stage4
590Move to the stage directory files not included in @code{stagestuff} in
591@file{config-lang.in} or otherwise moved by the main @file{Makefile}.
592@end table
593
594@item lang-options.h
595This file provides entries for @code{documented_lang_options} in
596@file{toplev.c} describing command-line options the front end accepts
597for @option{--help} output.
598@item lang-specs.h
599This file provides entries for @code{default_compilers} in
600@file{gcc.c} which override the default of giving an error that a
601compiler for that language is not installed.
602@item @var{language}-tree.def
603This file, which need not exist, defines any language-specific tree
604codes.
605@end table
606
607@node Front End Config
608@subsubsection The Front End @file{config-lang.in} File
609
610Each language subdirectory contains a @file{config-lang.in} file.
611This file is a shell script that may define some variables describing
612the language:
613
614@table @code
615@item language
616This definition must be present, and gives the name of the language
617for some purposes such as arguments to @option{--enable-languages}.
618@item lang_requires
619If defined, this variable lists (space-separated) language front ends
620other than C that this front end requires to be enabled (with the
621names given being their @code{language} settings). For example, the
622Java front end depends on the C++ front end, so sets
623@samp{lang_requires=c++}.
624@item target_libs
625If defined, this variable lists (space-separated) targets in the top
626level @file{Makefile} to build the runtime libraries for this
627language, such as @code{target-libobjc}.
628@item lang_dirs
629If defined, this variable lists (space-separated) top level
630directories (parallel to @file{gcc}), apart from the runtime libraries,
631that should not be configured if this front end is not built.
632@item build_by_default
633If defined to @samp{no}, this language front end is not built unless
634enabled in a @option{--enable-languages} argument. Otherwise, front
635ends are built by default, subject to any special logic in
636@file{configure.in} (as is present to disable the Ada front end if the
637Ada compiler is not already installed).
638@item boot_language
639If defined to @samp{yes}, this front end is built in stage 1 of the
640bootstrap. This is only relevant to front ends written in their own
641languages.
642@item compilers
643If defined, a space-separated list of compiler executables that should
644be installed in @file{@var{libsubdir}}. The names here will each end
645with @samp{\$(exeext)}.
646@item stagestuff
647If defined, a space-separated list of files that should be moved to
648the @file{stage@var{n}} directories in each stage of bootstrap.
649@item outputs
650If defined, a space-separated list of files that should be generated
651by @file{configure} substituting values in them. This mechanism can
652be used to create a file @file{@var{language}/Makefile} from
653@file{@var{language}/Makefile.in}, but this is deprecated, building
654everything from the single @file{gcc/Makefile} is preferred.
655@end table
656
657@node Back End
658@subsection Anatomy of a Target Back End
659
660A back end for a target architecture in GCC has the following parts:
661
662@itemize @bullet
663@item
664A directory @file{@var{machine}} under @file{gcc/config}, containing a
665machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
666, Machine Descriptions}), header files @file{@var{machine}.h} and
667@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
668(@pxref{Target Macros, , Target Description Macros and Functions}),
669possibly a target Makefile fragment @file{t-@var{machine}}
670(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
671some other files. The names of these files may be changed from the
672defaults given by explicit specifications in @file{config.gcc}.
673@item
674Entries in @file{config.gcc} (@pxref{System Config, , The
675@file{config.gcc} File}) for the systems with this target
676architecture.
677@item
678Documentation in @file{gcc/doc/invoke.texi} for any command-line
679options supported by this target (@pxref{Run-time Target, , Run-time
680Target Specification}). This means both entries in the summary table
681of options and details of the individual options.
682@item
683Documentation in @file{gcc/doc/extend.texi} for any target-specific
684attributes supported (@pxref{Target Attributes, , Defining
685target-specific uses of @code{__attribute__}}), including where the
686same attribute is already supported on some targets, which are
687enumerated in the manual.
688@item
689Documentation in @file{gcc/doc/extend.texi} for any target-specific
690pragmas supported.
691@item
692Documentation in @file{gcc/doc/extend.texi} of any target-specific
693built-in functions supported.
694@item
695Documentation in @file{gcc/doc/md.texi} of any target-specific
696constraint letters (@pxref{Machine Constraints, , Constraints for
697Particular Machines}).
698@item
699A note in @file{gcc/doc/contrib.texi} under the person or people who
700contributed the target support.
701@item
702Entries in @file{gcc/doc/install.texi} for all target triplets
703supported with this target architecture, giving details of any special
704notes about installation for this target, or saying that there are no
705special notes if there are none.
706@item
707Possibly other support outside the @file{gcc} directory for runtime
708libraries. FIXME: reference docs for this. The libstdc++ porting
709manual needs to be installed as info for this to work, or to be a
710chapter of this manual.
711@end itemize
712
713If the back end is added to the official GCC CVS repository, the
714following are also necessary:
715
716@itemize @bullet
717@item
718An entry for the target architecture in @file{readings.html} on the
719GCC web site, with any relevant links.
720@item
721A news item about the contribution of support for that target
722architecture, in @file{index.html} on the GCC web site.
723@item
724Normally, one or more maintainers of that target listed in
725@file{MAINTAINERS}. Some existing architectures may be unmaintained,
726but it would be unusual to add support for a target that does not have
727a maintainer when support is added.
728@end itemize
729
730@node Test Suites
731@section Test Suites
732
733GCC contains several test suites to help maintain compiler quality.
734Most of the runtime libraries and language front ends in GCC have test
735suites. Currently only the C language test suites are documented
736here; FIXME: document the others.
737
738@menu
739* Test Idioms:: Idioms used in test suite code.
740* C Tests:: The C language test suites.
|