]>
Commit | Line | Data |
---|---|---|
99dee823 | 1 | @c Copyright (C) 2002-2021 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. | |
0a553c7e JM |
17 | @end menu |
18 | ||
19 | @include configterms.texi | |
20 | ||
21 | @node Top Level | |
22 | @section Top Level Source Directory | |
23 | ||
24 | The top level source directory in a GCC distribution contains several | |
25 | files and directories that are shared with other software | |
26 | distributions such as that of GNU Binutils. It also contains several | |
27 | subdirectories that contain parts of GCC and its runtime libraries: | |
28 | ||
29 | @table @file | |
30 | @item boehm-gc | |
97a2feb6 MK |
31 | The Boehm conservative garbage collector, optionally used as part of |
32 | the ObjC runtime library when configured with @option{--enable-objc-gc}. | |
0a553c7e | 33 | |
3a1ef68a | 34 | @item config |
7a50adb7 | 35 | Autoconf macros and Makefile fragments used throughout the tree. |
3a1ef68a | 36 | |
0a553c7e JM |
37 | @item contrib |
38 | Contributed scripts that may be found useful in conjunction with GCC@. | |
39 | One of these, @file{contrib/texi2pod.pl}, is used to generate man | |
40 | pages from Texinfo manuals as part of the GCC build process. | |
41 | ||
10270471 LG |
42 | @item fixincludes |
43 | The support for fixing system headers to work with GCC@. See | |
44 | @file{fixincludes/README} for more information. The headers fixed by | |
45 | this mechanism are installed in @file{@var{libsubdir}/include-fixed}. | |
46 | Along with those headers, @file{README-fixinc} is also installed, as | |
47 | @file{@var{libsubdir}/include-fixed/README}. | |
48 | ||
0a553c7e JM |
49 | @item gcc |
50 | The main sources of GCC itself (except for runtime libraries), | |
51 | including optimizers, support for different target architectures, | |
2eac577f | 52 | language front ends, and testsuites. @xref{gcc Directory, , The |
0a553c7e JM |
53 | @file{gcc} Subdirectory}, for details. |
54 | ||
3a1ef68a RO |
55 | @item gnattools |
56 | Support tools for GNAT. | |
57 | ||
0a553c7e JM |
58 | @item include |
59 | Headers for the @code{libiberty} library. | |
60 | ||
10270471 LG |
61 | @item intl |
62 | GNU @code{libintl}, from GNU @code{gettext}, for systems which do not | |
3a1ef68a | 63 | include it in @code{libc}. |
10270471 | 64 | |
cd271054 AC |
65 | @item libada |
66 | The Ada runtime library. | |
67 | ||
39ce30d8 | 68 | @item libatomic |
630ba2fd | 69 | The runtime support library for atomic operations (e.g.@: for @code{__sync} |
39ce30d8 SB |
70 | and @code{__atomic}). |
71 | ||
3c95eb0e GDR |
72 | @item libcpp |
73 | The C preprocessor library. | |
74 | ||
3a1ef68a RO |
75 | @item libdecnumber |
76 | The Decimal Float support library. | |
0a553c7e JM |
77 | |
78 | @item libffi | |
97a2feb6 | 79 | The @code{libffi} library, used as part of the Go runtime library. |
0a553c7e | 80 | |
3a1ef68a RO |
81 | @item libgcc |
82 | The GCC runtime library. | |
83 | ||
84 | @item libgfortran | |
85 | The Fortran runtime library. | |
86 | ||
7a938933 ILT |
87 | @item libgo |
88 | The Go runtime library. The bulk of this library is mirrored from the | |
a1ece5c0 | 89 | @uref{https://github.com/@/golang/go, master Go repository}. |
7a938933 | 90 | |
3a1ef68a | 91 | @item libgomp |
f1f3453e | 92 | The GNU Offloading and Multi Processing Runtime Library. |
3a1ef68a | 93 | |
0a553c7e | 94 | @item libiberty |
81034129 | 95 | The @code{libiberty} library, used for portability and for some |
0a553c7e JM |
96 | generally useful data structures and algorithms. @xref{Top, , |
97 | Introduction, libiberty, @sc{gnu} libiberty}, for more information | |
98 | about this library. | |
99 | ||
39ce30d8 SB |
100 | @item libitm |
101 | The runtime support library for transactional memory. | |
102 | ||
0a553c7e | 103 | @item libobjc |
46e34f96 | 104 | The Objective-C and Objective-C++ runtime library. |
0a553c7e | 105 | |
39ce30d8 SB |
106 | @item libquadmath |
107 | The runtime support library for quad-precision math operations. | |
108 | ||
b4c522fa IB |
109 | @item libphobos |
110 | The D standard and runtime library. The bulk of this library is mirrored | |
111 | from the @uref{https://github.com/@/dlang, master D repositories}. | |
112 | ||
3a1ef68a RO |
113 | @item libssp |
114 | The Stack protector runtime library. | |
115 | ||
0a553c7e JM |
116 | @item libstdc++-v3 |
117 | The C++ runtime library. | |
118 | ||
d7f09764 | 119 | @item lto-plugin |
0d40ed43 | 120 | Plugin used by the linker if link-time optimizations are enabled. |
d7f09764 | 121 | |
0a553c7e JM |
122 | @item maintainer-scripts |
123 | Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}. | |
124 | ||
125 | @item zlib | |
97a2feb6 MK |
126 | The @code{zlib} compression library, used for compressing and |
127 | uncompressing GCC's intermediate language in LTO object files. | |
0a553c7e JM |
128 | @end table |
129 | ||
130 | The build system in the top level directory, including how recursion | |
131 | into subdirectories works and how building runtime libraries for | |
132 | multilibs is handled, is documented in a separate manual, included | |
133 | with GNU Binutils. @xref{Top, , GNU configure and build system, | |
134 | configure, The GNU configure and build system}, for details. | |
135 | ||
136 | @node gcc Directory | |
137 | @section The @file{gcc} Subdirectory | |
138 | ||
139 | The @file{gcc} directory contains many files that are part of the C | |
140 | sources of GCC, other files used as part of the configuration and | |
141 | build process, and subdirectories including documentation and a | |
2eac577f | 142 | testsuite. The files that are sources of GCC are documented in a |
0a553c7e JM |
143 | separate chapter. @xref{Passes, , Passes and Files of the Compiler}. |
144 | ||
145 | @menu | |
146 | * Subdirectories:: Subdirectories of @file{gcc}. | |
147 | * Configuration:: The configuration process, and the files it uses. | |
148 | * Build:: The build system in the @file{gcc} directory. | |
149 | * Makefile:: Targets in @file{gcc/Makefile}. | |
150 | * Library Files:: Library source files and headers under @file{gcc/}. | |
151 | * Headers:: Headers installed by GCC. | |
152 | * Documentation:: Building documentation in GCC. | |
153 | * Front End:: Anatomy of a language front end. | |
154 | * Back End:: Anatomy of a target back end. | |
155 | @end menu | |
156 | ||
157 | @node Subdirectories | |
158 | @subsection Subdirectories of @file{gcc} | |
159 | ||
160 | The @file{gcc} directory contains the following subdirectories: | |
161 | ||
162 | @table @file | |
163 | @item @var{language} | |
164 | Subdirectories for various languages. Directories containing a file | |
165 | @file{config-lang.in} are language subdirectories. The contents of | |
d4a10d0a SB |
166 | the subdirectories @file{c} (for C), @file{cp} (for C++), |
167 | @file{objc} (for Objective-C), @file{objcp} (for Objective-C++), | |
168 | and @file{lto} (for LTO) are documented in this | |
169 | manual (@pxref{Passes, , Passes and Files of the Compiler}); | |
170 | those for other languages are not. @xref{Front End, , | |
d7f09764 DN |
171 | Anatomy of a Language Front End}, for details of the files in these |
172 | directories. | |
0a553c7e | 173 | |
9a99299d JM |
174 | @item common |
175 | Source files shared between the compiler drivers (such as | |
176 | @command{gcc}) and the compilers proper (such as @file{cc1}). If an | |
177 | architecture defines target hooks shared between those places, it also | |
178 | has a subdirectory in @file{common/config}. @xref{Target Structure}. | |
179 | ||
0a553c7e JM |
180 | @item config |
181 | Configuration files for supported architectures and operating | |
182 | systems. @xref{Back End, , Anatomy of a Target Back End}, for | |
c0cbdbd9 | 183 | details of the files in this directory. |
0a553c7e JM |
184 | |
185 | @item doc | |
186 | Texinfo documentation for GCC, together with automatically generated | |
187 | man pages and support for converting the installation manual to | |
188 | HTML@. @xref{Documentation}. | |
189 | ||
0a553c7e JM |
190 | @item ginclude |
191 | System headers installed by GCC, mainly those required by the C | |
192 | standard of freestanding implementations. @xref{Headers, , Headers | |
193 | Installed by GCC}, for details of when these and other headers are | |
194 | installed. | |
195 | ||
0a553c7e JM |
196 | @item po |
197 | Message catalogs with translations of messages produced by GCC into | |
198 | various languages, @file{@var{language}.po}. This directory also | |
199 | contains @file{gcc.pot}, the template for these message catalogues, | |
200 | @file{exgettext}, a wrapper around @command{gettext} to extract the | |
201 | messages from the GCC sources and create @file{gcc.pot}, which is run | |
7ba4ca63 | 202 | by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from |
0a553c7e JM |
203 | which messages should not be extracted. |
204 | ||
205 | @item testsuite | |
2eac577f JM |
206 | The GCC testsuites (except for those for runtime libraries). |
207 | @xref{Testsuites}. | |
0a553c7e JM |
208 | @end table |
209 | ||
210 | @node Configuration | |
211 | @subsection Configuration in the @file{gcc} Directory | |
212 | ||
213 | The @file{gcc} directory is configured with an Autoconf-generated | |
214 | script @file{configure}. The @file{configure} script is generated | |
3986a20d KC |
215 | from @file{configure.ac} and @file{aclocal.m4}. From the files |
216 | @file{configure.ac} and @file{acconfig.h}, Autoheader generates the | |
0a553c7e JM |
217 | file @file{config.in}. The file @file{cstamp-h.in} is used as a |
218 | timestamp. | |
219 | ||
220 | @menu | |
221 | * Config Fragments:: Scripts used by @file{configure}. | |
330532ab NN |
222 | * System Config:: The @file{config.build}, @file{config.host}, and |
223 | @file{config.gcc} files. | |
0a553c7e JM |
224 | * Configuration Files:: Files created by running @file{configure}. |
225 | @end menu | |
226 | ||
227 | @node Config Fragments | |
228 | @subsubsection Scripts Used by @file{configure} | |
229 | ||
230 | @file{configure} uses some other scripts to help in its work: | |
231 | ||
232 | @itemize @bullet | |
233 | @item The standard GNU @file{config.sub} and @file{config.guess} | |
6ccde948 | 234 | files, kept in the top level directory, are used. |
0a553c7e JM |
235 | |
236 | @item The file @file{config.gcc} is used to handle configuration | |
daf2f129 JM |
237 | specific to the particular target machine. The file |
238 | @file{config.build} is used to handle configuration specific to the | |
330532ab NN |
239 | particular build machine. The file @file{config.host} is used to handle |
240 | configuration specific to the particular host machine. (In general, | |
241 | these should only be used for features that cannot reasonably be tested in | |
242 | Autoconf feature tests.) | |
640d429d | 243 | @xref{System Config, , The @file{config.build}; @file{config.host}; |
330532ab | 244 | and @file{config.gcc} Files}, for details of the contents of these files. |
0a553c7e JM |
245 | |
246 | @item Each language subdirectory has a file | |
247 | @file{@var{language}/config-lang.in} that is used for | |
248 | front-end-specific configuration. @xref{Front End Config, , The Front | |
249 | End @file{config-lang.in} File}, for details of this file. | |
250 | ||
251 | @item A helper script @file{configure.frag} is used as part of | |
252 | creating the output of @file{configure}. | |
253 | @end itemize | |
254 | ||
255 | @node System Config | |
640d429d | 256 | @subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files |
330532ab NN |
257 | |
258 | The @file{config.build} file contains specific rules for particular systems | |
259 | which GCC is built on. This should be used as rarely as possible, as the | |
260 | behavior of the build system can always be detected by autoconf. | |
261 | ||
262 | The @file{config.host} file contains specific rules for particular systems | |
263 | which GCC will run on. This is rarely needed. | |
264 | ||
265 | The @file{config.gcc} file contains specific rules for particular systems | |
266 | which GCC will generate code for. This is usually needed. | |
267 | ||
268 | Each file has a list of the shell variables it sets, with descriptions, at the | |
269 | top of the file. | |
0a553c7e | 270 | |
5b28c537 | 271 | FIXME: document the contents of these files, and what variables should |
0a553c7e JM |
272 | be set to control build, host and target configuration. |
273 | ||
274 | @include configfiles.texi | |
275 | ||
276 | @node Build | |
277 | @subsection Build System in the @file{gcc} Directory | |
278 | ||
279 | FIXME: describe the build system, including what is built in what | |
280 | stages. Also list the various source files that are used in the build | |
281 | process but aren't source files of GCC itself and so aren't documented | |
282 | below (@pxref{Passes}). | |
283 | ||
284 | @include makefile.texi | |
285 | ||
286 | @node Library Files | |
287 | @subsection Library Source Files and Headers under the @file{gcc} Directory | |
288 | ||
289 | FIXME: list here, with explanation, all the C source files and headers | |
290 | under the @file{gcc} directory that aren't built into the GCC | |
291 | executable but rather are part of runtime libraries and object files, | |
292 | such as @file{crtstuff.c} and @file{unwind-dw2.c}. @xref{Headers, , | |
293 | Headers Installed by GCC}, for more information about the | |
294 | @file{ginclude} directory. | |
295 | ||
296 | @node Headers | |
297 | @subsection Headers Installed by GCC | |
298 | ||
299 | In general, GCC expects the system C library to provide most of the | |
300 | headers to be used with it. However, GCC will fix those headers if | |
301 | necessary to make them work with GCC, and will install some headers | |
302 | required of freestanding implementations. These headers are installed | |
303 | in @file{@var{libsubdir}/include}. Headers for non-C runtime | |
304 | libraries are also installed by GCC; these are not documented here. | |
305 | (FIXME: document them somewhere.) | |
306 | ||
307 | Several of the headers GCC installs are in the @file{ginclude} | |
308 | directory. These headers, @file{iso646.h}, | |
6c535c69 ZW |
309 | @file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, |
310 | are installed in @file{@var{libsubdir}/include}, | |
0a553c7e JM |
311 | unless the target Makefile fragment (@pxref{Target Fragment}) |
312 | overrides this by setting @code{USER_H}. | |
313 | ||
314 | In addition to these headers and those generated by fixing system | |
315 | headers to work with GCC, some other headers may also be installed in | |
316 | @file{@var{libsubdir}/include}. @file{config.gcc} may set | |
317 | @code{extra_headers}; this specifies additional headers under | |
cd42d3df RH |
318 | @file{config} to be installed on some systems. |
319 | ||
320 | GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. | |
daf2f129 | 321 | This is done to cope with command-line options that change the |
cd42d3df RH |
322 | representation of floating point numbers. |
323 | ||
324 | GCC also installs its own version of @code{<limits.h>}; this is generated | |
0a553c7e JM |
325 | from @file{glimits.h}, together with @file{limitx.h} and |
326 | @file{limity.h} if the system also has its own version of | |
327 | @code{<limits.h>}. (GCC provides its own header because it is | |
328 | required of ISO C freestanding implementations, but needs to include | |
329 | the system header from its own header as well because other standards | |
330 | such as POSIX specify additional values to be defined in | |
331 | @code{<limits.h>}.) The system's @code{<limits.h>} header is used via | |
332 | @file{@var{libsubdir}/include/syslimits.h}, which is copied from | |
333 | @file{gsyslimits.h} if it does not need fixing to work with GCC; if it | |
334 | needs fixing, @file{syslimits.h} is the fixed copy. | |
335 | ||
1617e5ee GK |
336 | GCC can also install @code{<tgmath.h>}. It will do this when |
337 | @file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}. | |
338 | ||
0a553c7e JM |
339 | @node Documentation |
340 | @subsection Building Documentation | |
341 | ||
342 | The main GCC documentation is in the form of manuals in Texinfo | |
cc5c2741 BM |
343 | format. These are installed in Info format; DVI versions may be |
344 | generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and | |
3a1ef68a | 345 | HTML versions by @samp{make html}. In addition, some man pages are |
0a553c7e JM |
346 | generated from the Texinfo manuals, there are some other text files |
347 | with miscellaneous documentation, and runtime libraries have their own | |
348 | documentation outside the @file{gcc} directory. FIXME: document the | |
349 | documentation for runtime libraries somewhere. | |
350 | ||
351 | @menu | |
352 | * Texinfo Manuals:: GCC manuals in Texinfo format. | |
353 | * Man Page Generation:: Generating man pages from Texinfo manuals. | |
354 | * Miscellaneous Docs:: Miscellaneous text files with documentation. | |
355 | @end menu | |
356 | ||
357 | @node Texinfo Manuals | |
358 | @subsubsection Texinfo Manuals | |
359 | ||
360 | The manuals for GCC as a whole, and the C and C++ front ends, are in | |
361 | files @file{doc/*.texi}. Other front ends have their own manuals in | |
362 | files @file{@var{language}/*.texi}. Common files | |
363 | @file{doc/include/*.texi} are provided which may be included in | |
364 | multiple manuals; the following files are in @file{doc/include}: | |
365 | ||
366 | @table @file | |
367 | @item fdl.texi | |
368 | The GNU Free Documentation License. | |
369 | @item funding.texi | |
370 | The section ``Funding Free Software''. | |
371 | @item gcc-common.texi | |
372 | Common definitions for manuals. | |
7db2226d | 373 | @item gpl_v3.texi |
0a553c7e JM |
374 | The GNU General Public License. |
375 | @item texinfo.tex | |
376 | A copy of @file{texinfo.tex} known to work with the GCC manuals. | |
377 | @end table | |
378 | ||
cc5c2741 | 379 | DVI-formatted manuals are generated by @samp{make dvi}, which uses |
ff2ce160 | 380 | @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). |
cc5c2741 BM |
381 | PDF-formatted manuals are generated by @samp{make pdf}, which uses |
382 | @command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}). HTML | |
3a1ef68a | 383 | formatted manuals are generated by @samp{make html}. Info |
7ba4ca63 | 384 | manuals are generated by @samp{make info} (which is run as part of |
0a553c7e JM |
385 | a bootstrap); this generates the manuals in the source directory, |
386 | using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, | |
387 | and they are included in release distributions. | |
388 | ||
389 | Manuals are also provided on the GCC web site, in both HTML and | |
390 | PostScript forms. This is done via the script | |
10502831 | 391 | @file{maintainer-scripts/update_web_docs_git}. Each manual to be |
0a553c7e JM |
392 | provided online must be listed in the definition of @code{MANUALS} in |
393 | that file; a file @file{@var{name}.texi} must only appear once in the | |
394 | source tree, and the output manual must have the same name as the | |
395 | source file. (However, other Texinfo files, included in manuals but | |
396 | not themselves the root files of manuals, may have names that appear | |
397 | more than once in the source tree.) The manual file | |
398 | @file{@var{name}.texi} should only include other files in its own | |
399 | directory or in @file{doc/include}. HTML manuals will be generated by | |
cc5c2741 BM |
400 | @samp{makeinfo --html}, PostScript manuals by @command{texi2dvi} |
401 | and @command{dvips}, and PDF manuals by @command{texi2pdf}. | |
402 | All Texinfo files that are parts of manuals must | |
3a1ef68a | 403 | be version-controlled, even if they are generated files, for the |
0a553c7e JM |
404 | generation of online manuals to work. |
405 | ||
406 | The installation manual, @file{doc/install.texi}, is also provided on | |
407 | the GCC web site. The HTML version is generated by the script | |
408 | @file{doc/install.texi2html}. | |
409 | ||
410 | @node Man Page Generation | |
411 | @subsubsection Man Page Generation | |
412 | ||
413 | Because of user demand, in addition to full Texinfo manuals, man pages | |
414 | are provided which contain extracts from those manuals. These man | |
415 | pages are generated from the Texinfo manuals using | |
416 | @file{contrib/texi2pod.pl} and @command{pod2man}. (The man page for | |
417 | @command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference | |
418 | to @file{gcc.1}, but all the other man pages are generated from | |
419 | Texinfo manuals.) | |
420 | ||
421 | Because many systems may not have the necessary tools installed to | |
422 | generate the man pages, they are only generated if the | |
423 | @file{configure} script detects that recent enough tools are | |
424 | installed, and the Makefiles allow generating man pages to fail | |
425 | without aborting the build. Man pages are also included in release | |
426 | distributions. They are generated in the source directory. | |
427 | ||
428 | Magic comments in Texinfo files starting @samp{@@c man} control what | |
429 | parts of a Texinfo file go into a man page. Only a subset of Texinfo | |
430 | is supported by @file{texi2pod.pl}, and it may be necessary to add | |
431 | support for more Texinfo features to this script when generating new | |
432 | man pages. To improve the man page output, some special Texinfo | |
433 | macros are provided in @file{doc/include/gcc-common.texi} which | |
434 | @file{texi2pod.pl} understands: | |
435 | ||
436 | @table @code | |
437 | @item @@gcctabopt | |
438 | Use in the form @samp{@@table @@gcctabopt} for tables of options, | |
439 | where for printed output the effect of @samp{@@code} is better than | |
440 | that of @samp{@@option} but for man page output a different effect is | |
441 | wanted. | |
442 | @item @@gccoptlist | |
443 | Use for summary lists of options in manuals. | |
444 | @item @@gol | |
445 | Use at the end of each line inside @samp{@@gccoptlist}. This is | |
446 | necessary to avoid problems with differences in how the | |
447 | @samp{@@gccoptlist} macro is handled by different Texinfo formatters. | |
448 | @end table | |
449 | ||
450 | FIXME: describe the @file{texi2pod.pl} input language and magic | |
451 | comments in more detail. | |
452 | ||
453 | @node Miscellaneous Docs | |
454 | @subsubsection Miscellaneous Documentation | |
455 | ||
456 | In addition to the formal documentation that is installed by GCC, | |
3a1ef68a RO |
457 | there are several other text files in the @file{gcc} subdirectory |
458 | with miscellaneous documentation: | |
0a553c7e JM |
459 | |
460 | @table @file | |
461 | @item ABOUT-GCC-NLS | |
462 | Notes on GCC's Native Language Support. FIXME: this should be part of | |
463 | this manual rather than a separate file. | |
464 | @item ABOUT-NLS | |
465 | Notes on the Free Translation Project. | |
466 | @item COPYING | |
3a1ef68a RO |
467 | @itemx COPYING3 |
468 | The GNU General Public License, Versions 2 and 3. | |
0a553c7e | 469 | @item COPYING.LIB |
3a1ef68a RO |
470 | @itemx COPYING3.LIB |
471 | The GNU Lesser General Public License, Versions 2.1 and 3. | |
0a553c7e JM |
472 | @item *ChangeLog* |
473 | @itemx */ChangeLog* | |
474 | Change log files for various parts of GCC@. | |
475 | @item LANGUAGES | |
476 | Details of a few changes to the GCC front-end interface. FIXME: the | |
477 | information in this file should be part of general documentation of | |
478 | the front-end interface in this manual. | |
479 | @item ONEWS | |
480 | Information about new features in old versions of GCC@. (For recent | |
481 | versions, the information is on the GCC web site.) | |
482 | @item README.Portability | |
483 | Information about portability issues when writing code in GCC@. FIXME: | |
484 | why isn't this part of this manual or of the GCC Coding Conventions? | |
0a553c7e JM |
485 | @end table |
486 | ||
487 | FIXME: document such files in subdirectories, at least @file{config}, | |
d4a10d0a | 488 | @file{c}, @file{cp}, @file{objc}, @file{testsuite}. |
0a553c7e JM |
489 | |
490 | @node Front End | |
491 | @subsection Anatomy of a Language Front End | |
492 | ||
493 | A front end for a language in GCC has the following parts: | |
494 | ||
495 | @itemize @bullet | |
496 | @item | |
497 | A directory @file{@var{language}} under @file{gcc} containing source | |
498 | files for that front end. @xref{Front End Directory, , The Front End | |
499 | @file{@var{language}} Directory}, for details. | |
500 | @item | |
501 | A mention of the language in the list of supported languages in | |
502 | @file{gcc/doc/install.texi}. | |
503 | @item | |
a72967cd JM |
504 | A mention of the name under which the language's runtime library is |
505 | recognized by @option{--enable-shared=@var{package}} in the | |
506 | documentation of that option in @file{gcc/doc/install.texi}. | |
507 | @item | |
508 | A mention of any special prerequisites for building the front end in | |
509 | the documentation of prerequisites in @file{gcc/doc/install.texi}. | |
510 | @item | |
0a553c7e JM |
511 | Details of contributors to that front end in |
512 | @file{gcc/doc/contrib.texi}. If the details are in that front end's | |
513 | own manual then there should be a link to that manual's list in | |
514 | @file{contrib.texi}. | |
515 | @item | |
516 | Information about support for that language in | |
517 | @file{gcc/doc/frontends.texi}. | |
518 | @item | |
519 | Information about standards for that language, and the front end's | |
520 | support for them, in @file{gcc/doc/standards.texi}. This may be a | |
521 | link to such information in the front end's own manual. | |
522 | @item | |
523 | Details of source file suffixes for that language and @option{-x | |
524 | @var{lang}} options supported, in @file{gcc/doc/invoke.texi}. | |
525 | @item | |
526 | Entries in @code{default_compilers} in @file{gcc.c} for source file | |
527 | suffixes for that language. | |
528 | @item | |
2eac577f | 529 | Preferably testsuites, which may be under @file{gcc/testsuite} or |
0a553c7e | 530 | runtime library directories. FIXME: document somewhere how to write |
2eac577f | 531 | testsuite harnesses. |
0a553c7e JM |
532 | @item |
533 | Probably a runtime library for the language, outside the @file{gcc} | |
534 | directory. FIXME: document this further. | |
535 | @item | |
536 | Details of the directories of any runtime libraries in | |
537 | @file{gcc/doc/sourcebuild.texi}. | |
60911f14 | 538 | @item |
3a1ef68a RO |
539 | Check targets in @file{Makefile.def} for the top-level @file{Makefile} |
540 | to check just the compiler or the compiler and runtime library for the | |
541 | language. | |
0a553c7e JM |
542 | @end itemize |
543 | ||
5dc81ee9 | 544 | If the front end is added to the official GCC source repository, the |
0a553c7e JM |
545 | following are also necessary: |
546 | ||
547 | @itemize @bullet | |
548 | @item | |
c487d8b6 | 549 | At least one Bugzilla component for bugs in that front end and runtime |
fda9c731 | 550 | libraries. This category needs to be added to the Bugzilla database. |
0a553c7e JM |
551 | @item |
552 | Normally, one or more maintainers of that front end listed in | |
553 | @file{MAINTAINERS}. | |
554 | @item | |
555 | Mentions on the GCC web site in @file{index.html} and | |
556 | @file{frontends.html}, with any relevant links on | |
557 | @file{readings.html}. (Front ends that are not an official part of | |
558 | GCC may also be listed on @file{frontends.html}, with relevant links.) | |
559 | @item | |
560 | A news item on @file{index.html}, and possibly an announcement on the | |
561 | @email{gcc-announce@@gcc.gnu.org} mailing list. | |
562 | @item | |
563 | The front end's manuals should be mentioned in | |
10502831 | 564 | @file{maintainer-scripts/update_web_docs_git} (@pxref{Texinfo Manuals}) |
0a553c7e JM |
565 | and the online manuals should be linked to from |
566 | @file{onlinedocs/index.html}. | |
567 | @item | |
568 | Any old releases or CVS repositories of the front end, before its | |
aeebd94c JB |
569 | inclusion in GCC, should be made available on the GCC web site at |
570 | @uref{https://gcc.gnu.org/pub/gcc/old-releases/}. | |
0a553c7e JM |
571 | @item |
572 | The release and snapshot script @file{maintainer-scripts/gcc_release} | |
573 | should be updated to generate appropriate tarballs for this front end. | |
574 | @item | |
575 | If this front end includes its own version files that include the | |
576 | current date, @file{maintainer-scripts/update_version} should be | |
577 | updated accordingly. | |
0a553c7e JM |
578 | @end itemize |
579 | ||
580 | @menu | |
581 | * Front End Directory:: The front end @file{@var{language}} directory. | |
582 | * Front End Config:: The front end @file{config-lang.in} file. | |
3a1ef68a | 583 | * Front End Makefile:: The front end @file{Make-lang.in} file. |
0a553c7e JM |
584 | @end menu |
585 | ||
586 | @node Front End Directory | |
587 | @subsubsection The Front End @file{@var{language}} Directory | |
588 | ||
589 | A front end @file{@var{language}} directory contains the source files | |
590 | of that front end (but not of any runtime libraries, which should be | |
591 | outside the @file{gcc} directory). This includes documentation, and | |
3a1ef68a | 592 | possibly some subsidiary programs built alongside the front end. |
0a553c7e JM |
593 | Certain files are special and other parts of the compiler depend on |
594 | their names: | |
595 | ||
596 | @table @file | |
597 | @item config-lang.in | |
598 | This file is required in all language subdirectories. @xref{Front End | |
599 | Config, , The Front End @file{config-lang.in} File}, for details of | |
600 | its contents | |
601 | @item Make-lang.in | |
3a1ef68a RO |
602 | This file is required in all language subdirectories. @xref{Front End |
603 | Makefile, , The Front End @file{Make-lang.in} File}, for details of its | |
604 | contents. | |
605 | @item lang.opt | |
606 | This file registers the set of switches that the front end accepts on | |
607 | the command line, and their @option{--help} text. @xref{Options}. | |
608 | @item lang-specs.h | |
609 | This file provides entries for @code{default_compilers} in | |
610 | @file{gcc.c} which override the default of giving an error that a | |
611 | compiler for that language is not installed. | |
612 | @item @var{language}-tree.def | |
613 | This file, which need not exist, defines any language-specific tree | |
614 | codes. | |
615 | @end table | |
616 | ||
617 | @node Front End Config | |
618 | @subsubsection The Front End @file{config-lang.in} File | |
619 | ||
d4a10d0a SB |
620 | Each language subdirectory contains a @file{config-lang.in} file. |
621 | This file is a shell script that may define some variables describing | |
622 | the language: | |
3a1ef68a RO |
623 | |
624 | @table @code | |
625 | @item language | |
626 | This definition must be present, and gives the name of the language | |
627 | for some purposes such as arguments to @option{--enable-languages}. | |
628 | @item lang_requires | |
629 | If defined, this variable lists (space-separated) language front ends | |
630 | other than C that this front end requires to be enabled (with the | |
631 | names given being their @code{language} settings). For example, the | |
97a2feb6 MK |
632 | Obj-C++ front end depends on the C++ and ObjC front ends, so sets |
633 | @samp{lang_requires="objc c++"}. | |
3a1ef68a RO |
634 | @item subdir_requires |
635 | If defined, this variable lists (space-separated) front end directories | |
636 | other than C that this front end requires to be present. For example, | |
637 | the Objective-C++ front end uses source files from the C++ and | |
638 | Objective-C front ends, so sets @samp{subdir_requires="cp objc"}. | |
639 | @item target_libs | |
640 | If defined, this variable lists (space-separated) targets in the top | |
641 | level @file{Makefile} to build the runtime libraries for this | |
642 | language, such as @code{target-libobjc}. | |
643 | @item lang_dirs | |
644 | If defined, this variable lists (space-separated) top level | |
645 | directories (parallel to @file{gcc}), apart from the runtime libraries, | |
646 | that should not be configured if this front end is not built. | |
647 | @item build_by_default | |
648 | If defined to @samp{no}, this language front end is not built unless | |
649 | enabled in a @option{--enable-languages} argument. Otherwise, front | |
650 | ends are built by default, subject to any special logic in | |
651 | @file{configure.ac} (as is present to disable the Ada front end if the | |
652 | Ada compiler is not already installed). | |
653 | @item boot_language | |
654 | If defined to @samp{yes}, this front end is built in stage1 of the | |
655 | bootstrap. This is only relevant to front ends written in their own | |
656 | languages. | |
657 | @item compilers | |
658 | If defined, a space-separated list of compiler executables that will | |
659 | be run by the driver. The names here will each end | |
660 | with @samp{\$(exeext)}. | |
661 | @item outputs | |
662 | If defined, a space-separated list of files that should be generated | |
663 | by @file{configure} substituting values in them. This mechanism can | |
664 | be used to create a file @file{@var{language}/Makefile} from | |
665 | @file{@var{language}/Makefile.in}, but this is deprecated, building | |
666 | everything from the single @file{gcc/Makefile} is preferred. | |
667 | @item gtfiles | |
668 | If defined, a space-separated list of files that should be scanned by | |
669 | @file{gengtype.c} to generate the garbage collection tables and routines for | |
670 | this language. This excludes the files that are common to all front | |
671 | ends. @xref{Type Information}. | |
672 | ||
673 | @end table | |
674 | ||
675 | @node Front End Makefile | |
676 | @subsubsection The Front End @file{Make-lang.in} File | |
677 | ||
678 | Each language subdirectory contains a @file{Make-lang.in} file. It contains | |
0a553c7e JM |
679 | targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the |
680 | setting of @code{language} in @file{config-lang.in}) for the following | |
681 | values of @code{@var{hook}}, and any other Makefile rules required to | |
682 | build those targets (which may if necessary use other Makefiles | |
683 | specified in @code{outputs} in @file{config-lang.in}, although this is | |
880b9e7b | 684 | deprecated). It also adds any testsuite targets that can use the |
49a41726 JM |
685 | standard rule in @file{gcc/Makefile.in} to the variable |
686 | @code{lang_checks}. | |
0a553c7e JM |
687 | |
688 | @table @code | |
f457c50c | 689 | @item all.cross |
0a553c7e JM |
690 | @itemx start.encap |
691 | @itemx rest.encap | |
692 | FIXME: exactly what goes in each of these targets? | |
65ebbf81 TT |
693 | @item tags |
694 | Build an @command{etags} @file{TAGS} file in the language subdirectory | |
695 | in the source tree. | |
0a553c7e | 696 | @item info |
ce5c1cf3 | 697 | Build info documentation for the front end, in the build directory. |
7ba4ca63 | 698 | This target is only called by @samp{make bootstrap} if a suitable |
0a553c7e | 699 | version of @command{makeinfo} is available, so does not need to check |
ce5c1cf3 | 700 | for this, and should fail if an error occurs. |
0a553c7e JM |
701 | @item dvi |
702 | Build DVI documentation for the front end, in the build directory. | |
703 | This should be done using @code{$(TEXI2DVI)}, with appropriate | |
704 | @option{-I} arguments pointing to directories of included files. | |
cc5c2741 BM |
705 | @item pdf |
706 | Build PDF documentation for the front end, in the build directory. | |
707 | This should be done using @code{$(TEXI2PDF)}, with appropriate | |
708 | @option{-I} arguments pointing to directories of included files. | |
9d65c5cb | 709 | @item html |
0e8f8fea | 710 | Build HTML documentation for the front end, in the build directory. |
ce5c1cf3 | 711 | @item man |
0a553c7e | 712 | Build generated man pages for the front end from Texinfo manuals |
ce5c1cf3 | 713 | (@pxref{Man Page Generation}), in the build directory. This target |
0a553c7e JM |
714 | is only called if the necessary tools are available, but should ignore |
715 | errors so as not to stop the build if errors occur; man pages are | |
716 | optional and the tools involved may be installed in a broken way. | |
0a553c7e JM |
717 | @item install-common |
718 | Install everything that is part of the front end, apart from the | |
719 | compiler executables listed in @code{compilers} in | |
8e5f33ff | 720 | @file{config-lang.in}. |
0a553c7e JM |
721 | @item install-info |
722 | Install info documentation for the front end, if it is present in the | |
97ae108d | 723 | source directory. This target should have dependencies on info files |
880b9e7b | 724 | that should be installed. |
0a553c7e JM |
725 | @item install-man |
726 | Install man pages for the front end. This target should ignore | |
727 | errors. | |
2a4c0366 TG |
728 | @item install-plugin |
729 | Install headers needed for plugins. | |
ce5c1cf3 KC |
730 | @item srcextra |
731 | Copies its dependencies into the source directory. This generally should | |
da543234 | 732 | be used for generated files such as Bison output files which are not |
3a1ef68a | 733 | version-controlled, but should be included in any release tarballs. This |
ce5c1cf3 KC |
734 | target will be executed during a bootstrap if |
735 | @samp{--enable-generated-files-in-srcdir} was specified as a | |
736 | @file{configure} option. | |
737 | @item srcinfo | |
738 | @itemx srcman | |
739 | Copies its dependencies into the source directory. These targets will be | |
740 | executed during a bootstrap if @samp{--enable-generated-files-in-srcdir} | |
741 | was specified as a @file{configure} option. | |
0a553c7e JM |
742 | @item uninstall |
743 | Uninstall files installed by installing the compiler. This is | |
744 | currently documented not to be supported, so the hook need not do | |
745 | anything. | |
746 | @item mostlyclean | |
747 | @itemx clean | |
748 | @itemx distclean | |
0a553c7e | 749 | @itemx maintainer-clean |
a03ad584 | 750 | The language parts of the standard GNU |
8a36672b | 751 | @samp{*clean} targets. @xref{Standard Targets, , Standard Targets for |
0a553c7e | 752 | Users, standards, GNU Coding Standards}, for details of the standard |
a03ad584 | 753 | targets. For GCC, @code{maintainer-clean} should delete |
3a1ef68a RO |
754 | all generated files in the source directory that are not version-controlled, |
755 | but should not delete anything that is. | |
0a553c7e JM |
756 | @end table |
757 | ||
6cba282a TT |
758 | @file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS} |
759 | to a list of host object files that are used by that language. | |
760 | ||
0a553c7e JM |
761 | @node Back End |
762 | @subsection Anatomy of a Target Back End | |
763 | ||
764 | A back end for a target architecture in GCC has the following parts: | |
765 | ||
766 | @itemize @bullet | |
767 | @item | |
768 | A directory @file{@var{machine}} under @file{gcc/config}, containing a | |
769 | machine description @file{@var{machine}.md} file (@pxref{Machine Desc, | |
770 | , Machine Descriptions}), header files @file{@var{machine}.h} and | |
771 | @file{@var{machine}-protos.h} and a source file @file{@var{machine}.c} | |
772 | (@pxref{Target Macros, , Target Description Macros and Functions}), | |
773 | possibly a target Makefile fragment @file{t-@var{machine}} | |
774 | (@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe | |
775 | some other files. The names of these files may be changed from the | |
776 | defaults given by explicit specifications in @file{config.gcc}. | |
777 | @item | |
a5381466 ZW |
778 | If necessary, a file @file{@var{machine}-modes.def} in the |
779 | @file{@var{machine}} directory, containing additional machine modes to | |
780 | represent condition codes. @xref{Condition Code}, for further details. | |
781 | @item | |
75685792 RS |
782 | An optional @file{@var{machine}.opt} file in the @file{@var{machine}} |
783 | directory, containing a list of target-specific options. You can also | |
784 | add other option files using the @code{extra_options} variable in | |
785 | @file{config.gcc}. @xref{Options}. | |
786 | @item | |
0a553c7e JM |
787 | Entries in @file{config.gcc} (@pxref{System Config, , The |
788 | @file{config.gcc} File}) for the systems with this target | |
789 | architecture. | |
790 | @item | |
791 | Documentation in @file{gcc/doc/invoke.texi} for any command-line | |
792 | options supported by this target (@pxref{Run-time Target, , Run-time | |
793 | Target Specification}). This means both entries in the summary table | |
794 | of options and details of the individual options. | |
795 | @item | |
796 | Documentation in @file{gcc/doc/extend.texi} for any target-specific | |
797 | attributes supported (@pxref{Target Attributes, , Defining | |
798 | target-specific uses of @code{__attribute__}}), including where the | |
799 | same attribute is already supported on some targets, which are | |
800 | enumerated in the manual. | |
801 | @item | |
802 | Documentation in @file{gcc/doc/extend.texi} for any target-specific | |
803 | pragmas supported. | |
804 | @item | |
0975678f JM |
805 | Documentation in @file{gcc/doc/extend.texi} of any target-specific |
806 | built-in functions supported. | |
0a553c7e | 807 | @item |
a2bec818 DJ |
808 | Documentation in @file{gcc/doc/extend.texi} of any target-specific |
809 | format checking styles supported. | |
810 | @item | |
0a553c7e JM |
811 | Documentation in @file{gcc/doc/md.texi} of any target-specific |
812 | constraint letters (@pxref{Machine Constraints, , Constraints for | |
813 | Particular Machines}). | |
814 | @item | |
815 | A note in @file{gcc/doc/contrib.texi} under the person or people who | |
816 | contributed the target support. | |
817 | @item | |
818 | Entries in @file{gcc/doc/install.texi} for all target triplets | |
819 | supported with this target architecture, giving details of any special | |
820 | notes about installation for this target, or saying that there are no | |
821 | special notes if there are none. | |
822 | @item | |
823 | Possibly other support outside the @file{gcc} directory for runtime | |
3a1ef68a | 824 | libraries. FIXME: reference docs for this. The @code{libstdc++} porting |
0a553c7e JM |
825 | manual needs to be installed as info for this to work, or to be a |
826 | chapter of this manual. | |
827 | @end itemize | |
828 | ||
e095eec1 SL |
829 | The @file{@var{machine}.h} header is included very early in GCC's |
830 | standard sequence of header files, while @file{@var{machine}-protos.h} | |
831 | is included late in the sequence. Thus @file{@var{machine}-protos.h} | |
832 | can include declarations referencing types that are not defined when | |
833 | @file{@var{machine}.h} is included, specifically including those from | |
834 | @file{rtl.h} and @file{tree.h}. Since both RTL and tree types may not | |
835 | be available in every context where @file{@var{machine}-protos.h} is | |
836 | included, in this file you should guard declarations using these types | |
837 | inside appropriate @code{#ifdef RTX_CODE} or @code{#ifdef TREE_CODE} | |
838 | conditional code segments. | |
839 | ||
840 | If the backend uses shared data structures that require @code{GTY} markers | |
841 | for garbage collection (@pxref{Type Information}), you must declare those | |
842 | in @file{@var{machine}.h} rather than @file{@var{machine}-protos.h}. | |
843 | Any definitions required for building libgcc must also go in | |
844 | @file{@var{machine}.h}. | |
845 | ||
8fcc61f8 RS |
846 | GCC uses the macro @code{IN_TARGET_CODE} to distinguish between |
847 | machine-specific @file{.c} and @file{.cc} files and | |
848 | machine-independent @file{.c} and @file{.cc} files. Machine-specific | |
849 | files should use the directive: | |
850 | ||
851 | @example | |
852 | #define IN_TARGET_CODE 1 | |
853 | @end example | |
854 | ||
855 | before including @code{config.h}. | |
856 | ||
5dc81ee9 | 857 | If the back end is added to the official GCC source repository, the |
0a553c7e JM |
858 | following are also necessary: |
859 | ||
860 | @itemize @bullet | |
861 | @item | |
862 | An entry for the target architecture in @file{readings.html} on the | |
863 | GCC web site, with any relevant links. | |
864 | @item | |
0acdc221 JM |
865 | Details of the properties of the back end and target architecture in |
866 | @file{backends.html} on the GCC web site. | |
867 | @item | |
0a553c7e JM |
868 | A news item about the contribution of support for that target |
869 | architecture, in @file{index.html} on the GCC web site. | |
870 | @item | |
871 | Normally, one or more maintainers of that target listed in | |
872 | @file{MAINTAINERS}. Some existing architectures may be unmaintained, | |
873 | but it would be unusual to add support for a target that does not have | |
874 | a maintainer when support is added. | |
bcb521e9 JM |
875 | @item |
876 | Target triplets covering all @file{config.gcc} stanzas for the target, | |
877 | in the list in @file{contrib/config-list.mk}. | |
0a553c7e JM |
878 | @end itemize |
879 | ||
2eac577f | 880 | @node Testsuites |
500cdcb0 | 881 | @chapter Testsuites |
0a553c7e | 882 | |
2eac577f JM |
883 | GCC contains several testsuites to help maintain compiler quality. |
884 | Most of the runtime libraries and language front ends in GCC have | |
885 | testsuites. Currently only the C language testsuites are documented | |
0a553c7e JM |
886 | here; FIXME: document the others. |
887 | ||
888 | @menu | |
2eac577f | 889 | * Test Idioms:: Idioms used in testsuite code. |
35fdf04e | 890 | * Test Directives:: Directives used within DejaGnu tests. |
2eac577f JM |
891 | * Ada Tests:: The Ada language testsuites. |
892 | * C Tests:: The C language testsuites. | |
d7f09764 | 893 | * LTO Testing:: Support for testing link-time optimizations. |
138d4703 JJ |
894 | * gcov Testing:: Support for testing gcov. |
895 | * profopt Testing:: Support for testing profile-directed optimizations. | |
46b2356d | 896 | * compat Testing:: Support for testing binary compatibility. |
91a5b394 | 897 | * Torture Tests:: Support for torture testing using multiple options. |
71103b61 DM |
898 | * GIMPLE Tests:: Support for testing GIMPLE passes. |
899 | * RTL Tests:: Support for testing RTL passes. | |
0a553c7e JM |
900 | @end menu |
901 | ||
902 | @node Test Idioms | |
500cdcb0 | 903 | @section Idioms Used in Testsuite Code |
0a553c7e | 904 | |
1eaf20ec | 905 | In general, C testcases have a trailing @file{-@var{n}.c}, starting |
4ef84575 JM |
906 | with @file{-1.c}, in case other testcases with similar names are added |
907 | later. If the test is a test of some well-defined feature, it should | |
908 | have a name referring to that feature such as | |
909 | @file{@var{feature}-1.c}. If it does not test a well-defined feature | |
910 | but just happens to exercise a bug somewhere in the compiler, and a | |
911 | bug report has been filed for this bug in the GCC bug database, | |
912 | @file{pr@var{bug-number}-1.c} is the appropriate form of name. | |
913 | Otherwise (for miscellaneous bugs not filed in the GCC bug database), | |
914 | and previously more generally, test cases are named after the date on | |
915 | which they were added. This allows people to tell at a glance whether | |
916 | a test failure is because of a recently found bug that has not yet | |
917 | been fixed, or whether it may be a regression, but does not give any | |
918 | other information about the bug or where discussion of it may be | |
919 | found. Some other language testsuites follow similar conventions. | |
0a553c7e | 920 | |
2eac577f | 921 | In the @file{gcc.dg} testsuite, it is often necessary to test that an |
0a553c7e JM |
922 | error is indeed a hard error and not just a warning---for example, |
923 | where it is a constraint violation in the C standard, which must | |
924 | become an error with @option{-pedantic-errors}. The following idiom, | |
925 | where the first line shown is line @var{line} of the file and the line | |
926 | that generates the error, is used for this: | |
927 | ||
928 | @smallexample | |
929 | /* @{ dg-bogus "warning" "warning in place of error" @} */ | |
930 | /* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */ | |
931 | @end smallexample | |
932 | ||
933 | It may be necessary to check that an expression is an integer constant | |
934 | expression and has a certain value. To check that @code{@var{E}} has | |
935 | value @code{@var{V}}, an idiom similar to the following is used: | |
936 | ||
937 | @smallexample | |
938 | char x[((E) == (V) ? 1 : -1)]; | |
939 | @end smallexample | |
940 | ||
941 | In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make | |
942 | assertions about the types of expressions. See, for example, | |
943 | @file{gcc.dg/c99-condexpr-1.c}. The more subtle uses depend on the | |
944 | exact rules for the types of conditional expressions in the C | |
945 | standard; see, for example, @file{gcc.dg/c99-intconst-1.c}. | |
946 | ||
947 | It is useful to be able to test that optimizations are being made | |
948 | properly. This cannot be done in all cases, but it can be done where | |
949 | the optimization will lead to code being optimized away (for example, | |
950 | where flow analysis or alias analysis should show that certain code | |
951 | cannot be called) or to functions not being called because they have | |
952 | been expanded as built-in functions. Such tests go in | |
953 | @file{gcc.c-torture/execute}. Where code should be optimized away, a | |
954 | call to a nonexistent function such as @code{link_failure ()} may be | |
955 | inserted; a definition | |
956 | ||
957 | @smallexample | |
958 | #ifndef __OPTIMIZE__ | |
959 | void | |
960 | link_failure (void) | |
961 | @{ | |
962 | abort (); | |
963 | @} | |
964 | #endif | |
965 | @end smallexample | |
966 | ||
967 | @noindent | |
968 | will also be needed so that linking still succeeds when the test is | |
969 | run without optimization. When all calls to a built-in function | |
970 | should have been optimized and no calls to the non-built-in version of | |
971 | the function should remain, that function may be defined as | |
972 | @code{static} to call @code{abort ()} (although redeclaring a function | |
973 | as static may not work on all targets). | |
974 | ||
4b2ece8f NN |
975 | All testcases must be portable. Target-specific testcases must have |
976 | appropriate code to avoid causing failures on unsupported systems; | |
977 | unfortunately, the mechanisms for this differ by directory. | |
978 | ||
2eac577f | 979 | FIXME: discuss non-C testsuites here. |
0a553c7e | 980 | |
35fdf04e | 981 | @node Test Directives |
500cdcb0 | 982 | @section Directives used within DejaGnu tests |
35fdf04e | 983 | |
d4f3924a JJ |
984 | @menu |
985 | * Directives:: Syntax and descriptions of test directives. | |
986 | * Selectors:: Selecting targets to which a test applies. | |
987 | * Effective-Target Keywords:: Keywords describing target attributes. | |
988 | * Add Options:: Features for @code{dg-add-options} | |
989 | * Require Support:: Variants of @code{dg-require-@var{support}} | |
990 | * Final Actions:: Commands for use in @code{dg-final} | |
991 | @end menu | |
992 | ||
993 | @node Directives | |
994 | @subsection Syntax and Descriptions of test directives | |
995 | ||
35fdf04e | 996 | Test directives appear within comments in a test source file and begin |
0ee5ccdf | 997 | with @code{dg-}. Some of these are defined within DejaGnu and others |
35fdf04e JJ |
998 | are local to the GCC testsuite. |
999 | ||
1000 | The order in which test directives appear in a test can be important: | |
1001 | directives local to GCC sometimes override information used by the | |
1002 | DejaGnu directives, which know nothing about the GCC directives, so the | |
1003 | DejaGnu directives must precede GCC directives. | |
1004 | ||
d4f3924a JJ |
1005 | Several test directives include selectors (@pxref{Selectors, , }) |
1006 | which are usually preceded by the keyword @code{target} or @code{xfail}. | |
8d2d2ec6 | 1007 | |
d4f3924a | 1008 | @subsubsection Specify how to build the test |
35fdf04e JJ |
1009 | |
1010 | @table @code | |
1011 | @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @} | |
1012 | @var{do-what-keyword} specifies how the test is compiled and whether | |
1013 | it is executed. It is one of: | |
1014 | ||
1015 | @table @code | |
1016 | @item preprocess | |
1017 | Compile with @option{-E} to run only the preprocessor. | |
35fdf04e | 1018 | @item compile |
e492980b RIL |
1019 | Compile with @option{-S} to produce an assembly code file. |
1020 | @item assemble | |
35fdf04e JJ |
1021 | Compile with @option{-c} to produce a relocatable object file. |
1022 | @item link | |
1023 | Compile, assemble, and link to produce an executable file. | |
1024 | @item run | |
1025 | Produce and run an executable file, which is expected to return | |
1026 | an exit code of 0. | |
1027 | @end table | |
1028 | ||
1029 | The default is @code{compile}. That can be overridden for a set of | |
1030 | tests by redefining @code{dg-do-what-default} within the @code{.exp} | |
1031 | file for those tests. | |
1032 | ||
1033 | If the directive includes the optional @samp{@{ target @var{selector} @}} | |
d4f3924a JJ |
1034 | then the test is skipped unless the target system matches the |
1035 | @var{selector}. | |
35fdf04e | 1036 | |
17a7cb4e | 1037 | If @var{do-what-keyword} is @code{run} and the directive includes |
fdaea7e2 JJ |
1038 | the optional @samp{@{ xfail @var{selector} @}} and the selector is met |
1039 | then the test is expected to fail. The @code{xfail} clause is ignored | |
17a7cb4e | 1040 | for other values of @var{do-what-keyword}; those tests can use |
fdaea7e2 | 1041 | directive @code{dg-xfail-if}. |
d4f3924a JJ |
1042 | @end table |
1043 | ||
1044 | @subsubsection Specify additional compiler options | |
35fdf04e | 1045 | |
d4f3924a | 1046 | @table @code |
35fdf04e JJ |
1047 | @item @{ dg-options @var{options} [@{ target @var{selector} @}] @} |
1048 | This DejaGnu directive provides a list of compiler options, to be used | |
1049 | if the target system matches @var{selector}, that replace the default | |
1050 | options used for this set of tests. | |
1051 | ||
923158be | 1052 | @item @{ dg-add-options @var{feature} @dots{} @} |
db9a0df0 RS |
1053 | Add any compiler options that are needed to access certain features. |
1054 | This directive does nothing on targets that enable the features by | |
1055 | default, or that don't provide them at all. It must come after | |
1056 | all @code{dg-options} directives. | |
d4f3924a | 1057 | For supported values of @var{feature} see @ref{Add Options, ,}. |
91ffe356 RO |
1058 | |
1059 | @item @{ dg-additional-options @var{options} [@{ target @var{selector} @}] @} | |
1060 | This directive provides a list of compiler options, to be used | |
1061 | if the target system matches @var{selector}, that are added to the default | |
1062 | options used for this set of tests. | |
db9a0df0 RS |
1063 | @end table |
1064 | ||
d4f3924a JJ |
1065 | @subsubsection Modify the test timeout value |
1066 | ||
1067 | The normal timeout limit, in seconds, is found by searching the | |
1068 | following in order: | |
d4038ca2 JJ |
1069 | |
1070 | @itemize @bullet | |
1071 | @item the value defined by an earlier @code{dg-timeout} directive in | |
1072 | the test | |
1073 | ||
1074 | @item variable @var{tool_timeout} defined by the set of tests | |
1075 | ||
e2f08cac | 1076 | @item @var{gcc},@var{timeout} set in the target board |
d4038ca2 JJ |
1077 | |
1078 | @item 300 | |
1079 | @end itemize | |
1080 | ||
d4f3924a JJ |
1081 | @table @code |
1082 | @item @{ dg-timeout @var{n} [@{target @var{selector} @}] @} | |
1083 | Set the time limit for the compilation and for the execution of the test | |
1084 | to the specified number of seconds. | |
1085 | ||
17a7cb4e RO |
1086 | @item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @} |
1087 | Multiply the normal time limit for compilation and execution of the test | |
1088 | by the specified floating-point factor. | |
d4f3924a JJ |
1089 | @end table |
1090 | ||
1091 | @subsubsection Skip a test for some targets | |
17a7cb4e | 1092 | |
d4f3924a | 1093 | @table @code |
8ec49cff | 1094 | @item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} |
15e7a617 JJ |
1095 | Arguments @var{include-opts} and @var{exclude-opts} are lists in which |
1096 | each element is a string of zero or more GCC options. | |
1097 | Skip the test if all of the following conditions are met: | |
1098 | @itemize @bullet | |
1099 | @item the test system is included in @var{selector} | |
1100 | ||
1101 | @item for at least one of the option strings in @var{include-opts}, | |
1102 | every option from that string is in the set of options with which | |
1103 | the test would be compiled; use @samp{"*"} for an @var{include-opts} list | |
8ec49cff JJ |
1104 | that matches any options; that is the default if @var{include-opts} is |
1105 | not specified | |
15e7a617 JJ |
1106 | |
1107 | @item for each of the option strings in @var{exclude-opts}, at least one | |
1108 | option from that string is not in the set of options with which the test | |
8ec49cff JJ |
1109 | would be compiled; use @samp{""} for an empty @var{exclude-opts} list; |
1110 | that is the default if @var{exclude-opts} is not specified | |
15e7a617 JJ |
1111 | @end itemize |
1112 | ||
1113 | For example, to skip a test if option @code{-Os} is present: | |
1114 | ||
1115 | @smallexample | |
1116 | /* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */ | |
1117 | @end smallexample | |
1118 | ||
1119 | To skip a test if both options @code{-O2} and @code{-g} are present: | |
1120 | ||
1121 | @smallexample | |
1122 | /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */ | |
1123 | @end smallexample | |
1124 | ||
1125 | To skip a test if either @code{-O2} or @code{-O3} is present: | |
1126 | ||
1127 | @smallexample | |
1128 | /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */ | |
1129 | @end smallexample | |
1130 | ||
d4f3924a | 1131 | To skip a test unless option @code{-Os} is present: |
15e7a617 JJ |
1132 | |
1133 | @smallexample | |
1134 | /* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */ | |
1135 | @end smallexample | |
1136 | ||
1137 | To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g} | |
1138 | but not if @code{-fpic} is also present: | |
1139 | ||
1140 | @smallexample | |
1141 | /* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */ | |
1142 | @end smallexample | |
35fdf04e | 1143 | |
d795a8ef | 1144 | @item @{ dg-require-effective-target @var{keyword} [@{ target @var{selector} @}] @} |
d4f3924a JJ |
1145 | Skip the test if the test target, including current multilib flags, |
1146 | is not covered by the effective-target keyword. | |
40f1bdd9 RO |
1147 | If the directive includes the optional @samp{@{ @var{selector} @}} |
1148 | then the effective-target test is only performed if the target system | |
1149 | matches the @var{selector}. | |
d4f3924a JJ |
1150 | This directive must appear after any @code{dg-do} directive in the test |
1151 | and before any @code{dg-additional-sources} directive. | |
1152 | @xref{Effective-Target Keywords, , }. | |
35fdf04e JJ |
1153 | |
1154 | @item @{ dg-require-@var{support} args @} | |
d4f3924a | 1155 | Skip the test if the target does not provide the required support. |
9f143763 JJ |
1156 | These directives must appear after any @code{dg-do} directive in the test |
1157 | and before any @code{dg-additional-sources} directive. | |
35fdf04e JJ |
1158 | They require at least one argument, which can be an empty string if the |
1159 | specific procedure does not examine the argument. | |
d4f3924a JJ |
1160 | @xref{Require Support, , }, for a complete list of these directives. |
1161 | @end table | |
35fdf04e | 1162 | |
d4f3924a JJ |
1163 | @subsubsection Expect a test to fail for some targets |
1164 | ||
1165 | @table @code | |
1166 | @item @{ dg-xfail-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} | |
1167 | Expect the test to fail if the conditions (which are the same as for | |
1168 | @code{dg-skip-if}) are met. This does not affect the execute step. | |
1169 | ||
1170 | @item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @} | |
1171 | Expect the execute step of a test to fail if the conditions (which are | |
1172 | the same as for @code{dg-skip-if}) are met. | |
1173 | @end table | |
1174 | ||
63668666 MP |
1175 | @subsubsection Expect the compiler to crash |
1176 | ||
1177 | @table @code | |
1178 | @item @{ dg-ice @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} | |
1179 | Expect the compiler to crash with an internal compiler error and return | |
1180 | a nonzero exit status if the conditions (which are the same as for | |
1181 | @code{dg-skip-if}) are met. Used for tests that test bugs that have not been | |
1182 | fixed yet. | |
1183 | @end table | |
1184 | ||
d4f3924a | 1185 | @subsubsection Expect the test executable to fail |
35fdf04e | 1186 | |
d4f3924a | 1187 | @table @code |
8ec49cff | 1188 | @item @{ dg-shouldfail @var{comment} [@{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]]] @} |
263108e1 JJ |
1189 | Expect the test executable to return a nonzero exit status if the |
1190 | conditions (which are the same as for @code{dg-skip-if}) are met. | |
d4f3924a JJ |
1191 | @end table |
1192 | ||
1193 | @subsubsection Verify compiler messages | |
09c4cadd JL |
1194 | Where @var{line} is an accepted argument for these commands, a value of @samp{0} |
1195 | can be used if there is no line associated with the message. | |
263108e1 | 1196 | |
d4f3924a | 1197 | @table @code |
8964d5aa | 1198 | @item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @} |
35fdf04e JJ |
1199 | This DejaGnu directive appears on a source line that is expected to get |
1200 | an error message, or else specifies the source line associated with the | |
1201 | message. If there is no message for that line or if the text of that | |
1202 | message is not matched by @var{regexp} then the check fails and | |
1203 | @var{comment} is included in the @code{FAIL} message. The check does | |
d4f3924a | 1204 | not look for the string @samp{error} unless it is part of @var{regexp}. |
35fdf04e | 1205 | |
8964d5aa | 1206 | @item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @} |
35fdf04e JJ |
1207 | This DejaGnu directive appears on a source line that is expected to get |
1208 | a warning message, or else specifies the source line associated with the | |
1209 | message. If there is no message for that line or if the text of that | |
1210 | message is not matched by @var{regexp} then the check fails and | |
1211 | @var{comment} is included in the @code{FAIL} message. The check does | |
d4f3924a | 1212 | not look for the string @samp{warning} unless it is part of @var{regexp}. |
35fdf04e | 1213 | |
8964d5aa | 1214 | @item @{ dg-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @} |
ba2f32a9 JJ |
1215 | The line is expected to get a message other than an error or warning. |
1216 | If there is no message for that line or if the text of that message is | |
1217 | not matched by @var{regexp} then the check fails and @var{comment} is | |
1218 | included in the @code{FAIL} message. | |
1219 | ||
8964d5aa | 1220 | @item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] ]] @} |
35fdf04e JJ |
1221 | This DejaGnu directive appears on a source line that should not get a |
1222 | message matching @var{regexp}, or else specifies the source line | |
1223 | associated with the bogus message. It is usually used with @samp{xfail} | |
1224 | to indicate that the message is a known problem for a particular set of | |
1225 | targets. | |
1226 | ||
1b4b1fc7 TV |
1227 | @item @{ dg-line @var{linenumvar} @} |
1228 | This DejaGnu directive sets the variable @var{linenumvar} to the line number of | |
1229 | the source line. The variable @var{linenumvar} can then be used in subsequent | |
1230 | @code{dg-error}, @code{dg-warning}, @code{dg-message} and @code{dg-bogus} | |
1231 | directives. For example: | |
1232 | ||
1233 | @smallexample | |
1234 | int a; /* @{ dg-line first_def_a @} */ | |
1235 | float a; /* @{ dg-error "conflicting types of" @} */ | |
1236 | /* @{ dg-message "previous declaration of" "" @{ target *-*-* @} first_def_a @} */ | |
1237 | @end smallexample | |
1238 | ||
35fdf04e JJ |
1239 | @item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @} |
1240 | This DejaGnu directive indicates that the test is expected to fail due | |
cc95a845 | 1241 | to compiler messages that are not handled by @samp{dg-error}, |
ce396345 JJ |
1242 | @samp{dg-warning} or @samp{dg-bogus}. For this directive @samp{xfail} |
1243 | has the same effect as @samp{target}. | |
35fdf04e | 1244 | |
d4f3924a JJ |
1245 | @item @{ dg-prune-output @var{regexp} @} |
1246 | Prune messages matching @var{regexp} from the test output. | |
1247 | @end table | |
1248 | ||
1249 | @subsubsection Verify output of the test executable | |
1250 | ||
1251 | @table @code | |
35fdf04e JJ |
1252 | @item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @} |
1253 | This DejaGnu directive compares @var{regexp} to the combined output | |
1254 | that the test executable writes to @file{stdout} and @file{stderr}. | |
d4f3924a | 1255 | @end table |
35fdf04e | 1256 | |
7c4491e3 TC |
1257 | @subsubsection Specify environment variables for a test |
1258 | ||
1259 | @table @code | |
1260 | @item @{ dg-set-compiler-env-var @var{var_name} "@var{var_value}" @} | |
1261 | Specify that the environment variable @var{var_name} needs to be set | |
1262 | to @var{var_value} before invoking the compiler on the test file. | |
1263 | ||
1264 | @item @{ dg-set-target-env-var @var{var_name} "@var{var_value}" @} | |
1265 | Specify that the environment variable @var{var_name} needs to be set | |
1266 | to @var{var_value} before execution of the program created by the test. | |
1267 | @end table | |
1268 | ||
d4f3924a | 1269 | @subsubsection Specify additional files for a test |
35fdf04e | 1270 | |
d4f3924a | 1271 | @table @code |
35fdf04e JJ |
1272 | @item @{ dg-additional-files "@var{filelist}" @} |
1273 | Specify additional files, other than source files, that must be copied | |
1274 | to the system where the compiler runs. | |
1275 | ||
1276 | @item @{ dg-additional-sources "@var{filelist}" @} | |
1277 | Specify additional source files to appear in the compile line | |
1278 | following the main test file. | |
d4f3924a | 1279 | @end table |
35fdf04e | 1280 | |
d4f3924a JJ |
1281 | @subsubsection Add checks at the end of a test |
1282 | ||
1283 | @table @code | |
35fdf04e JJ |
1284 | @item @{ dg-final @{ @var{local-directive} @} @} |
1285 | This DejaGnu directive is placed within a comment anywhere in the | |
1286 | source file and is processed after the test has been compiled and run. | |
cc95a845 | 1287 | Multiple @samp{dg-final} commands are processed in the order in which |
d4f3924a JJ |
1288 | they appear in the source file. @xref{Final Actions, , }, for a list |
1289 | of directives that can be used within @code{dg-final}. | |
1290 | @end table | |
35fdf04e | 1291 | |
d4f3924a JJ |
1292 | @node Selectors |
1293 | @subsection Selecting targets to which a test applies | |
1294 | ||
1295 | Several test directives include @var{selector}s to limit the targets | |
1296 | for which a test is run or to declare that a test is expected to fail | |
1297 | on particular targets. | |
1298 | ||
1299 | A selector is: | |
1300 | @itemize @bullet | |
776de6b2 JJ |
1301 | @item one or more target triplets, possibly including wildcard characters; |
1302 | use @samp{*-*-*} to match any target | |
d4f3924a JJ |
1303 | @item a single effective-target keyword (@pxref{Effective-Target Keywords}) |
1304 | @item a logical expression | |
1305 | @end itemize | |
1306 | ||
776de6b2 JJ |
1307 | Depending on the context, the selector specifies whether a test is |
1308 | skipped and reported as unsupported or is expected to fail. A context | |
1309 | that allows either @samp{target} or @samp{xfail} also allows | |
1310 | @samp{@{ target @var{selector1} xfail @var{selector2} @}} | |
1311 | to skip the test for targets that don't match @var{selector1} and the | |
1312 | test to fail for targets that match @var{selector2}. | |
d4f3924a JJ |
1313 | |
1314 | A selector expression appears within curly braces and uses a single | |
1315 | logical operator: one of @samp{!}, @samp{&&}, or @samp{||}. An | |
1316 | operand is another selector expression, an effective-target keyword, | |
1317 | a single target triplet, or a list of target triplets within quotes or | |
1318 | curly braces. For example: | |
1319 | ||
1320 | @smallexample | |
1321 | @{ target @{ ! "hppa*-*-* ia64*-*-*" @} @} | |
1322 | @{ target @{ powerpc*-*-* && lp64 @} @} | |
1323 | @{ xfail @{ lp64 || vect_no_align @} @} | |
1324 | @end smallexample | |
1325 | ||
1326 | @node Effective-Target Keywords | |
1327 | @subsection Keywords describing target attributes | |
1328 | ||
1329 | Effective-target keywords identify sets of targets that support | |
1330 | particular functionality. They are used to limit tests to be run only | |
1331 | for particular targets, or to specify that particular sets of targets | |
1332 | are expected to fail some tests. | |
1333 | ||
1334 | Effective-target keywords are defined in @file{lib/target-supports.exp} in | |
1335 | the GCC testsuite, with the exception of those that are documented as | |
1336 | being local to a particular test directory. | |
1337 | ||
1338 | The @samp{effective target} takes into account all of the compiler options | |
1339 | with which the test will be compiled, including the multilib options. | |
1340 | By convention, keywords ending in @code{_nocache} can also include options | |
1341 | specified for the particular test in an earlier @code{dg-options} or | |
1342 | @code{dg-add-options} directive. | |
1343 | ||
89453706 SB |
1344 | @subsubsection Endianness |
1345 | ||
1346 | @table @code | |
1347 | @item be | |
1348 | Target uses big-endian memory order for multi-byte and multi-word data. | |
1349 | ||
1350 | @item le | |
1351 | Target uses little-endian memory order for multi-byte and multi-word data. | |
1352 | @end table | |
1353 | ||
d4f3924a | 1354 | @subsubsection Data type sizes |
35fdf04e JJ |
1355 | |
1356 | @table @code | |
d4f3924a JJ |
1357 | @item ilp32 |
1358 | Target has 32-bit @code{int}, @code{long}, and pointers. | |
0455fecf | 1359 | |
d4f3924a JJ |
1360 | @item lp64 |
1361 | Target has 32-bit @code{int}, 64-bit @code{long} and pointers. | |
0455fecf | 1362 | |
d4f3924a JJ |
1363 | @item llp64 |
1364 | Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long} | |
1365 | and pointers. | |
0455fecf | 1366 | |
d4f3924a JJ |
1367 | @item double64 |
1368 | Target has 64-bit @code{double}. | |
0455fecf | 1369 | |
d4f3924a JJ |
1370 | @item double64plus |
1371 | Target has @code{double} that is 64 bits or longer. | |
1372 | ||
8241efd1 PB |
1373 | @item longdouble128 |
1374 | Target has 128-bit @code{long double}. | |
1375 | ||
d4f3924a JJ |
1376 | @item int32plus |
1377 | Target has @code{int} that is at 32 bits or longer. | |
1378 | ||
1379 | @item int16 | |
1380 | Target has @code{int} that is 16 bits or shorter. | |
1381 | ||
1409f3b0 JL |
1382 | @item longlong64 |
1383 | Target has 64-bit @code{long long}. | |
1384 | ||
75bc3841 BS |
1385 | @item long_neq_int |
1386 | Target has @code{int} and @code{long} with different sizes. | |
1387 | ||
92ea8e1b JL |
1388 | @item short_eq_int |
1389 | Target has @code{short} and @code{int} with the same size. | |
1390 | ||
1391 | @item ptr_eq_short | |
1392 | Target has pointers (@code{void *}) and @code{short} with the same size. | |
1393 | ||
27c16e61 JL |
1394 | @item int_eq_float |
1395 | Target has @code{int} and @code{float} with the same size. | |
1396 | ||
1397 | @item ptr_eq_long | |
1398 | Target has pointers (@code{void *}) and @code{long} with the same size. | |
1399 | ||
d4f3924a JJ |
1400 | @item large_double |
1401 | Target supports @code{double} that is longer than @code{float}. | |
1402 | ||
1403 | @item large_long_double | |
1404 | Target supports @code{long double} that is longer than @code{double}. | |
1405 | ||
1406 | @item ptr32plus | |
1407 | Target has pointers that are 32 bits or longer. | |
1408 | ||
f4a14e09 | 1409 | @item size20plus |
92ea8e1b | 1410 | Target has a 20-bit or larger address space, so supports at least |
f4a14e09 JL |
1411 | 16-bit array and structure sizes. |
1412 | ||
92ea8e1b JL |
1413 | @item size24plus |
1414 | Target has a 24-bit or larger address space, so supports at least | |
1415 | 20-bit array and structure sizes. | |
1416 | ||
d4f3924a | 1417 | @item size32plus |
92ea8e1b | 1418 | Target has a 32-bit or larger address space, so supports at least |
f4a14e09 | 1419 | 24-bit array and structure sizes. |
d4f3924a JJ |
1420 | |
1421 | @item 4byte_wchar_t | |
1422 | Target has @code{wchar_t} that is at least 4 bytes. | |
c65699ef JM |
1423 | |
1424 | @item float@var{n} | |
1425 | Target has the @code{_Float@var{n}} type. | |
1426 | ||
1427 | @item float@var{n}x | |
1428 | Target has the @code{_Float@var{n}x} type. | |
1429 | ||
1430 | @item float@var{n}_runtime | |
1431 | Target has the @code{_Float@var{n}} type, including runtime support | |
1432 | for any options added with @code{dg-add-options}. | |
1433 | ||
1434 | @item float@var{n}x_runtime | |
1435 | Target has the @code{_Float@var{n}x} type, including runtime support | |
1436 | for any options added with @code{dg-add-options}. | |
1437 | ||
1438 | @item floatn_nx_runtime | |
1439 | Target has runtime support for any options added with | |
1440 | @code{dg-add-options} for any @code{_Float@var{n}} or | |
1441 | @code{_Float@var{n}x} type. | |
d4f3924a | 1442 | |
08500461 PK |
1443 | @item inf |
1444 | Target supports floating point infinite (@code{inf}) for type | |
1445 | @code{double}. | |
3cfe746f JM |
1446 | |
1447 | @item inff | |
1448 | Target supports floating point infinite (@code{inf}) for type | |
1449 | @code{float}. | |
08500461 | 1450 | @end table |
d4f3924a JJ |
1451 | @subsubsection Fortran-specific attributes |
1452 | ||
1453 | @table @code | |
1454 | @item fortran_integer_16 | |
1455 | Target supports Fortran @code{integer} that is 16 bytes or longer. | |
1456 | ||
63b62fa0 JW |
1457 | @item fortran_real_10 |
1458 | Target supports Fortran @code{real} that is 10 bytes or longer. | |
1459 | ||
1460 | @item fortran_real_16 | |
1461 | Target supports Fortran @code{real} that is 16 bytes or longer. | |
1462 | ||
d4f3924a JJ |
1463 | @item fortran_large_int |
1464 | Target supports Fortran @code{integer} kinds larger than @code{integer(8)}. | |
1465 | ||
1466 | @item fortran_large_real | |
1467 | Target supports Fortran @code{real} kinds larger than @code{real(8)}. | |
1468 | @end table | |
1469 | ||
1470 | @subsubsection Vector-specific attributes | |
1471 | ||
1472 | @table @code | |
331e1a56 RS |
1473 | @item vect_align_stack_vars |
1474 | The target's ABI allows stack variables to be aligned to the preferred | |
1475 | vector alignment. | |
1476 | ||
0267732b RS |
1477 | @item vect_avg_qi |
1478 | Target supports both signed and unsigned averaging operations on vectors | |
1479 | of bytes. | |
1480 | ||
58cc9876 YW |
1481 | @item vect_mulhrs_hi |
1482 | Target supports both signed and unsigned multiply-high-with-round-and-scale | |
1483 | operations on vectors of half-words. | |
1484 | ||
c0c2f013 YW |
1485 | @item vect_sdiv_pow2_si |
1486 | Target supports signed division by constant power-of-2 operations | |
1487 | on vectors of 4-byte integers. | |
1488 | ||
d4f3924a JJ |
1489 | @item vect_condition |
1490 | Target supports vector conditional operations. | |
1491 | ||
5a02adf6 BC |
1492 | @item vect_cond_mixed |
1493 | Target supports vector conditional operations where comparison operands | |
1494 | have different type from the value operands. | |
1495 | ||
d4f3924a JJ |
1496 | @item vect_double |
1497 | Target supports hardware vectors of @code{double}. | |
1498 | ||
0d2b3bca | 1499 | @item vect_double_cond_arith |
6c4fd4a9 RS |
1500 | Target supports conditional addition, subtraction, multiplication, |
1501 | division, minimum and maximum on vectors of @code{double}, via the | |
1502 | @code{cond_} optabs. | |
0d2b3bca | 1503 | |
4d83db5d RS |
1504 | @item vect_element_align_preferred |
1505 | The target's preferred vector alignment is the same as the element | |
1506 | alignment. | |
1507 | ||
d4f3924a | 1508 | @item vect_float |
ef57eeb2 RS |
1509 | Target supports hardware vectors of @code{float} when |
1510 | @option{-funsafe-math-optimizations} is in effect. | |
1511 | ||
1512 | @item vect_float_strict | |
1513 | Target supports hardware vectors of @code{float} when | |
1514 | @option{-funsafe-math-optimizations} is not in effect. | |
1515 | This implies @code{vect_float}. | |
d4f3924a JJ |
1516 | |
1517 | @item vect_int | |
1518 | Target supports hardware vectors of @code{int}. | |
1519 | ||
d4f3924a JJ |
1520 | @item vect_long |
1521 | Target supports hardware vectors of @code{long}. | |
1522 | ||
1523 | @item vect_long_long | |
1524 | Target supports hardware vectors of @code{long long}. | |
1525 | ||
58c036c8 RS |
1526 | @item vect_check_ptrs |
1527 | Target supports the @code{check_raw_ptrs} and @code{check_war_ptrs} | |
1528 | optabs on vectors. | |
1529 | ||
c2700f74 RS |
1530 | @item vect_fully_masked |
1531 | Target supports fully-masked (also known as fully-predicated) loops, | |
1532 | so that vector loops can handle partial as well as full vectors. | |
1533 | ||
8c26cfc6 RB |
1534 | @item vect_masked_load |
1535 | Target supports vector masked loads. | |
1536 | ||
c48a8e71 RS |
1537 | @item vect_masked_store |
1538 | Target supports vector masked stores. | |
1539 | ||
f307441a RS |
1540 | @item vect_scatter_store |
1541 | Target supports vector scatter stores. | |
1542 | ||
d4f3924a JJ |
1543 | @item vect_aligned_arrays |
1544 | Target aligns arrays to vector alignment boundary. | |
1545 | ||
1546 | @item vect_hw_misalign | |
1547 | Target supports a vector misalign access. | |
1548 | ||
1549 | @item vect_no_align | |
1550 | Target does not support a vector alignment mechanism. | |
1551 | ||
4f15b6a2 AK |
1552 | @item vect_peeling_profitable |
1553 | Target might require to peel loops for alignment purposes. | |
1554 | ||
1b950569 TV |
1555 | @item vect_no_int_min_max |
1556 | Target does not support a vector min and max instruction on @code{int}. | |
d4f3924a JJ |
1557 | |
1558 | @item vect_no_int_add | |
1559 | Target does not support a vector add instruction on @code{int}. | |
1560 | ||
1561 | @item vect_no_bitwise | |
1562 | Target does not support vector bitwise instructions. | |
1563 | ||
ce19a482 RS |
1564 | @item vect_bool_cmp |
1565 | Target supports comparison of @code{bool} vectors for at least one | |
1566 | vector length. | |
1567 | ||
28cebdb1 RS |
1568 | @item vect_char_add |
1569 | Target supports addition of @code{char} vectors for at least one | |
1570 | vector length. | |
1571 | ||
d4f3924a JJ |
1572 | @item vect_char_mult |
1573 | Target supports @code{vector char} multiplication. | |
1574 | ||
1575 | @item vect_short_mult | |
1576 | Target supports @code{vector short} multiplication. | |
1577 | ||
1578 | @item vect_int_mult | |
1579 | Target supports @code{vector int} multiplication. | |
1580 | ||
c059a92e AK |
1581 | @item vect_long_mult |
1582 | Target supports 64 bit @code{vector long} multiplication. | |
1583 | ||
d4f3924a JJ |
1584 | @item vect_extract_even_odd |
1585 | Target supports vector even/odd element extraction. | |
1586 | ||
1587 | @item vect_extract_even_odd_wide | |
1588 | Target supports vector even/odd element extraction of vectors with elements | |
1589 | @code{SImode} or larger. | |
1590 | ||
1591 | @item vect_interleave | |
1592 | Target supports vector interleaving. | |
1593 | ||
1594 | @item vect_strided | |
1595 | Target supports vector interleaving and extract even/odd. | |
1596 | ||
1597 | @item vect_strided_wide | |
1598 | Target supports vector interleaving and extract even/odd for wide | |
1599 | element types. | |
1600 | ||
1601 | @item vect_perm | |
1602 | Target supports vector permutation. | |
1603 | ||
8b26c549 RS |
1604 | @item vect_perm_byte |
1605 | Target supports permutation of vectors with 8-bit elements. | |
1606 | ||
1607 | @item vect_perm_short | |
1608 | Target supports permutation of vectors with 16-bit elements. | |
1609 | ||
1610 | @item vect_perm3_byte | |
1611 | Target supports permutation of vectors with 8-bit elements, and for the | |
1612 | default vector length it is possible to permute: | |
1613 | @example | |
1614 | @{ a0, a1, a2, b0, b1, b2, @dots{} @} | |
1615 | @end example | |
1616 | to: | |
1617 | @example | |
1618 | @{ a0, a0, a0, b0, b0, b0, @dots{} @} | |
1619 | @{ a1, a1, a1, b1, b1, b1, @dots{} @} | |
1620 | @{ a2, a2, a2, b2, b2, b2, @dots{} @} | |
1621 | @end example | |
1622 | using only two-vector permutes, regardless of how long the sequence is. | |
1623 | ||
1624 | @item vect_perm3_int | |
1625 | Like @code{vect_perm3_byte}, but for 32-bit elements. | |
1626 | ||
1627 | @item vect_perm3_short | |
1628 | Like @code{vect_perm3_byte}, but for 16-bit elements. | |
1629 | ||
d4f3924a JJ |
1630 | @item vect_shift |
1631 | Target supports a hardware vector shift operation. | |
1632 | ||
b8353767 RS |
1633 | @item vect_unaligned_possible |
1634 | Target prefers vectors to have an alignment greater than element | |
1635 | alignment, but also allows unaligned vector accesses in some | |
1636 | circumstances. | |
1637 | ||
32c7bafd RS |
1638 | @item vect_variable_length |
1639 | Target has variable-length vectors. | |
1640 | ||
d4f3924a JJ |
1641 | @item vect_widen_sum_hi_to_si |
1642 | Target supports a vector widening summation of @code{short} operands | |
1643 | into @code{int} results, or can promote (unpack) from @code{short} | |
1644 | to @code{int}. | |
1645 | ||
1646 | @item vect_widen_sum_qi_to_hi | |
1647 | Target supports a vector widening summation of @code{char} operands | |
1648 | into @code{short} results, or can promote (unpack) from @code{char} | |
1649 | to @code{short}. | |
1650 | ||
1651 | @item vect_widen_sum_qi_to_si | |
1652 | Target supports a vector widening summation of @code{char} operands | |
1653 | into @code{int} results. | |
1654 | ||
1655 | @item vect_widen_mult_qi_to_hi | |
1656 | Target supports a vector widening multiplication of @code{char} operands | |
1657 | into @code{short} results, or can promote (unpack) from @code{char} to | |
1658 | @code{short} and perform non-widening multiplication of @code{short}. | |
1659 | ||
1660 | @item vect_widen_mult_hi_to_si | |
1661 | Target supports a vector widening multiplication of @code{short} operands | |
1662 | into @code{int} results, or can promote (unpack) from @code{short} to | |
1663 | @code{int} and perform non-widening multiplication of @code{int}. | |
1664 | ||
5d1a5a53 CH |
1665 | @item vect_widen_mult_si_to_di_pattern |
1666 | Target supports a vector widening multiplication of @code{int} operands | |
1667 | into @code{long} results. | |
1668 | ||
d4f3924a JJ |
1669 | @item vect_sdot_qi |
1670 | Target supports a vector dot-product of @code{signed char}. | |
1671 | ||
1672 | @item vect_udot_qi | |
1673 | Target supports a vector dot-product of @code{unsigned char}. | |
1674 | ||
1675 | @item vect_sdot_hi | |
1676 | Target supports a vector dot-product of @code{signed short}. | |
1677 | ||
1678 | @item vect_udot_hi | |
1679 | Target supports a vector dot-product of @code{unsigned short}. | |
1680 | ||
1681 | @item vect_pack_trunc | |
1682 | Target supports a vector demotion (packing) of @code{short} to @code{char} | |
1683 | and from @code{int} to @code{short} using modulo arithmetic. | |
1684 | ||
1685 | @item vect_unpack | |
1686 | Target supports a vector promotion (unpacking) of @code{char} to @code{short} | |
1687 | and from @code{char} to @code{int}. | |
1688 | ||
1689 | @item vect_intfloat_cvt | |
1690 | Target supports conversion from @code{signed int} to @code{float}. | |
1691 | ||
1692 | @item vect_uintfloat_cvt | |
1693 | Target supports conversion from @code{unsigned int} to @code{float}. | |
1694 | ||
1695 | @item vect_floatint_cvt | |
1696 | Target supports conversion from @code{float} to @code{signed int}. | |
1697 | ||
1698 | @item vect_floatuint_cvt | |
1699 | Target supports conversion from @code{float} to @code{unsigned int}. | |
af29617a | 1700 | |
30d027da AK |
1701 | @item vect_intdouble_cvt |
1702 | Target supports conversion from @code{signed int} to @code{double}. | |
1703 | ||
1704 | @item vect_doubleint_cvt | |
1705 | Target supports conversion from @code{double} to @code{signed int}. | |
1706 | ||
af29617a AH |
1707 | @item vect_max_reduc |
1708 | Target supports max reduction for vectors. | |
592fbfb5 TC |
1709 | |
1710 | @item vect_sizes_16B_8B | |
1711 | Target supports 16- and 8-bytes vectors. | |
1712 | ||
1713 | @item vect_sizes_32B_16B | |
1714 | Target supports 32- and 16-bytes vectors. | |
898f07b0 RS |
1715 | |
1716 | @item vect_logical_reduc | |
1717 | Target supports AND, IOR and XOR reduction on vectors. | |
bb6c2b68 RS |
1718 | |
1719 | @item vect_fold_extract_last | |
1720 | Target supports the @code{fold_extract_last} optab. | |
d0939f42 KL |
1721 | |
1722 | @item vect_len_load_store | |
1723 | Target supports the @code{len_load} and @code{len_store} optabs. | |
1724 | ||
1725 | @item vect_partial_vectors_usage_1 | |
1726 | Target supports loop vectorization with partial vectors and | |
1727 | @code{vect-partial-vector-usage} is set to 1. | |
1728 | ||
1729 | @item vect_partial_vectors_usage_2 | |
1730 | Target supports loop vectorization with partial vectors and | |
1731 | @code{vect-partial-vector-usage} is set to 2. | |
1732 | ||
1733 | @item vect_partial_vectors | |
1734 | Target supports loop vectorization with partial vectors and | |
1735 | @code{vect-partial-vector-usage} is nonzero. | |
d4f3924a JJ |
1736 | @end table |
1737 | ||
1738 | @subsubsection Thread Local Storage attributes | |
1739 | ||
1740 | @table @code | |
1741 | @item tls | |
1742 | Target supports thread-local storage. | |
1743 | ||
1744 | @item tls_native | |
1745 | Target supports native (rather than emulated) thread-local storage. | |
1746 | ||
1747 | @item tls_runtime | |
1748 | Test system supports executing TLS executables. | |
1749 | @end table | |
1750 | ||
1751 | @subsubsection Decimal floating point attributes | |
1752 | ||
1753 | @table @code | |
1754 | @item dfp | |
1755 | Targets supports compiling decimal floating point extension to C. | |
1756 | ||
1757 | @item dfp_nocache | |
1758 | Including the options used to compile this particular test, the | |
1759 | target supports compiling decimal floating point extension to C. | |
1760 | ||
1761 | @item dfprt | |
1762 | Test system can execute decimal floating point tests. | |
1763 | ||
1764 | @item dfprt_nocache | |
1765 | Including the options used to compile this particular test, the | |
1766 | test system can execute decimal floating point tests. | |
1767 | ||
1768 | @item hard_dfp | |
1769 | Target generates decimal floating point instructions with current options. | |
1770 | @end table | |
1771 | ||
1772 | @subsubsection ARM-specific attributes | |
1773 | ||
1774 | @table @code | |
1775 | @item arm32 | |
1776 | ARM target generates 32-bit code. | |
1777 | ||
084a454e AV |
1778 | @item arm_little_endian |
1779 | ARM target that generates little-endian code. | |
1780 | ||
d4f3924a JJ |
1781 | @item arm_eabi |
1782 | ARM target adheres to the ABI for the ARM Architecture. | |
1783 | ||
d7cf3dc7 CL |
1784 | @item arm_fp_ok |
1785 | @anchor{arm_fp_ok} | |
1786 | ARM target defines @code{__ARM_FP} using @code{-mfloat-abi=softfp} or | |
1787 | equivalent options. Some multilibs may be incompatible with these | |
1788 | options. | |
1789 | ||
8001f59c CL |
1790 | @item arm_fp_dp_ok |
1791 | @anchor{arm_fp_dp_ok} | |
1792 | ARM target defines @code{__ARM_FP} with double-precision support using | |
1793 | @code{-mfloat-abi=softfp} or equivalent options. Some multilibs may | |
1794 | be incompatible with these options. | |
1795 | ||
552b56fc JB |
1796 | @item arm_hf_eabi |
1797 | ARM target adheres to the VFP and Advanced SIMD Register Arguments | |
1798 | variant of the ABI for the ARM Architecture (as selected with | |
1799 | @code{-mfloat-abi=hard}). | |
1800 | ||
dececdaa | 1801 | @item arm_softfloat |
33314b11 | 1802 | ARM target uses emulated floating point operations. |
dececdaa | 1803 | |
d4f3924a JJ |
1804 | @item arm_hard_vfp_ok |
1805 | ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}. | |
1806 | Some multilibs may be incompatible with these options. | |
1807 | ||
1808 | @item arm_iwmmxt_ok | |
1809 | ARM target supports @code{-mcpu=iwmmxt}. | |
1810 | Some multilibs may be incompatible with this option. | |
1811 | ||
1812 | @item arm_neon | |
1813 | ARM target supports generating NEON instructions. | |
1814 | ||
d45c2a1b BC |
1815 | @item arm_tune_string_ops_prefer_neon |
1816 | Test CPU tune supports inlining string operations with NEON instructions. | |
1817 | ||
d4f3924a JJ |
1818 | @item arm_neon_hw |
1819 | Test system supports executing NEON instructions. | |
1820 | ||
8b2ab9cb RR |
1821 | @item arm_neonv2_hw |
1822 | Test system supports executing NEON v2 instructions. | |
1823 | ||
d4f3924a | 1824 | @item arm_neon_ok |
0c422e74 DJ |
1825 | @anchor{arm_neon_ok} |
1826 | ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible | |
1827 | options. Some multilibs may be incompatible with these options. | |
1828 | ||
c8e3c356 CL |
1829 | @item arm_neon_ok_no_float_abi |
1830 | @anchor{arm_neon_ok_no_float_abi} | |
1831 | ARM Target supports NEON with @code{-mfpu=neon}, but without any | |
1832 | -mfloat-abi= option. Some multilibs may be incompatible with this | |
1833 | option. | |
1834 | ||
8b2ab9cb | 1835 | @item arm_neonv2_ok |
178a71a9 RR |
1836 | @anchor{arm_neonv2_ok} |
1837 | ARM Target supports @code{-mfpu=neon-vfpv4 -mfloat-abi=softfp} or compatible | |
8b2ab9cb RR |
1838 | options. Some multilibs may be incompatible with these options. |
1839 | ||
7fe43755 MW |
1840 | @item arm_fp16_ok |
1841 | @anchor{arm_fp16_ok} | |
1842 | Target supports options to generate VFP half-precision floating-point | |
1843 | instructions. Some multilibs may be incompatible with these | |
1844 | options. This test is valid for ARM only. | |
1845 | ||
1846 | @item arm_fp16_hw | |
1847 | Target supports executing VFP half-precision floating-point | |
1848 | instructions. This test is valid for ARM only. | |
1849 | ||
0c422e74 DJ |
1850 | @item arm_neon_fp16_ok |
1851 | @anchor{arm_neon_fp16_ok} | |
1852 | ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible | |
48c44783 AL |
1853 | options, including @code{-mfp16-format=ieee} if necessary to obtain the |
1854 | @code{__fp16} type. Some multilibs may be incompatible with these options. | |
1855 | ||
1856 | @item arm_neon_fp16_hw | |
1857 | Test system supports executing Neon half-precision float instructions. | |
1858 | (Implies previous.) | |
d4f3924a | 1859 | |
a5b42ee7 MW |
1860 | @item arm_fp16_alternative_ok |
1861 | ARM target supports the ARM FP16 alternative format. Some multilibs | |
1862 | may be incompatible with the options needed. | |
1863 | ||
1864 | @item arm_fp16_none_ok | |
1865 | ARM target supports specifying none as the ARM FP16 format. | |
1866 | ||
d4f3924a JJ |
1867 | @item arm_thumb1_ok |
1868 | ARM target generates Thumb-1 code for @code{-mthumb}. | |
1869 | ||
1870 | @item arm_thumb2_ok | |
1871 | ARM target generates Thumb-2 code for @code{-mthumb}. | |
1872 | ||
084a454e AV |
1873 | @item arm_nothumb |
1874 | ARM target that is not using Thumb. | |
1875 | ||
d4f3924a JJ |
1876 | @item arm_vfp_ok |
1877 | ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}. | |
1878 | Some multilibs may be incompatible with these options. | |
cf5607f8 | 1879 | |
6d3715b9 | 1880 | @item arm_vfp3_ok |
e332c729 | 1881 | @anchor{arm_vfp3_ok} |
6d3715b9 RL |
1882 | ARM target supports @code{-mfpu=vfp3 -mfloat-abi=softfp}. |
1883 | Some multilibs may be incompatible with these options. | |
1884 | ||
127abeb2 | 1885 | @item arm_arch_v8a_hard_ok |
668d8f3c | 1886 | @anchor{arm_arch_v8a_hard_ok} |
127abeb2 RS |
1887 | The compiler is targeting @code{arm*-*-*} and can compile and assemble code |
1888 | using the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}. | |
1889 | This is not enough to guarantee that linking works. | |
1890 | ||
1891 | @item arm_arch_v8a_hard_multilib | |
1892 | The compiler is targeting @code{arm*-*-*} and can build programs using | |
1893 | the options @code{-march=armv8-a -mfpu=neon-fp-armv8 -mfloat-abi=hard}. | |
1894 | The target can also run the resulting binaries. | |
1895 | ||
e3f9361d KT |
1896 | @item arm_v8_vfp_ok |
1897 | ARM target supports @code{-mfpu=fp-armv8 -mfloat-abi=softfp}. | |
1898 | Some multilibs may be incompatible with these options. | |
1899 | ||
71aa66e4 KT |
1900 | @item arm_v8_neon_ok |
1901 | ARM target supports @code{-mfpu=neon-fp-armv8 -mfloat-abi=softfp}. | |
1902 | Some multilibs may be incompatible with these options. | |
1903 | ||
07b140c2 | 1904 | @item arm_v8_1a_neon_ok |
1b9e31cf | 1905 | @anchor{arm_v8_1a_neon_ok} |
d7dccfa3 | 1906 | ARM target supports options to generate ARMv8.1-A Adv.SIMD instructions. |
07b140c2 MW |
1907 | Some multilibs may be incompatible with these options. |
1908 | ||
1909 | @item arm_v8_1a_neon_hw | |
d7dccfa3 | 1910 | ARM target supports executing ARMv8.1-A Adv.SIMD instructions. Some |
07b140c2 MW |
1911 | multilibs may be incompatible with the options needed. Implies |
1912 | arm_v8_1a_neon_ok. | |
1913 | ||
042dee3e TP |
1914 | @item arm_acq_rel |
1915 | ARM target supports acquire-release instructions. | |
1916 | ||
1b9e31cf MW |
1917 | @item arm_v8_2a_fp16_scalar_ok |
1918 | @anchor{arm_v8_2a_fp16_scalar_ok} | |
d7dccfa3 | 1919 | ARM target supports options to generate instructions for ARMv8.2-A and |
1b9e31cf MW |
1920 | scalar instructions from the FP16 extension. Some multilibs may be |
1921 | incompatible with these options. | |
1922 | ||
1923 | @item arm_v8_2a_fp16_scalar_hw | |
d7dccfa3 | 1924 | ARM target supports executing instructions for ARMv8.2-A and scalar |
1b9e31cf MW |
1925 | instructions from the FP16 extension. Some multilibs may be |
1926 | incompatible with these options. Implies arm_v8_2a_fp16_neon_ok. | |
1927 | ||
1928 | @item arm_v8_2a_fp16_neon_ok | |
1929 | @anchor{arm_v8_2a_fp16_neon_ok} | |
d7dccfa3 | 1930 | ARM target supports options to generate instructions from ARMv8.2-A with |
1b9e31cf MW |
1931 | the FP16 extension. Some multilibs may be incompatible with these |
1932 | options. Implies arm_v8_2a_fp16_scalar_ok. | |
1933 | ||
1934 | @item arm_v8_2a_fp16_neon_hw | |
d7dccfa3 | 1935 | ARM target supports executing instructions from ARMv8.2-A with the FP16 |
1b9e31cf MW |
1936 | extension. Some multilibs may be incompatible with these options. |
1937 | Implies arm_v8_2a_fp16_neon_ok and arm_v8_2a_fp16_scalar_hw. | |
1938 | ||
2b5de014 TC |
1939 | @item arm_v8_2a_dotprod_neon_ok |
1940 | @anchor{arm_v8_2a_dotprod_neon_ok} | |
d7dccfa3 | 1941 | ARM target supports options to generate instructions from ARMv8.2-A with |
2b5de014 TC |
1942 | the Dot Product extension. Some multilibs may be incompatible with these |
1943 | options. | |
1944 | ||
1945 | @item arm_v8_2a_dotprod_neon_hw | |
d7dccfa3 | 1946 | ARM target supports executing instructions from ARMv8.2-A with the Dot |
2b5de014 TC |
1947 | Product extension. Some multilibs may be incompatible with these options. |
1948 | Implies arm_v8_2a_dotprod_neon_ok. | |
1949 | ||
06e95715 KT |
1950 | @item arm_fp16fml_neon_ok |
1951 | @anchor{arm_fp16fml_neon_ok} | |
1952 | ARM target supports extensions to generate the @code{VFMAL} and @code{VFMLS} | |
1953 | half-precision floating-point instructions available from ARMv8.2-A and | |
1954 | onwards. Some multilibs may be incompatible with these options. | |
1955 | ||
9260fb06 SMW |
1956 | @item arm_v8_2a_bf16_neon_ok |
1957 | ARM target supports options to generate instructions from ARMv8.2-A with | |
1958 | the BFloat16 extension (bf16). Some multilibs may be incompatible with these | |
1959 | options. | |
1960 | ||
1961 | @item arm_v8_2a_i8mm_ok | |
1962 | ARM target supports options to generate instructions from ARMv8.2-A with | |
1963 | the 8-Bit Integer Matrix Multiply extension (i8mm). Some multilibs may be | |
1964 | incompatible with these options. | |
1965 | ||
131fbdd7 MI |
1966 | @item arm_v8_1m_mve_ok |
1967 | ARM target supports options to generate instructions from ARMv8.1-M with | |
1968 | the M-Profile Vector Extension (MVE). Some multilibs may be incompatible | |
1969 | with these options. | |
1970 | ||
99abb146 SP |
1971 | @item arm_v8_1m_mve_fp_ok |
1972 | ARM target supports options to generate instructions from ARMv8.1-M with | |
1973 | the Half-precision floating-point instructions (HP), Floating-point Extension | |
1974 | (FP) along with M-Profile Vector Extension (MVE). Some multilibs may be | |
1975 | incompatible with these options. | |
1976 | ||
1977 | @item arm_mve_hw | |
1978 | Test system supports executing MVE instructions. | |
1979 | ||
975e6670 DZ |
1980 | @item arm_v8m_main_cde |
1981 | ARM target supports options to generate instructions from ARMv8-M with | |
1982 | the Custom Datapath Extension (CDE). Some multilibs may be incompatible | |
1983 | with these options. | |
1984 | ||
1985 | @item arm_v8m_main_cde_fp | |
1986 | ARM target supports options to generate instructions from ARMv8-M with | |
1987 | the Custom Datapath Extension (CDE) and floating-point (VFP). | |
1988 | Some multilibs may be incompatible with these options. | |
1989 | ||
1990 | @item arm_v8_1m_main_cde_mve | |
1991 | ARM target supports options to generate instructions from ARMv8.1-M with | |
1992 | the Custom Datapath Extension (CDE) and M-Profile Vector Extension (MVE). | |
1993 | Some multilibs may be incompatible with these options. | |
1994 | ||
cf5607f8 GY |
1995 | @item arm_prefer_ldrd_strd |
1996 | ARM target prefers @code{LDRD} and @code{STRD} instructions over | |
1997 | @code{LDM} and @code{STM} instructions. | |
1998 | ||
2b9509a3 TP |
1999 | @item arm_thumb1_movt_ok |
2000 | ARM target generates Thumb-1 code for @code{-mthumb} with @code{MOVW} | |
2001 | and @code{MOVT} instructions available. | |
2002 | ||
5ce15300 TP |
2003 | @item arm_thumb1_cbz_ok |
2004 | ARM target generates Thumb-1 code for @code{-mthumb} with | |
2005 | @code{CBZ} and @code{CBNZ} instructions available. | |
2006 | ||
e72531b9 PK |
2007 | @item arm_divmod_simode |
2008 | ARM target for which divmod transform is disabled, if it supports hardware | |
2009 | div instruction. | |
2010 | ||
de7b5723 AV |
2011 | @item arm_cmse_ok |
2012 | ARM target supports ARMv8-M Security Extensions, enabled by the @code{-mcmse} | |
2013 | option. | |
2014 | ||
d57daa0c AV |
2015 | @item arm_coproc1_ok |
2016 | @anchor{arm_coproc1_ok} | |
2017 | ARM target supports the following coprocessor instructions: @code{CDP}, | |
2018 | @code{LDC}, @code{STC}, @code{MCR} and @code{MRC}. | |
2019 | ||
2020 | @item arm_coproc2_ok | |
2021 | @anchor{arm_coproc2_ok} | |
2022 | ARM target supports all the coprocessor instructions also listed as supported | |
2023 | in @ref{arm_coproc1_ok} in addition to the following: @code{CDP2}, @code{LDC2}, | |
2024 | @code{LDC2l}, @code{STC2}, @code{STC2l}, @code{MCR2} and @code{MRC2}. | |
2025 | ||
2026 | @item arm_coproc3_ok | |
2027 | @anchor{arm_coproc3_ok} | |
2028 | ARM target supports all the coprocessor instructions also listed as supported | |
2029 | in @ref{arm_coproc2_ok} in addition the following: @code{MCRR} and @code{MRRC}. | |
2030 | ||
2031 | @item arm_coproc4_ok | |
2032 | ARM target supports all the coprocessor instructions also listed as supported | |
2033 | in @ref{arm_coproc3_ok} in addition the following: @code{MCRR2} and @code{MRRC2}. | |
53cd0ac6 KT |
2034 | |
2035 | @item arm_simd32_ok | |
2036 | @anchor{arm_simd32_ok} | |
2037 | ARM Target supports options suitable for accessing the SIMD32 intrinsics from | |
2038 | @code{arm_acle.h}. | |
2039 | Some multilibs may be incompatible with these options. | |
2040 | ||
cf16f980 KT |
2041 | @item arm_qbit_ok |
2042 | @anchor{arm_qbit_ok} | |
2043 | ARM Target supports options suitable for accessing the Q-bit manipulation | |
2044 | intrinsics from @code{arm_acle.h}. | |
2045 | Some multilibs may be incompatible with these options. | |
2046 | ||
d414c915 CL |
2047 | @item arm_softfp_ok |
2048 | @anchor{arm_softfp_ok} | |
2049 | ARM target supports the @code{-mfloat-abi=softfp} option. | |
2050 | ||
2051 | @item arm_hard_ok | |
2052 | @anchor{arm_hard_ok} | |
2053 | ARM target supports the @code{-mfloat-abi=hard} option. | |
2054 | ||
d2ed233c AC |
2055 | @item arm_v8_1_lob_ok |
2056 | @anchor{arm_v8_1_lob_ok} | |
2057 | ARM Target supports executing the Armv8.1-M Mainline Low Overhead Loop | |
2058 | instructions @code{DLS} and @code{LE}. | |
2059 | Some multilibs may be incompatible with these options. | |
2060 | ||
2061 | @item arm_thumb2_ok_no_arm_v8_1_lob | |
2062 | ARM target generates Thumb-2 code for @code{-mthumb} but does not | |
2063 | support executing the Armv8.1-M Mainline Low Overhead Loop | |
2064 | instructions @code{DLS} and @code{LE}. | |
2065 | ||
d4f3924a JJ |
2066 | @end table |
2067 | ||
8997ef18 JW |
2068 | @subsubsection AArch64-specific attributes |
2069 | ||
2070 | @table @code | |
2db16594 KT |
2071 | @item aarch64_asm_<ext>_ok |
2072 | AArch64 assembler supports the architecture extension @code{ext} via the | |
2073 | @code{.arch_extension} pseudo-op. | |
d0baaae3 JW |
2074 | @item aarch64_tiny |
2075 | AArch64 target which generates instruction sequences for tiny memory model. | |
2076 | @item aarch64_small | |
2077 | AArch64 target which generates instruction sequences for small memory model. | |
2078 | @item aarch64_large | |
2079 | AArch64 target which generates instruction sequences for large memory model. | |
2080 | @item aarch64_little_endian | |
2081 | AArch64 target which generates instruction sequences for little endian. | |
2082 | @item aarch64_big_endian | |
2083 | AArch64 target which generates instruction sequences for big endian. | |
8997ef18 JW |
2084 | @item aarch64_small_fpic |
2085 | Binutils installed on test system supports relocation types required by -fpic | |
2086 | for AArch64 small memory model. | |
38e62001 RS |
2087 | @item aarch64_sve_hw |
2088 | AArch64 target that is able to generate and execute SVE code (regardless of | |
2089 | whether it does so by default). | |
2090 | @item aarch64_sve128_hw | |
2091 | @itemx aarch64_sve256_hw | |
2092 | @itemx aarch64_sve512_hw | |
2093 | @itemx aarch64_sve1024_hw | |
2094 | @itemx aarch64_sve2048_hw | |
2095 | Like @code{aarch64_sve_hw}, but also test for an exact hardware vector length. | |
8997ef18 | 2096 | |
d2b86e14 AC |
2097 | @item aarch64_fjcvtzs_hw |
2098 | AArch64 target that is able to generate and execute armv8.3-a FJCVTZS | |
2099 | instruction. | |
8997ef18 JW |
2100 | @end table |
2101 | ||
d4f3924a JJ |
2102 | @subsubsection MIPS-specific attributes |
2103 | ||
2104 | @table @code | |
2105 | @item mips64 | |
2106 | MIPS target supports 64-bit instructions. | |
2107 | ||
2108 | @item nomips16 | |
2109 | MIPS target does not produce MIPS16 code. | |
2110 | ||
2111 | @item mips16_attribute | |
2112 | MIPS target can generate MIPS16 code. | |
2113 | ||
2114 | @item mips_loongson | |
2115 | MIPS target is a Loongson-2E or -2F target using an ABI that supports | |
2116 | the Loongson vector modes. | |
2117 | ||
6cf538da RS |
2118 | @item mips_msa |
2119 | MIPS target supports @code{-mmsa}, MIPS SIMD Architecture (MSA). | |
2120 | ||
d4f3924a JJ |
2121 | @item mips_newabi_large_long_double |
2122 | MIPS target supports @code{long double} larger than @code{double} | |
2123 | when using the new ABI. | |
2124 | ||
2125 | @item mpaired_single | |
2126 | MIPS target supports @code{-mpaired-single}. | |
2127 | @end table | |
2128 | ||
92ea8e1b JL |
2129 | @subsubsection MSP430-specific attributes |
2130 | ||
2131 | @table @code | |
2132 | @item msp430_small | |
2133 | MSP430 target has the small memory model enabled (@code{-msmall}). | |
2134 | ||
2135 | @item msp430_large | |
2136 | MSP430 target has the large memory model enabled (@code{-mlarge}). | |
2137 | @end table | |
2138 | ||
d4f3924a | 2139 | @subsubsection PowerPC-specific attributes |
0455fecf | 2140 | |
d4f3924a | 2141 | @table @code |
f4853e92 PB |
2142 | |
2143 | @item dfp_hw | |
2144 | PowerPC target supports executing hardware DFP instructions. | |
2145 | ||
2146 | @item p8vector_hw | |
2147 | PowerPC target supports executing VSX instructions (ISA 2.07). | |
2148 | ||
d4f3924a JJ |
2149 | @item powerpc64 |
2150 | Test system supports executing 64-bit instructions. | |
2151 | ||
2152 | @item powerpc_altivec | |
2153 | PowerPC target supports AltiVec. | |
2154 | ||
2155 | @item powerpc_altivec_ok | |
2156 | PowerPC target supports @code{-maltivec}. | |
2157 | ||
f4853e92 PB |
2158 | @item powerpc_eabi_ok |
2159 | PowerPC target supports @code{-meabi}. | |
2160 | ||
2161 | @item powerpc_elfv2 | |
2162 | PowerPC target supports @code{-mabi=elfv2}. | |
2163 | ||
d4f3924a JJ |
2164 | @item powerpc_fprs |
2165 | PowerPC target supports floating-point registers. | |
2166 | ||
2167 | @item powerpc_hard_double | |
2168 | PowerPC target supports hardware double-precision floating-point. | |
2169 | ||
f4853e92 PB |
2170 | @item powerpc_htm_ok |
2171 | PowerPC target supports @code{-mhtm} | |
2172 | ||
2173 | @item powerpc_p8vector_ok | |
2174 | PowerPC target supports @code{-mpower8-vector} | |
2175 | ||
598bd687 KN |
2176 | @item powerpc_popcntb_ok |
2177 | PowerPC target supports the @code{popcntb} instruction, indicating | |
2178 | that this target supports @code{-mcpu=power5}. | |
2179 | ||
d4f3924a JJ |
2180 | @item powerpc_ppu_ok |
2181 | PowerPC target supports @code{-mcpu=cell}. | |
2182 | ||
2183 | @item powerpc_spe | |
2184 | PowerPC target supports PowerPC SPE. | |
2185 | ||
2186 | @item powerpc_spe_nocache | |
2187 | Including the options used to compile this particular test, the | |
2188 | PowerPC target supports PowerPC SPE. | |
2189 | ||
2190 | @item powerpc_spu | |
2191 | PowerPC target supports PowerPC SPU. | |
2192 | ||
d4f3924a JJ |
2193 | @item powerpc_vsx_ok |
2194 | PowerPC target supports @code{-mvsx}. | |
2195 | ||
2196 | @item powerpc_405_nocache | |
2197 | Including the options used to compile this particular test, the | |
2198 | PowerPC target supports PowerPC 405. | |
2199 | ||
f4853e92 PB |
2200 | @item ppc_recip_hw |
2201 | PowerPC target supports executing reciprocal estimate instructions. | |
2202 | ||
d4f3924a JJ |
2203 | @item vmx_hw |
2204 | PowerPC target supports executing AltiVec instructions. | |
f4853e92 PB |
2205 | |
2206 | @item vsx_hw | |
2207 | PowerPC target supports executing VSX instructions (ISA 2.06). | |
be7ad7df KL |
2208 | |
2209 | @item has_arch_pwr5 | |
2210 | PowerPC target pre-defines macro _ARCH_PWR5 which means the @code{-mcpu} | |
2211 | setting is Power5 or later. | |
2212 | ||
2213 | @item has_arch_pwr6 | |
2214 | PowerPC target pre-defines macro _ARCH_PWR6 which means the @code{-mcpu} | |
2215 | setting is Power6 or later. | |
2216 | ||
2217 | @item has_arch_pwr7 | |
2218 | PowerPC target pre-defines macro _ARCH_PWR7 which means the @code{-mcpu} | |
2219 | setting is Power7 or later. | |
2220 | ||
2221 | @item has_arch_pwr8 | |
2222 | PowerPC target pre-defines macro _ARCH_PWR8 which means the @code{-mcpu} | |
2223 | setting is Power8 or later. | |
2224 | ||
2225 | @item has_arch_pwr9 | |
2226 | PowerPC target pre-defines macro _ARCH_PWR9 which means the @code{-mcpu} | |
2227 | setting is Power9 or later. | |
d4f3924a JJ |
2228 | @end table |
2229 | ||
2230 | @subsubsection Other hardware attributes | |
2231 | ||
8a1a5194 | 2232 | @c Please keep this table sorted alphabetically. |
d4f3924a | 2233 | @table @code |
5316dd1b WD |
2234 | @item autoincdec |
2235 | Target supports autoincrement/decrement addressing. | |
2236 | ||
d4f3924a | 2237 | @item avx |
500b16c3 RO |
2238 | Target supports compiling @code{avx} instructions. |
2239 | ||
2240 | @item avx_runtime | |
2241 | Target supports the execution of @code{avx} instructions. | |
d4f3924a | 2242 | |
122f9da1 DS |
2243 | @item avx2 |
2244 | Target supports compiling @code{avx2} instructions. | |
2245 | ||
2246 | @item avx2_runtime | |
2247 | Target supports the execution of @code{avx2} instructions. | |
2248 | ||
ca813880 | 2249 | @item avxvnni |
2250 | Target supports the execution of @code{avxvnni} instructions. | |
2251 | ||
122f9da1 DS |
2252 | @item avx512f |
2253 | Target supports compiling @code{avx512f} instructions. | |
2254 | ||
2255 | @item avx512f_runtime | |
2256 | Target supports the execution of @code{avx512f} instructions. | |
2257 | ||
8d1184f0 HL |
2258 | @item avx512vp2intersect |
2259 | Target supports the execution of @code{avx512vp2intersect} instructions. | |
2260 | ||
5c609842 | 2261 | @item amx_tile |
2262 | Target supports the execution of @code{amx-tile} instructions. | |
2263 | ||
2264 | @item amx_int8 | |
2265 | Target supports the execution of @code{amx-int8} instructions. | |
2266 | ||
2267 | @item amx_bf16 | |
2268 | Target supports the execution of @code{amx-bf16} instructions. | |
2269 | ||
d4f3924a JJ |
2270 | @item cell_hw |
2271 | Test system can execute AltiVec and Cell PPU instructions. | |
2272 | ||
2273 | @item coldfire_fpu | |
2274 | Target uses a ColdFire FPU. | |
2275 | ||
8a1a5194 TV |
2276 | @item divmod |
2277 | Target supporting hardware divmod insn or divmod libcall. | |
2278 | ||
2279 | @item divmod_simode | |
2280 | Target supporting hardware divmod insn or divmod libcall for SImode. | |
2281 | ||
d4f3924a JJ |
2282 | @item hard_float |
2283 | Target supports FPU instructions. | |
2284 | ||
94910f22 SE |
2285 | @item non_strict_align |
2286 | Target does not require strict alignment. | |
2287 | ||
8a1a5194 TV |
2288 | @item pie_copyreloc |
2289 | The x86-64 target linker supports PIE with copy reloc. | |
2290 | ||
8d4f5c68 TV |
2291 | @item rdrand |
2292 | Target supports x86 @code{rdrand} instruction. | |
2293 | ||
1e43cc94 KT |
2294 | @item sqrt_insn |
2295 | Target has a square root instruction that the compiler can generate. | |
2296 | ||
ae6a0535 RO |
2297 | @item sse |
2298 | Target supports compiling @code{sse} instructions. | |
2299 | ||
39354b3b RO |
2300 | @item sse_runtime |
2301 | Target supports the execution of @code{sse} instructions. | |
2302 | ||
40f1bdd9 RO |
2303 | @item sse2 |
2304 | Target supports compiling @code{sse2} instructions. | |
2305 | ||
39354b3b RO |
2306 | @item sse2_runtime |
2307 | Target supports the execution of @code{sse2} instructions. | |
2308 | ||
d4f3924a JJ |
2309 | @item sync_char_short |
2310 | Target supports atomic operations on @code{char} and @code{short}. | |
2311 | ||
2312 | @item sync_int_long | |
2313 | Target supports atomic operations on @code{int} and @code{long}. | |
2314 | ||
2315 | @item ultrasparc_hw | |
2316 | Test environment appears to run executables on a simulator that | |
2317 | accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS} | |
2318 | or @code{EM_SPARCV9} executables. | |
2319 | ||
2320 | @item vect_cmdline_needed | |
2321 | Target requires a command line argument to enable a SIMD instruction set. | |
77ad54d9 | 2322 | |
c37691e5 TC |
2323 | @item xorsign |
2324 | Target supports the xorsign optab expansion. | |
2325 | ||
d4f3924a JJ |
2326 | @end table |
2327 | ||
2328 | @subsubsection Environment attributes | |
2329 | ||
2330 | @table @code | |
2331 | @item c | |
2332 | The language for the compiler under test is C. | |
2333 | ||
2334 | @item c++ | |
2335 | The language for the compiler under test is C++. | |
2336 | ||
2337 | @item c99_runtime | |
2338 | Target provides a full C99 runtime. | |
2339 | ||
2340 | @item correct_iso_cpp_string_wchar_protos | |
2341 | Target @code{string.h} and @code{wchar.h} headers provide C++ required | |
2342 | overloads for @code{strchr} etc. functions. | |
2343 | ||
6d9434e5 RO |
2344 | @item d_runtime |
2345 | Target provides the D runtime. | |
2346 | ||
b57e1621 IB |
2347 | @item d_runtime_has_std_library |
2348 | Target provides the D standard library (Phobos). | |
2349 | ||
d4f3924a JJ |
2350 | @item dummy_wcsftime |
2351 | Target uses a dummy @code{wcsftime} function that always returns zero. | |
2352 | ||
2353 | @item fd_truncate | |
2354 | Target can truncate a file from a file descriptor, as used by | |
630ba2fd | 2355 | @file{libgfortran/io/unix.c:fd_truncate}; i.e.@: @code{ftruncate} or |
d4f3924a JJ |
2356 | @code{chsize}. |
2357 | ||
55ac4e01 CL |
2358 | @item fenv |
2359 | Target provides @file{fenv.h} include file. | |
2360 | ||
2361 | @item fenv_exceptions | |
2362 | Target supports @file{fenv.h} with all the standard IEEE exceptions | |
2363 | and floating-point exceptions are raised by arithmetic operations. | |
2364 | ||
6c8e4f4d JM |
2365 | @item fenv_exceptions_dfp |
2366 | Target supports @file{fenv.h} with all the standard IEEE exceptions | |
2367 | and floating-point exceptions are raised by arithmetic operations for | |
2368 | decimal floating point. | |
2369 | ||
7eee6d21 AO |
2370 | @item fileio |
2371 | Target offers such file I/O library functions as @code{fopen}, | |
2372 | @code{fclose}, @code{tmpnam}, and @code{remove}. This is a link-time | |
2373 | requirement for the presence of the functions in the library; even if | |
2374 | they fail at runtime, the requirement is still regarded as satisfied. | |
2375 | ||
d4f3924a JJ |
2376 | @item freestanding |
2377 | Target is @samp{freestanding} as defined in section 4 of the C99 standard. | |
2378 | Effectively, it is a target which supports no extra headers or libraries | |
2379 | other than what is considered essential. | |
2380 | ||
54649631 TT |
2381 | @item gettimeofday |
2382 | Target supports @code{gettimeofday}. | |
2383 | ||
d4f3924a JJ |
2384 | @item init_priority |
2385 | Target supports constructors with initialization priority arguments. | |
2386 | ||
2387 | @item inttypes_types | |
2388 | Target has the basic signed and unsigned types in @code{inttypes.h}. | |
2389 | This is for tests that GCC's notions of these types agree with those | |
2390 | in the header, as some systems have only @code{inttypes.h}. | |
2391 | ||
2392 | @item lax_strtofp | |
2393 | Target might have errors of a few ULP in string to floating-point | |
2394 | conversion functions and overflow is not always detected correctly by | |
2395 | those functions. | |
2396 | ||
37b12f58 IE |
2397 | @item mempcpy |
2398 | Target provides @code{mempcpy} function. | |
2399 | ||
8175c19c RO |
2400 | @item mmap |
2401 | Target supports @code{mmap}. | |
2402 | ||
d4f3924a JJ |
2403 | @item newlib |
2404 | Target supports Newlib. | |
2405 | ||
571bbd0d JL |
2406 | @item newlib_nano_io |
2407 | GCC was configured with @code{--enable-newlib-nano-formatted-io}, which reduces | |
2408 | the code size of Newlib formatted I/O functions. | |
2409 | ||
d4f3924a JJ |
2410 | @item pow10 |
2411 | Target provides @code{pow10} function. | |
2412 | ||
2413 | @item pthread | |
2414 | Target can compile using @code{pthread.h} with no errors or warnings. | |
2415 | ||
2416 | @item pthread_h | |
2417 | Target has @code{pthread.h}. | |
2418 | ||
0fa3d594 RO |
2419 | @item run_expensive_tests |
2420 | Expensive testcases (usually those that consume excessive amounts of CPU | |
2421 | time) should be run on this target. This can be enabled by setting the | |
2422 | @env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string. | |
2423 | ||
d4f3924a | 2424 | @item simulator |
630ba2fd SB |
2425 | Test system runs executables on a simulator (i.e.@: slowly) rather than |
2426 | hardware (i.e.@: fast). | |
d4f3924a | 2427 | |
18787c38 TV |
2428 | @item signal |
2429 | Target has @code{signal.h}. | |
2430 | ||
01704e5a RO |
2431 | @item stabs |
2432 | Target supports the stabs debugging format. | |
2433 | ||
d4f3924a JJ |
2434 | @item stdint_types |
2435 | Target has the basic signed and unsigned C types in @code{stdint.h}. | |
2436 | This will be obsolete when GCC ensures a working @code{stdint.h} for | |
2437 | all targets. | |
2438 | ||
37b12f58 IE |
2439 | @item stpcpy |
2440 | Target provides @code{stpcpy} function. | |
2441 | ||
d4f3924a JJ |
2442 | @item trampolines |
2443 | Target supports trampolines. | |
2444 | ||
2445 | @item uclibc | |
2446 | Target supports uClibc. | |
2447 | ||
2448 | @item unwrapped | |
2449 | Target does not use a status wrapper. | |
2450 | ||
2451 | @item vxworks_kernel | |
2452 | Target is a VxWorks kernel. | |
2453 | ||
2454 | @item vxworks_rtp | |
2455 | Target is a VxWorks RTP. | |
2456 | ||
2457 | @item wchar | |
2458 | Target supports wide characters. | |
2459 | @end table | |
2460 | ||
2461 | @subsubsection Other attributes | |
2462 | ||
2463 | @table @code | |
6fbec038 L |
2464 | @item R_flag_in_section |
2465 | Target supports the 'R' flag in .section directive in assembly inputs. | |
2466 | ||
d4f3924a JJ |
2467 | @item automatic_stack_alignment |
2468 | Target supports automatic stack alignment. | |
2469 | ||
7dbf8707 CL |
2470 | @item branch_cost |
2471 | Target supports @option{-branch-cost=N}. | |
2472 | ||
d4f3924a JJ |
2473 | @item cxa_atexit |
2474 | Target uses @code{__cxa_atexit}. | |
2475 | ||
2476 | @item default_packed | |
2477 | Target has packed layout of structure members by default. | |
2478 | ||
3f21b8e3 AS |
2479 | @item exceptions |
2480 | Target supports exceptions. | |
2481 | ||
a9046e98 JL |
2482 | @item exceptions_enabled |
2483 | Target supports exceptions and they are enabled in the current | |
2484 | testing configuration. | |
2485 | ||
d4f3924a JJ |
2486 | @item fgraphite |
2487 | Target supports Graphite optimizations. | |
2488 | ||
2489 | @item fixed_point | |
2490 | Target supports fixed-point extension to C. | |
2491 | ||
41dbbb37 TS |
2492 | @item fopenacc |
2493 | Target supports OpenACC via @option{-fopenacc}. | |
2494 | ||
d4f3924a JJ |
2495 | @item fopenmp |
2496 | Target supports OpenMP via @option{-fopenmp}. | |
2497 | ||
2498 | @item fpic | |
2499 | Target supports @option{-fpic} and @option{-fPIC}. | |
2500 | ||
2501 | @item freorder | |
2502 | Target supports @option{-freorder-blocks-and-partition}. | |
2503 | ||
2504 | @item fstack_protector | |
2505 | Target supports @option{-fstack-protector}. | |
2506 | ||
659b24d6 RO |
2507 | @item gas |
2508 | Target uses GNU @command{as}. | |
2509 | ||
d4f3924a JJ |
2510 | @item gc_sections |
2511 | Target supports @option{--gc-sections}. | |
2512 | ||
14a393a3 RO |
2513 | @item gld |
2514 | Target uses GNU @command{ld}. | |
2515 | ||
d4f3924a JJ |
2516 | @item keeps_null_pointer_checks |
2517 | Target keeps null pointer checks, either due to the use of | |
2518 | @option{-fno-delete-null-pointer-checks} or hardwired into the target. | |
2519 | ||
b50002c4 AS |
2520 | @item llvm_binutils |
2521 | Target is using an LLVM assembler and/or linker, instead of GNU Binutils. | |
2522 | ||
d4f3924a JJ |
2523 | @item lto |
2524 | Compiler has been configured to support link-time optimization (LTO). | |
2525 | ||
c7e8e26e JJ |
2526 | @item lto_incremental |
2527 | Compiler and linker support link-time optimization relocatable linking | |
2528 | with @option{-r} and @option{-flto} options. | |
2529 | ||
d45eae79 SL |
2530 | @item naked_functions |
2531 | Target supports the @code{naked} function attribute. | |
2532 | ||
d4f3924a JJ |
2533 | @item named_sections |
2534 | Target supports named sections. | |
2535 | ||
2536 | @item natural_alignment_32 | |
2537 | Target uses natural alignment (aligned to type size) for types of | |
2538 | 32 bits or less. | |
2539 | ||
2540 | @item target_natural_alignment_64 | |
2541 | Target uses natural alignment (aligned to type size) for types of | |
2542 | 64 bits or less. | |
2543 | ||
f0033821 CL |
2544 | @item noinit |
2545 | Target supports the @code{noinit} variable attribute. | |
2546 | ||
d4f3924a JJ |
2547 | @item nonpic |
2548 | Target does not generate PIC by default. | |
2549 | ||
694d4a6d L |
2550 | @item o_flag_in_section |
2551 | Target supports the 'o' flag in .section directive in assembly inputs. | |
2552 | ||
b50002c4 AS |
2553 | @item offload_gcn |
2554 | Target has been configured for OpenACC/OpenMP offloading on AMD GCN. | |
2555 | ||
762ca203 JL |
2556 | @item persistent |
2557 | Target supports the @code{persistent} variable attribute. | |
2558 | ||
a8d790df L |
2559 | @item pie_enabled |
2560 | Target generates PIE by default. | |
2561 | ||
d4f3924a JJ |
2562 | @item pcc_bitfield_type_matters |
2563 | Target defines @code{PCC_BITFIELD_TYPE_MATTERS}. | |
2564 | ||
2565 | @item pe_aligned_commons | |
2566 | Target supports @option{-mpe-aligned-commons}. | |
2567 | ||
8340fbd7 RO |
2568 | @item pie |
2569 | Target supports @option{-pie}, @option{-fpie} and @option{-fPIE}. | |
2570 | ||
1f1fd3e2 TT |
2571 | @item rdynamic |
2572 | Target supports @option{-rdynamic}. | |
2573 | ||
c566cc9f RS |
2574 | @item scalar_all_fma |
2575 | Target supports all four fused multiply-add optabs for both @code{float} | |
2576 | and @code{double}. These optabs are: @code{fma_optab}, @code{fms_optab}, | |
2577 | @code{fnma_optab} and @code{fnms_optab}. | |
2578 | ||
d4f3924a JJ |
2579 | @item section_anchors |
2580 | Target supports section anchors. | |
2581 | ||
2582 | @item short_enums | |
2583 | Target defaults to short enums. | |
2584 | ||
0069a009 | 2585 | @item stack_size |
6b92ab17 TV |
2586 | @anchor{stack_size_et} |
2587 | Target has limited stack size. The stack size limit can be obtained using the | |
2588 | STACK_SIZE macro defined by @ref{stack_size_ao,,@code{dg-add-options} feature | |
2589 | @code{stack_size}}. | |
0069a009 | 2590 | |
d4f3924a JJ |
2591 | @item static |
2592 | Target supports @option{-static}. | |
2593 | ||
2594 | @item static_libgfortran | |
2595 | Target supports statically linking @samp{libgfortran}. | |
2596 | ||
2597 | @item string_merging | |
2598 | Target supports merging string constants at link time. | |
2599 | ||
2600 | @item ucn | |
2601 | Target supports compiling and assembling UCN. | |
2602 | ||
2603 | @item ucn_nocache | |
2604 | Including the options used to compile this particular test, the | |
2605 | target supports compiling and assembling UCN. | |
2606 | ||
2607 | @item unaligned_stack | |
2608 | Target does not guarantee that its @code{STACK_BOUNDARY} is greater than | |
2609 | or equal to the required vector alignment. | |
2610 | ||
2611 | @item vector_alignment_reachable | |
2612 | Vector alignment is reachable for types of 32 bits or less. | |
2613 | ||
2614 | @item vector_alignment_reachable_for_64bit | |
2615 | Vector alignment is reachable for types of 64 bits or less. | |
2616 | ||
2617 | @item wchar_t_char16_t_compatible | |
2618 | Target supports @code{wchar_t} that is compatible with @code{char16_t}. | |
2619 | ||
2620 | @item wchar_t_char32_t_compatible | |
2621 | Target supports @code{wchar_t} that is compatible with @code{char32_t}. | |
813ba013 JJ |
2622 | |
2623 | @item comdat_group | |
2624 | Target uses comdat groups. | |
a5362c6a JM |
2625 | |
2626 | @item indirect_calls | |
2627 | Target supports indirect calls, i.e. calls where the target is not | |
2628 | constant. | |
d2a359fe L |
2629 | |
2630 | @item lgccjit | |
2631 | Target supports -lgccjit, i.e. libgccjit.so can be linked into jit tests. | |
d4f3924a JJ |
2632 | @end table |
2633 | ||
2634 | @subsubsection Local to tests in @code{gcc.target/i386} | |
2635 | ||
2636 | @table @code | |
40f1bdd9 RO |
2637 | @item 3dnow |
2638 | Target supports compiling @code{3dnow} instructions. | |
2639 | ||
d4f3924a JJ |
2640 | @item aes |
2641 | Target supports compiling @code{aes} instructions. | |
2642 | ||
2643 | @item fma4 | |
2644 | Target supports compiling @code{fma4} instructions. | |
2645 | ||
aa992ce7 IS |
2646 | @item mfentry |
2647 | Target supports the @code{-mfentry} option that alters the | |
2648 | position of profiling calls such that they precede the prologue. | |
2649 | ||
d4f3924a JJ |
2650 | @item ms_hook_prologue |
2651 | Target supports attribute @code{ms_hook_prologue}. | |
2652 | ||
2653 | @item pclmul | |
2654 | Target supports compiling @code{pclmul} instructions. | |
2655 | ||
40f1bdd9 RO |
2656 | @item sse3 |
2657 | Target supports compiling @code{sse3} instructions. | |
2658 | ||
d4f3924a JJ |
2659 | @item sse4 |
2660 | Target supports compiling @code{sse4} instructions. | |
2661 | ||
2662 | @item sse4a | |
2663 | Target supports compiling @code{sse4a} instructions. | |
2664 | ||
2665 | @item ssse3 | |
2666 | Target supports compiling @code{ssse3} instructions. | |
2667 | ||
2668 | @item vaes | |
2669 | Target supports compiling @code{vaes} instructions. | |
2670 | ||
2671 | @item vpclmul | |
2672 | Target supports compiling @code{vpclmul} instructions. | |
2673 | ||
2674 | @item xop | |
2675 | Target supports compiling @code{xop} instructions. | |
2676 | @end table | |
2677 | ||
d4f3924a JJ |
2678 | @subsubsection Local to tests in @code{gcc.test-framework} |
2679 | ||
2680 | @table @code | |
2681 | @item no | |
2682 | Always returns 0. | |
2683 | ||
2684 | @item yes | |
2685 | Always returns 1. | |
2686 | @end table | |
2687 | ||
2688 | @node Add Options | |
2689 | @subsection Features for @code{dg-add-options} | |
2690 | ||
2691 | The supported values of @var{feature} for directive @code{dg-add-options} | |
2692 | are: | |
2693 | ||
2694 | @table @code | |
d7cf3dc7 CL |
2695 | @item arm_fp |
2696 | @code{__ARM_FP} definition. Only ARM targets support this feature, and only then | |
2697 | in certain modes; see the @ref{arm_fp_ok,,arm_fp_ok effective target | |
2698 | keyword}. | |
2699 | ||
8001f59c CL |
2700 | @item arm_fp_dp |
2701 | @code{__ARM_FP} definition with double-precision support. Only ARM | |
2702 | targets support this feature, and only then in certain modes; see the | |
2703 | @ref{arm_fp_dp_ok,,arm_fp_dp_ok effective target keyword}. | |
2704 | ||
16c9d3b1 RO |
2705 | @item arm_neon |
2706 | NEON support. Only ARM targets support this feature, and only then | |
2707 | in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target | |
2708 | keyword}. | |
2709 | ||
7fe43755 MW |
2710 | @item arm_fp16 |
2711 | VFP half-precision floating point support. This does not select the | |
2712 | FP16 format; for that, use @ref{arm_fp16_ieee,,arm_fp16_ieee} or | |
2713 | @ref{arm_fp16_alternative,,arm_fp16_alternative} instead. This | |
2714 | feature is only supported by ARM targets and then only in certain | |
2715 | modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target | |
2716 | keyword}. | |
2717 | ||
2718 | @item arm_fp16_ieee | |
2719 | @anchor{arm_fp16_ieee} | |
2720 | ARM IEEE 754-2008 format VFP half-precision floating point support. | |
2721 | This feature is only supported by ARM targets and then only in certain | |
2722 | modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target | |
2723 | keyword}. | |
2724 | ||
2725 | @item arm_fp16_alternative | |
2726 | @anchor{arm_fp16_alternative} | |
2727 | ARM Alternative format VFP half-precision floating point support. | |
2728 | This feature is only supported by ARM targets and then only in certain | |
2729 | modes; see the @ref{arm_fp16_ok,,arm_fp16_ok effective target | |
2730 | keyword}. | |
2731 | ||
16c9d3b1 RO |
2732 | @item arm_neon_fp16 |
2733 | NEON and half-precision floating point support. Only ARM targets | |
2734 | support this feature, and only then in certain modes; see | |
48c44783 | 2735 | the @ref{arm_neon_fp16_ok,,arm_neon_fp16_ok effective target keyword}. |
16c9d3b1 | 2736 | |
6d3715b9 RL |
2737 | @item arm_vfp3 |
2738 | arm vfp3 floating point support; see | |
2739 | the @ref{arm_vfp3_ok,,arm_vfp3_ok effective target keyword}. | |
2740 | ||
127abeb2 RS |
2741 | @item arm_arch_v8a_hard |
2742 | Add options for ARMv8-A and the hard-float variant of the AAPCS, | |
2743 | if this is supported by the compiler; see the | |
2744 | @ref{arm_arch_v8a_hard_ok,,arm_arch_v8a_hard_ok} effective target keyword. | |
2745 | ||
1b9e31cf | 2746 | @item arm_v8_1a_neon |
d7dccfa3 | 2747 | Add options for ARMv8.1-A with Adv.SIMD support, if this is supported |
1b9e31cf MW |
2748 | by the target; see the @ref{arm_v8_1a_neon_ok,,arm_v8_1a_neon_ok} |
2749 | effective target keyword. | |
2750 | ||
2751 | @item arm_v8_2a_fp16_scalar | |
d7dccfa3 | 2752 | Add options for ARMv8.2-A with scalar FP16 support, if this is |
1b9e31cf MW |
2753 | supported by the target; see the |
2754 | @ref{arm_v8_2a_fp16_scalar_ok,,arm_v8_2a_fp16_scalar_ok} effective | |
2755 | target keyword. | |
2756 | ||
2757 | @item arm_v8_2a_fp16_neon | |
d7dccfa3 | 2758 | Add options for ARMv8.2-A with Adv.SIMD FP16 support, if this is |
1b9e31cf MW |
2759 | supported by the target; see the |
2760 | @ref{arm_v8_2a_fp16_neon_ok,,arm_v8_2a_fp16_neon_ok} effective target | |
2761 | keyword. | |
2762 | ||
2b5de014 | 2763 | @item arm_v8_2a_dotprod_neon |
d7dccfa3 | 2764 | Add options for ARMv8.2-A with Adv.SIMD Dot Product support, if this is |
2b5de014 TC |
2765 | supported by the target; see the |
2766 | @ref{arm_v8_2a_dotprod_neon_ok} effective target keyword. | |
2767 | ||
06e95715 KT |
2768 | @item arm_fp16fml_neon |
2769 | Add options to enable generation of the @code{VFMAL} and @code{VFMSL} | |
2770 | instructions, if this is supported by the target; see the | |
2771 | @ref{arm_fp16fml_neon_ok} effective target keyword. | |
2772 | ||
d4f3924a JJ |
2773 | @item bind_pic_locally |
2774 | Add the target-specific flags needed to enable functions to bind | |
2775 | locally when using pic/PIC passes in the testsuite. | |
2776 | ||
c65699ef JM |
2777 | @item float@var{n} |
2778 | Add the target-specific flags needed to use the @code{_Float@var{n}} type. | |
2779 | ||
2780 | @item float@var{n}x | |
2781 | Add the target-specific flags needed to use the @code{_Float@var{n}x} type. | |
2782 | ||
d4f3924a JJ |
2783 | @item ieee |
2784 | Add the target-specific flags needed to enable full IEEE | |
2785 | compliance mode. | |
2786 | ||
2787 | @item mips16_attribute | |
2788 | @code{mips16} function attributes. | |
2789 | Only MIPS targets support this feature, and only then in certain modes. | |
0c422e74 | 2790 | |
6b92ab17 TV |
2791 | @item stack_size |
2792 | @anchor{stack_size_ao} | |
2793 | Add the flags needed to define macro STACK_SIZE and set it to the stack size | |
2794 | limit associated with the @ref{stack_size_et,,@code{stack_size} effective | |
2795 | target}. | |
2796 | ||
674931d2 AS |
2797 | @item sqrt_insn |
2798 | Add the target-specific flags needed to enable hardware square root | |
2799 | instructions, if any. | |
2800 | ||
16c9d3b1 RO |
2801 | @item tls |
2802 | Add the target-specific flags needed to use thread-local storage. | |
d4f3924a JJ |
2803 | @end table |
2804 | ||
2805 | @node Require Support | |
2806 | @subsection Variants of @code{dg-require-@var{support}} | |
2807 | ||
2808 | A few of the @code{dg-require} directives take arguments. | |
2809 | ||
2810 | @table @code | |
2811 | @item dg-require-iconv @var{codeset} | |
2812 | Skip the test if the target does not support iconv. @var{codeset} is | |
2813 | the codeset to convert to. | |
2814 | ||
2815 | @item dg-require-profiling @var{profopt} | |
2816 | Skip the test if the target does not support profiling with option | |
2817 | @var{profopt}. | |
2818 | ||
9e00a397 CL |
2819 | @item dg-require-stack-check @var{check} |
2820 | Skip the test if the target does not support the @code{-fstack-check} | |
2821 | option. If @var{check} is @code{""}, support for @code{-fstack-check} | |
2822 | is checked, for @code{-fstack-check=("@var{check}")} otherwise. | |
2823 | ||
7ff6bdb7 TV |
2824 | @item dg-require-stack-size @var{size} |
2825 | Skip the test if the target does not support a stack size of @var{size}. | |
2826 | ||
d4f3924a JJ |
2827 | @item dg-require-visibility @var{vis} |
2828 | Skip the test if the target does not support the @code{visibility} attribute. | |
2829 | If @var{vis} is @code{""}, support for @code{visibility("hidden")} is | |
2830 | checked, for @code{visibility("@var{vis}")} otherwise. | |
2831 | @end table | |
2832 | ||
2833 | The original @code{dg-require} directives were defined before there | |
2834 | was support for effective-target keywords. The directives that do not | |
2835 | take arguments could be replaced with effective-target keywords. | |
2836 | ||
2837 | @table @code | |
2838 | @item dg-require-alias "" | |
2839 | Skip the test if the target does not support the @samp{alias} attribute. | |
2840 | ||
6dd2a13c RO |
2841 | @item dg-require-ascii-locale "" |
2842 | Skip the test if the host does not support an ASCII locale. | |
2843 | ||
d4f3924a JJ |
2844 | @item dg-require-compat-dfp "" |
2845 | Skip this test unless both compilers in a @file{compat} testsuite | |
2846 | support decimal floating point. | |
2847 | ||
2848 | @item dg-require-cxa-atexit "" | |
2849 | Skip the test if the target does not support @code{__cxa_atexit}. | |
2850 | This is equivalent to @code{dg-require-effective-target cxa_atexit}. | |
2851 | ||
2852 | @item dg-require-dll "" | |
2853 | Skip the test if the target does not support DLL attributes. | |
2854 | ||
757bf1df DM |
2855 | @item dg-require-dot "" |
2856 | Skip the test if the host does not have @command{dot}. | |
2857 | ||
d4f3924a JJ |
2858 | @item dg-require-fork "" |
2859 | Skip the test if the target does not support @code{fork}. | |
2860 | ||
2861 | @item dg-require-gc-sections "" | |
2862 | Skip the test if the target's linker does not support the | |
2863 | @code{--gc-sections} flags. | |
2864 | This is equivalent to @code{dg-require-effective-target gc-sections}. | |
2865 | ||
2866 | @item dg-require-host-local "" | |
2867 | Skip the test if the host is remote, rather than the same as the build | |
2868 | system. Some tests are incompatible with DejaGnu's handling of remote | |
2869 | hosts, which involves copying the source file to the host and compiling | |
2870 | it with a relative path and "@code{-o a.out}". | |
2871 | ||
2872 | @item dg-require-mkfifo "" | |
2873 | Skip the test if the target does not support @code{mkfifo}. | |
2874 | ||
2875 | @item dg-require-named-sections "" | |
2876 | Skip the test is the target does not support named sections. | |
2877 | This is equivalent to @code{dg-require-effective-target named_sections}. | |
2878 | ||
2879 | @item dg-require-weak "" | |
2880 | Skip the test if the target does not support weak symbols. | |
2881 | ||
2882 | @item dg-require-weak-override "" | |
2883 | Skip the test if the target does not support overriding weak symbols. | |
2884 | @end table | |
2885 | ||
2886 | @node Final Actions | |
2887 | @subsection Commands for use in @code{dg-final} | |
2888 | ||
2889 | The GCC testsuite defines the following directives to be used within | |
2890 | @code{dg-final}. | |
2891 | ||
2892 | @subsubsection Scan a particular file | |
2893 | ||
2894 | @table @code | |
35fdf04e JJ |
2895 | @item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] |
2896 | Passes if @var{regexp} matches text in @var{filename}. | |
35fdf04e JJ |
2897 | @item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}] |
2898 | Passes if @var{regexp} does not match text in @var{filename}. | |
d4f3924a JJ |
2899 | @item scan-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}] |
2900 | Passes if @var{regexp} matches in Fortran module @var{module}. | |
757bf1df DM |
2901 | @item dg-check-dot @var{filename} |
2902 | Passes if @var{filename} is a valid @file{.dot} file (by running | |
2903 | @code{dot -Tpng} on it, and verifying the exit code is 0). | |
d4f3924a | 2904 | @end table |
35fdf04e | 2905 | |
d4f3924a | 2906 | @subsubsection Scan the assembly output |
35fdf04e | 2907 | |
d4f3924a | 2908 | @table @code |
35fdf04e JJ |
2909 | @item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}] |
2910 | Passes if @var{regex} matches text in the test's assembler output. | |
2911 | ||
2912 | @item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}] | |
2913 | Passes if @var{regex} does not match text in the test's assembler output. | |
2914 | ||
d4f3924a JJ |
2915 | @item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}] |
2916 | Passes if @var{regex} is matched exactly @var{num} times in the test's | |
2917 | assembler output. | |
2918 | ||
35fdf04e JJ |
2919 | @item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}] |
2920 | Passes if @var{regex} matches text in the test's demangled assembler output. | |
2921 | ||
2922 | @item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}] | |
2923 | Passes if @var{regex} does not match text in the test's demangled assembler | |
2924 | output. | |
2925 | ||
f1eeabc1 RO |
2926 | @item scan-assembler-symbol-section @var{functions} @var{section} [@{ target/xfail @var{selector} @}] |
2927 | Passes if @var{functions} are all in @var{section}. The caller needs to | |
2928 | allow for @code{USER_LABEL_PREFIX} and different section name conventions. | |
2929 | ||
2930 | @item scan-symbol-section @var{filename} @var{functions} @var{section} [@{ target/xfail @var{selector} @}] | |
2931 | Passes if @var{functions} are all in @var{section}in @var{filename}. | |
2932 | The same caveats as for @code{scan-assembler-symbol-section} apply. | |
2933 | ||
d4f3924a JJ |
2934 | @item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}] |
2935 | Passes if @var{symbol} is defined as a hidden symbol in the test's | |
2936 | assembly output. | |
2937 | ||
2938 | @item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}] | |
2939 | Passes if @var{symbol} is not defined as a hidden symbol in the test's | |
2940 | assembly output. | |
4d706ff8 | 2941 | |
7ed2d6cb | 2942 | @item check-function-bodies @var{prefix} @var{terminator} [@var{options} [@{ target/xfail @var{selector} @}]] |
4d706ff8 RS |
2943 | Looks through the source file for comments that give the expected assembly |
2944 | output for selected functions. Each line of expected output starts with the | |
2945 | prefix string @var{prefix} and the expected output for a function as a whole | |
2946 | is followed by a line that starts with the string @var{terminator}. | |
2947 | Specifying an empty terminator is equivalent to specifying @samp{"*/"}. | |
2948 | ||
7ed2d6cb RS |
2949 | @var{options}, if specified, is a list of regular expressions, each of |
2950 | which matches a full command-line option. A non-empty list prevents | |
2951 | the test from running unless all of the given options are present on the | |
2952 | command line. This can help if a source file is compiled both with | |
2953 | and without optimization, since it is rarely useful to check the full | |
2954 | function body for unoptimized code. | |
4d706ff8 RS |
2955 | |
2956 | The first line of the expected output for a function @var{fn} has the form: | |
2957 | ||
2958 | @smallexample | |
2959 | @var{prefix} @var{fn}: [@{ target/xfail @var{selector} @}] | |
2960 | @end smallexample | |
2961 | ||
2962 | Subsequent lines of the expected output also start with @var{prefix}. | |
2963 | In both cases, whitespace after @var{prefix} is not significant. | |
2964 | ||
2965 | The test discards assembly directives such as @code{.cfi_startproc} | |
2966 | and local label definitions such as @code{.LFB0} from the compiler's | |
2967 | assembly output. It then matches the result against the expected | |
2968 | output for a function as a single regular expression. This means that | |
2969 | later lines can use backslashes to refer back to @samp{(@dots{})} | |
2970 | captures on earlier lines. For example: | |
2971 | ||
2972 | @smallexample | |
2973 | /* @{ dg-final @{ check-function-bodies "**" "" "-DCHECK_ASM" @} @} */ | |
2974 | @dots{} | |
2975 | /* | |
2976 | ** add_w0_s8_m: | |
2977 | ** mov (z[0-9]+\.b), w0 | |
2978 | ** add z0\.b, p0/m, z0\.b, \1 | |
2979 | ** ret | |
2980 | */ | |
2981 | svint8_t add_w0_s8_m (@dots{}) @{ @dots{} @} | |
2982 | @dots{} | |
2983 | /* | |
2984 | ** add_b0_s8_m: | |
2985 | ** mov (z[0-9]+\.b), b0 | |
2986 | ** add z1\.b, p0/m, z1\.b, \1 | |
2987 | ** ret | |
2988 | */ | |
2989 | svint8_t add_b0_s8_m (@dots{}) @{ @dots{} @} | |
2990 | @end smallexample | |
2991 | ||
2992 | checks whether the implementations of @code{add_w0_s8_m} and | |
2993 | @code{add_b0_s8_m} match the regular expressions given. The test only | |
2994 | runs when @samp{-DCHECK_ASM} is passed on the command line. | |
2995 | ||
2996 | It is possible to create non-capturing multi-line regular expression | |
2997 | groups of the form @samp{(@var{a}|@var{b}|@dots{})} by putting the | |
2998 | @samp{(}, @samp{|} and @samp{)} on separate lines (each still using | |
2999 | @var{prefix}). For example: | |
3000 | ||
3001 | @smallexample | |
3002 | /* | |
3003 | ** cmple_f16_tied: | |
3004 | ** ( | |
3005 | ** fcmge p0\.h, p0/z, z1\.h, z0\.h | |
3006 | ** | | |
3007 | ** fcmle p0\.h, p0/z, z0\.h, z1\.h | |
3008 | ** ) | |
3009 | ** ret | |
3010 | */ | |
3011 | svbool_t cmple_f16_tied (@dots{}) @{ @dots{} @} | |
3012 | @end smallexample | |
3013 | ||
3014 | checks whether @code{cmple_f16_tied} is implemented by the | |
3015 | @code{fcmge} instruction followed by @code{ret} or by the | |
3016 | @code{fcmle} instruction followed by @code{ret}. The test is | |
3017 | still a single regular rexpression. | |
3018 | ||
3019 | A line containing just: | |
3020 | ||
3021 | @smallexample | |
3022 | @var{prefix} ... | |
3023 | @end smallexample | |
3024 | ||
3025 | stands for zero or more unmatched lines; the whitespace after | |
3026 | @var{prefix} is again not significant. | |
3027 | ||
d4f3924a JJ |
3028 | @end table |
3029 | ||
3030 | @subsubsection Scan optimization dump files | |
35fdf04e | 3031 | |
9220b511 | 3032 | These commands are available for @var{kind} of @code{tree}, @code{ltrans-tree}, |
9b09e453 TV |
3033 | @code{offload-tree}, @code{rtl}, @code{offload-rtl}, @code{ipa}, and |
3034 | @code{wpa-ipa}. | |
d4f3924a JJ |
3035 | |
3036 | @table @code | |
3037 | @item scan-@var{kind}-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] | |
35fdf04e JJ |
3038 | Passes if @var{regex} matches text in the dump file with suffix @var{suffix}. |
3039 | ||
d4f3924a | 3040 | @item scan-@var{kind}-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] |
35fdf04e JJ |
3041 | Passes if @var{regex} does not match text in the dump file with suffix |
3042 | @var{suffix}. | |
3043 | ||
d4f3924a JJ |
3044 | @item scan-@var{kind}-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}] |
3045 | Passes if @var{regex} is found exactly @var{num} times in the dump file | |
3046 | with suffix @var{suffix}. | |
3047 | ||
3048 | @item scan-@var{kind}-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] | |
35fdf04e JJ |
3049 | Passes if @var{regex} matches demangled text in the dump file with |
3050 | suffix @var{suffix}. | |
3051 | ||
d4f3924a | 3052 | @item scan-@var{kind}-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}] |
35fdf04e JJ |
3053 | Passes if @var{regex} does not match demangled text in the dump file with |
3054 | suffix @var{suffix}. | |
d4f3924a JJ |
3055 | @end table |
3056 | ||
d4501bbe FH |
3057 | The @var{suffix} argument which describes the dump file to be scanned |
3058 | may contain a glob pattern that must expand to exactly one file | |
3059 | name. This is useful if, e.g., different pass instances are executed | |
3060 | depending on torture testing command-line flags, producing dump files | |
3061 | whose names differ only in their pass instance number suffix. For | |
3062 | example, to scan instances 1, 2, 3 of a tree pass ``mypass'' for | |
3063 | occurrences of the string ``code has been optimized'', use: | |
3064 | @smallexample | |
3065 | /* @{ dg-options "-fdump-tree-mypass" @} */ | |
3066 | /* @{ dg-final @{ scan-tree-dump "code has been optimized" "mypass\[1-3\]" @} @} */ | |
3067 | @end smallexample | |
3068 | ||
3069 | ||
72e3a529 | 3070 | @subsubsection Check for output files |
35fdf04e | 3071 | |
d4f3924a | 3072 | @table @code |
d6682e21 JJ |
3073 | @item output-exists [@{ target/xfail @var{selector} @}] |
3074 | Passes if compiler output file exists. | |
3075 | ||
3076 | @item output-exists-not [@{ target/xfail @var{selector} @}] | |
3077 | Passes if compiler output file does not exist. | |
d4f3924a | 3078 | |
d4f3924a JJ |
3079 | @item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}] |
3080 | Passes if the pattern is present in the final executable. | |
72e3a529 TP |
3081 | |
3082 | @item scan-symbol-not @var{regexp} [@{ target/xfail @var{selector} @}] | |
3083 | Passes if the pattern is absent from the final executable. | |
d4f3924a | 3084 | @end table |
d6682e21 | 3085 | |
d4f3924a JJ |
3086 | @subsubsection Checks for @command{gcov} tests |
3087 | ||
3088 | @table @code | |
35fdf04e JJ |
3089 | @item run-gcov @var{sourcefile} |
3090 | Check line counts in @command{gcov} tests. | |
3091 | ||
3092 | @item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @} | |
3093 | Check branch and/or call counts, in addition to line counts, in | |
3094 | @command{gcov} tests. | |
3095 | @end table | |
d4f3924a JJ |
3096 | |
3097 | @subsubsection Clean up generated test files | |
3098 | ||
c469078d BRF |
3099 | Usually the test-framework removes files that were generated during |
3100 | testing. If a testcase, for example, uses any dumping mechanism to | |
3101 | inspect a passes dump file, the testsuite recognized the dump option | |
3102 | passed to the tool and schedules a final cleanup to remove these files. | |
3103 | ||
3104 | There are, however, following additional cleanup directives that can be | |
3105 | used to annotate a testcase "manually". | |
d4f3924a JJ |
3106 | @table @code |
3107 | @item cleanup-coverage-files | |
3108 | Removes coverage data files generated for this test. | |
3109 | ||
b3781fcb BRF |
3110 | @item cleanup-modules "@var{list-of-extra-modules}" |
3111 | Removes Fortran module files generated for this test, excluding the | |
3112 | module names listed in keep-modules. | |
3113 | Cleaning up module files is usually done automatically by the testsuite | |
3114 | by looking at the source files and removing the modules after the test | |
3115 | has been executed. | |
3116 | @smallexample | |
3117 | module MoD1 | |
3118 | end module MoD1 | |
3119 | module Mod2 | |
3120 | end module Mod2 | |
3121 | module moD3 | |
3122 | end module moD3 | |
3123 | module mod4 | |
3124 | end module mod4 | |
3125 | ! @{ dg-final @{ cleanup-modules "mod1 mod2" @} @} ! redundant | |
3126 | ! @{ dg-final @{ keep-modules "mod3 mod4" @} @} | |
3127 | @end smallexample | |
3128 | ||
3129 | @item keep-modules "@var{list-of-modules-not-to-delete}" | |
3130 | Whitespace separated list of module names that should not be deleted by | |
3131 | cleanup-modules. | |
3132 | If the list of modules is empty, all modules defined in this file are kept. | |
3133 | @smallexample | |
3134 | module maybe_unneeded | |
3135 | end module maybe_unneeded | |
3136 | module keep1 | |
3137 | end module keep1 | |
3138 | module keep2 | |
3139 | end module keep2 | |
3140 | ! @{ dg-final @{ keep-modules "keep1 keep2" @} @} ! just keep these two | |
3141 | ! @{ dg-final @{ keep-modules "" @} @} ! keep all | |
3142 | @end smallexample | |
d4f3924a | 3143 | |
c469078d BRF |
3144 | @item dg-keep-saved-temps "@var{list-of-suffixes-not-to-delete}" |
3145 | Whitespace separated list of suffixes that should not be deleted | |
3146 | automatically in a testcase that uses @option{-save-temps}. | |
3147 | @smallexample | |
3148 | // @{ dg-options "-save-temps -fpch-preprocess -I." @} | |
3149 | int main() @{ return 0; @} | |
3150 | // @{ dg-keep-saved-temps ".s" @} ! just keep assembler file | |
3151 | // @{ dg-keep-saved-temps ".s" ".i" @} ! ... and .i | |
3152 | // @{ dg-keep-saved-temps ".ii" ".o" @} ! or just .ii and .o | |
3153 | @end smallexample | |
3154 | ||
d4f3924a JJ |
3155 | @item cleanup-profile-file |
3156 | Removes profiling files generated for this test. | |
3157 | ||
35fdf04e JJ |
3158 | @end table |
3159 | ||
d0a74d7e | 3160 | @node Ada Tests |
500cdcb0 | 3161 | @section Ada Language Testsuites |
d0a74d7e | 3162 | |
bebd5f99 | 3163 | The Ada testsuite includes executable tests from the ACATS |
2eac577f | 3164 | testsuite, publicly available at |
bebd5f99 | 3165 | @uref{http://www.ada-auth.org/acats.html}. |
d0a74d7e | 3166 | |
2eac577f | 3167 | These tests are integrated in the GCC testsuite in the |
d4f3924a | 3168 | @file{ada/acats} directory, and |
d0a74d7e | 3169 | enabled automatically when running @code{make check}, assuming |
8a36672b | 3170 | the Ada language has been enabled when configuring GCC@. |
d0a74d7e | 3171 | |
2eac577f | 3172 | You can also run the Ada testsuite independently, using |
d0a74d7e | 3173 | @code{make check-ada}, or run a subset of the tests by specifying which |
8a36672b | 3174 | chapter to run, e.g.: |
d0a74d7e AC |
3175 | |
3176 | @smallexample | |
3177 | $ make check-ada CHAPTERS="c3 c9" | |
3178 | @end smallexample | |
3179 | ||
3180 | The tests are organized by directory, each directory corresponding to | |
17a7cb4e | 3181 | a chapter of the Ada Reference Manual. So for example, @file{c9} corresponds |
d0a74d7e AC |
3182 | to chapter 9, which deals with tasking features of the language. |
3183 | ||
78466c0e JM |
3184 | The tests are run using two @command{sh} scripts: @file{run_acats} and |
3185 | @file{run_all.sh}. To run the tests using a simulator or a cross | |
3186 | target, see the small | |
3187 | customization section at the top of @file{run_all.sh}. | |
d0a74d7e AC |
3188 | |
3189 | These tests are run using the build tree: they can be run without doing | |
3190 | a @code{make install}. | |
3191 | ||
0a553c7e | 3192 | @node C Tests |
500cdcb0 | 3193 | @section C Language Testsuites |
0a553c7e | 3194 | |
2eac577f | 3195 | GCC contains the following C language testsuites, in the |
0a553c7e JM |
3196 | @file{gcc/testsuite} directory: |
3197 | ||
3198 | @table @file | |
4b2ece8f | 3199 | @item gcc.dg |
daf2f129 | 3200 | This contains tests of particular features of the C compiler, using the |
4b2ece8f NN |
3201 | more modern @samp{dg} harness. Correctness tests for various compiler |
3202 | features should go here if possible. | |
3203 | ||
daf2f129 JM |
3204 | Magic comments determine whether the file |
3205 | is preprocessed, compiled, linked or run. In these tests, error and warning | |
3206 | message texts are compared against expected texts or regular expressions | |
4b2ece8f NN |
3207 | given in comments. These tests are run with the options @samp{-ansi -pedantic} |
3208 | unless other options are given in the test. Except as noted below they | |
3209 | are not run with multiple optimization options. | |
6ccfe27c JJ |
3210 | @item gcc.dg/compat |
3211 | This subdirectory contains tests for binary compatibility using | |
17a7cb4e | 3212 | @file{lib/compat.exp}, which in turn uses the language-independent support |
6ccfe27c | 3213 | (@pxref{compat Testing, , Support for testing binary compatibility}). |
4b2ece8f NN |
3214 | @item gcc.dg/cpp |
3215 | This subdirectory contains tests of the preprocessor. | |
3216 | @item gcc.dg/debug | |
3217 | This subdirectory contains tests for debug formats. Tests in this | |
3218 | subdirectory are run for each debug format that the compiler supports. | |
3219 | @item gcc.dg/format | |
3220 | This subdirectory contains tests of the @option{-Wformat} format | |
3221 | checking. Tests in this directory are run with and without | |
3222 | @option{-DWIDE}. | |
3223 | @item gcc.dg/noncompile | |
3224 | This subdirectory contains tests of code that should not compile and | |
3225 | does not need any special compilation options. They are run with | |
3226 | multiple optimization options, since sometimes invalid code crashes | |
3227 | the compiler with optimization. | |
3228 | @item gcc.dg/special | |
3229 | FIXME: describe this. | |
3230 | ||
3231 | @item gcc.c-torture | |
c0478a66 | 3232 | This contains particular code fragments which have historically broken easily. |
4b2ece8f NN |
3233 | These tests are run with multiple optimization options, so tests for features |
3234 | which only break at some optimization levels belong here. This also contains | |
daf2f129 | 3235 | tests to check that certain optimizations occur. It might be worthwhile to |
4b2ece8f NN |
3236 | separate the correctness tests cleanly from the code quality tests, but |
3237 | it hasn't been done yet. | |
3238 | ||
0a553c7e JM |
3239 | @item gcc.c-torture/compat |
3240 | FIXME: describe this. | |
3241 | ||
3242 | This directory should probably not be used for new tests. | |
3243 | @item gcc.c-torture/compile | |
2eac577f | 3244 | This testsuite contains test cases that should compile, but do not |
0a553c7e JM |
3245 | need to link or run. These test cases are compiled with several |
3246 | different combinations of optimization options. All warnings are | |
3247 | disabled for these test cases, so this directory is not suitable if | |
3248 | you wish to test for the presence or absence of compiler warnings. | |
3249 | While special options can be set, and tests disabled on specific | |
3250 | platforms, by the use of @file{.x} files, mostly these test cases | |
3251 | should not contain platform dependencies. FIXME: discuss how defines | |
6c6b519a | 3252 | such as @code{STACK_SIZE} are used. |
0a553c7e | 3253 | @item gcc.c-torture/execute |
2eac577f | 3254 | This testsuite contains test cases that should compile, link and run; |
0a553c7e | 3255 | otherwise the same comments as for @file{gcc.c-torture/compile} apply. |
4b2ece8f NN |
3256 | @item gcc.c-torture/execute/ieee |
3257 | This contains tests which are specific to IEEE floating point. | |
0a553c7e JM |
3258 | @item gcc.c-torture/unsorted |
3259 | FIXME: describe this. | |
3260 | ||
3261 | This directory should probably not be used for new tests. | |
17a7cb4e | 3262 | @item gcc.misc-tests |
138d4703 JJ |
3263 | This directory contains C tests that require special handling. Some |
3264 | of these tests have individual expect files, and others share | |
3265 | special-purpose expect files: | |
3266 | ||
3267 | @table @file | |
3268 | @item @code{bprob*.c} | |
17a7cb4e RO |
3269 | Test @option{-fbranch-probabilities} using |
3270 | @file{gcc.misc-tests/bprob.exp}, which | |
138d4703 JJ |
3271 | in turn uses the generic, language-independent framework |
3272 | (@pxref{profopt Testing, , Support for testing profile-directed | |
3273 | optimizations}). | |
3274 | ||
138d4703 JJ |
3275 | @item @code{gcov*.c} |
3276 | Test @command{gcov} output using @file{gcov.exp}, which in turn uses the | |
3277 | language-independent support (@pxref{gcov Testing, , Support for testing gcov}). | |
3278 | ||
3279 | @item @code{i386-pf-*.c} | |
3280 | Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. | |
3281 | @end table | |
3282 | ||
17a7cb4e RO |
3283 | @item gcc.test-framework |
3284 | @table @file | |
3285 | @item @code{dg-*.c} | |
3286 | Test the testsuite itself using @file{gcc.test-framework/test-framework.exp}. | |
3287 | @end table | |
3288 | ||
0a553c7e JM |
3289 | @end table |
3290 | ||
3291 | FIXME: merge in @file{testsuite/README.gcc} and discuss the format of | |
3292 | test cases and magic comments more. | |
f702e700 | 3293 | |
d7f09764 | 3294 | @node LTO Testing |
500cdcb0 | 3295 | @section Support for testing link-time optimizations |
d7f09764 DN |
3296 | |
3297 | Tests for link-time optimizations usually require multiple source files | |
3298 | that are compiled separately, perhaps with different sets of options. | |
3299 | There are several special-purpose test directives used for these tests. | |
3300 | ||
3301 | @table @code | |
3302 | @item @{ dg-lto-do @var{do-what-keyword} @} | |
3303 | @var{do-what-keyword} specifies how the test is compiled and whether | |
3304 | it is executed. It is one of: | |
3305 | ||
3306 | @table @code | |
3307 | @item assemble | |
3308 | Compile with @option{-c} to produce a relocatable object file. | |
3309 | @item link | |
3310 | Compile, assemble, and link to produce an executable file. | |
3311 | @item run | |
3312 | Produce and run an executable file, which is expected to return | |
3313 | an exit code of 0. | |
3314 | @end table | |
3315 | ||
3316 | The default is @code{assemble}. That can be overridden for a set of | |
3317 | tests by redefining @code{dg-do-what-default} within the @code{.exp} | |
3318 | file for those tests. | |
3319 | ||
3320 | Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional | |
3321 | @samp{target} or @samp{xfail} list. Use @code{dg-skip-if}, | |
3322 | @code{dg-xfail-if}, or @code{dg-xfail-run-if}. | |
3323 | ||
3324 | @item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@} | |
3325 | This directive provides a list of one or more sets of compiler options | |
3326 | to override @var{LTO_OPTIONS}. Each test will be compiled and run with | |
3327 | each of these sets of options. | |
d4f3924a | 3328 | |
cf3e1041 | 3329 | @item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@} |
d4f3924a JJ |
3330 | This directive adds @var{options} to the linker options used. |
3331 | ||
86de8875 | 3332 | @item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@} |
d4f3924a | 3333 | This directive removes @var{options} from the set of linker options used. |
d7f09764 DN |
3334 | @end table |
3335 | ||
138d4703 | 3336 | @node gcov Testing |
500cdcb0 | 3337 | @section Support for testing @command{gcov} |
138d4703 JJ |
3338 | |
3339 | Language-independent support for testing @command{gcov}, and for checking | |
3340 | that branch profiling produces expected values, is provided by the | |
17a7cb4e RO |
3341 | expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures |
3342 | in @file{lib/gcc-dg.exp} to compile and run the test program. A typical | |
c75095b2 | 3343 | @command{gcov} test contains the following DejaGnu commands within comments: |
138d4703 JJ |
3344 | |
3345 | @smallexample | |
bb7c147f | 3346 | @{ dg-options "--coverage" @} |
138d4703 JJ |
3347 | @{ dg-do run @{ target native @} @} |
3348 | @{ dg-final @{ run-gcov sourcefile @} @} | |
3349 | @end smallexample | |
3350 | ||
3351 | Checks of @command{gcov} output can include line counts, branch percentages, | |
3352 | and call return percentages. All of these checks are requested via | |
3353 | commands that appear in comments in the test's source file. | |
3354 | Commands to check line counts are processed by default. | |
3355 | Commands to check branch percentages and call return percentages are | |
7760d7f9 JJ |
3356 | processed if the @command{run-gcov} command has arguments @code{branches} |
3357 | or @code{calls}, respectively. For example, the following specifies | |
4ec7afd7 | 3358 | checking both, as well as passing @option{-b} to @command{gcov}: |
7760d7f9 JJ |
3359 | |
3360 | @smallexample | |
3361 | @{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @} | |
3362 | @end smallexample | |
138d4703 JJ |
3363 | |
3364 | A line count command appears within a comment on the source line | |
3365 | that is expected to get the specified count and has the form | |
3366 | @code{count(@var{cnt})}. A test should only check line counts for | |
3367 | lines that will get the same count for any architecture. | |
3368 | ||
3369 | Commands to check branch percentages (@code{branch}) and call | |
3370 | return percentages (@code{returns}) are very similar to each other. | |
3371 | A beginning command appears on or before the first of a range of | |
3372 | lines that will report the percentage, and the ending command | |
3373 | follows that range of lines. The beginning command can include a | |
3374 | list of percentages, all of which are expected to be found within | |
3375 | the range. A range is terminated by the next command of the same | |
3376 | kind. A command @code{branch(end)} or @code{returns(end)} marks | |
3377 | the end of a range without starting a new one. For example: | |
3378 | ||
3379 | @smallexample | |
12bcfaa1 JM |
3380 | if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */ |
3381 | /* @r{branch(end)} */ | |
138d4703 JJ |
3382 | foo (i, j); |
3383 | @end smallexample | |
3384 | ||
3385 | For a call return percentage, the value specified is the | |
3386 | percentage of calls reported to return. For a branch percentage, | |
3387 | the value is either the expected percentage or 100 minus that | |
3388 | value, since the direction of a branch can differ depending on the | |
3389 | target or the optimization level. | |
3390 | ||
3391 | Not all branches and calls need to be checked. A test should not | |
3392 | check for branches that might be optimized away or replaced with | |
3393 | predicated instructions. Don't check for calls inserted by the | |
3394 | compiler or ones that might be inlined or optimized away. | |
3395 | ||
3396 | A single test can check for combinations of line counts, branch | |
3397 | percentages, and call return percentages. The command to check a | |
3398 | line count must appear on the line that will report that count, but | |
3399 | commands to check branch percentages and call return percentages can | |
3400 | bracket the lines that report them. | |
3401 | ||
3402 | @node profopt Testing | |
500cdcb0 | 3403 | @section Support for testing profile-directed optimizations |
138d4703 JJ |
3404 | |
3405 | The file @file{profopt.exp} provides language-independent support for | |
3406 | checking correct execution of a test built with profile-directed | |
3407 | optimization. This testing requires that a test program be built and | |
3408 | executed twice. The first time it is compiled to generate profile | |
3409 | data, and the second time it is compiled to use the data that was | |
3410 | generated during the first execution. The second execution is to | |
3411 | verify that the test produces the expected results. | |
3412 | ||
3413 | To check that the optimization actually generated better code, a | |
3414 | test can be built and run a third time with normal optimizations to | |
3415 | verify that the performance is better with the profile-directed | |
3416 | optimizations. @file{profopt.exp} has the beginnings of this kind | |
3417 | of support. | |
3418 | ||
3419 | @file{profopt.exp} provides generic support for profile-directed | |
3420 | optimizations. Each set of tests that uses it provides information | |
3421 | about a specific optimization: | |
3422 | ||
3423 | @table @code | |
3424 | @item tool | |
2dd76960 | 3425 | tool being tested, e.g., @command{gcc} |
138d4703 JJ |
3426 | |
3427 | @item profile_option | |
3428 | options used to generate profile data | |
3429 | ||
3430 | @item feedback_option | |
3431 | options used to optimize using that profile data | |
3432 | ||
3433 | @item prof_ext | |
3434 | suffix of profile data files | |
3435 | ||
3436 | @item PROFOPT_OPTIONS | |
3437 | list of options with which to run each test, similar to the lists for | |
3438 | torture tests | |
d4f3924a JJ |
3439 | |
3440 | @item @{ dg-final-generate @{ @var{local-directive} @} @} | |
3441 | This directive is similar to @code{dg-final}, but the | |
3442 | @var{local-directive} is run after the generation of profile data. | |
3443 | ||
3444 | @item @{ dg-final-use @{ @var{local-directive} @} @} | |
3445 | The @var{local-directive} is run after the profile data have been | |
3446 | used. | |
138d4703 | 3447 | @end table |
46b2356d JJ |
3448 | |
3449 | @node compat Testing | |
500cdcb0 | 3450 | @section Support for testing binary compatibility |
46b2356d JJ |
3451 | |
3452 | The file @file{compat.exp} provides language-independent support for | |
2eac577f JM |
3453 | binary compatibility testing. It supports testing interoperability of |
3454 | two compilers that follow the same ABI, or of multiple sets of | |
3455 | compiler options that should not affect binary compatibility. It is | |
3456 | intended to be used for testsuites that complement ABI testsuites. | |
46b2356d JJ |
3457 | |
3458 | A test supported by this framework has three parts, each in a | |
3459 | separate source file: a main program and two pieces that interact | |
3460 | with each other to split up the functionality being tested. | |
3461 | ||
3462 | @table @file | |
3463 | @item @var{testname}_main.@var{suffix} | |
3464 | Contains the main program, which calls a function in file | |
3465 | @file{@var{testname}_x.@var{suffix}}. | |
3466 | ||
3467 | @item @var{testname}_x.@var{suffix} | |
3468 | Contains at least one call to a function in | |
3469 | @file{@var{testname}_y.@var{suffix}}. | |
3470 | ||
3471 | @item @var{testname}_y.@var{suffix} | |
3472 | Shares data with, or gets arguments from, | |
3473 | @file{@var{testname}_x.@var{suffix}}. | |
3474 | @end table | |
3475 | ||
3476 | Within each test, the main program and one functional piece are | |
3477 | compiled by the GCC under test. The other piece can be compiled by | |
3478 | an alternate compiler. If no alternate compiler is specified, | |
3479 | then all three source files are all compiled by the GCC under test. | |
c75095b2 JJ |
3480 | You can specify pairs of sets of compiler options. The first element |
3481 | of such a pair specifies options used with the GCC under test, and the | |
3482 | second element of the pair specifies options used with the alternate | |
3483 | compiler. Each test is compiled with each pair of options. | |
46b2356d JJ |
3484 | |
3485 | @file{compat.exp} defines default pairs of compiler options. | |
3486 | These can be overridden by defining the environment variable | |
3487 | @env{COMPAT_OPTIONS} as: | |
3488 | ||
3489 | @smallexample | |
3490 | COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] | |
923158be | 3491 | @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]" |
46b2356d JJ |
3492 | @end smallexample |
3493 | ||
3494 | where @var{tsti} and @var{alti} are lists of options, with @var{tsti} | |
3495 | used by the compiler under test and @var{alti} used by the alternate | |
3496 | compiler. For example, with | |
3497 | @code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, | |
4ec7afd7 KH |
3498 | the test is first built with @option{-g -O0} by the compiler under |
3499 | test and with @option{-O3} by the alternate compiler. The test is | |
3500 | built a second time using @option{-fpic} by the compiler under test | |
3501 | and @option{-fPIC -O2} by the alternate compiler. | |
46b2356d JJ |
3502 | |
3503 | An alternate compiler is specified by defining an environment | |
c75095b2 JJ |
3504 | variable to be the full pathname of an installed compiler; for C |
3505 | define @env{ALT_CC_UNDER_TEST}, and for C++ define | |
3506 | @env{ALT_CXX_UNDER_TEST}. These will be written to the | |
3507 | @file{site.exp} file used by DejaGnu. The default is to build each | |
46b2356d JJ |
3508 | test with the compiler under test using the first of each pair of |
3509 | compiler options from @env{COMPAT_OPTIONS}. When | |
c75095b2 | 3510 | @env{ALT_CC_UNDER_TEST} or |
46b2356d JJ |
3511 | @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using |
3512 | the compiler under test but with combinations of the options from | |
3513 | @env{COMPAT_OPTIONS}. | |
3514 | ||
3515 | To run only the C++ compatibility suite using the compiler under test | |
3516 | and another version of GCC using specific compiler options, do the | |
3517 | following from @file{@var{objdir}/gcc}: | |
3518 | ||
3519 | @smallexample | |
3520 | rm site.exp | |
3521 | make -k \ | |
3522 | ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ | |
17a7cb4e | 3523 | COMPAT_OPTIONS="@var{lists as shown above}" \ |
46b2356d JJ |
3524 | check-c++ \ |
3525 | RUNTESTFLAGS="compat.exp" | |
3526 | @end smallexample | |
3527 | ||
3528 | A test that fails when the source files are compiled with different | |
3529 | compilers, but passes when the files are compiled with the same | |
3530 | compiler, demonstrates incompatibility of the generated code or | |
3531 | runtime support. A test that fails for the alternate compiler but | |
3532 | passes for the compiler under test probably tests for a bug that was | |
3533 | fixed in the compiler under test but is present in the alternate | |
3534 | compiler. | |
c75095b2 JJ |
3535 | |
3536 | The binary compatibility tests support a small number of test framework | |
3537 | commands that appear within comments in a test file. | |
3538 | ||
3539 | @table @code | |
3540 | @item dg-require-* | |
3541 | These commands can be used in @file{@var{testname}_main.@var{suffix}} | |
3542 | to skip the test if specific support is not available on the target. | |
3543 | ||
3544 | @item dg-options | |
3545 | The specified options are used for compiling this particular source | |
3546 | file, appended to the options from @env{COMPAT_OPTIONS}. When this | |
3547 | command appears in @file{@var{testname}_main.@var{suffix}} the options | |
3548 | are also used to link the test program. | |
3549 | ||
3550 | @item dg-xfail-if | |
3551 | This command can be used in a secondary source file to specify that | |
3552 | compilation is expected to fail for particular options on particular | |
3553 | targets. | |
3554 | @end table | |
91a5b394 JJ |
3555 | |
3556 | @node Torture Tests | |
500cdcb0 | 3557 | @section Support for torture testing using multiple options |
91a5b394 JJ |
3558 | |
3559 | Throughout the compiler testsuite there are several directories whose | |
3560 | tests are run multiple times, each with a different set of options. | |
3561 | These are known as torture tests. | |
17a7cb4e | 3562 | @file{lib/torture-options.exp} defines procedures to |
91a5b394 JJ |
3563 | set up these lists: |
3564 | ||
3565 | @table @code | |
3566 | @item torture-init | |
3567 | Initialize use of torture lists. | |
3568 | @item set-torture-options | |
3569 | Set lists of torture options to use for tests with and without loops. | |
3570 | Optionally combine a set of torture options with a set of other | |
3571 | options, as is done with Objective-C runtime options. | |
3572 | @item torture-finish | |
3573 | Finalize use of torture lists. | |
3574 | @end table | |
3575 | ||
3576 | The @file{.exp} file for a set of tests that use torture options must | |
a640c13b | 3577 | include calls to these three procedures if: |
91a5b394 | 3578 | |
6f03c42c | 3579 | @itemize @bullet |
91a5b394 JJ |
3580 | @item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}. |
3581 | ||
3582 | @item It calls @var{$@{tool@}}@code{-torture} or | |
3583 | @var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c}, | |
3584 | @code{fortran}, or @code{objc}. | |
3585 | ||
3586 | @item It calls @code{dg-pch}. | |
3587 | @end itemize | |
3588 | ||
3589 | It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest} | |
3590 | to call the torture procedures if the tests should use the list in | |
3591 | @var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}. | |
3592 | ||
3593 | Most uses of torture options can override the default lists by defining | |
52ebab2b JJ |
3594 | @var{TORTURE_OPTIONS} or add to the default list by defining |
3595 | @var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc} | |
3596 | file or add them to the @file{site.exp} file; for example | |
3597 | ||
3598 | @smallexample | |
07e5b056 JJ |
3599 | set ADDITIONAL_TORTURE_OPTIONS [list \ |
3600 | @{ -O2 -ftree-loop-linear @} \ | |
52ebab2b JJ |
3601 | @{ -O2 -fpeel-loops @} ] |
3602 | @end smallexample | |
71103b61 DM |
3603 | |
3604 | @node GIMPLE Tests | |
3605 | @section Support for testing GIMPLE passes | |
3606 | ||
3607 | As of gcc 7, C functions can be tagged with @code{__GIMPLE} to indicate | |
3608 | that the function body will be GIMPLE, rather than C. The compiler requires | |
3609 | the option @option{-fgimple} to enable this functionality. For example: | |
3610 | ||
3611 | @smallexample | |
3612 | /* @{ dg-do compile @} */ | |
3613 | /* @{ dg-options "-O -fgimple" @} */ | |
3614 | ||
3615 | void __GIMPLE (startwith ("dse2")) foo () | |
3616 | @{ | |
3617 | int a; | |
3618 | ||
3619 | bb_2: | |
3620 | if (a > 4) | |
3621 | goto bb_3; | |
3622 | else | |
3623 | goto bb_4; | |
3624 | ||
3625 | bb_3: | |
3626 | a_2 = 10; | |
3627 | goto bb_5; | |
3628 | ||
3629 | bb_4: | |
3630 | a_3 = 20; | |
3631 | ||
3632 | bb_5: | |
3633 | a_1 = __PHI (bb_3: a_2, bb_4: a_3); | |
3634 | a_4 = a_1 + 4; | |
3635 | ||
3636 | return; | |
3637 | @} | |
3638 | @end smallexample | |
3639 | ||
3640 | The @code{startwith} argument indicates at which pass to begin. | |
3641 | ||
630ba2fd | 3642 | Use the dump modifier @code{-gimple} (e.g.@: @option{-fdump-tree-all-gimple}) |
71103b61 DM |
3643 | to make tree dumps more closely follow the format accepted by the GIMPLE |
3644 | parser. | |
3645 | ||
3646 | Example DejaGnu tests of GIMPLE can be seen in the source tree at | |
3647 | @file{gcc/testsuite/gcc.dg/gimplefe-*.c}. | |
3648 | ||
3649 | The @code{__GIMPLE} parser is integrated with the C tokenizer and | |
3650 | preprocessor, so it should be possible to use macros to build out | |
3651 | test coverage. | |
3652 | ||
3653 | @node RTL Tests | |
3654 | @section Support for testing RTL passes | |
3655 | ||
3656 | As of gcc 7, C functions can be tagged with @code{__RTL} to indicate that the | |
3657 | function body will be RTL, rather than C. For example: | |
3658 | ||
3659 | @smallexample | |
3660 | double __RTL (startwith ("ira")) test (struct foo *f, const struct bar *b) | |
3661 | @{ | |
3662 | (function "test" | |
3663 | [...snip; various directives go in here...] | |
3664 | ) ;; function "test" | |
3665 | @} | |
3666 | @end smallexample | |
3667 | ||
3668 | The @code{startwith} argument indicates at which pass to begin. | |
3669 | ||
3670 | The parser expects the RTL body to be in the format emitted by this | |
3671 | dumping function: | |
3672 | ||
3673 | @smallexample | |
3674 | DEBUG_FUNCTION void | |
3675 | print_rtx_function (FILE *outfile, function *fn, bool compact); | |
3676 | @end smallexample | |
3677 | ||
3678 | when "compact" is true. So you can capture RTL in the correct format | |
3679 | from the debugger using: | |
3680 | ||
3681 | @smallexample | |
3682 | (gdb) print_rtx_function (stderr, cfun, true); | |
3683 | @end smallexample | |
3684 | ||
3685 | and copy and paste the output into the body of the C function. | |
3686 | ||
3687 | Example DejaGnu tests of RTL can be seen in the source tree under | |
3688 | @file{gcc/testsuite/gcc.dg/rtl}. | |
3689 | ||
3690 | The @code{__RTL} parser is not integrated with the C tokenizer or | |
3691 | preprocessor, and works simply by reading the relevant lines within | |
3692 | the braces. In particular, the RTL body must be on separate lines from | |
3693 | the enclosing braces, and the preprocessor is not usable within it. |