| 1 |
@c Copyright (C) 2003-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 Options |
| 6 |
@chapter Option specification files |
| 7 |
@cindex option specification files |
| 8 |
@cindex @samp{optc-gen.awk} |
| 9 |
|
| 10 |
Most GCC command-line options are described by special option |
| 11 |
definition files, the names of which conventionally end in |
| 12 |
@code{.opt}. This chapter describes the format of these files. |
| 13 |
|
| 14 |
@menu |
| 15 |
* Option file format:: The general layout of the files |
| 16 |
* Option properties:: Supported option properties |
| 17 |
@end menu |
| 18 |
|
| 19 |
@node Option file format |
| 20 |
@section Option file format |
| 21 |
|
| 22 |
Option files are a simple list of records in which each field occupies |
| 23 |
its own line and in which the records themselves are separated by |
| 24 |
blank lines. Comments may appear on their own line anywhere within |
| 25 |
the file and are preceded by semicolons. Whitespace is allowed before |
| 26 |
the semicolon. |
| 27 |
|
| 28 |
The files can contain the following types of record: |
| 29 |
|
| 30 |
@itemize @bullet |
| 31 |
@item |
| 32 |
A language definition record. These records have two fields: the |
| 33 |
string @samp{Language} and the name of the language. Once a language |
| 34 |
has been declared in this way, it can be used as an option property. |
| 35 |
@xref{Option properties}. |
| 36 |
|
| 37 |
@item |
| 38 |
A target specific save record to save additional information. These |
| 39 |
records have two fields: the string @samp{TargetSave}, and a |
| 40 |
declaration type to go in the @code{cl_target_option} structure. |
| 41 |
|
| 42 |
@item |
| 43 |
A variable record to define a variable used to store option |
| 44 |
information. These records have two fields: the string |
| 45 |
@samp{Variable}, and a declaration of the type and name of the |
| 46 |
variable, optionally with an initializer (but without any trailing |
| 47 |
@samp{;}). These records may be used for variables used for many |
| 48 |
options where declaring the initializer in a single option definition |
| 49 |
record, or duplicating it in many records, would be inappropriate, or |
| 50 |
for variables set in option handlers rather than referenced by |
| 51 |
@code{Var} properties. |
| 52 |
|
| 53 |
@item |
| 54 |
A variable record to define a variable used to store option |
| 55 |
information. These records have two fields: the string |
| 56 |
@samp{TargetVariable}, and a declaration of the type and name of the |
| 57 |
variable, optionally with an initializer (but without any trailing |
| 58 |
@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable} |
| 59 |
and @samp{TargetSave} records in that the variable is defined in the |
| 60 |
@code{gcc_options} structure, but these variables are also stored in |
| 61 |
the @code{cl_target_option} structure. The variables are saved in the |
| 62 |
target save code and restored in the target restore code. |
| 63 |
|
| 64 |
@item |
| 65 |
A variable record to record any additional files that the |
| 66 |
@file{options.h} file should include. This is useful to provide |
| 67 |
enumeration or structure definitions needed for target variables. |
| 68 |
These records have two fields: the string @samp{HeaderInclude} and the |
| 69 |
name of the include file. |
| 70 |
|
| 71 |
@item |
| 72 |
A variable record to record any additional files that the |
| 73 |
@file{options.cc} or @file{options-save.cc} file should include. This |
| 74 |
is useful to provide |
| 75 |
inline functions needed for target variables and/or @code{#ifdef} |
| 76 |
sequences to properly set up the initialization. These records have |
| 77 |
two fields: the string @samp{SourceInclude} and the name of the |
| 78 |
include file. |
| 79 |
|
| 80 |
@item |
| 81 |
An enumeration record to define a set of strings that may be used as |
| 82 |
arguments to an option or options. These records have three fields: |
| 83 |
the string @samp{Enum}, a space-separated list of properties and help |
| 84 |
text used to describe the set of strings in @option{--help} output. |
| 85 |
Properties use the same format as option properties; the following are |
| 86 |
valid: |
| 87 |
@table @code |
| 88 |
@item Name(@var{name}) |
| 89 |
This property is required; @var{name} must be a name (suitable for use |
| 90 |
in C identifiers) used to identify the set of strings in @code{Enum} |
| 91 |
option properties. |
| 92 |
|
| 93 |
@item Type(@var{type}) |
| 94 |
This property is required; @var{type} is the C type for variables set |
| 95 |
by options using this enumeration together with @code{Var}. |
| 96 |
|
| 97 |
@item UnknownError(@var{message}) |
| 98 |
The message @var{message} will be used as an error message if the |
| 99 |
argument is invalid; for enumerations without @code{UnknownError}, a |
| 100 |
generic error message is used. @var{message} should contain a single |
| 101 |
@samp{%qs} format, which will be used to format the invalid argument. |
| 102 |
@end table |
| 103 |
|
| 104 |
@item |
| 105 |
An enumeration value record to define one of the strings in a set |
| 106 |
given in an @samp{Enum} record. These records have two fields: the |
| 107 |
string @samp{EnumValue} and a space-separated list of properties. |
| 108 |
Properties use the same format as option properties; the following are |
| 109 |
valid: |
| 110 |
@table @code |
| 111 |
@item Enum(@var{name}) |
| 112 |
This property is required; @var{name} says which @samp{Enum} record |
| 113 |
this @samp{EnumValue} record corresponds to. |
| 114 |
|
| 115 |
@item String(@var{string}) |
| 116 |
This property is required; @var{string} is the string option argument |
| 117 |
being described by this record. |
| 118 |
|
| 119 |
@item Value(@var{value}) |
| 120 |
This property is required; it says what value (representable as |
| 121 |
@code{int}) should be used for the given string. |
| 122 |
|
| 123 |
@item Canonical |
| 124 |
This property is optional. If present, it says the present string is |
| 125 |
the canonical one among all those with the given value. Other strings |
| 126 |
yielding that value will be mapped to this one so specs do not need to |
| 127 |
handle them. |
| 128 |
|
| 129 |
@item DriverOnly |
| 130 |
This property is optional. If present, the present string will only |
| 131 |
be accepted by the driver. This is used for cases such as |
| 132 |
@option{-march=native} that are processed by the driver so that |
| 133 |
@samp{gcc -v} shows how the options chosen depended on the system on |
| 134 |
which the compiler was run. |
| 135 |
|
| 136 |
@item Set(@var{number}) |
| 137 |
This property is optional, required for enumerations used in |
| 138 |
@code{EnumSet} options. @var{number} should be decimal number between |
| 139 |
1 and 64 inclusive and divides the enumeration into a set of |
| 140 |
sets of mutually exclusive arguments. Arguments with the same |
| 141 |
@var{number} can't be specified together in the same option, but |
| 142 |
arguments with different @var{number} can. @var{value} needs to be |
| 143 |
chosen such that a mask of all @var{value} values from the same set |
| 144 |
@var{number} bitwise ored doesn't overlap with masks for other sets. |
| 145 |
When @code{-foption=arg_from_set1,arg_from_set4} and |
| 146 |
@code{-fno-option=arg_from_set3} are used, the effect is that previous |
| 147 |
value of the @code{Var} will get bits from set 1 and 4 masks cleared, |
| 148 |
ored @code{Value} of @code{arg_from_set1} and @code{arg_from_set4} |
| 149 |
and then will get bits from set 3 mask cleared. |
| 150 |
@end table |
| 151 |
|
| 152 |
@item |
| 153 |
An option definition record. These records have the following fields: |
| 154 |
@enumerate |
| 155 |
@item |
| 156 |
the name of the option, with the leading ``-'' removed |
| 157 |
@item |
| 158 |
a space-separated list of option properties (@pxref{Option properties}) |
| 159 |
@item |
| 160 |
the help text to use for @option{--help} (omitted if the second field |
| 161 |
contains the @code{Undocumented} property). |
| 162 |
@end enumerate |
| 163 |
|
| 164 |
By default, all options beginning with ``f'', ``g'', ``W'' or ``m'' are |
| 165 |
implicitly assumed to take a ``no-'' form. This form should not be |
| 166 |
listed separately. If an option beginning with one of these letters |
| 167 |
does not have a ``no-'' form, you can use the @code{RejectNegative} |
| 168 |
property to reject it. |
| 169 |
|
| 170 |
The help text is automatically line-wrapped before being displayed. |
| 171 |
Normally the name of the option is printed on the left-hand side of |
| 172 |
the output and the help text is printed on the right. However, if the |
| 173 |
help text contains a tab character, the text to the left of the tab is |
| 174 |
used instead of the option's name and the text to the right of the |
| 175 |
tab forms the help text. This allows you to elaborate on what type |
| 176 |
of argument the option takes. |
| 177 |
|
| 178 |
There is no support for different help texts for different languages. |
| 179 |
If an option is supported for multiple languages, use a generic |
| 180 |
description that is correct for all of them. |
| 181 |
|
| 182 |
If an option has multiple option definition records (in different |
| 183 |
front ends' @file{*.opt} files, and/or @file{gcc/common.opt}, for |
| 184 |
example), convention is to not duplicate the help text for each of |
| 185 |
them, but instead put a comment like @code{; documented in common.opt} |
| 186 |
in place of the help text for all but one of the multiple option |
| 187 |
definition records. |
| 188 |
|
| 189 |
@item |
| 190 |
A target mask record. These records have one field of the form |
| 191 |
@samp{Mask(@var{x})}. The options-processing script will automatically |
| 192 |
allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for |
| 193 |
each mask name @var{x} and set the macro @code{MASK_@var{x}} to the |
| 194 |
appropriate bitmask. It will also declare a @code{TARGET_@var{x}} |
| 195 |
macro that has the value 1 when bit @code{MASK_@var{x}} is set and |
| 196 |
0 otherwise. |
| 197 |
|
| 198 |
They are primarily intended to declare target masks that are not |
| 199 |
associated with user options, either because these masks represent |
| 200 |
internal switches or because the options are not available on all |
| 201 |
configurations and yet the masks always need to be defined. |
| 202 |
@end itemize |
| 203 |
|
| 204 |
@node Option properties |
| 205 |
@section Option properties |
| 206 |
|
| 207 |
The second field of an option record can specify any of the following |
| 208 |
properties. When an option takes an argument, it is enclosed in parentheses |
| 209 |
following the option property name. The parser that handles option files |
| 210 |
is quite simplistic, and will be tricked by any nested parentheses within |
| 211 |
the argument text itself; in this case, the entire option argument can |
| 212 |
be wrapped in curly braces within the parentheses to demarcate it, e.g.: |
| 213 |
|
| 214 |
@smallexample |
| 215 |
Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@}) |
| 216 |
@end smallexample |
| 217 |
|
| 218 |
@table @code |
| 219 |
@item Common |
| 220 |
The option is available for all languages and targets. |
| 221 |
|
| 222 |
@item Target |
| 223 |
The option is available for all languages but is target-specific. |
| 224 |
|
| 225 |
@item Driver |
| 226 |
The option is handled by the compiler driver using code not shared |
| 227 |
with the compilers proper (@file{cc1} etc.). |
| 228 |
|
| 229 |
@item @var{language} |
| 230 |
The option is available when compiling for the given language. |
| 231 |
|
| 232 |
It is possible to specify several different languages for the same |
| 233 |
option. Each @var{language} must have been declared by an earlier |
| 234 |
@code{Language} record. @xref{Option file format}. |
| 235 |
|
| 236 |
@item RejectDriver |
| 237 |
The option is only handled by the compilers proper (@file{cc1} etc.)@: |
| 238 |
and should not be accepted by the driver. |
| 239 |
|
| 240 |
@item RejectNegative |
| 241 |
The option does not have a ``no-'' form. All options beginning with |
| 242 |
``f'', ``g'', ``W'' or ``m'' are assumed to have a ``no-'' form unless |
| 243 |
this property is used. |
| 244 |
|
| 245 |
@item Negative(@var{othername}) |
| 246 |
The option will turn off another option @var{othername}, which is |
| 247 |
the option name with the leading ``-'' removed. This chain action will |
| 248 |
propagate through the @code{Negative} property of the option to be |
| 249 |
turned off. The driver will prune options, removing those that are |
| 250 |
turned off by some later option. This pruning is not done for options |
| 251 |
with @code{Joined} or @code{JoinedOrMissing} properties, unless the |
| 252 |
options have both the @code{RejectNegative} property and the @code{Negative} |
| 253 |
property mentions itself. |
| 254 |
|
| 255 |
As a consequence, if you have a group of mutually-exclusive |
| 256 |
options, their @code{Negative} properties should form a circular chain. |
| 257 |
For example, if options @option{-@var{a}}, @option{-@var{b}} and |
| 258 |
@option{-@var{c}} are mutually exclusive, their respective @code{Negative} |
| 259 |
properties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})} |
| 260 |
and @samp{Negative(@var{a})}. |
| 261 |
|
| 262 |
@item Joined |
| 263 |
@itemx Separate |
| 264 |
The option takes a mandatory argument. @code{Joined} indicates |
| 265 |
that the option and argument can be included in the same @code{argv} |
| 266 |
entry (as with @code{-mflush-func=@var{name}}, for example). |
| 267 |
@code{Separate} indicates that the option and argument can be |
| 268 |
separate @code{argv} entries (as with @code{-o}). An option is |
| 269 |
allowed to have both of these properties. |
| 270 |
|
| 271 |
@item JoinedOrMissing |
| 272 |
The option takes an optional argument. If the argument is given, |
| 273 |
it will be part of the same @code{argv} entry as the option itself. |
| 274 |
|
| 275 |
This property cannot be used alongside @code{Joined} or @code{Separate}. |
| 276 |
|
| 277 |
@item MissingArgError(@var{message}) |
| 278 |
For an option marked @code{Joined} or @code{Separate}, the message |
| 279 |
@var{message} will be used as an error message if the mandatory |
| 280 |
argument is missing; for options without @code{MissingArgError}, a |
| 281 |
generic error message is used. @var{message} should contain a single |
| 282 |
@samp{%qs} format, which will be used to format the name of the option |
| 283 |
passed. |
| 284 |
|
| 285 |
@item Args(@var{n}) |
| 286 |
For an option marked @code{Separate}, indicate that it takes @var{n} |
| 287 |
arguments. The default is 1. |
| 288 |
|
| 289 |
@item UInteger |
| 290 |
The option's argument is a non-negative integer consisting of either |
| 291 |
decimal or hexadecimal digits interpreted as @code{int}. Hexadecimal |
| 292 |
integers may optionally start with the @code{0x} or @code{0X} prefix. |
| 293 |
The option parser validates and converts the argument before passing |
| 294 |
it to the relevant option handler. @code{UInteger} should also be used |
| 295 |
with options like @code{-falign-loops} where both @code{-falign-loops} |
| 296 |
and @code{-falign-loops}=@var{n} are supported to make sure the saved |
| 297 |
options are given a full integer. Positive values of the argument in |
| 298 |
excess of @code{INT_MAX} wrap around zero. |
| 299 |
|
| 300 |
@item Host_Wide_Int |
| 301 |
The option's argument is a non-negative integer consisting of either |
| 302 |
decimal or hexadecimal digits interpreted as the widest integer type |
| 303 |
on the host. As with an @code{UInteger} argument, hexadecimal integers |
| 304 |
may optionally start with the @code{0x} or @code{0X} prefix. The option |
| 305 |
parser validates and converts the argument before passing it to |
| 306 |
the relevant option handler. @code{Host_Wide_Int} should be used with |
| 307 |
options that need to accept very large values. Positive values of |
| 308 |
the argument in excess of @code{HOST_WIDE_INT_M1U} are assigned |
| 309 |
@code{HOST_WIDE_INT_M1U}. |
| 310 |
|
| 311 |
@item IntegerRange(@var{n}, @var{m}) |
| 312 |
The options's arguments are integers of type @code{int}. The option's |
| 313 |
parser validates that the value of an option integer argument is within |
| 314 |
the closed range [@var{n}, @var{m}]. |
| 315 |
|
| 316 |
@item ByteSize |
| 317 |
A property applicable only to @code{UInteger} or @code{Host_Wide_Int} |
| 318 |
arguments. The option's integer argument is interpreted as if in infinite |
| 319 |
precision using saturation arithmetic in the corresponding type. The argument |
| 320 |
may be followed by a @samp{byte-size} suffix designating a multiple of bytes |
| 321 |
such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively, |
| 322 |
@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and @code{GiB} |
| 323 |
for gigabyte and gigibyte, and so on. @code{ByteSize} should be used for |
| 324 |
with options that take a very large argument representing a size in bytes, |
| 325 |
such as @option{-Wlarger-than=}. |
| 326 |
|
| 327 |
@item ToLower |
| 328 |
The option's argument should be converted to lowercase as part of |
| 329 |
putting it in canonical form, and before comparing with the strings |
| 330 |
indicated by any @code{Enum} property. |
| 331 |
|
| 332 |
@item NoDriverArg |
| 333 |
For an option marked @code{Separate}, the option only takes an |
| 334 |
argument in the compiler proper, not in the driver. This is for |
| 335 |
compatibility with existing options that are used both directly and |
| 336 |
via @option{-Wp,}; new options should not have this property. |
| 337 |
|
| 338 |
@item Var(@var{var}) |
| 339 |
The state of this option should be stored in variable @var{var} |
| 340 |
(actually a macro for @code{global_options.x_@var{var}}). |
| 341 |
The way that the state is stored depends on the type of option: |
| 342 |
|
| 343 |
@itemize @bullet |
| 344 |
@item |
| 345 |
If the option uses the @code{Mask} or @code{InverseMask} properties, |
| 346 |
@var{var} is the integer variable that contains the mask. |
| 347 |
|
| 348 |
@item |
| 349 |
If the option is a normal on/off switch, @var{var} is an integer |
| 350 |
variable that is nonzero when the option is enabled. The options |
| 351 |
parser will set the variable to 1 when the positive form of the |
| 352 |
option is used and 0 when the ``no-'' form is used. |
| 353 |
|
| 354 |
@item |
| 355 |
If the option takes an argument and has the @code{UInteger} property, |
| 356 |
@var{var} is an integer variable that stores the value of the argument. |
| 357 |
|
| 358 |
@item |
| 359 |
If the option takes an argument and has the @code{Enum} property, |
| 360 |
@var{var} is a variable (type given in the @code{Type} property of the |
| 361 |
@samp{Enum} record whose @code{Name} property has the same argument as |
| 362 |
the @code{Enum} property of this option) that stores the value of the |
| 363 |
argument. |
| 364 |
|
| 365 |
@item |
| 366 |
If the option has the @code{Defer} property, @var{var} is a pointer to |
| 367 |
a @code{VEC(cl_deferred_option,heap)} that stores the option for later |
| 368 |
processing. (@var{var} is declared with type @code{void *} and needs |
| 369 |
to be cast to @code{VEC(cl_deferred_option,heap)} before use.) |
| 370 |
|
| 371 |
@item |
| 372 |
Otherwise, if the option takes an argument, @var{var} is a pointer to |
| 373 |
the argument string. The pointer will be null if the argument is optional |
| 374 |
and wasn't given. |
| 375 |
@end itemize |
| 376 |
|
| 377 |
The option-processing script will usually zero-initialize @var{var}. |
| 378 |
You can modify this behavior using @code{Init}. |
| 379 |
|
| 380 |
@item Var(@var{var}, @var{set}) |
| 381 |
The option controls an integer variable @var{var} and is active when |
| 382 |
@var{var} equals @var{set}. The option parser will set @var{var} to |
| 383 |
@var{set} when the positive form of the option is used and @code{!@var{set}} |
| 384 |
when the ``no-'' form is used. |
| 385 |
|
| 386 |
@var{var} is declared in the same way as for the single-argument form |
| 387 |
described above. |
| 388 |
|
| 389 |
@item Init(@var{value}) |
| 390 |
The variable specified by the @code{Var} property should be statically |
| 391 |
initialized to @var{value}. If more than one option using the same |
| 392 |
variable specifies @code{Init}, all must specify the same initializer. |
| 393 |
|
| 394 |
@item WarnRemoved |
| 395 |
The option is removed and every usage of such option will |
| 396 |
result in a warning. We use it option backward compatibility. |
| 397 |
|
| 398 |
@item Mask(@var{name}) |
| 399 |
The option is associated with a bit in the @code{target_flags} |
| 400 |
variable (@pxref{Run-time Target}) and is active when that bit is set. |
| 401 |
You may also specify @code{Var} to select a variable other than |
| 402 |
@code{target_flags}. |
| 403 |
|
| 404 |
The options-processing script will automatically allocate a unique bit |
| 405 |
for the option. If the option is attached to @samp{target_flags}, |
| 406 |
the script will set the macro @code{MASK_@var{name}} to the appropriate |
| 407 |
bitmask. It will also declare a @code{TARGET_@var{name}} macro that has |
| 408 |
the value 1 when the option is active and 0 otherwise. If you use @code{Var} |
| 409 |
to attach the option to a different variable, the bitmask macro with be |
| 410 |
called @code{OPTION_MASK_@var{name}}. |
| 411 |
|
| 412 |
@item InverseMask(@var{othername}) |
| 413 |
@itemx InverseMask(@var{othername}, @var{thisname}) |
| 414 |
The option is the inverse of another option that has the |
| 415 |
@code{Mask(@var{othername})} property. If @var{thisname} is given, |
| 416 |
the options-processing script will declare a @code{TARGET_@var{thisname}} |
| 417 |
macro that is 1 when the option is active and 0 otherwise. |
| 418 |
|
| 419 |
@item Enum(@var{name}) |
| 420 |
The option's argument is a string from the set of strings associated |
| 421 |
with the corresponding @samp{Enum} record. The string is checked and |
| 422 |
converted to the integer specified in the corresponding |
| 423 |
@samp{EnumValue} record before being passed to option handlers. |
| 424 |
|
| 425 |
@item EnumSet |
| 426 |
Must be used together with the @code{Enum(@var{name})} property. |
| 427 |
Corresponding @samp{Enum} record must use @code{Set} properties. |
| 428 |
The option's argument is either a string from the set like for |
| 429 |
@code{Enum(@var{name})}, but with a slightly different behavior that |
| 430 |
the whole @code{Var} isn't overwritten, but only the bits in all the |
| 431 |
enumeration values with the same set bitwise ored together. |
| 432 |
Or option's argument can be a comma separated list of strings where |
| 433 |
each string is from a different @code{Set(@var{number})}. |
| 434 |
|
| 435 |
@item EnumBitSet |
| 436 |
Must be used together with the @code{Enum(@var{name})} property. |
| 437 |
Similar to @samp{EnumSet}, but corresponding @samp{Enum} record must |
| 438 |
not use @code{Set} properties, each @code{EnumValue} should have |
| 439 |
@code{Value} that is a power of 2, each value is treated as its own |
| 440 |
set and its value as the set's mask, so there are no mutually |
| 441 |
exclusive arguments. |
| 442 |
|
| 443 |
@item Defer |
| 444 |
The option should be stored in a vector, specified with @code{Var}, |
| 445 |
for later processing. |
| 446 |
|
| 447 |
@item Alias(@var{opt}) |
| 448 |
@itemx Alias(@var{opt}, @var{arg}) |
| 449 |
@itemx Alias(@var{opt}, @var{posarg}, @var{negarg}) |
| 450 |
The option is an alias for @option{-@var{opt}} (or the negative form |
| 451 |
of that option, depending on @code{NegativeAlias}). In the first form, |
| 452 |
any argument passed to the alias is considered to be passed to |
| 453 |
@option{-@var{opt}}, and @option{-@var{opt}} is considered to be |
| 454 |
negated if the alias is used in negated form. In the second form, the |
| 455 |
alias may not be negated or have an argument, and @var{posarg} is |
| 456 |
considered to be passed as an argument to @option{-@var{opt}}. In the |
| 457 |
third form, the alias may not have an argument, if the alias is used |
| 458 |
in the positive form then @var{posarg} is considered to be passed to |
| 459 |
@option{-@var{opt}}, and if the alias is used in the negative form |
| 460 |
then @var{negarg} is considered to be passed to @option{-@var{opt}}. |
| 461 |
|
| 462 |
Aliases should not specify @code{Var} or @code{Mask} or |
| 463 |
@code{UInteger}. Aliases should normally specify the same languages |
| 464 |
as the target of the alias; the flags on the target will be used to |
| 465 |
determine any diagnostic for use of an option for the wrong language, |
| 466 |
while those on the alias will be used to identify what command-line |
| 467 |
text is the option and what text is any argument to that option. |
| 468 |
|
| 469 |
When an @code{Alias} definition is used for an option, driver specs do |
| 470 |
not need to handle it and no @samp{OPT_} enumeration value is defined |
| 471 |
for it; only the canonical form of the option will be seen in those |
| 472 |
places. |
| 473 |
|
| 474 |
@item NegativeAlias |
| 475 |
For an option marked with @code{Alias(@var{opt})}, the option is |
| 476 |
considered to be an alias for the positive form of @option{-@var{opt}} |
| 477 |
if negated and for the negative form of @option{-@var{opt}} if not |
| 478 |
negated. @code{NegativeAlias} may not be used with the forms of |
| 479 |
@code{Alias} taking more than one argument. |
| 480 |
|
| 481 |
@item Ignore |
| 482 |
This option is ignored apart from printing any warning specified using |
| 483 |
@code{Warn}. The option will not be seen by specs and no @samp{OPT_} |
| 484 |
enumeration value is defined for it. |
| 485 |
|
| 486 |
@item SeparateAlias |
| 487 |
For an option marked with @code{Joined}, @code{Separate} and |
| 488 |
@code{Alias}, the option only acts as an alias when passed a separate |
| 489 |
argument; with a joined argument it acts as a normal option, with an |
| 490 |
@samp{OPT_} enumeration value. This is for compatibility with the |
| 491 |
Java @option{-d} option and should not be used for new options. |
| 492 |
|
| 493 |
@item Warn(@var{message}) |
| 494 |
If this option is used, output the warning @var{message}. |
| 495 |
@var{message} is a format string, either taking a single operand with |
| 496 |
a @samp{%qs} format which is the option name, or not taking any |
| 497 |
operands, which is passed to the @samp{warning} function. If an alias |
| 498 |
is marked @code{Warn}, the target of the alias must not also be marked |
| 499 |
@code{Warn}. |
| 500 |
|
| 501 |
@item Warning |
| 502 |
This is a warning option and should be shown as such in |
| 503 |
@option{--help} output. This flag does not currently affect anything |
| 504 |
other than @option{--help}. |
| 505 |
|
| 506 |
@item Optimization |
| 507 |
This is an optimization option. It should be shown as such in |
| 508 |
@option{--help} output, and any associated variable named using |
| 509 |
@code{Var} should be saved and restored when the optimization level is |
| 510 |
changed with @code{optimize} attributes. |
| 511 |
|
| 512 |
@item PerFunction |
| 513 |
This is an option that can be overridden on a per-function basis. |
| 514 |
@code{Optimization} implies @code{PerFunction}, but options that do not |
| 515 |
affect executable code generation may use this flag instead, so that the |
| 516 |
option is not taken into account in ways that might affect executable |
| 517 |
code generation. |
| 518 |
|
| 519 |
@item Param |
| 520 |
This is an option that is a parameter. |
| 521 |
|
| 522 |
@item Undocumented |
| 523 |
The option is deliberately missing documentation and should not |
| 524 |
be included in the @option{--help} output. |
| 525 |
|
| 526 |
@item Condition(@var{cond}) |
| 527 |
The option should only be accepted if preprocessor condition |
| 528 |
@var{cond} is true. Note that any C declarations associated with the |
| 529 |
option will be present even if @var{cond} is false; @var{cond} simply |
| 530 |
controls whether the option is accepted and whether it is printed in |
| 531 |
the @option{--help} output. |
| 532 |
|
| 533 |
@item Save |
| 534 |
Build the @code{cl_target_option} structure to hold a copy of the |
| 535 |
option, add the functions @code{cl_target_option_save} and |
| 536 |
@code{cl_target_option_restore} to save and restore the options. |
| 537 |
|
| 538 |
@item SetByCombined |
| 539 |
The option may also be set by a combined option such as |
| 540 |
@option{-ffast-math}. This causes the @code{gcc_options} struct to |
| 541 |
have a field @code{frontend_set_@var{name}}, where @code{@var{name}} |
| 542 |
is the name of the field holding the value of this option (without the |
| 543 |
leading @code{x_}). This gives the front end a way to indicate that |
| 544 |
the value has been set explicitly and should not be changed by the |
| 545 |
combined option. For example, some front ends use this to prevent |
| 546 |
@option{-ffast-math} and @option{-fno-fast-math} from changing the |
| 547 |
value of @option{-fmath-errno} for languages that do not use |
| 548 |
@code{errno}. |
| 549 |
|
| 550 |
@item EnabledBy(@var{opt}) |
| 551 |
@itemx EnabledBy(@var{opt} || @var{opt2}) |
| 552 |
@itemx EnabledBy(@var{opt} && @var{opt2}) |
| 553 |
If not explicitly set, the option is set to the value of |
| 554 |
@option{-@var{opt}}; multiple options can be given, separated by |
| 555 |
@code{||}. The third form using @code{&&} specifies that the option is |
| 556 |
only set if both @var{opt} and @var{opt2} are set. The options @var{opt} |
| 557 |
and @var{opt2} must have the @code{Common} property; otherwise, use |
| 558 |
@code{LangEnabledBy}. |
| 559 |
|
| 560 |
@item LangEnabledBy(@var{language}, @var{opt}) |
| 561 |
@itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg}) |
| 562 |
When compiling for the given language, the option is set to the value |
| 563 |
of @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list |
| 564 |
of @code{||} separated options. In the second form, if |
| 565 |
@var{opt} is used in the positive form then @var{posarg} is considered |
| 566 |
to be passed to the option, and if @var{opt} is used in the negative |
| 567 |
form then @var{negarg} is considered to be passed to the option. It |
| 568 |
is possible to specify several different languages. Each |
| 569 |
@var{language} must have been declared by an earlier @code{Language} |
| 570 |
record. @xref{Option file format}. |
| 571 |
|
| 572 |
@item NoDWARFRecord |
| 573 |
The option is omitted from the producer string written by |
| 574 |
@option{-grecord-gcc-switches}. |
| 575 |
|
| 576 |
@item PchIgnore |
| 577 |
Even if this is a target option, this option will not be recorded / compared |
| 578 |
to determine if a precompiled header file matches. |
| 579 |
|
| 580 |
@item CPP(@var{var}) |
| 581 |
The state of this option should be kept in sync with the preprocessor |
| 582 |
option @var{var}. If this property is set, then properties @code{Var} |
| 583 |
and @code{Init} must be set as well. |
| 584 |
|
| 585 |
@item CppReason(@var{CPP_W_Enum}) |
| 586 |
This warning option corresponds to @code{cpplib.h} warning reason code |
| 587 |
@var{CPP_W_Enum}. This should only be used for warning options of the |
| 588 |
C-family front-ends. |
| 589 |
|
| 590 |
@end table |