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