Option specification files
**************************

Most GCC command-line options are described by special option definition files, the names of which conventionally end in .opt.  This chapter describes the format of these files.

Option file format
==================

Option files are a simple list of records in which each field occupies its own line and in which the records themselves are separated by blank lines.  Comments may appear on their own line anywhere within the file and are preceded by semicolons.  Whitespace is allowed before the semicolon.

The files can contain the following types of record:

  * A language definition record.  These records have two fields: the string Language and the name of the language.  Once a language has been declared in this way, it can be used as an option property. See Option properties.

  * A target specific save record to save additional information. These records have two fields: the string TargetSave, and a declaration type to go in the cl_target_option structure.

  * A variable record to define a variable used to store option information.  These records have two fields: the string Variable, and a declaration of the type and name of the variable, optionally with an initializer (but without any trailing ;).  These records may be used for variables used for many options where declaring the initializer in a single option definition record, or duplicating it in many records, would be inappropriate, or for variables set in option handlers rather than referenced by Var properties.

  * A variable record to define a variable used to store option information.  These records have two fields: the string TargetVariable, and a declaration of the type and name of the variable, optionally with an initializer (but without any trailing ;).  TargetVariable is a combination of Variable and TargetSave records in that the variable is defined in the gcc_options structure, but these variables are also stored in the cl_target_option structure.  The variables are saved in the target save code and restored in the target restore code.

  * A variable record to record any additional files that the options.h file should include.  This is useful to provide enumeration or structure definitions needed for target variables. These records have two fields: the string HeaderInclude and the name of the include file.

  * A variable record to record any additional files that the options.cc or options-save.cc file should include.  This is useful to provide inline functions needed for target variables and/or #ifdef sequences to properly set up the initialization.  These records have two fields: the string SourceInclude and the name of the include file.

  * An enumeration record to define a set of strings that may be used as arguments to an option or options.  These records have three fields: the string Enum, a space-separated list of properties and help text used to describe the set of strings in --help output. Properties use the same format as option properties; the following are valid:

     Name(NAME)
          This property is required; NAME must be a name (suitable for use in C identifiers) used to identify the set of strings in Enum option properties.

     Type(TYPE)
          This property is required; TYPE is the C type for variables set by options using this enumeration together with Var.

     UnknownError(MESSAGE)
          The message MESSAGE will be used as an error message if the argument is invalid; for enumerations without UnknownError, a generic error message is used.  MESSAGE should contain a single %qs format, which will be used to format the invalid argument.

  * An enumeration value record to define one of the strings in a set given in an Enum record.  These records have two fields: the string EnumValue and a space-separated list of properties. Properties use the same format as option properties; the following are valid:

     Enum(NAME)
          This property is required; NAME says which Enum record this EnumValue record corresponds to.

     String(STRING)
          This property is required; STRING is the string option argument being described by this record.

     Value(VALUE)
          This property is required; it says what value (representable as int) should be used for the given string.

     Canonical
          This property is optional.  If present, it says the present string is the canonical one among all those with the given value.  Other strings yielding that value will be mapped to this one so specs do not need to handle them.

     DriverOnly
          This property is optional.  If present, the present string will only be accepted by the driver.  This is used for cases such as -march=native that are processed by the driver so that gcc -v shows how the options chosen depended on the system on which the compiler was run.

     Set(NUMBER)
          This property is optional, required for enumerations used in EnumSet options.  NUMBER should be decimal number between 1 and 64 inclusive and divides the enumeration into a set of sets of mutually exclusive arguments.  Arguments with the same NUMBER can't be specified together in the same option, but arguments with different NUMBER can.  VALUE needs to be chosen such that a mask of all VALUE values from the same set NUMBER bitwise ored doesn't overlap with masks for other sets. When -foption=arg_from_set1,arg_from_set4 and -fno-option=arg_from_set3 are used, the effect is that previous value of the Var will get bits from set 1 and 4 masks cleared, ored Value of arg_from_set1 and arg_from_set4 and then will get bits from set 3 mask cleared.

  * An option definition record.  These records have the following fields:

      1. the name of the option, with the leading ``-'' removed

      2. a space-separated list of option properties (see Option properties)

      3. the help text to use for --help (omitted if the second field contains the Undocumented property).

     By default, all options beginning with ``f'', ``W'' or ``m'' are implicitly assumed to take a ``no-'' form.  This form should not be listed separately.  If an option beginning with one of these letters does not have a ``no-'' form, you can use the RejectNegative property to reject it.

     The help text is automatically line-wrapped before being displayed. Normally the name of the option is printed on the left-hand side of the output and the help text is printed on the right.  However, if the help text contains a tab character, the text to the left of the tab is used instead of the option's name and the text to the right of the tab forms the help text.  This allows you to elaborate on what type of argument the option takes.

     There is no support for different help texts for different languages. If an option is supported for multiple languages, use a generic description that is correct for all of them.

     If an option has multiple option definition records (in different front ends' *.opt files, and/or gcc/common.opt, for example), convention is to not duplicate the help text for each of them, but instead put a comment like ; documented in common.opt in place of the help text for all but one of the multiple option definition records.

  * A target mask record.  These records have one field of the form Mask(X).  The options-processing script will automatically allocate a bit in target_flags (see Run-time Target) for each mask name X and set the macro MASK_X to the appropriate bitmask.  It will also declare a TARGET_X macro that has the value 1 when bit MASK_X is set and 0 otherwise.

     They are primarily intended to declare target masks that are not associated with user options, either because these masks represent internal switches or because the options are not available on all configurations and yet the masks always need to be defined.

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.  The driver will prune options, removing those that are turned off by some later option.  This pruning is not done for options with Joined or JoinedOrMissing properties, unless the options have both the RejectNegative property and the Negative property mentions itself.

     As a consequence, if you have a group of mutually-exclusive options, their Negative properties should form a circular chain. For example, if options -A, -B and -C are mutually exclusive, their respective Negative properties should be Negative(B), Negative(C) and Negative(A).

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 consisting of either decimal or hexadecimal digits interpreted as int.  Hexadecimal integers may optionally start with the 0x or 0X prefix. The option parser validates and converts the argument before passing it to the relevant option handler.  UInteger should also be used with 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.  Positive values of the argument in excess of INT_MAX wrap around zero.

Host_Wide_Int
     The option's argument is a non-negative integer consisting of either decimal or hexadecimal digits interpreted as the widest integer type on the host.  As with an UInteger argument, hexadecimal integers may optionally start with the 0x or 0X prefix.  The option parser validates and converts the argument before passing it to the relevant option handler.  Host_Wide_Int should be used with options that need to accept very large values.  Positive values of the argument in excess of HOST_WIDE_INT_M1U are assigned HOST_WIDE_INT_M1U.

IntegerRange(N, M)
     The options's arguments are integers of type int.  The option's parser validates that the value of an option integer argument is within the closed range [N, M].

ByteSize
     A property applicable only to UInteger or Host_Wide_Int arguments.  The option's integer argument is interpreted as if in infinite precision using saturation arithmetic in the corresponding type.  The argument may be followed by a byte-size suffix designating a multiple of bytes such as kB and KiB for kilobyte and kibibyte, respectively, MB and MiB for megabyte and mebibyte, GB and GiB for gigabyte and gigibyte, and so on.  ByteSize should be used for with options that take a very large argument representing a size in bytes, such as -Wlarger-than=.

ToLower
     The option's argument should be converted to lowercase as part of putting it in canonical form, and before comparing with the strings indicated by any Enum property.

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:

WarnRemoved
     The option is removed and every usage of such option will result in a warning.  We use it option backward compatibility.

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.

       * 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.

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 bitmask macro with be called OPTION_MASK_NAME.

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.

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.

EnumSet
     Must be used together with the Enum(NAME) property. Corresponding Enum record must use Set properties. The option's argument is either a string from the set like for Enum(NAME), but with a slightly different behavior that the whole Var isn't overwritten, but only the bits in all the enumeration values with the same set bitwise ored together. Or option's argument can be a comma separated list of strings where each string is from a different Set(NUMBER).

EnumBitSet
     Must be used together with the Enum(NAME) property. Similar to EnumSet, but corresponding Enum record must not use Set properties, each EnumValue should have Value that is a power of 2, each value is treated as its own set and its value as the set's mask, so there are no mutually exclusive arguments.

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 (or the negative form of that option, depending on NegativeAlias).  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.

NegativeAlias
     For an option marked with Alias(OPT), the option is considered to be an alias for the positive form of -OPT if negated and for the negative form of -OPT if not negated.  NegativeAlias may not be used with the forms of Alias taking more than one argument.

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.

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.

PerFunction
     This is an option that can be overridden on a per-function basis. Optimization implies PerFunction, but options that do not affect executable code generation may use this flag instead, so that the option is not taken into account in ways that might affect executable code generation.

Param
     This is an option that is a parameter.

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.

EnabledBy(OPT)
EnabledBy(OPT || OPT2)
EnabledBy(OPT && OPT2)
     If not explicitly set, the option is set to the value of -OPT; multiple options can be given, separated by ||.  The third form using && specifies that the option is only set if both OPT and OPT2 are set. The options OPT and OPT2 must have the Common property; otherwise, use LangEnabledBy.

LangEnabledBy(LANGUAGE, OPT)
LangEnabledBy(LANGUAGE, OPT, POSARG, NEGARG)
     When compiling for the given language, the option is set to the value of -OPT, if not explicitly set. OPT can be also a list of || separated options. In the second form, if OPT is used in the positive form then POSARG is considered to be passed to the option, and if OPT is used in the negative form then NEGARG is considered to be passed to the option.  It is possible to specify several different languages.  Each LANGUAGE must have been declared by an earlier Language record.  See Option file format.

NoDWARFRecord
     The option is omitted from the producer string written by -grecord-gcc-switches.

PchIgnore
     Even if this is a target option, this option will not be recorded / compared to determine if a precompiled header file matches.

CPP(VAR)
     The state of this option should be kept in sync with the preprocessor option VAR.  If this property is set, then properties Var and Init must be set as well.

CppReason(CPP_W_ENUM)
     This warning option corresponds to cpplib.h warning reason code CPP_W_ENUM.  This should only be used for warning options of the C-family front-ends.