OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.2.2/] [gcc/] [doc/] [sourcebuild.texi] - Blame information for rev 154

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.