gccint: Option file format
1
1 8.1 Option file format
1 ======================
1
1 Option files are a simple list of records in which each field occupies
1 its own line and in which the records themselves are separated by blank
1 lines. Comments may appear on their own line anywhere within the file
1 and are preceded by semicolons. Whitespace is allowed before the
1 semicolon.
1
1 The files can contain the following types of record:
1
1 * A language definition record. These records have two fields: the
1 string 'Language' and the name of the language. Once a language
1 has been declared in this way, it can be used as an option
1 property. ⇒Option properties.
1
1 * A target specific save record to save additional information.
1 These records have two fields: the string 'TargetSave', and a
1 declaration type to go in the 'cl_target_option' structure.
1
1 * A variable record to define a variable used to store option
1 information. These records have two fields: the string 'Variable',
1 and a declaration of the type and name of the variable, optionally
1 with an initializer (but without any trailing ';'). These records
1 may be used for variables used for many options where declaring the
1 initializer in a single option definition record, or duplicating it
1 in many records, would be inappropriate, or for variables set in
1 option handlers rather than referenced by 'Var' properties.
1
1 * A variable record to define a variable used to store option
1 information. These records have two fields: the string
1 'TargetVariable', and a declaration of the type and name of the
1 variable, optionally with an initializer (but without any trailing
1 ';'). 'TargetVariable' is a combination of 'Variable' and
1 'TargetSave' records in that the variable is defined in the
1 'gcc_options' structure, but these variables are also stored in the
1 'cl_target_option' structure. The variables are saved in the
1 target save code and restored in the target restore code.
1
1 * A variable record to record any additional files that the
1 'options.h' file should include. This is useful to provide
1 enumeration or structure definitions needed for target variables.
1 These records have two fields: the string 'HeaderInclude' and the
1 name of the include file.
1
1 * A variable record to record any additional files that the
1 'options.c' or 'options-save.c' file should include. This is
1 useful to provide inline functions needed for target variables
1 and/or '#ifdef' sequences to properly set up the initialization.
1 These records have two fields: the string 'SourceInclude' and the
1 name of the include file.
1
1 * An enumeration record to define a set of strings that may be used
1 as arguments to an option or options. These records have three
1 fields: the string 'Enum', a space-separated list of properties and
1 help text used to describe the set of strings in '--help' output.
1 Properties use the same format as option properties; the following
1 are valid:
1 'Name(NAME)'
1 This property is required; NAME must be a name (suitable for
1 use in C identifiers) used to identify the set of strings in
1 'Enum' option properties.
1
1 'Type(TYPE)'
1 This property is required; TYPE is the C type for variables
1 set by options using this enumeration together with 'Var'.
1
1 'UnknownError(MESSAGE)'
1 The message MESSAGE will be used as an error message if the
1 argument is invalid; for enumerations without 'UnknownError',
1 a generic error message is used. MESSAGE should contain a
1 single '%qs' format, which will be used to format the invalid
1 argument.
1
1 * An enumeration value record to define one of the strings in a set
1 given in an 'Enum' record. These records have two fields: the
1 string 'EnumValue' and a space-separated list of properties.
1 Properties use the same format as option properties; the following
1 are valid:
1 'Enum(NAME)'
1 This property is required; NAME says which 'Enum' record this
1 'EnumValue' record corresponds to.
1
1 'String(STRING)'
1 This property is required; STRING is the string option
1 argument being described by this record.
1
1 'Value(VALUE)'
1 This property is required; it says what value (representable
1 as 'int') should be used for the given string.
1
1 'Canonical'
1 This property is optional. If present, it says the present
1 string is the canonical one among all those with the given
1 value. Other strings yielding that value will be mapped to
1 this one so specs do not need to handle them.
1
1 'DriverOnly'
1 This property is optional. If present, the present string
1 will only be accepted by the driver. This is used for cases
1 such as '-march=native' that are processed by the driver so
1 that 'gcc -v' shows how the options chosen depended on the
1 system on which the compiler was run.
1
1 * An option definition record. These records have the following
1 fields:
1 1. the name of the option, with the leading "-" removed
1 properties::)
1 3. the help text to use for '--help' (omitted if the second field
1 contains the 'Undocumented' property).
1
1 By default, all options beginning with "f", "W" or "m" are
1 implicitly assumed to take a "no-" form. This form should not be
1 listed separately. If an option beginning with one of these
1 letters does not have a "no-" form, you can use the
1 'RejectNegative' property to reject it.
1
1 The help text is automatically line-wrapped before being displayed.
1 Normally the name of the option is printed on the left-hand side of
1 the output and the help text is printed on the right. However, if
1 the help text contains a tab character, the text to the left of the
1 tab is used instead of the option's name and the text to the right
1 of the tab forms the help text. This allows you to elaborate on
1 what type of argument the option takes.
1
1 * A target mask record. These records have one field of the form
1 'Mask(X)'. The options-processing script will automatically
1 allocate a bit in 'target_flags' (⇒Run-time Target) for each
1 mask name X and set the macro 'MASK_X' to the appropriate bitmask.
1 It will also declare a 'TARGET_X' macro that has the value 1 when
1 bit 'MASK_X' is set and 0 otherwise.
1
1 They are primarily intended to declare target masks that are not
1 associated with user options, either because these masks represent
1 internal switches or because the options are not available on all
1 configurations and yet the masks always need to be defined.
1