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.

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

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

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.

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.

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.

Var(VAR)
     The state of this option should be stored in variable 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.

       * 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 declare VAR in options.c and leave it to be zero-initialized at start-up time. You can modify this behavior using VarExists and 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.

VarExists
     The variable specified by the Var property already exists. No definition should be added to options.c in response to this option record.

     You should use this property only if the variable is declared outside options.c.

Init(VALUE)
     The variable specified by the Var property should be statically initialized to VALUE.

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.

Report
     The state of the option should be printed by -fverbose-asm.

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.