Option properties - GNU Compiler Collection (GCC) Internals
Description: GNU Compiler Collection (GCC) Internals

Previous: Option file format, Up: Options

### 8.2 Option properties

The second field of an option record can specify any of the following properties. When an option takes an argument, it is enclosed in parentheses following the option property name. The parser that handles option files is quite simplistic, and will be tricked by any nested parentheses within the argument text itself; in this case, the entire option argument can be wrapped in curly braces within the parentheses to demarcate it, e.g.:

         Condition({defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)})

`Common`
  The option is available for all languages and targets.
`Target`
  The option is available for all languages but is target-specific.
`Driver`
  The option is handled by the compiler driver using code not shared with the compilers proper (`cc1` etc.).
language
  The option is available when compiling for the given language.

  It is possible to specify several different languages for the same option. Each language must have been declared by an earlier `Language` record. See Option file format.

`RejectDriver`
  The option is only handled by the compilers proper (`cc1` etc.) and should not be accepted by the driver.
`RejectNegative`
  The option does not have a “no-” form. All options beginning with “f”, “W” or “m” are assumed to have a “no-” form unless this property is used.
`Negative(`othername`)`
  The option will turn off another option othername, which is the option name with the leading “-” removed. This chain action will propagate through the `Negative` property of the option to be turned off.
`Joined`
`Separate`
  The option takes a mandatory argument. `Joined` indicates that the option and argument can be included in the same `argv` entry (as with `-mflush-func=`name, for example). `Separate` indicates that the option and argument can be separate `argv` entries (as with `-o`). An option is allowed to have both of these properties.
`JoinedOrMissing`
  The option takes an optional argument. If the argument is given, it will be part of the same `argv` entry as the option itself.

  This property cannot be used alongside `Joined` or `Separate`.

`MissingArgError(`message`)`
  For an option marked `Joined` or `Separate`, the message message will be used as an error message if the mandatory argument is missing; for options without `MissingArgError`, a generic error message is used. message should contain a single ‘`%qs`’ format, which will be used to format the name of the option passed.
`Args(`n`)`
  For an option marked `Separate`, indicate that it takes n arguments. The default is 1.
`UInteger`
  The option's argument is a non-negative integer. The option parser will check and convert the argument before passing it to the relevant option handler. `UInteger` should also be used on options like `-falign-loops` where both `-falign-loops` and `-falign-loops`=n are supported to make sure the saved options are given a full integer.
`NoDriverArg`
  For an option marked `Separate`, the option only takes an argument in the compiler proper, not in the driver. This is for compatibility with existing options that are used both directly and via `-Wp,`; new options should not have this property.
`Var(`var`)`
  The state of this option should be stored in variable var (actually a macro for `global_options.x_`var). The way that the state is stored depends on the type of option:
  - If the option uses the `Mask` or `InverseMask` properties, var is the integer variable that contains the mask.
  - If the option is a normal on/off switch, var is an integer variable that is nonzero when the option is enabled. The options parser will set the variable to 1 when the positive form of the option is used and 0 when the “no-” form is used.
  - If the option takes an argument and has the `UInteger` property, var is an integer variable that stores the value of the argument.
  - If the option takes an argument and has the `Enum` property, var is a variable (type given in the `Type` property of the ‘`Enum`’ record whose `Name` property has the same argument as the `Enum` property of this option) that stores the value of the argument.
  - If the option has the `Defer` property, var is a pointer to a `VEC(cl_deferred_option,heap)` that stores the option for later processing. (var is declared with type `void *` and needs to be cast to `VEC(cl_deferred_option,heap)` before use.)
  - Otherwise, if the option takes an argument, var is a pointer to the argument string. The pointer will be null if the argument is optional and wasn't given.

  The option-processing script will usually zero-initialize var. You can modify this behavior using `Init`.

`Var(`var`,` set`)`
  The option controls an integer variable var and is active when var equals set. The option parser will set var to set when the positive form of the option is used and `!`set when the “no-” form is used.

  var is declared in the same way as for the single-argument form described above.

`Init(`value`)`
  The variable specified by the `Var` property should be statically initialized to value. If more than one option using the same variable specifies `Init`, all must specify the same initializer.
