gccint: Option properties
1
1 8.2 Option properties
1 =====================
1
1 The second field of an option record can specify any of the following
1 properties. When an option takes an argument, it is enclosed in
1 parentheses following the option property name. The parser that handles
1 option files is quite simplistic, and will be tricked by any nested
1 parentheses within the argument text itself; in this case, the entire
1 option argument can be wrapped in curly braces within the parentheses to
1 demarcate it, e.g.:
1
1 Condition({defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)})
1
1 'Common'
1 The option is available for all languages and targets.
1
1 'Target'
1 The option is available for all languages but is target-specific.
1
1 'Driver'
1 The option is handled by the compiler driver using code not shared
1 with the compilers proper ('cc1' etc.).
1
1 'LANGUAGE'
1 The option is available when compiling for the given language.
1
1 It is possible to specify several different languages for the same
1 option. Each LANGUAGE must have been declared by an earlier
1 'Language' record. ⇒Option file format.
1
1 'RejectDriver'
1 The option is only handled by the compilers proper ('cc1' etc.) and
1 should not be accepted by the driver.
1
1 'RejectNegative'
1 The option does not have a "no-" form. All options beginning with
1 "f", "W" or "m" are assumed to have a "no-" form unless this
1 property is used.
1
1 'Negative(OTHERNAME)'
1 The option will turn off another option OTHERNAME, which is the
1 option name with the leading "-" removed. This chain action will
1 propagate through the 'Negative' property of the option to be
1 turned off.
1
1 As a consequence, if you have a group of mutually-exclusive
1 options, their 'Negative' properties should form a circular chain.
1 For example, if options '-A', '-B' and '-C' are mutually exclusive,
1 their respective 'Negative' properties should be 'Negative(B)',
1 'Negative(C)' and 'Negative(A)'.
1
1 'Joined'
1 'Separate'
1 The option takes a mandatory argument. 'Joined' indicates that the
1 option and argument can be included in the same 'argv' entry (as
1 with '-mflush-func=NAME', for example). 'Separate' indicates that
1 the option and argument can be separate 'argv' entries (as with
1 '-o'). An option is allowed to have both of these properties.
1
1 'JoinedOrMissing'
1 The option takes an optional argument. If the argument is given,
1 it will be part of the same 'argv' entry as the option itself.
1
1 This property cannot be used alongside 'Joined' or 'Separate'.
1
1 'MissingArgError(MESSAGE)'
1 For an option marked 'Joined' or 'Separate', the message MESSAGE
1 will be used as an error message if the mandatory argument is
1 missing; for options without 'MissingArgError', a generic error
1 message is used. MESSAGE should contain a single '%qs' format,
1 which will be used to format the name of the option passed.
1
1 'Args(N)'
1 For an option marked 'Separate', indicate that it takes N
1 arguments. The default is 1.
1
1 'UInteger'
1 The option's argument is a non-negative integer. The option parser
1 will check and convert the argument before passing it to the
1 relevant option handler. 'UInteger' should also be used on options
1 like '-falign-loops' where both '-falign-loops' and
1 '-falign-loops'=N are supported to make sure the saved options are
1 given a full integer.
1
1 'ToLower'
1 The option's argument should be converted to lowercase as part of
1 putting it in canonical form, and before comparing with the strings
1 indicated by any 'Enum' property.
1
1 'NoDriverArg'
1 For an option marked 'Separate', the option only takes an argument
1 in the compiler proper, not in the driver. This is for
1 compatibility with existing options that are used both directly and
1 via '-Wp,'; new options should not have this property.
1
1 'Var(VAR)'
1 The state of this option should be stored in variable VAR (actually
1 a macro for 'global_options.x_VAR'). The way that the state is
1 stored depends on the type of option:
1
1 * If the option uses the 'Mask' or 'InverseMask' properties, VAR
1 is the integer variable that contains the mask.
1
1 * If the option is a normal on/off switch, VAR is an integer
1 variable that is nonzero when the option is enabled. The
1 options parser will set the variable to 1 when the positive
1 form of the option is used and 0 when the "no-" form is used.
1
1 * If the option takes an argument and has the 'UInteger'
1 property, VAR is an integer variable that stores the value of
1 the argument.
1
1 * If the option takes an argument and has the 'Enum' property,
1 VAR is a variable (type given in the 'Type' property of the
1 'Enum' record whose 'Name' property has the same argument as
1 the 'Enum' property of this option) that stores the value of
1 the argument.
1
1 * If the option has the 'Defer' property, VAR is a pointer to a
1 'VEC(cl_deferred_option,heap)' that stores the option for
1 later processing. (VAR is declared with type 'void *' and
1 needs to be cast to 'VEC(cl_deferred_option,heap)' before
1 use.)
1
1 * Otherwise, if the option takes an argument, VAR is a pointer
1 to the argument string. The pointer will be null if the
1 argument is optional and wasn't given.
1
1 The option-processing script will usually zero-initialize VAR. You
1 can modify this behavior using 'Init'.
1
1 'Var(VAR, SET)'
1 The option controls an integer variable VAR and is active when VAR
1 equals SET. The option parser will set VAR to SET when the
1 positive form of the option is used and '!SET' when the "no-" form
1 is used.
1
1 VAR is declared in the same way as for the single-argument form
1 described above.
1
1 'Init(VALUE)'
1 The variable specified by the 'Var' property should be statically
1 initialized to VALUE. If more than one option using the same
1 variable specifies 'Init', all must specify the same initializer.
1
1 'Mask(NAME)'
1 The option is associated with a bit in the 'target_flags' variable
1 (⇒Run-time Target) and is active when that bit is set. You
1 may also specify 'Var' to select a variable other than
1 'target_flags'.
1
1 The options-processing script will automatically allocate a unique
1 bit for the option. If the option is attached to 'target_flags',
1 the script will set the macro 'MASK_NAME' to the appropriate
1 bitmask. It will also declare a 'TARGET_NAME' macro that has the
1 value 1 when the option is active and 0 otherwise. If you use
1 'Var' to attach the option to a different variable, the bitmask
1 macro with be called 'OPTION_MASK_NAME'.
1
1 'InverseMask(OTHERNAME)'
1 'InverseMask(OTHERNAME, THISNAME)'
1 The option is the inverse of another option that has the
1 'Mask(OTHERNAME)' property. If THISNAME is given, the
1 options-processing script will declare a 'TARGET_THISNAME' macro
1 that is 1 when the option is active and 0 otherwise.
1
1 'Enum(NAME)'
1 The option's argument is a string from the set of strings
1 associated with the corresponding 'Enum' record. The string is
1 checked and converted to the integer specified in the corresponding
1 'EnumValue' record before being passed to option handlers.
1
1 'Defer'
1 The option should be stored in a vector, specified with 'Var', for
1 later processing.
1
1 'Alias(OPT)'
1 'Alias(OPT, ARG)'
1 'Alias(OPT, POSARG, NEGARG)'
1 The option is an alias for '-OPT' (or the negative form of that
1 option, depending on 'NegativeAlias'). In the first form, any
1 argument passed to the alias is considered to be passed to '-OPT',
1 and '-OPT' is considered to be negated if the alias is used in
1 negated form. In the second form, the alias may not be negated or
1 have an argument, and POSARG is considered to be passed as an
1 argument to '-OPT'. In the third form, the alias may not have an
1 argument, if the alias is used in the positive form then POSARG is
1 considered to be passed to '-OPT', and if the alias is used in the
1 negative form then NEGARG is considered to be passed to '-OPT'.
1
1 Aliases should not specify 'Var' or 'Mask' or 'UInteger'. Aliases
1 should normally specify the same languages as the target of the
1 alias; the flags on the target will be used to determine any
1 diagnostic for use of an option for the wrong language, while those
1 on the alias will be used to identify what command-line text is the
1 option and what text is any argument to that option.
1
1 When an 'Alias' definition is used for an option, driver specs do
1 not need to handle it and no 'OPT_' enumeration value is defined
1 for it; only the canonical form of the option will be seen in those
1 places.
1
1 'NegativeAlias'
1 For an option marked with 'Alias(OPT)', the option is considered to
1 be an alias for the positive form of '-OPT' if negated and for the
1 negative form of '-OPT' if not negated. 'NegativeAlias' may not be
1 used with the forms of 'Alias' taking more than one argument.
1
1 'Ignore'
1 This option is ignored apart from printing any warning specified
1 using 'Warn'. The option will not be seen by specs and no 'OPT_'
1 enumeration value is defined for it.
1
1 'SeparateAlias'
1 For an option marked with 'Joined', 'Separate' and 'Alias', the
1 option only acts as an alias when passed a separate argument; with
1 a joined argument it acts as a normal option, with an 'OPT_'
1 enumeration value. This is for compatibility with the Java '-d'
1 option and should not be used for new options.
1
1 'Warn(MESSAGE)'
1 If this option is used, output the warning MESSAGE. MESSAGE is a
1 format string, either taking a single operand with a '%qs' format
1 which is the option name, or not taking any operands, which is
1 passed to the 'warning' function. If an alias is marked 'Warn',
1 the target of the alias must not also be marked 'Warn'.
1
1 'Report'
1 The state of the option should be printed by '-fverbose-asm'.
1
1 'Warning'
1 This is a warning option and should be shown as such in '--help'
1 output. This flag does not currently affect anything other than
1 '--help'.
1
1 'Optimization'
1 This is an optimization option. It should be shown as such in
1 '--help' output, and any associated variable named using 'Var'
1 should be saved and restored when the optimization level is changed
1 with 'optimize' attributes.
1
1 'PerFunction'
1 This is an option that can be overridden on a per-function basis.
1 'Optimization' implies 'PerFunction', but options that do not
1 affect executable code generation may use this flag instead, so
1 that the option is not taken into account in ways that might affect
1 executable code generation.
1
1 'Undocumented'
1 The option is deliberately missing documentation and should not be
1 included in the '--help' output.
1
1 'Condition(COND)'
1 The option should only be accepted if preprocessor condition COND
1 is true. Note that any C declarations associated with the option
1 will be present even if COND is false; COND simply controls whether
1 the option is accepted and whether it is printed in the '--help'
1 output.
1
1 'Save'
1 Build the 'cl_target_option' structure to hold a copy of the
1 option, add the functions 'cl_target_option_save' and
1 'cl_target_option_restore' to save and restore the options.
1
1 'SetByCombined'
1 The option may also be set by a combined option such as
1 '-ffast-math'. This causes the 'gcc_options' struct to have a
1 field 'frontend_set_NAME', where 'NAME' is the name of the field
1 holding the value of this option (without the leading 'x_'). This
1 gives the front end a way to indicate that the value has been set
1 explicitly and should not be changed by the combined option. For
1 example, some front ends use this to prevent '-ffast-math' and
1 '-fno-fast-math' from changing the value of '-fmath-errno' for
1 languages that do not use 'errno'.
1
1 'EnabledBy(OPT)'
1 'EnabledBy(OPT || OPT2)'
1 'EnabledBy(OPT && OPT2)'
1 If not explicitly set, the option is set to the value of '-OPT';
1 multiple options can be given, separated by '||'. The third form
1 using '&&' specifies that the option is only set if both OPT and
1 OPT2 are set. The options OPT and OPT2 must have the 'Common'
1 property; otherwise, use 'LangEnabledBy'.
1
1 'LangEnabledBy(LANGUAGE, OPT)'
1 'LangEnabledBy(LANGUAGE, OPT, POSARG, NEGARG)'
1 When compiling for the given language, the option is set to the
1 value of '-OPT', if not explicitly set. OPT can be also a list of
1 '||' separated options. In the second form, if OPT is used in the
1 positive form then POSARG is considered to be passed to the option,
1 and if OPT is used in the negative form then NEGARG is considered
1 to be passed to the option. It is possible to specify several
1 different languages. Each LANGUAGE must have been declared by an
1 earlier 'Language' record. ⇒Option file format.
1
1 'NoDWARFRecord'
1 The option is omitted from the producer string written by
1 '-grecord-gcc-switches'.
1
1 'PchIgnore'
1 Even if this is a target option, this option will not be recorded /
1 compared to determine if a precompiled header file matches.
1
1 'CPP(VAR)'
1 The state of this option should be kept in sync with the
1 preprocessor option VAR. If this property is set, then properties
1 'Var' and 'Init' must be set as well.
1
1 'CppReason(CPP_W_ENUM)'
1 This warning option corresponds to 'cpplib.h' warning reason code
1 CPP_W_ENUM. This should only be used for warning options of the
1 C-family front-ends.
1