]>
Commit | Line | Data |
---|---|---|
56ae1316 | 1 | @c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc. |
0a553c7e JM |
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 | ||
8 | This chapter describes the structure of the GCC source tree, and how | |
9 | GCC is built. The user documentation for building and installing GCC | |
10 | is in a separate manual (@uref{http://gcc.gnu.org/install/}), with | |
11 | which it is presumed that you are familiar. | |
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. | |
2eac577f | 17 | * Testsuites:: The GCC testsuites. |
0a553c7e JM |
18 | @end menu |
19 | ||
20 | @include configterms.texi | |
21 | ||
22 | @node Top Level | |
23 | @section Top Level Source Directory | |
24 | ||
25 | The top level source directory in a GCC distribution contains several | |
26 | files and directories that are shared with other software | |
27 | distributions such as that of GNU Binutils. It also contains several | |
28 | subdirectories that contain parts of GCC and its runtime libraries: | |
29 | ||
30 | @table @file | |
31 | @item boehm-gc | |
32 | The Boehm conservative garbage collector, used as part of the Java | |
33 | runtime library. | |
34 | ||
35 | @item contrib | |
36 | Contributed scripts that may be found useful in conjunction with GCC@. | |
37 | One of these, @file{contrib/texi2pod.pl}, is used to generate man | |
38 | pages from Texinfo manuals as part of the GCC build process. | |
39 | ||
40 | @item fastjar | |
41 | An implementation of the @command{jar} command, used with the Java | |
42 | front end. | |
43 | ||
44 | @item gcc | |
45 | The main sources of GCC itself (except for runtime libraries), | |
46 | including optimizers, support for different target architectures, | |
2eac577f | 47 | language front ends, and testsuites. @xref{gcc Directory, , The |
0a553c7e JM |
48 | @file{gcc} Subdirectory}, for details. |
49 | ||
50 | @item include | |
51 | Headers for the @code{libiberty} library. | |
52 | ||
cd271054 AC |
53 | @item libada |
54 | The Ada runtime library. | |
55 | ||
fc55c95e RM |
56 | @item libbanshee |
57 | The @code{libbanshee} library, used for Andersen-style points-to analysis. | |
58 | ||
3c95eb0e GDR |
59 | @item libcpp |
60 | The C preprocessor library. | |
61 | ||
6de9cd9a | 62 | @item libgfortran |
0a553c7e JM |
63 | The Fortran runtime library. |
64 | ||
65 | @item libffi | |
66 | The @code{libffi} library, used as part of the Java runtime library. | |
67 | ||
68 | @item libiberty | |
81034129 | 69 | The @code{libiberty} library, used for portability and for some |
0a553c7e JM |
70 | generally useful data structures and algorithms. @xref{Top, , |
71 | Introduction, libiberty, @sc{gnu} libiberty}, for more information | |
72 | about this library. | |
73 | ||
74 | @item libjava | |
75 | The Java runtime library. | |
76 | ||
fc55c95e RM |
77 | @item libmudflap |
78 | The @code{libmudflap} library, used for instrumenting pointer and array | |
79 | dereferencing operations. | |
80 | ||
0a553c7e JM |
81 | @item libobjc |
82 | The Objective-C runtime library. | |
83 | ||
84 | @item libstdc++-v3 | |
85 | The C++ runtime library. | |
86 | ||
87 | @item maintainer-scripts | |
88 | Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. | |
89 | ||
90 | @item zlib | |
91 | The @code{zlib} compression library, used by the Java front end and as | |
92 | part of the Java runtime library. | |
93 | @end table | |
94 | ||
95 | The build system in the top level directory, including how recursion | |
96 | into subdirectories works and how building runtime libraries for | |
97 | multilibs is handled, is documented in a separate manual, included | |
98 | with GNU Binutils. @xref{Top, , GNU configure and build system, | |
99 | configure, The GNU configure and build system}, for details. | |
100 | ||
101 | @node gcc Directory | |
102 | @section The @file{gcc} Subdirectory | |
103 | ||
104 | The @file{gcc} directory contains many files that are part of the C | |
105 | sources of GCC, other files used as part of the configuration and | |
106 | build process, and subdirectories including documentation and a | |
2eac577f | 107 | testsuite. The files that are sources of GCC are documented in a |
0a553c7e JM |
108 | separate chapter. @xref{Passes, , Passes and Files of the Compiler}. |
109 | ||
110 | @menu | |
111 | * Subdirectories:: Subdirectories of @file{gcc}. | |
112 | * Configuration:: The configuration process, and the files it uses. | |
113 | * Build:: The build system in the @file{gcc} directory. | |
114 | * Makefile:: Targets in @file{gcc/Makefile}. | |
115 | * Library Files:: Library source files and headers under @file{gcc/}. | |
116 | * Headers:: Headers installed by GCC. | |
117 | * Documentation:: Building documentation in GCC. | |
118 | * Front End:: Anatomy of a language front end. | |
119 | * Back End:: Anatomy of a target back end. | |
120 | @end menu | |
121 | ||
122 | @node Subdirectories | |
123 | @subsection Subdirectories of @file{gcc} | |
124 | ||
125 | The @file{gcc} directory contains the following subdirectories: | |
126 | ||
127 | @table @file | |
128 | @item @var{language} | |
129 | Subdirectories for various languages. Directories containing a file | |
130 | @file{config-lang.in} are language subdirectories. The contents of | |
131 | the subdirectories @file{cp} (for C++) and @file{objc} (for | |
132 | Objective-C) are documented in this manual (@pxref{Passes, , Passes | |
133 | and Files of the Compiler}); those for other languages are not. | |
134 | @xref{Front End, , Anatomy of a Language Front End}, for details of | |
135 | the files in these directories. | |
136 | ||
137 | @item config | |
138 | Configuration files for supported architectures and operating | |
139 | systems. @xref{Back End, , Anatomy of a Target Back End}, for | |
c0cbdbd9 | 140 | details of the files in this directory. |
0a553c7e JM |
141 | |
142 | @item doc | |
143 | Texinfo documentation for GCC, together with automatically generated | |
144 | man pages and support for converting the installation manual to | |
145 | HTML@. @xref{Documentation}. | |
146 | ||
147 | @item fixinc | |
148 | The support for fixing system headers to work with GCC@. See | |
149 | @file{fixinc/README} for more information. The headers fixed by this | |
150 | mechanism are installed in @file{@var{libsubdir}/include}. Along with | |
151 | those headers, @file{README-fixinc} is also installed, as | |
152 | @file{@var{libsubdir}/include/README}. | |
153 | ||
154 | @item ginclude | |
155 | System headers installed by GCC, mainly those required by the C | |
156 | standard of freestanding implementations. @xref{Headers, , Headers | |
157 | Installed by GCC}, for details of when these and other headers are | |
158 | installed. | |
159 | ||
160 | @item intl | |
161 | GNU @code{libintl}, from GNU @code{gettext}, for systems which do not | |
162 | include it in libc. Properly, this directory should be at top level, | |
163 | parallel to the @file{gcc} directory. | |
164 | ||
165 | @item po | |
166 | Message catalogs with translations of messages produced by GCC into | |
167 | various languages, @file{@var{language}.po}. This directory also | |
168 | contains @file{gcc.pot}, the template for these message catalogues, | |
169 | @file{exgettext}, a wrapper around @command{gettext} to extract the | |
170 | messages from the GCC sources and create @file{gcc.pot}, which is run | |
7ba4ca63 | 171 | by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from |
0a553c7e JM |
172 | which messages should not be extracted. |
173 | ||
174 | @item testsuite | |
2eac577f JM |
175 | The GCC testsuites (except for those for runtime libraries). |
176 | @xref{Testsuites}. | |
0a553c7e JM |
177 | @end table |
178 | ||
179 | @node Configuration | |
180 | @subsection Configuration in the @file{gcc} Directory | |
181 | ||
182 | The @file{gcc} directory is configured with an Autoconf-generated | |
183 | script @file{configure}. The @file{configure} script is generated | |
3986a20d KC |
184 | from @file{configure.ac} and @file{aclocal.m4}. From the files |
185 | @file{configure.ac} and @file{acconfig.h}, Autoheader generates the | |
0a553c7e JM |
186 | file @file{config.in}. The file @file{cstamp-h.in} is used as a |
187 | timestamp. | |
188 | ||
189 | @menu | |
190 | * Config Fragments:: Scripts used by @file{configure}. | |
330532ab NN |
191 | * System Config:: The @file{config.build}, @file{config.host}, and |
192 | @file{config.gcc} files. | |
0a553c7e JM |
193 | * Configuration Files:: Files created by running @file{configure}. |
194 | @end menu | |
195 | ||
196 | @node Config Fragments | |
197 | @subsubsection Scripts Used by @file{configure} | |
198 | ||
199 | @file{configure} uses some other scripts to help in its work: | |
200 | ||
201 | @itemize @bullet | |
202 | @item The standard GNU @file{config.sub} and @file{config.guess} | |
203 | files, kept in the top level directory, are used. FIXME: when is the | |
204 | @file{config.guess} file in the @file{gcc} directory (that just calls | |
205 | the top level one) used? | |
206 | ||
207 | @item The file @file{config.gcc} is used to handle configuration | |
daf2f129 JM |
208 | specific to the particular target machine. The file |
209 | @file{config.build} is used to handle configuration specific to the | |
330532ab NN |
210 | particular build machine. The file @file{config.host} is used to handle |
211 | configuration specific to the particular host machine. (In general, | |
212 | these should only be used for features that cannot reasonably be tested in | |
213 | Autoconf feature tests.) | |
640d429d | 214 | @xref{System Config, , The @file{config.build}; @file{config.host}; |
330532ab | 215 | and @file{config.gcc} Files}, for details of the contents of these files. |
0a553c7e JM |
216 | |
217 | @item Each language subdirectory has a file | |
218 | @file{@var{language}/config-lang.in} that is used for | |
219 | front-end-specific configuration. @xref{Front End Config, , The Front | |
220 | End @file{config-lang.in} File}, for details of this file. | |
221 | ||
222 | @item A helper script @file{configure.frag} is used as part of | |
223 | creating the output of @file{configure}. | |
224 | @end itemize | |
225 | ||
226 | @node System Config | |
640d429d | 227 | @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files |
330532ab NN |
228 | |
229 | The @file{config.build} file contains specific rules for particular systems | |
230 | which GCC is built on. This should be used as rarely as possible, as the | |
231 | behavior of the build system can always be detected by autoconf. | |
232 | ||
233 | The @file{config.host} file contains specific rules for particular systems | |
234 | which GCC will run on. This is rarely needed. | |
235 | ||
236 | The @file{config.gcc} file contains specific rules for particular systems | |
237 | which GCC will generate code for. This is usually needed. | |
238 | ||
239 | Each file has a list of the shell variables it sets, with descriptions, at the | |
240 | top of the file. | |
0a553c7e | 241 | |
5b28c537 | 242 | FIXME: document the contents of these files, and what variables should |
0a553c7e JM |
243 | be set to control build, host and target configuration. |
244 | ||
245 | @include configfiles.texi | |
246 | ||
247 | @node Build | |
248 | @subsection Build System in the @file{gcc} Directory | |
249 | ||
250 | FIXME: describe the build system, including what is built in what | |
251 | stages. Also list the various source files that are used in the build | |
252 | process but aren't source files of GCC itself and so aren't documented | |
253 | below (@pxref{Passes}). | |
254 | ||
255 | @include makefile.texi | |
256 | ||
257 | @node Library Files | |
258 | @subsection Library Source Files and Headers under the @file{gcc} Directory | |
259 | ||
260 | FIXME: list here, with explanation, all the C source files and headers | |
261 | under the @file{gcc} directory that aren't built into the GCC | |
262 | executable but rather are part of runtime libraries and object files, | |
263 | such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , | |
264 | Headers Installed by GCC}, for more information about the | |
265 | @file{ginclude} directory. | |
266 | ||
267 | @node Headers | |
268 | @subsection Headers Installed by GCC | |
269 | ||
270 | In general, GCC expects the system C library to provide most of the | |
271 | headers to be used with it. However, GCC will fix those headers if | |
272 | necessary to make them work with GCC, and will install some headers | |
273 | required of freestanding implementations. These headers are installed | |
274 | in @file{@var{libsubdir}/include}. Headers for non-C runtime | |
275 | libraries are also installed by GCC; these are not documented here. | |
276 | (FIXME: document them somewhere.) | |
277 | ||
278 | Several of the headers GCC installs are in the @file{ginclude} | |
279 | directory. These headers, @file{iso646.h}, | |
6c535c69 ZW |
280 | @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, |
281 | are installed in @file{@var{libsubdir}/include}, | |
0a553c7e JM |
282 | unless the target Makefile fragment (@pxref{Target Fragment}) |
283 | overrides this by setting @code{USER_H}. | |
284 | ||
285 | In addition to these headers and those generated by fixing system | |
286 | headers to work with GCC, some other headers may also be installed in | |
287 | @file{@var{libsubdir}/include}. @file{config.gcc} may set | |
288 | @code{extra_headers}; this specifies additional headers under | |
cd42d3df RH |
289 | @file{config} to be installed on some systems. |
290 | ||
291 | GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. | |
daf2f129 | 292 | This is done to cope with command-line options that change the |
cd42d3df RH |
293 | representation of floating point numbers. |
294 | ||
295 | GCC also installs its own version of @code{<limits.h>}; this is generated | |
0a553c7e JM |
296 | from @file{glimits.h}, together with @file{limitx.h} and |
297 | @file{limity.h} if the system also has its own version of | |
298 | @code{<limits.h>}. (GCC provides its own header because it is | |
299 | required of ISO C freestanding implementations, but needs to include | |
300 | the system header from its own header as well because other standards | |
301 | such as POSIX specify additional values to be defined in | |
302 | @code{<limits.h>}.) The system's @code{<limits.h>} header is used via | |
303 | @file{@var{libsubdir}/include/syslimits.h}, which is copied from | |
304 | @file{gsyslimits.h} if it does not need fixing to work with GCC; if it | |
305 | needs fixing, @file{syslimits.h} is the fixed copy. | |
306 | ||
307 | @node Documentation | |
308 | @subsection Building Documentation | |
309 | ||
310 | The main GCC documentation is in the form of manuals in Texinfo | |
311 | format. These are installed in Info format, and DVI versions may be | |
7ba4ca63 | 312 | generated by @samp{make dvi}. In addition, some man pages are |
0a553c7e JM |
313 | generated from the Texinfo manuals, there are some other text files |
314 | with miscellaneous documentation, and runtime libraries have their own | |
315 | documentation outside the @file{gcc} directory. FIXME: document the | |
316 | documentation for runtime libraries somewhere. | |
317 | ||
318 | @menu | |
319 | * Texinfo Manuals:: GCC manuals in Texinfo format. | |
320 | * Man Page Generation:: Generating man pages from Texinfo manuals. | |
321 | * Miscellaneous Docs:: Miscellaneous text files with documentation. | |
322 | @end menu | |
323 | ||
324 | @node Texinfo Manuals | |
325 | @subsubsection Texinfo Manuals | |
326 | ||
327 | The manuals for GCC as a whole, and the C and C++ front ends, are in | |
328 | files @file{doc/*.texi}. Other front ends have their own manuals in | |
329 | files @file{@var{language}/*.texi}. Common files | |
330 | @file{doc/include/*.texi} are provided which may be included in | |
331 | multiple manuals; the following files are in @file{doc/include}: | |
332 | ||
333 | @table @file | |
334 | @item fdl.texi | |
335 | The GNU Free Documentation License. | |
336 | @item funding.texi | |
337 | The section ``Funding Free Software''. | |
338 | @item gcc-common.texi | |
339 | Common definitions for manuals. | |
340 | @item gpl.texi | |
341 | The GNU General Public License. | |
342 | @item texinfo.tex | |
343 | A copy of @file{texinfo.tex} known to work with the GCC manuals. | |
344 | @end table | |
345 | ||
7ba4ca63 | 346 | DVI formatted manuals are generated by @samp{make dvi}, which uses |
0a553c7e | 347 | @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info |
7ba4ca63 | 348 | manuals are generated by @samp{make info} (which is run as part of |
0a553c7e JM |
349 | a bootstrap); this generates the manuals in the source directory, |
350 | using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, | |
351 | and they are included in release distributions. | |
352 | ||
353 | Manuals are also provided on the GCC web site, in both HTML and | |
354 | PostScript forms. This is done via the script | |
355 | @file{maintainer-scripts/update_web_docs}. Each manual to be | |
356 | provided online must be listed in the definition of @code{MANUALS} in | |
357 | that file; a file @file{@var{name}.texi} must only appear once in the | |
358 | source tree, and the output manual must have the same name as the | |
359 | source file. (However, other Texinfo files, included in manuals but | |
360 | not themselves the root files of manuals, may have names that appear | |
361 | more than once in the source tree.) The manual file | |
362 | @file{@var{name}.texi} should only include other files in its own | |
363 | directory or in @file{doc/include}. HTML manuals will be generated by | |
7ba4ca63 | 364 | @samp{makeinfo --html} and PostScript manuals by @command{texi2dvi} |
0a553c7e JM |
365 | and @command{dvips}. All Texinfo files that are parts of manuals must |
366 | be checked into CVS, even if they are generated files, for the | |
367 | generation of online manuals to work. | |
368 | ||
369 | The installation manual, @file{doc/install.texi}, is also provided on | |
370 | the GCC web site. The HTML version is generated by the script | |
371 | @file{doc/install.texi2html}. | |
372 | ||
373 | @node Man Page Generation | |
374 | @subsubsection Man Page Generation | |
375 | ||
376 | Because of user demand, in addition to full Texinfo manuals, man pages | |
377 | are provided which contain extracts from those manuals. These man | |
378 | pages are generated from the Texinfo manuals using | |
379 | @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for | |
380 | @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference | |
381 | to @file{gcc.1}, but all the other man pages are generated from | |
382 | Texinfo manuals.) | |
383 | ||
384 | Because many systems may not have the necessary tools installed to | |
385 | generate the man pages, they are only generated if the | |
386 | @file{configure} script detects that recent enough tools are | |
387 | installed, and the Makefiles allow generating man pages to fail | |
388 | without aborting the build. Man pages are also included in release | |
389 | distributions. They are generated in the source directory. | |
390 | ||
391 | Magic comments in Texinfo files starting @samp{@@c man} control what | |
392 | parts of a Texinfo file go into a man page. Only a subset of Texinfo | |
393 | is supported by @file{texi2pod.pl}, and it may be necessary to add | |
394 | support for more Texinfo features to this script when generating new | |
395 | man pages. To improve the man page output, some special Texinfo | |
396 | macros are provided in @file{doc/include/gcc-common.texi} which | |
397 | @file{texi2pod.pl} understands: | |
398 | ||
399 | @table @code | |
400 | @item @@gcctabopt | |
401 | Use in the form @samp{@@table @@gcctabopt} for tables of options, | |
402 | where for printed output the effect of @samp{@@code} is better than | |
403 | that of @samp{@@option} but for man page output a different effect is | |
404 | wanted. | |
405 | @item @@gccoptlist | |
406 | Use for summary lists of options in manuals. | |
407 | @item @@gol | |
408 | Use at the end of each line inside @samp{@@gccoptlist}. This is | |
409 | necessary to avoid problems with differences in how the | |
410 | @samp{@@gccoptlist} macro is handled by different Texinfo formatters. | |
411 | @end table | |
412 | ||
413 | FIXME: describe the @file{texi2pod.pl} input language and magic | |
414 | comments in more detail. | |
415 | ||
416 | @node Miscellaneous Docs | |
417 | @subsubsection Miscellaneous Documentation | |
418 | ||
419 | In addition to the formal documentation that is installed by GCC, | |
420 | there are several other text files with miscellaneous documentation: | |
421 | ||
422 | @table @file | |
423 | @item ABOUT-GCC-NLS | |
424 | Notes on GCC's Native Language Support. FIXME: this should be part of | |
425 | this manual rather than a separate file. | |
426 | @item ABOUT-NLS | |
427 | Notes on the Free Translation Project. | |
428 | @item COPYING | |
429 | The GNU General Public License. | |
430 | @item COPYING.LIB | |
431 | The GNU Lesser General Public License. | |
432 | @item *ChangeLog* | |
433 | @itemx */ChangeLog* | |
434 | Change log files for various parts of GCC@. | |
435 | @item LANGUAGES | |
436 | Details of a few changes to the GCC front-end interface. FIXME: the | |
437 | information in this file should be part of general documentation of | |
438 | the front-end interface in this manual. | |
439 | @item ONEWS | |
440 | Information about new features in old versions of GCC@. (For recent | |
441 | versions, the information is on the GCC web site.) | |
442 | @item README.Portability | |
443 | Information about portability issues when writing code in GCC@. FIXME: | |
444 | why isn't this part of this manual or of the GCC Coding Conventions? | |
445 | @item SERVICE | |
446 | A pointer to the GNU Service Directory. | |
447 | @end table | |
448 | ||
449 | FIXME: document such files in subdirectories, at least @file{config}, | |
450 | @file{cp}, @file{objc}, @file{testsuite}. | |
451 | ||
452 | @node Front End | |
453 | @subsection Anatomy of a Language Front End | |
454 | ||
455 | A front end for a language in GCC has the following parts: | |
456 | ||
457 | @itemize @bullet | |
458 | @item | |
459 | A directory @file{@var{language}} under @file{gcc} containing source | |
460 | files for that front end. @xref{Front End Directory, , The Front End | |
461 | @file{@var{language}} Directory}, for details. | |
462 | @item | |
463 | A mention of the language in the list of supported languages in | |
464 | @file{gcc/doc/install.texi}. | |
465 | @item | |
a72967cd JM |
466 | A mention of the name under which the language's runtime library is |
467 | recognized by @option{--enable-shared=@var{package}} in the | |
468 | documentation of that option in @file{gcc/doc/install.texi}. | |
469 | @item | |
470 | A mention of any special prerequisites for building the front end in | |
471 | the documentation of prerequisites in @file{gcc/doc/install.texi}. | |
472 | @item | |
0a553c7e JM |
473 | Details of contributors to that front end in |
474 | @file{gcc/doc/contrib.texi}. If the details are in that front end's | |
475 | own manual then there should be a link to that manual's list in | |
476 | @file{contrib.texi}. | |
477 | @item | |
478 | Information about support for that language in | |
479 | @file{gcc/doc/frontends.texi}. | |
480 | @item | |
481 | Information about standards for that language, and the front end's | |
482 | support for them, in @file{gcc/doc/standards.texi}. This may be a | |
483 | link to such information in the front end's own manual. | |
484 | @item | |
485 | Details of source file suffixes for that language and @option{-x | |
486 | @var{lang}} options supported, in @file{gcc/doc/invoke.texi}. | |
487 | @item | |
488 | Entries in @code{default_compilers} in @file{gcc.c} for source file | |
489 | suffixes for that language. | |
490 | @item | |
2eac577f | 491 | Preferably testsuites, which may be under @file{gcc/testsuite} or |
0a553c7e | 492 | runtime library directories. FIXME: document somewhere how to write |
2eac577f | 493 | testsuite harnesses. |
0a553c7e JM |
494 | @item |
495 | Probably a runtime library for the language, outside the @file{gcc} | |
496 | directory. FIXME: document this further. | |
497 | @item | |
498 | Details of the directories of any runtime libraries in | |
499 | @file{gcc/doc/sourcebuild.texi}. | |
500 | @end itemize | |
501 | ||
502 | If the front end is added to the official GCC CVS repository, the | |
503 | following are also necessary: | |
504 | ||
505 | @itemize @bullet | |
506 | @item | |
c487d8b6 | 507 | At least one Bugzilla component for bugs in that front end and runtime |
0a553c7e | 508 | libraries. This category needs to be mentioned in |
b10d2c9d | 509 | @file{gcc/gccbug.in}, as well as being added to the Bugzilla database. |
0a553c7e JM |
510 | @item |
511 | Normally, one or more maintainers of that front end listed in | |
512 | @file{MAINTAINERS}. | |
513 | @item | |
514 | Mentions on the GCC web site in @file{index.html} and | |
515 | @file{frontends.html}, with any relevant links on | |
516 | @file{readings.html}. (Front ends that are not an official part of | |
517 | GCC may also be listed on @file{frontends.html}, with relevant links.) | |
518 | @item | |
519 | A news item on @file{index.html}, and possibly an announcement on the | |
520 | @email{gcc-announce@@gcc.gnu.org} mailing list. | |
521 | @item | |
522 | The front end's manuals should be mentioned in | |
523 | @file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals}) | |
524 | and the online manuals should be linked to from | |
525 | @file{onlinedocs/index.html}. | |
526 | @item | |
527 | Any old releases or CVS repositories of the front end, before its | |
528 | inclusion in GCC, should be made available on the GCC FTP site | |
529 | @uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}. | |
530 | @item | |
531 | The release and snapshot script @file{maintainer-scripts/gcc_release} | |
532 | should be updated to generate appropriate tarballs for this front end. | |
2870428f JM |
533 | The associated @file{maintainer-scripts/snapshot-README} and |
534 | @file{maintainer-scripts/snapshot-index.html} files should be updated | |
535 | to list the tarballs and diffs for this front end. | |
0a553c7e JM |
536 | @item |
537 | If this front end includes its own version files that include the | |
538 | current date, @file{maintainer-scripts/update_version} should be | |
539 | updated accordingly. | |
540 | @item | |
541 | @file{CVSROOT/modules} in the GCC CVS repository should be updated. | |
542 | @end itemize | |
543 | ||
544 | @menu | |
545 | * Front End Directory:: The front end @file{@var{language}} directory. | |
546 | * Front End Config:: The front end @file{config-lang.in} file. | |
547 | @end menu | |
548 | ||
549 | @node Front End Directory | |
550 | @subsubsection The Front End @file{@var{language}} Directory | |
551 | ||
552 | A front end @file{@var{language}} directory contains the source files | |
553 | of that front end (but not of any runtime libraries, which should be | |
554 | outside the @file{gcc} directory). This includes documentation, and | |
555 | possibly some subsidiary programs build alongside the front end. | |
556 | Certain files are special and other parts of the compiler depend on | |
557 | their names: | |
558 | ||
559 | @table @file | |
560 | @item config-lang.in | |
561 | This file is required in all language subdirectories. @xref{Front End | |
562 | Config, , The Front End @file{config-lang.in} File}, for details of | |
563 | its contents | |
564 | @item Make-lang.in | |
565 | This file is required in all language subdirectories. It contains | |
566 | targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the | |
567 | setting of @code{language} in @file{config-lang.in}) for the following | |
568 | values of @code{@var{hook}}, and any other Makefile rules required to | |
569 | build those targets (which may if necessary use other Makefiles | |
570 | specified in @code{outputs} in @file{config-lang.in}, although this is | |
62b81e45 MM |
571 | deprecated). Some hooks are defined by using a double-colon rule for |
572 | @code{@var{hook}}, rather than by using a target of form | |
573 | @code{@var{lang}.@var{hook}}. These hooks are called ``double-colon | |
49a41726 JM |
574 | hooks'' below. It also adds any testsuite targets that can use the |
575 | standard rule in @file{gcc/Makefile.in} to the variable | |
576 | @code{lang_checks}. | |
0a553c7e JM |
577 | |
578 | @table @code | |
579 | @item all.build | |
580 | @itemx all.cross | |
581 | @itemx start.encap | |
582 | @itemx rest.encap | |
583 | FIXME: exactly what goes in each of these targets? | |
65ebbf81 TT |
584 | @item tags |
585 | Build an @command{etags} @file{TAGS} file in the language subdirectory | |
586 | in the source tree. | |
0a553c7e | 587 | @item info |
ce5c1cf3 | 588 | Build info documentation for the front end, in the build directory. |
7ba4ca63 | 589 | This target is only called by @samp{make bootstrap} if a suitable |
0a553c7e | 590 | version of @command{makeinfo} is available, so does not need to check |
ce5c1cf3 | 591 | for this, and should fail if an error occurs. |
0a553c7e JM |
592 | @item dvi |
593 | Build DVI documentation for the front end, in the build directory. | |
594 | This should be done using @code{$(TEXI2DVI)}, with appropriate | |
595 | @option{-I} arguments pointing to directories of included files. | |
62b81e45 | 596 | This hook is a double-colon hook. |
ce5c1cf3 | 597 | @item man |
0a553c7e | 598 | Build generated man pages for the front end from Texinfo manuals |
ce5c1cf3 | 599 | (@pxref{Man Page Generation}), in the build directory. This target |
0a553c7e JM |
600 | is only called if the necessary tools are available, but should ignore |
601 | errors so as not to stop the build if errors occur; man pages are | |
602 | optional and the tools involved may be installed in a broken way. | |
603 | @item install-normal | |
604 | FIXME: what is this target for? | |
605 | @item install-common | |
606 | Install everything that is part of the front end, apart from the | |
607 | compiler executables listed in @code{compilers} in | |
8e5f33ff | 608 | @file{config-lang.in}. |
0a553c7e JM |
609 | @item install-info |
610 | Install info documentation for the front end, if it is present in the | |
97ae108d MM |
611 | source directory. This target should have dependencies on info files |
612 | that should be installed. This hook is a double-colon hook. | |
0a553c7e JM |
613 | @item install-man |
614 | Install man pages for the front end. This target should ignore | |
615 | errors. | |
ce5c1cf3 KC |
616 | @item srcextra |
617 | Copies its dependencies into the source directory. This generally should | |
618 | be used for generated files such as @file{gcc/c-parse.c} which are not | |
619 | present in CVS, but should be included in any release tarballs. This | |
620 | target will be executed during a bootstrap if | |
621 | @samp{--enable-generated-files-in-srcdir} was specified as a | |
622 | @file{configure} option. | |
623 | @item srcinfo | |
624 | @itemx srcman | |
625 | Copies its dependencies into the source directory. These targets will be | |
626 | executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} | |
627 | was specified as a @file{configure} option. | |
0a553c7e JM |
628 | @item uninstall |
629 | Uninstall files installed by installing the compiler. This is | |
630 | currently documented not to be supported, so the hook need not do | |
631 | anything. | |
632 | @item mostlyclean | |
633 | @itemx clean | |
634 | @itemx distclean | |
0a553c7e | 635 | @itemx maintainer-clean |
a03ad584 | 636 | The language parts of the standard GNU |
0a553c7e JM |
637 | @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for |
638 | Users, standards, GNU Coding Standards}, for details of the standard | |
a03ad584 | 639 | targets. For GCC, @code{maintainer-clean} should delete |
0a553c7e JM |
640 | all generated files in the source directory that are not checked into |
641 | CVS, but should not delete anything checked into CVS@. | |
642 | @item stage1 | |
643 | @itemx stage2 | |
644 | @itemx stage3 | |
645 | @itemx stage4 | |
295e823c JH |
646 | @itemx stageprofile |
647 | @itemx stagefeedback | |
0a553c7e JM |
648 | Move to the stage directory files not included in @code{stagestuff} in |
649 | @file{config-lang.in} or otherwise moved by the main @file{Makefile}. | |
650 | @end table | |
651 | ||
9756074d NB |
652 | @item lang.opt |
653 | This file registers the set of switches that the front end accepts on | |
2cc98056 NB |
654 | the command line, and their --help text. The file format is |
655 | documented in the file @file{c.opt}. These files are processed by the | |
656 | script @file{opts.sh}. | |
0a553c7e JM |
657 | @item lang-specs.h |
658 | This file provides entries for @code{default_compilers} in | |
659 | @file{gcc.c} which override the default of giving an error that a | |
660 | compiler for that language is not installed. | |
661 | @item @var{language}-tree.def | |
662 | This file, which need not exist, defines any language-specific tree | |
663 | codes. | |
664 | @end table | |
665 | ||
666 | @node Front End Config | |
667 | @subsubsection The Front End @file{config-lang.in} File | |
668 | ||
8ac9d31f TJ |
669 | Each language subdirectory contains a @file{config-lang.in} file. In |
670 | addition the main directory contains @file{c-config-lang.in}, which | |
671 | contains limited information for the C language. This file is a shell | |
672 | script that may define some variables describing the language: | |
0a553c7e JM |
673 | |
674 | @table @code | |
675 | @item language | |
676 | This definition must be present, and gives the name of the language | |
677 | for some purposes such as arguments to @option{--enable-languages}. | |
678 | @item lang_requires | |
679 | If defined, this variable lists (space-separated) language front ends | |
680 | other than C that this front end requires to be enabled (with the | |
681 | names given being their @code{language} settings). For example, the | |
682 | Java front end depends on the C++ front end, so sets | |
683 | @samp{lang_requires=c++}. | |
684 | @item target_libs | |
685 | If defined, this variable lists (space-separated) targets in the top | |
686 | level @file{Makefile} to build the runtime libraries for this | |
687 | language, such as @code{target-libobjc}. | |
688 | @item lang_dirs | |
689 | If defined, this variable lists (space-separated) top level | |
690 | directories (parallel to @file{gcc}), apart from the runtime libraries, | |
691 | that should not be configured if this front end is not built. | |
692 | @item build_by_default | |
693 | If defined to @samp{no}, this language front end is not built unless | |
694 | enabled in a @option{--enable-languages} argument. Otherwise, front | |
695 | ends are built by default, subject to any special logic in | |
3986a20d | 696 | @file{configure.ac} (as is present to disable the Ada front end if the |
0a553c7e JM |
697 | Ada compiler is not already installed). |
698 | @item boot_language | |
699 | If defined to @samp{yes}, this front end is built in stage 1 of the | |
700 | bootstrap. This is only relevant to front ends written in their own | |
701 | languages. | |
702 | @item compilers | |
8e5f33ff GK |
703 | If defined, a space-separated list of compiler executables that will |
704 | be run by the driver. The names here will each end | |
0a553c7e JM |
705 | with @samp{\$(exeext)}. |
706 | @item stagestuff | |
707 | If defined, a space-separated list of files that should be moved to | |
708 | the @file{stage@var{n}} directories in each stage of bootstrap. | |
709 | @item outputs | |
710 | If defined, a space-separated list of files that should be generated | |
711 | by @file{configure} substituting values in them. This mechanism can | |
712 | be used to create a file @file{@var{language}/Makefile} from | |
713 | @file{@var{language}/Makefile.in}, but this is deprecated, building | |
714 | everything from the single @file{gcc/Makefile} is preferred. | |
8ac9d31f TJ |
715 | @item gtfiles |
716 | If defined, a space-separated list of files that should be scanned by | |
717 | gengtype.c to generate the garbage collection tables and routines for | |
718 | this language. This excludes the files that are common to all front | |
719 | ends. @xref{Type Information}. | |
6de9cd9a DN |
720 | @item need_gmp |
721 | If defined to @samp{yes}, this frontend requires the GMP library. | |
722 | Enables configure tests for GMP, which set @code{GMPLIBS} and | |
723 | @code{GMPINC} appropriately. | |
8ac9d31f | 724 | |
0a553c7e JM |
725 | @end table |
726 | ||
727 | @node Back End | |
728 | @subsection Anatomy of a Target Back End | |
729 | ||
730 | A back end for a target architecture in GCC has the following parts: | |
731 | ||
732 | @itemize @bullet | |
733 | @item | |
734 | A directory @file{@var{machine}} under @file{gcc/config}, containing a | |
735 | machine description @file{@var{machine}.md} file (@pxref{Machine Desc, | |
736 | , Machine Descriptions}), header files @file{@var{machine}.h} and | |
737 | @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} | |
738 | (@pxref{Target Macros, , Target Description Macros and Functions}), | |
739 | possibly a target Makefile fragment @file{t-@var{machine}} | |
740 | (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe | |
741 | some other files. The names of these files may be changed from the | |
742 | defaults given by explicit specifications in @file{config.gcc}. | |
743 | @item | |
a5381466 ZW |
744 | If necessary, a file @file{@var{machine}-modes.def} in the |
745 | @file{@var{machine}} directory, containing additional machine modes to | |
746 | represent condition codes. @xref{Condition Code}, for further details. | |
747 | @item | |
0a553c7e JM |
748 | Entries in @file{config.gcc} (@pxref{System Config, , The |
749 | @file{config.gcc} File}) for the systems with this target | |
750 | architecture. | |
751 | @item | |
752 | Documentation in @file{gcc/doc/invoke.texi} for any command-line | |
753 | options supported by this target (@pxref{Run-time Target, , Run-time | |
754 | Target Specification}). This means both entries in the summary table | |
755 | of options and details of the individual options. | |
756 | @item | |
757 | Documentation in @file{gcc/doc/extend.texi} for any target-specific | |
758 | attributes supported (@pxref{Target Attributes, , Defining | |
759 | target-specific uses of @code{__attribute__}}), including where the | |
760 | same attribute is already supported on some targets, which are | |
761 | enumerated in the manual. | |
762 | @item | |
763 | Documentation in @file{gcc/doc/extend.texi} for any target-specific | |
764 | pragmas supported. | |
765 | @item | |
0975678f JM |
766 | Documentation in @file{gcc/doc/extend.texi} of any target-specific |
767 | built-in functions supported. | |
0a553c7e JM |
768 | @item |
769 | Documentation in @file{gcc/doc/md.texi} of any target-specific | |
770 | constraint letters (@pxref{Machine Constraints, , Constraints for | |
771 | Particular Machines}). | |
772 | @item | |
773 | A note in @file{gcc/doc/contrib.texi} under the person or people who | |
774 | contributed the target support. | |
775 | @item | |
776 | Entries in @file{gcc/doc/install.texi} for all target triplets | |
777 | supported with this target architecture, giving details of any special | |
778 | notes about installation for this target, or saying that there are no | |
779 | special notes if there are none. | |
780 | @item | |
781 | Possibly other support outside the @file{gcc} directory for runtime | |
782 | libraries. FIXME: reference docs for this. The libstdc++ porting | |
783 | manual needs to be installed as info for this to work, or to be a | |
784 | chapter of this manual. | |
785 | @end itemize | |
786 | ||
787 | If the back end is added to the official GCC CVS repository, the | |
788 | following are also necessary: | |
789 | ||
790 | @itemize @bullet | |
791 | @item | |
792 | An entry for the target architecture in @file{readings.html} on the | |
793 | GCC web site, with any relevant links. | |
794 | @item | |
0acdc221 JM |
795 | Details of the properties of the back end and target architecture in |
796 | @file{backends.html} on the GCC web site. | |
797 | @item | |
0a553c7e JM |
798 | A news item about the contribution of support for that target |
799 | architecture, in @file{index.html} on the GCC web site. | |
800 | @item | |
801 | Normally, one or more maintainers of that target listed in | |
802 | @file{MAINTAINERS}. Some existing architectures may be unmaintained, | |
803 | but it would be unusual to add support for a target that does not have | |
804 | a maintainer when support is added. | |
805 | @end itemize | |
806 | ||
2eac577f JM |
807 | @node Testsuites |
808 | @section Testsuites | |
0a553c7e | 809 | |
2eac577f JM |
810 | GCC contains several testsuites to help maintain compiler quality. |
811 | Most of the runtime libraries and language front ends in GCC have | |
812 | testsuites. Currently only the C language testsuites are documented | |
0a553c7e JM |
813 | here; FIXME: document the others. |
814 | ||
815 | @menu | |
2eac577f JM |
816 | * Test Idioms:: Idioms used in testsuite code. |
817 | * Ada Tests:: The Ada language testsuites. | |
818 | * C Tests:: The C language testsuites. | |
819 | * libgcj Tests:: The Java library testsuites. | |
138d4703 JJ |
820 | * gcov Testing:: Support for testing gcov. |
821 | * profopt Testing:: Support for testing profile-directed optimizations. | |
46b2356d | 822 | * compat Testing:: Support for testing binary compatibility. |
0a553c7e JM |
823 | @end menu |
824 | ||
825 | @node Test Idioms | |
2eac577f | 826 | @subsection Idioms Used in Testsuite Code |
0a553c7e | 827 | |
4ef84575 JM |
828 | In general C testcases have a trailing @file{-@var{n}.c}, starting |
829 | with @file{-1.c}, in case other testcases with similar names are added | |
830 | later. If the test is a test of some well-defined feature, it should | |
831 | have a name referring to that feature such as | |
832 | @file{@var{feature}-1.c}. If it does not test a well-defined feature | |
833 | but just happens to exercise a bug somewhere in the compiler, and a | |
834 | bug report has been filed for this bug in the GCC bug database, | |
835 | @file{pr@var{bug-number}-1.c} is the appropriate form of name. | |
836 | Otherwise (for miscellaneous bugs not filed in the GCC bug database), | |
837 | and previously more generally, test cases are named after the date on | |
838 | which they were added. This allows people to tell at a glance whether | |
839 | a test failure is because of a recently found bug that has not yet | |
840 | been fixed, or whether it may be a regression, but does not give any | |
841 | other information about the bug or where discussion of it may be | |
842 | found. Some other language testsuites follow similar conventions. | |
0a553c7e | 843 | |
2eac577f | 844 | In the @file{gcc.dg} testsuite, it is often necessary to test that an |
0a553c7e JM |
845 | error is indeed a hard error and not just a warning---for example, |
846 | where it is a constraint violation in the C standard, which must | |
847 | become an error with @option{-pedantic-errors}. The following idiom, | |
848 | where the first line shown is line @var{line} of the file and the line | |
849 | that generates the error, is used for this: | |
850 | ||
851 | @smallexample | |
852 | /* @{ dg-bogus "warning" "warning in place of error" @} */ | |
853 | /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ | |
854 | @end smallexample | |
855 | ||
856 | It may be necessary to check that an expression is an integer constant | |
857 | expression and has a certain value. To check that @code{@var{E}} has | |
858 | value @code{@var{V}}, an idiom similar to the following is used: | |
859 | ||
860 | @smallexample | |
861 | char x[((E) == (V) ? 1 : -1)]; | |
862 | @end smallexample | |
863 | ||
864 | In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make | |
865 | assertions about the types of expressions. See, for example, | |
866 | @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the | |
867 | exact rules for the types of conditional expressions in the C | |
868 | standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. | |
869 | ||
870 | It is useful to be able to test that optimizations are being made | |
871 | properly. This cannot be done in all cases, but it can be done where | |
872 | the optimization will lead to code being optimized away (for example, | |
873 | where flow analysis or alias analysis should show that certain code | |
874 | cannot be called) or to functions not being called because they have | |
875 | been expanded as built-in functions. Such tests go in | |
876 | @file{gcc.c-torture/execute}. Where code should be optimized away, a | |
877 | call to a nonexistent function such as @code{link_failure ()} may be | |
878 | inserted; a definition | |
879 | ||
880 | @smallexample | |
881 | #ifndef __OPTIMIZE__ | |
882 | void | |
883 | link_failure (void) | |
884 | @{ | |
885 | abort (); | |
886 | @} | |
887 | #endif | |
888 | @end smallexample | |
889 | ||
890 | @noindent | |
891 | will also be needed so that linking still succeeds when the test is | |
892 | run without optimization. When all calls to a built-in function | |
893 | should have been optimized and no calls to the non-built-in version of | |
894 | the function should remain, that function may be defined as | |
895 | @code{static} to call @code{abort ()} (although redeclaring a function | |
896 | as static may not work on all targets). | |
897 | ||
4b2ece8f NN |
898 | All testcases must be portable. Target-specific testcases must have |
899 | appropriate code to avoid causing failures on unsupported systems; | |
900 | unfortunately, the mechanisms for this differ by directory. | |
901 | ||
2eac577f | 902 | FIXME: discuss non-C testsuites here. |
0a553c7e | 903 | |
d0a74d7e | 904 | @node Ada Tests |
2eac577f | 905 | @subsection Ada Language Testsuites |
d0a74d7e | 906 | |
2eac577f JM |
907 | The Ada testsuite includes executable tests from the ACATS 2.5 |
908 | testsuite, publicly available at | |
909 | @uref{http://www.adaic.org/compilers/acats/2.5} | |
d0a74d7e | 910 | |
2eac577f | 911 | These tests are integrated in the GCC testsuite in the |
d0a74d7e AC |
912 | @file{gcc/testsuite/ada/acats} directory, and |
913 | enabled automatically when running @code{make check}, assuming | |
914 | the Ada language has been enabled when configuring GCC. | |
915 | ||
2eac577f | 916 | You can also run the Ada testsuite independently, using |
d0a74d7e AC |
917 | @code{make check-ada}, or run a subset of the tests by specifying which |
918 | chapter to run, e.g: | |
919 | ||
920 | @smallexample | |
921 | $ make check-ada CHAPTERS="c3 c9" | |
922 | @end smallexample | |
923 | ||
924 | The tests are organized by directory, each directory corresponding to | |
925 | a chapter of the Ada Reference Manual. So for example, c9 corresponds | |
926 | to chapter 9, which deals with tasking features of the language. | |
927 | ||
928 | There is also an extra chapter called @file{gcc} containing a template for | |
929 | creating new executable tests. | |
930 | ||
931 | The tests are run using two 'sh' scripts: run_acats and run_all.sh | |
932 | To run the tests using a simulator or a cross target, see the small | |
933 | customization section at the top of run_all.sh | |
934 | ||
935 | These tests are run using the build tree: they can be run without doing | |
936 | a @code{make install}. | |
937 | ||
0a553c7e | 938 | @node C Tests |
2eac577f | 939 | @subsection C Language Testsuites |
0a553c7e | 940 | |
2eac577f | 941 | GCC contains the following C language testsuites, in the |
0a553c7e JM |
942 | @file{gcc/testsuite} directory: |
943 | ||
944 | @table @file | |
4b2ece8f | 945 | @item gcc.dg |
daf2f129 | 946 | This contains tests of particular features of the C compiler, using the |
4b2ece8f NN |
947 | more modern @samp{dg} harness. Correctness tests for various compiler |
948 | features should go here if possible. | |
949 | ||
daf2f129 JM |
950 | Magic comments determine whether the file |
951 | is preprocessed, compiled, linked or run. In these tests, error and warning | |
952 | message texts are compared against expected texts or regular expressions | |
4b2ece8f NN |
953 | given in comments. These tests are run with the options @samp{-ansi -pedantic} |
954 | unless other options are given in the test. Except as noted below they | |
955 | are not run with multiple optimization options. | |
6ccfe27c JJ |
956 | @item gcc.dg/compat |
957 | This subdirectory contains tests for binary compatibility using | |
958 | @file{compat.exp}, which in turn uses the language-independent support | |
959 | (@pxref{compat Testing, , Support for testing binary compatibility}). | |
4b2ece8f NN |
960 | @item gcc.dg/cpp |
961 | This subdirectory contains tests of the preprocessor. | |
962 | @item gcc.dg/debug | |
963 | This subdirectory contains tests for debug formats. Tests in this | |
964 | subdirectory are run for each debug format that the compiler supports. | |
965 | @item gcc.dg/format | |
966 | This subdirectory contains tests of the @option{-Wformat} format | |
967 | checking. Tests in this directory are run with and without | |
968 | @option{-DWIDE}. | |
969 | @item gcc.dg/noncompile | |
970 | This subdirectory contains tests of code that should not compile and | |
971 | does not need any special compilation options. They are run with | |
972 | multiple optimization options, since sometimes invalid code crashes | |
973 | the compiler with optimization. | |
974 | @item gcc.dg/special | |
975 | FIXME: describe this. | |
976 | ||
977 | @item gcc.c-torture | |
c0478a66 | 978 | This contains particular code fragments which have historically broken easily. |
4b2ece8f NN |
979 | These tests are run with multiple optimization options, so tests for features |
980 | which only break at some optimization levels belong here. This also contains | |
daf2f129 | 981 | tests to check that certain optimizations occur. It might be worthwhile to |
4b2ece8f NN |
982 | separate the correctness tests cleanly from the code quality tests, but |
983 | it hasn't been done yet. | |
984 | ||
0a553c7e JM |
985 | @item gcc.c-torture/compat |
986 | FIXME: describe this. | |
987 | ||
988 | This directory should probably not be used for new tests. | |
989 | @item gcc.c-torture/compile | |
2eac577f | 990 | This testsuite contains test cases that should compile, but do not |
0a553c7e JM |
991 | need to link or run. These test cases are compiled with several |
992 | different combinations of optimization options. All warnings are | |
993 | disabled for these test cases, so this directory is not suitable if | |
994 | you wish to test for the presence or absence of compiler warnings. | |
995 | While special options can be set, and tests disabled on specific | |
996 | platforms, by the use of @file{.x} files, mostly these test cases | |
997 | should not contain platform dependencies. FIXME: discuss how defines | |
998 | such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. | |
999 | @item gcc.c-torture/execute | |
2eac577f | 1000 | This testsuite contains test cases that should compile, link and run; |
0a553c7e | 1001 | otherwise the same comments as for @file{gcc.c-torture/compile} apply. |
4b2ece8f NN |
1002 | @item gcc.c-torture/execute/ieee |
1003 | This contains tests which are specific to IEEE floating point. | |
0a553c7e JM |
1004 | @item gcc.c-torture/unsorted |
1005 | FIXME: describe this. | |
1006 | ||
1007 | This directory should probably not be used for new tests. | |
0a553c7e | 1008 | @item gcc.c-torture/misc-tests |
138d4703 JJ |
1009 | This directory contains C tests that require special handling. Some |
1010 | of these tests have individual expect files, and others share | |
1011 | special-purpose expect files: | |
1012 | ||
1013 | @table @file | |
1014 | @item @code{bprob*.c} | |
1015 | Test @option{-fbranch-probabilities} using @file{bprob.exp}, which | |
1016 | in turn uses the generic, language-independent framework | |
1017 | (@pxref{profopt Testing, , Support for testing profile-directed | |
1018 | optimizations}). | |
1019 | ||
1020 | @item @code{dg-*.c} | |
1021 | Test the testsuite itself using @file{dg-test.exp}. | |
1022 | ||
1023 | @item @code{gcov*.c} | |
1024 | Test @command{gcov} output using @file{gcov.exp}, which in turn uses the | |
1025 | language-independent support (@pxref{gcov Testing, , Support for testing gcov}). | |
1026 | ||
1027 | @item @code{i386-pf-*.c} | |
1028 | Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. | |
1029 | @end table | |
1030 | ||
0a553c7e JM |
1031 | @end table |
1032 | ||
1033 | FIXME: merge in @file{testsuite/README.gcc} and discuss the format of | |
1034 | test cases and magic comments more. | |
f702e700 JJ |
1035 | |
1036 | @node libgcj Tests | |
2eac577f | 1037 | @subsection The Java library testsuites. |
f702e700 | 1038 | |
0d5c606b RM |
1039 | Runtime tests are executed via @samp{make check} in the |
1040 | @file{@var{target}/libjava/testsuite} directory in the build | |
1041 | tree. Additional runtime tests can be checked into this testsuite. | |
f702e700 JJ |
1042 | |
1043 | Regression testing of the core packages in libgcj is also covered by the | |
2eac577f | 1044 | Mauve testsuite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project} |
f702e700 JJ |
1045 | develops tests for the Java Class Libraries. These tests are run as part |
1046 | of libgcj testing by placing the Mauve tree within the libjava testsuite | |
1047 | sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying | |
1048 | the location of that tree when invoking @samp{make}, as in | |
1049 | @samp{make MAUVEDIR=~/mauve check}. | |
1050 | ||
1051 | To detect regressions, a mechanism in @file{mauve.exp} compares the | |
1052 | failures for a test run against the list of expected failures in | |
1053 | @file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. | |
1054 | Update this file when adding new failing tests to Mauve, or when fixing | |
1055 | bugs in libgcj that had caused Mauve test failures. | |
1056 | ||
1057 | The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,, | |
2eac577f JM |
1058 | Jacks} project provides a testsuite for Java compilers that can be used |
1059 | to test changes that affect the GCJ front end. This testsuite is run as | |
f702e700 JJ |
1060 | part of Java testing by placing the Jacks tree within the the libjava |
1061 | testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. | |
1062 | ||
1063 | We encourage developers to contribute test cases to Mauve and Jacks. | |
138d4703 JJ |
1064 | |
1065 | @node gcov Testing | |
1066 | @subsection Support for testing @command{gcov} | |
1067 | ||
1068 | Language-independent support for testing @command{gcov}, and for checking | |
1069 | that branch profiling produces expected values, is provided by the | |
1070 | expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures | |
1071 | in @file{gcc.dg.exp} to compile and run the test program. A typical | |
1072 | @command{gcov} test contains the following DejaGNU commands within comments: | |
1073 | ||
1074 | @smallexample | |
1075 | @{ dg-options "-fprofile-arcs -ftest-coverage" @} | |
1076 | @{ dg-do run @{ target native @} @} | |
1077 | @{ dg-final @{ run-gcov sourcefile @} @} | |
1078 | @end smallexample | |
1079 | ||
1080 | Checks of @command{gcov} output can include line counts, branch percentages, | |
1081 | and call return percentages. All of these checks are requested via | |
1082 | commands that appear in comments in the test's source file. | |
1083 | Commands to check line counts are processed by default. | |
1084 | Commands to check branch percentages and call return percentages are | |
7760d7f9 JJ |
1085 | processed if the @command{run-gcov} command has arguments @code{branches} |
1086 | or @code{calls}, respectively. For example, the following specifies | |
1087 | checking both, as well as passing @code{-b} to @command{gcov}: | |
1088 | ||
1089 | @smallexample | |
1090 | @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} | |
1091 | @end smallexample | |
138d4703 JJ |
1092 | |
1093 | A line count command appears within a comment on the source line | |
1094 | that is expected to get the specified count and has the form | |
1095 | @code{count(@var{cnt})}. A test should only check line counts for | |
1096 | lines that will get the same count for any architecture. | |
1097 | ||
1098 | Commands to check branch percentages (@code{branch}) and call | |
1099 | return percentages (@code{returns}) are very similar to each other. | |
1100 | A beginning command appears on or before the first of a range of | |
1101 | lines that will report the percentage, and the ending command | |
1102 | follows that range of lines. The beginning command can include a | |
1103 | list of percentages, all of which are expected to be found within | |
1104 | the range. A range is terminated by the next command of the same | |
1105 | kind. A command @code{branch(end)} or @code{returns(end)} marks | |
1106 | the end of a range without starting a new one. For example: | |
1107 | ||
1108 | @smallexample | |
1109 | if (i > 10 && j > i && j < 20) /* branch(27 50 75) */ | |
1110 | /* branch(end) */ | |
1111 | foo (i, j); | |
1112 | @end smallexample | |
1113 | ||
1114 | For a call return percentage, the value specified is the | |
1115 | percentage of calls reported to return. For a branch percentage, | |
1116 | the value is either the expected percentage or 100 minus that | |
1117 | value, since the direction of a branch can differ depending on the | |
1118 | target or the optimization level. | |
1119 | ||
1120 | Not all branches and calls need to be checked. A test should not | |
1121 | check for branches that might be optimized away or replaced with | |
1122 | predicated instructions. Don't check for calls inserted by the | |
1123 | compiler or ones that might be inlined or optimized away. | |
1124 | ||
1125 | A single test can check for combinations of line counts, branch | |
1126 | percentages, and call return percentages. The command to check a | |
1127 | line count must appear on the line that will report that count, but | |
1128 | commands to check branch percentages and call return percentages can | |
1129 | bracket the lines that report them. | |
1130 | ||
1131 | @node profopt Testing | |
1132 | @subsection Support for testing profile-directed optimizations | |
1133 | ||
1134 | The file @file{profopt.exp} provides language-independent support for | |
1135 | checking correct execution of a test built with profile-directed | |
1136 | optimization. This testing requires that a test program be built and | |
1137 | executed twice. The first time it is compiled to generate profile | |
1138 | data, and the second time it is compiled to use the data that was | |
1139 | generated during the first execution. The second execution is to | |
1140 | verify that the test produces the expected results. | |
1141 | ||
1142 | To check that the optimization actually generated better code, a | |
1143 | test can be built and run a third time with normal optimizations to | |
1144 | verify that the performance is better with the profile-directed | |
1145 | optimizations. @file{profopt.exp} has the beginnings of this kind | |
1146 | of support. | |
1147 | ||
1148 | @file{profopt.exp} provides generic support for profile-directed | |
1149 | optimizations. Each set of tests that uses it provides information | |
1150 | about a specific optimization: | |
1151 | ||
1152 | @table @code | |
1153 | @item tool | |
2dd76960 | 1154 | tool being tested, e.g., @command{gcc} |
138d4703 JJ |
1155 | |
1156 | @item profile_option | |
1157 | options used to generate profile data | |
1158 | ||
1159 | @item feedback_option | |
1160 | options used to optimize using that profile data | |
1161 | ||
1162 | @item prof_ext | |
1163 | suffix of profile data files | |
1164 | ||
1165 | @item PROFOPT_OPTIONS | |
1166 | list of options with which to run each test, similar to the lists for | |
1167 | torture tests | |
1168 | @end table | |
46b2356d JJ |
1169 | |
1170 | @node compat Testing | |
1171 | @subsection Support for testing binary compatibility | |
1172 | ||
1173 | The file @file{compat.exp} provides language-independent support for | |
2eac577f JM |
1174 | binary compatibility testing. It supports testing interoperability of |
1175 | two compilers that follow the same ABI, or of multiple sets of | |
1176 | compiler options that should not affect binary compatibility. It is | |
1177 | intended to be used for testsuites that complement ABI testsuites. | |
46b2356d JJ |
1178 | |
1179 | A test supported by this framework has three parts, each in a | |
1180 | separate source file: a main program and two pieces that interact | |
1181 | with each other to split up the functionality being tested. | |
1182 | ||
1183 | @table @file | |
1184 | @item @var{testname}_main.@var{suffix} | |
1185 | Contains the main program, which calls a function in file | |
1186 | @file{@var{testname}_x.@var{suffix}}. | |
1187 | ||
1188 | @item @var{testname}_x.@var{suffix} | |
1189 | Contains at least one call to a function in | |
1190 | @file{@var{testname}_y.@var{suffix}}. | |
1191 | ||
1192 | @item @var{testname}_y.@var{suffix} | |
1193 | Shares data with, or gets arguments from, | |
1194 | @file{@var{testname}_x.@var{suffix}}. | |
1195 | @end table | |
1196 | ||
1197 | Within each test, the main program and one functional piece are | |
1198 | compiled by the GCC under test. The other piece can be compiled by | |
1199 | an alternate compiler. If no alternate compiler is specified, | |
1200 | then all three source files are all compiled by the GCC under test. | |
1201 | It's also possible to specify a pair of lists of compiler options, | |
1202 | one list for each compiler, so that each test will be compiled with | |
1203 | each pair of options. | |
1204 | ||
1205 | @file{compat.exp} defines default pairs of compiler options. | |
1206 | These can be overridden by defining the environment variable | |
1207 | @env{COMPAT_OPTIONS} as: | |
1208 | ||
1209 | @smallexample | |
1210 | COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] | |
1211 | ...[list @{@var{tstn}@} @{@var{altn}@}]]" | |
1212 | @end smallexample | |
1213 | ||
1214 | where @var{tsti} and @var{alti} are lists of options, with @var{tsti} | |
1215 | used by the compiler under test and @var{alti} used by the alternate | |
1216 | compiler. For example, with | |
1217 | @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, | |
1218 | the test is first built with @code{-g -O0} by the compiler under | |
1219 | test and with @code{-O3} by the alternate compiler. The test is | |
1220 | built a second time using @code{-fpic} by the compiler under test | |
1221 | and @code{-fPIC -O2} by the alternate compiler. | |
1222 | ||
1223 | An alternate compiler is specified by defining an environment | |
1224 | variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full | |
1225 | pathname of an installed compiler. That will be written to the | |
1226 | @file{site.exp} file used by DejaGNU. The default is to build each | |
1227 | test with the compiler under test using the first of each pair of | |
1228 | compiler options from @env{COMPAT_OPTIONS}. When | |
1229 | @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using | |
1230 | the compiler under test but with combinations of the options from | |
1231 | @env{COMPAT_OPTIONS}. | |
1232 | ||
1233 | To run only the C++ compatibility suite using the compiler under test | |
1234 | and another version of GCC using specific compiler options, do the | |
1235 | following from @file{@var{objdir}/gcc}: | |
1236 | ||
1237 | @smallexample | |
1238 | rm site.exp | |
1239 | make -k \ | |
1240 | ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ | |
1241 | COMPAT_OPTIONS="lists as shown above" \ | |
1242 | check-c++ \ | |
1243 | RUNTESTFLAGS="compat.exp" | |
1244 | @end smallexample | |
1245 | ||
1246 | A test that fails when the source files are compiled with different | |
1247 | compilers, but passes when the files are compiled with the same | |
1248 | compiler, demonstrates incompatibility of the generated code or | |
1249 | runtime support. A test that fails for the alternate compiler but | |
1250 | passes for the compiler under test probably tests for a bug that was | |
1251 | fixed in the compiler under test but is present in the alternate | |
1252 | compiler. |