`Mask(`name`)`
  The option is associated with a bit in the `target_flags` variable (see Run-time Target) and is active when that bit is set. You may also specify `Var` to select a variable other than `target_flags`.

  The options-processing script will automatically allocate a unique bit for the option. If the option is attached to ‘`target_flags`’, the script will set the macro `MASK_`name to the appropriate bitmask. It will also declare a `TARGET_`name macro that has the value 1 when the option is active and 0 otherwise. If you use `Var` to attach the option to a different variable, the associated macros are called `OPTION_MASK_`name and `OPTION_`name respectively.

  You can disable automatic bit allocation using `MaskExists`.

`InverseMask(`othername`)`
`InverseMask(`othername`,` thisname`)`
  The option is the inverse of another option that has the `Mask(`othername`)` property. If thisname is given, the options-processing script will declare a `TARGET_`thisname macro that is 1 when the option is active and 0 otherwise.
`MaskExists`
  The mask specified by the `Mask` property already exists. No `MASK` or `TARGET` definitions should be added to `options.h` in response to this option record.

  The main purpose of this property is to support synonymous options. The first option should use ‘`Mask(name)`’ and the others should use ‘`Mask(name) MaskExists`’.

`Enum(`name`)`
  The option's argument is a string from the set of strings associated with the corresponding ‘`Enum`’ record. The string is checked and converted to the integer specified in the corresponding ‘`EnumValue`’ record before being passed to option handlers.
`Defer`
  The option should be stored in a vector, specified with `Var`, for later processing.
`Alias(`opt`)`
`Alias(`opt`,` arg`)`
`Alias(`opt`,` posarg`,` negarg`)`
  The option is an alias for `-opt`. In the first form, any argument passed to the alias is considered to be passed to `-opt`, and `-opt` is considered to be negated if the alias is used in negated form. In the second form, the alias may not be negated or have an argument, and posarg is considered to be passed as an argument to `-opt`. In the third form, the alias may not have an argument, if the alias is used in the positive form then posarg is considered to be passed to `-opt`, and if the alias is used in the negative form then negarg is considered to be passed to `-opt`.

  Aliases should not specify `Var` or `Mask` or `UInteger`. Aliases should normally specify the same languages as the target of the alias; the flags on the target will be used to determine any diagnostic for use of an option for the wrong language, while those on the alias will be used to identify what command-line text is the option and what text is any argument to that option.

  When an `Alias` definition is used for an option, driver specs do not need to handle it and no ‘`OPT_`’ enumeration value is defined for it; only the canonical form of the option will be seen in those places.

`Ignore`
  This option is ignored apart from printing any warning specified using `Warn`. The option will not be seen by specs and no ‘`OPT_`’ enumeration value is defined for it.
`SeparateAlias`
  For an option marked with `Joined`, `Separate` and `Alias`, the option only acts as an alias when passed a separate argument; with a joined argument it acts as a normal option, with an ‘`OPT_`’ enumeration value. This is for compatibility with the Java `-d` option and should not be used for new options.
`Warn(`message`)`
  If this option is used, output the warning message. message is a format string, either taking a single operand with a ‘`%qs`’ format which is the option name, or not taking any operands, which is passed to the ‘`warning`’ function. If an alias is marked `Warn`, the target of the alias must not also be marked `Warn`.
`Report`
  The state of the option should be printed by `-fverbose-asm`.
`Warning`
  This is a warning option and should be shown as such in `--help` output. This flag does not currently affect anything other than `--help`.
`Optimization`
  This is an optimization option. It should be shown as such in `--help` output, and any associated variable named using `Var` should be saved and restored when the optimization level is changed with `optimize` attributes.
`Undocumented`
  The option is deliberately missing documentation and should not be included in the `--help` output.
`Condition(`cond`)`
  The option should only be accepted if preprocessor condition cond is true. Note that any C declarations associated with the option will be present even if cond is false; cond simply controls whether the option is accepted and whether it is printed in the `--help` output.
`Save`
  Build the `cl_target_option` structure to hold a copy of the option, add the functions `cl_target_option_save` and `cl_target_option_restore` to save and restore the options.
`SetByCombined`
  The option may also be set by a combined option such as `-ffast-math`. This causes the `gcc_options` struct to have a field `frontend_set_`name, where name is the name of the field holding the value of this option (without the leading `x_`). This gives the front end a way to indicate that the value has been set explicitly and should not be changed by the combined option. For example, some front ends use this to prevent `-ffast-math` and `-fno-fast-math` from changing the value of `-fmath-errno` for languages that do not use `errno`.