1*ec02198aSmrg@c Copyright (C) 2003-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@node Options 610d565efSmrg@chapter Option specification files 710d565efSmrg@cindex option specification files 810d565efSmrg@cindex @samp{optc-gen.awk} 910d565efSmrg 1010d565efSmrgMost GCC command-line options are described by special option 1110d565efSmrgdefinition files, the names of which conventionally end in 1210d565efSmrg@code{.opt}. This chapter describes the format of these files. 1310d565efSmrg 1410d565efSmrg@menu 1510d565efSmrg* Option file format:: The general layout of the files 1610d565efSmrg* Option properties:: Supported option properties 1710d565efSmrg@end menu 1810d565efSmrg 1910d565efSmrg@node Option file format 2010d565efSmrg@section Option file format 2110d565efSmrg 2210d565efSmrgOption files are a simple list of records in which each field occupies 2310d565efSmrgits own line and in which the records themselves are separated by 2410d565efSmrgblank lines. Comments may appear on their own line anywhere within 2510d565efSmrgthe file and are preceded by semicolons. Whitespace is allowed before 2610d565efSmrgthe semicolon. 2710d565efSmrg 2810d565efSmrgThe files can contain the following types of record: 2910d565efSmrg 3010d565efSmrg@itemize @bullet 3110d565efSmrg@item 3210d565efSmrgA language definition record. These records have two fields: the 3310d565efSmrgstring @samp{Language} and the name of the language. Once a language 3410d565efSmrghas been declared in this way, it can be used as an option property. 3510d565efSmrg@xref{Option properties}. 3610d565efSmrg 3710d565efSmrg@item 3810d565efSmrgA target specific save record to save additional information. These 3910d565efSmrgrecords have two fields: the string @samp{TargetSave}, and a 4010d565efSmrgdeclaration type to go in the @code{cl_target_option} structure. 4110d565efSmrg 4210d565efSmrg@item 4310d565efSmrgA variable record to define a variable used to store option 4410d565efSmrginformation. These records have two fields: the string 4510d565efSmrg@samp{Variable}, and a declaration of the type and name of the 4610d565efSmrgvariable, optionally with an initializer (but without any trailing 4710d565efSmrg@samp{;}). These records may be used for variables used for many 4810d565efSmrgoptions where declaring the initializer in a single option definition 4910d565efSmrgrecord, or duplicating it in many records, would be inappropriate, or 5010d565efSmrgfor variables set in option handlers rather than referenced by 5110d565efSmrg@code{Var} properties. 5210d565efSmrg 5310d565efSmrg@item 5410d565efSmrgA variable record to define a variable used to store option 5510d565efSmrginformation. These records have two fields: the string 5610d565efSmrg@samp{TargetVariable}, and a declaration of the type and name of the 5710d565efSmrgvariable, optionally with an initializer (but without any trailing 5810d565efSmrg@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable} 5910d565efSmrgand @samp{TargetSave} records in that the variable is defined in the 6010d565efSmrg@code{gcc_options} structure, but these variables are also stored in 6110d565efSmrgthe @code{cl_target_option} structure. The variables are saved in the 6210d565efSmrgtarget save code and restored in the target restore code. 6310d565efSmrg 6410d565efSmrg@item 6510d565efSmrgA variable record to record any additional files that the 6610d565efSmrg@file{options.h} file should include. This is useful to provide 6710d565efSmrgenumeration or structure definitions needed for target variables. 6810d565efSmrgThese records have two fields: the string @samp{HeaderInclude} and the 6910d565efSmrgname of the include file. 7010d565efSmrg 7110d565efSmrg@item 7210d565efSmrgA variable record to record any additional files that the 7310d565efSmrg@file{options.c} or @file{options-save.c} file should include. This 7410d565efSmrgis useful to provide 7510d565efSmrginline functions needed for target variables and/or @code{#ifdef} 7610d565efSmrgsequences to properly set up the initialization. These records have 7710d565efSmrgtwo fields: the string @samp{SourceInclude} and the name of the 7810d565efSmrginclude file. 7910d565efSmrg 8010d565efSmrg@item 8110d565efSmrgAn enumeration record to define a set of strings that may be used as 8210d565efSmrgarguments to an option or options. These records have three fields: 8310d565efSmrgthe string @samp{Enum}, a space-separated list of properties and help 8410d565efSmrgtext used to describe the set of strings in @option{--help} output. 8510d565efSmrgProperties use the same format as option properties; the following are 8610d565efSmrgvalid: 8710d565efSmrg@table @code 8810d565efSmrg@item Name(@var{name}) 8910d565efSmrgThis property is required; @var{name} must be a name (suitable for use 9010d565efSmrgin C identifiers) used to identify the set of strings in @code{Enum} 9110d565efSmrgoption properties. 9210d565efSmrg 9310d565efSmrg@item Type(@var{type}) 9410d565efSmrgThis property is required; @var{type} is the C type for variables set 9510d565efSmrgby options using this enumeration together with @code{Var}. 9610d565efSmrg 9710d565efSmrg@item UnknownError(@var{message}) 9810d565efSmrgThe message @var{message} will be used as an error message if the 9910d565efSmrgargument is invalid; for enumerations without @code{UnknownError}, a 10010d565efSmrggeneric error message is used. @var{message} should contain a single 10110d565efSmrg@samp{%qs} format, which will be used to format the invalid argument. 10210d565efSmrg@end table 10310d565efSmrg 10410d565efSmrg@item 10510d565efSmrgAn enumeration value record to define one of the strings in a set 10610d565efSmrggiven in an @samp{Enum} record. These records have two fields: the 10710d565efSmrgstring @samp{EnumValue} and a space-separated list of properties. 10810d565efSmrgProperties use the same format as option properties; the following are 10910d565efSmrgvalid: 11010d565efSmrg@table @code 11110d565efSmrg@item Enum(@var{name}) 11210d565efSmrgThis property is required; @var{name} says which @samp{Enum} record 11310d565efSmrgthis @samp{EnumValue} record corresponds to. 11410d565efSmrg 11510d565efSmrg@item String(@var{string}) 11610d565efSmrgThis property is required; @var{string} is the string option argument 11710d565efSmrgbeing described by this record. 11810d565efSmrg 11910d565efSmrg@item Value(@var{value}) 12010d565efSmrgThis property is required; it says what value (representable as 12110d565efSmrg@code{int}) should be used for the given string. 12210d565efSmrg 12310d565efSmrg@item Canonical 12410d565efSmrgThis property is optional. If present, it says the present string is 12510d565efSmrgthe canonical one among all those with the given value. Other strings 12610d565efSmrgyielding that value will be mapped to this one so specs do not need to 12710d565efSmrghandle them. 12810d565efSmrg 12910d565efSmrg@item DriverOnly 13010d565efSmrgThis property is optional. If present, the present string will only 13110d565efSmrgbe accepted by the driver. This is used for cases such as 13210d565efSmrg@option{-march=native} that are processed by the driver so that 13310d565efSmrg@samp{gcc -v} shows how the options chosen depended on the system on 13410d565efSmrgwhich the compiler was run. 13510d565efSmrg@end table 13610d565efSmrg 13710d565efSmrg@item 13810d565efSmrgAn option definition record. These records have the following fields: 13910d565efSmrg@enumerate 14010d565efSmrg@item 14110d565efSmrgthe name of the option, with the leading ``-'' removed 14210d565efSmrg@item 14310d565efSmrga space-separated list of option properties (@pxref{Option properties}) 14410d565efSmrg@item 14510d565efSmrgthe help text to use for @option{--help} (omitted if the second field 14610d565efSmrgcontains the @code{Undocumented} property). 14710d565efSmrg@end enumerate 14810d565efSmrg 14910d565efSmrgBy default, all options beginning with ``f'', ``W'' or ``m'' are 15010d565efSmrgimplicitly assumed to take a ``no-'' form. This form should not be 15110d565efSmrglisted separately. If an option beginning with one of these letters 15210d565efSmrgdoes not have a ``no-'' form, you can use the @code{RejectNegative} 15310d565efSmrgproperty to reject it. 15410d565efSmrg 15510d565efSmrgThe help text is automatically line-wrapped before being displayed. 15610d565efSmrgNormally the name of the option is printed on the left-hand side of 15710d565efSmrgthe output and the help text is printed on the right. However, if the 15810d565efSmrghelp text contains a tab character, the text to the left of the tab is 15910d565efSmrgused instead of the option's name and the text to the right of the 16010d565efSmrgtab forms the help text. This allows you to elaborate on what type 16110d565efSmrgof argument the option takes. 16210d565efSmrg 16310d565efSmrg@item 16410d565efSmrgA target mask record. These records have one field of the form 16510d565efSmrg@samp{Mask(@var{x})}. The options-processing script will automatically 16610d565efSmrgallocate a bit in @code{target_flags} (@pxref{Run-time Target}) for 16710d565efSmrgeach mask name @var{x} and set the macro @code{MASK_@var{x}} to the 16810d565efSmrgappropriate bitmask. It will also declare a @code{TARGET_@var{x}} 16910d565efSmrgmacro that has the value 1 when bit @code{MASK_@var{x}} is set and 17010d565efSmrg0 otherwise. 17110d565efSmrg 17210d565efSmrgThey are primarily intended to declare target masks that are not 17310d565efSmrgassociated with user options, either because these masks represent 17410d565efSmrginternal switches or because the options are not available on all 17510d565efSmrgconfigurations and yet the masks always need to be defined. 17610d565efSmrg@end itemize 17710d565efSmrg 17810d565efSmrg@node Option properties 17910d565efSmrg@section Option properties 18010d565efSmrg 18110d565efSmrgThe second field of an option record can specify any of the following 18210d565efSmrgproperties. When an option takes an argument, it is enclosed in parentheses 18310d565efSmrgfollowing the option property name. The parser that handles option files 18410d565efSmrgis quite simplistic, and will be tricked by any nested parentheses within 18510d565efSmrgthe argument text itself; in this case, the entire option argument can 18610d565efSmrgbe wrapped in curly braces within the parentheses to demarcate it, e.g.: 18710d565efSmrg 18810d565efSmrg@smallexample 18910d565efSmrgCondition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@}) 19010d565efSmrg@end smallexample 19110d565efSmrg 19210d565efSmrg@table @code 19310d565efSmrg@item Common 19410d565efSmrgThe option is available for all languages and targets. 19510d565efSmrg 19610d565efSmrg@item Target 19710d565efSmrgThe option is available for all languages but is target-specific. 19810d565efSmrg 19910d565efSmrg@item Driver 20010d565efSmrgThe option is handled by the compiler driver using code not shared 20110d565efSmrgwith the compilers proper (@file{cc1} etc.). 20210d565efSmrg 20310d565efSmrg@item @var{language} 20410d565efSmrgThe option is available when compiling for the given language. 20510d565efSmrg 20610d565efSmrgIt is possible to specify several different languages for the same 20710d565efSmrgoption. Each @var{language} must have been declared by an earlier 20810d565efSmrg@code{Language} record. @xref{Option file format}. 20910d565efSmrg 21010d565efSmrg@item RejectDriver 21110d565efSmrgThe option is only handled by the compilers proper (@file{cc1} etc.)@: 21210d565efSmrgand should not be accepted by the driver. 21310d565efSmrg 21410d565efSmrg@item RejectNegative 21510d565efSmrgThe option does not have a ``no-'' form. All options beginning with 21610d565efSmrg``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this 21710d565efSmrgproperty is used. 21810d565efSmrg 21910d565efSmrg@item Negative(@var{othername}) 22010d565efSmrgThe option will turn off another option @var{othername}, which is 22110d565efSmrgthe option name with the leading ``-'' removed. This chain action will 22210d565efSmrgpropagate through the @code{Negative} property of the option to be 2230fc04c29Smrgturned off. The driver will prune options, removing those that are 2240fc04c29Smrgturned off by some later option. This pruning is not done for options 2250fc04c29Smrgwith @code{Joined} or @code{JoinedOrMissing} properties, unless the 2260fc04c29Smrgoptions have either @code{RejectNegative} property or the @code{Negative} 2270fc04c29Smrgproperty mentions an option other than itself. 22810d565efSmrg 22910d565efSmrgAs a consequence, if you have a group of mutually-exclusive 23010d565efSmrgoptions, their @code{Negative} properties should form a circular chain. 23110d565efSmrgFor example, if options @option{-@var{a}}, @option{-@var{b}} and 23210d565efSmrg@option{-@var{c}} are mutually exclusive, their respective @code{Negative} 23310d565efSmrgproperties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})} 23410d565efSmrgand @samp{Negative(@var{a})}. 23510d565efSmrg 23610d565efSmrg@item Joined 23710d565efSmrg@itemx Separate 23810d565efSmrgThe option takes a mandatory argument. @code{Joined} indicates 23910d565efSmrgthat the option and argument can be included in the same @code{argv} 24010d565efSmrgentry (as with @code{-mflush-func=@var{name}}, for example). 24110d565efSmrg@code{Separate} indicates that the option and argument can be 24210d565efSmrgseparate @code{argv} entries (as with @code{-o}). An option is 24310d565efSmrgallowed to have both of these properties. 24410d565efSmrg 24510d565efSmrg@item JoinedOrMissing 24610d565efSmrgThe option takes an optional argument. If the argument is given, 24710d565efSmrgit will be part of the same @code{argv} entry as the option itself. 24810d565efSmrg 24910d565efSmrgThis property cannot be used alongside @code{Joined} or @code{Separate}. 25010d565efSmrg 25110d565efSmrg@item MissingArgError(@var{message}) 25210d565efSmrgFor an option marked @code{Joined} or @code{Separate}, the message 25310d565efSmrg@var{message} will be used as an error message if the mandatory 25410d565efSmrgargument is missing; for options without @code{MissingArgError}, a 25510d565efSmrggeneric error message is used. @var{message} should contain a single 25610d565efSmrg@samp{%qs} format, which will be used to format the name of the option 25710d565efSmrgpassed. 25810d565efSmrg 25910d565efSmrg@item Args(@var{n}) 26010d565efSmrgFor an option marked @code{Separate}, indicate that it takes @var{n} 26110d565efSmrgarguments. The default is 1. 26210d565efSmrg 26310d565efSmrg@item UInteger 2640fc04c29SmrgThe option's argument is a non-negative integer consisting of either 2650fc04c29Smrgdecimal or hexadecimal digits interpreted as @code{int}. Hexadecimal 2660fc04c29Smrgintegers may optionally start with the @code{0x} or @code{0X} prefix. 2670fc04c29SmrgThe option parser validates and converts the argument before passing 2680fc04c29Smrgit to the relevant option handler. @code{UInteger} should also be used 2690fc04c29Smrgwith options like @code{-falign-loops} where both @code{-falign-loops} 2700fc04c29Smrgand @code{-falign-loops}=@var{n} are supported to make sure the saved 2710fc04c29Smrgoptions are given a full integer. Positive values of the argument in 2720fc04c29Smrgexcess of @code{INT_MAX} wrap around zero. 2730fc04c29Smrg 2740fc04c29Smrg@item Host_Wide_Int 2750fc04c29SmrgThe option's argument is a non-negative integer consisting of either 2760fc04c29Smrgdecimal or hexadecimal digits interpreted as the widest integer type 2770fc04c29Smrgon the host. As with an @code{UInteger} argument, hexadecimal integers 2780fc04c29Smrgmay optionally start with the @code{0x} or @code{0X} prefix. The option 2790fc04c29Smrgparser validates and converts the argument before passing it to 2800fc04c29Smrgthe relevant option handler. @code{Host_Wide_Int} should be used with 2810fc04c29Smrgoptions that need to accept very large values. Positive values of 2820fc04c29Smrgthe argument in excess of @code{HOST_WIDE_INT_M1U} are assigned 2830fc04c29Smrg@code{HOST_WIDE_INT_M1U}. 2840fc04c29Smrg 2850fc04c29Smrg@item IntegerRange(@var{n}, @var{m}) 2860fc04c29SmrgThe options's arguments are integers of type @code{int}. The option's 2870fc04c29Smrgparser validates that the value of an option integer argument is within 2880fc04c29Smrgthe closed range [@var{n}, @var{m}]. 2890fc04c29Smrg 2900fc04c29Smrg@item ByteSize 2910fc04c29SmrgA property applicable only to @code{UInteger} or @code{Host_Wide_Int} 2920fc04c29Smrgarguments. The option's integer argument is interpreted as if in infinite 2930fc04c29Smrgprecision using saturation arithmetic in the corresponding type. The argument 2940fc04c29Smrgmay be followed by a @samp{byte-size} suffix designating a multiple of bytes 2950fc04c29Smrgsuch as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively, 2960fc04c29Smrg@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and @code{GiB} 2970fc04c29Smrgfor gigabyte and gigibyte, and so on. @code{ByteSize} should be used for 2980fc04c29Smrgwith options that take a very large argument representing a size in bytes, 2990fc04c29Smrgsuch as @option{-Wlarger-than=}. 30010d565efSmrg 30110d565efSmrg@item ToLower 30210d565efSmrgThe option's argument should be converted to lowercase as part of 30310d565efSmrgputting it in canonical form, and before comparing with the strings 30410d565efSmrgindicated by any @code{Enum} property. 30510d565efSmrg 30610d565efSmrg@item NoDriverArg 30710d565efSmrgFor an option marked @code{Separate}, the option only takes an 30810d565efSmrgargument in the compiler proper, not in the driver. This is for 30910d565efSmrgcompatibility with existing options that are used both directly and 31010d565efSmrgvia @option{-Wp,}; new options should not have this property. 31110d565efSmrg 31210d565efSmrg@item Var(@var{var}) 31310d565efSmrgThe state of this option should be stored in variable @var{var} 31410d565efSmrg(actually a macro for @code{global_options.x_@var{var}}). 31510d565efSmrgThe way that the state is stored depends on the type of option: 31610d565efSmrg 317*ec02198aSmrg@item WarnRemoved 318*ec02198aSmrgThe option is removed and every usage of such option will 319*ec02198aSmrgresult in a warning. We use it option backward compatibility. 3200fc04c29Smrg 3210fc04c29Smrg@item Var(@var{var}, @var{set}) 3220fc04c29SmrgThe option controls an integer variable @var{var} and is active when 3230fc04c29Smrg@var{var} equals @var{set}. The option parser will set @var{var} to 3240fc04c29Smrg@var{set} when the positive form of the option is used and @code{!@var{set}} 3250fc04c29Smrgwhen the ``no-'' form is used. 3260fc04c29Smrg 3270fc04c29Smrg@var{var} is declared in the same way as for the single-argument form 3280fc04c29Smrgdescribed above. 3290fc04c29Smrg 33010d565efSmrg@itemize @bullet 33110d565efSmrg@item 33210d565efSmrgIf the option uses the @code{Mask} or @code{InverseMask} properties, 33310d565efSmrg@var{var} is the integer variable that contains the mask. 33410d565efSmrg 33510d565efSmrg@item 33610d565efSmrgIf the option is a normal on/off switch, @var{var} is an integer 33710d565efSmrgvariable that is nonzero when the option is enabled. The options 33810d565efSmrgparser will set the variable to 1 when the positive form of the 33910d565efSmrgoption is used and 0 when the ``no-'' form is used. 34010d565efSmrg 34110d565efSmrg@item 34210d565efSmrgIf the option takes an argument and has the @code{UInteger} property, 34310d565efSmrg@var{var} is an integer variable that stores the value of the argument. 34410d565efSmrg 34510d565efSmrg@item 34610d565efSmrgIf the option takes an argument and has the @code{Enum} property, 34710d565efSmrg@var{var} is a variable (type given in the @code{Type} property of the 34810d565efSmrg@samp{Enum} record whose @code{Name} property has the same argument as 34910d565efSmrgthe @code{Enum} property of this option) that stores the value of the 35010d565efSmrgargument. 35110d565efSmrg 35210d565efSmrg@item 35310d565efSmrgIf the option has the @code{Defer} property, @var{var} is a pointer to 35410d565efSmrga @code{VEC(cl_deferred_option,heap)} that stores the option for later 35510d565efSmrgprocessing. (@var{var} is declared with type @code{void *} and needs 35610d565efSmrgto be cast to @code{VEC(cl_deferred_option,heap)} before use.) 35710d565efSmrg 35810d565efSmrg@item 35910d565efSmrgOtherwise, if the option takes an argument, @var{var} is a pointer to 36010d565efSmrgthe argument string. The pointer will be null if the argument is optional 36110d565efSmrgand wasn't given. 36210d565efSmrg@end itemize 36310d565efSmrg 36410d565efSmrgThe option-processing script will usually zero-initialize @var{var}. 36510d565efSmrgYou can modify this behavior using @code{Init}. 36610d565efSmrg 36710d565efSmrg@item Init(@var{value}) 36810d565efSmrgThe variable specified by the @code{Var} property should be statically 36910d565efSmrginitialized to @var{value}. If more than one option using the same 37010d565efSmrgvariable specifies @code{Init}, all must specify the same initializer. 37110d565efSmrg 37210d565efSmrg@item Mask(@var{name}) 37310d565efSmrgThe option is associated with a bit in the @code{target_flags} 37410d565efSmrgvariable (@pxref{Run-time Target}) and is active when that bit is set. 37510d565efSmrgYou may also specify @code{Var} to select a variable other than 37610d565efSmrg@code{target_flags}. 37710d565efSmrg 37810d565efSmrgThe options-processing script will automatically allocate a unique bit 37910d565efSmrgfor the option. If the option is attached to @samp{target_flags}, 38010d565efSmrgthe script will set the macro @code{MASK_@var{name}} to the appropriate 38110d565efSmrgbitmask. It will also declare a @code{TARGET_@var{name}} macro that has 38210d565efSmrgthe value 1 when the option is active and 0 otherwise. If you use @code{Var} 38310d565efSmrgto attach the option to a different variable, the bitmask macro with be 38410d565efSmrgcalled @code{OPTION_MASK_@var{name}}. 38510d565efSmrg 38610d565efSmrg@item InverseMask(@var{othername}) 38710d565efSmrg@itemx InverseMask(@var{othername}, @var{thisname}) 38810d565efSmrgThe option is the inverse of another option that has the 38910d565efSmrg@code{Mask(@var{othername})} property. If @var{thisname} is given, 39010d565efSmrgthe options-processing script will declare a @code{TARGET_@var{thisname}} 39110d565efSmrgmacro that is 1 when the option is active and 0 otherwise. 39210d565efSmrg 39310d565efSmrg@item Enum(@var{name}) 39410d565efSmrgThe option's argument is a string from the set of strings associated 39510d565efSmrgwith the corresponding @samp{Enum} record. The string is checked and 39610d565efSmrgconverted to the integer specified in the corresponding 39710d565efSmrg@samp{EnumValue} record before being passed to option handlers. 39810d565efSmrg 39910d565efSmrg@item Defer 40010d565efSmrgThe option should be stored in a vector, specified with @code{Var}, 40110d565efSmrgfor later processing. 40210d565efSmrg 40310d565efSmrg@item Alias(@var{opt}) 40410d565efSmrg@itemx Alias(@var{opt}, @var{arg}) 40510d565efSmrg@itemx Alias(@var{opt}, @var{posarg}, @var{negarg}) 40610d565efSmrgThe option is an alias for @option{-@var{opt}} (or the negative form 40710d565efSmrgof that option, depending on @code{NegativeAlias}). In the first form, 40810d565efSmrgany argument passed to the alias is considered to be passed to 40910d565efSmrg@option{-@var{opt}}, and @option{-@var{opt}} is considered to be 41010d565efSmrgnegated if the alias is used in negated form. In the second form, the 41110d565efSmrgalias may not be negated or have an argument, and @var{posarg} is 41210d565efSmrgconsidered to be passed as an argument to @option{-@var{opt}}. In the 41310d565efSmrgthird form, the alias may not have an argument, if the alias is used 41410d565efSmrgin the positive form then @var{posarg} is considered to be passed to 41510d565efSmrg@option{-@var{opt}}, and if the alias is used in the negative form 41610d565efSmrgthen @var{negarg} is considered to be passed to @option{-@var{opt}}. 41710d565efSmrg 41810d565efSmrgAliases should not specify @code{Var} or @code{Mask} or 41910d565efSmrg@code{UInteger}. Aliases should normally specify the same languages 42010d565efSmrgas the target of the alias; the flags on the target will be used to 42110d565efSmrgdetermine any diagnostic for use of an option for the wrong language, 42210d565efSmrgwhile those on the alias will be used to identify what command-line 42310d565efSmrgtext is the option and what text is any argument to that option. 42410d565efSmrg 42510d565efSmrgWhen an @code{Alias} definition is used for an option, driver specs do 42610d565efSmrgnot need to handle it and no @samp{OPT_} enumeration value is defined 42710d565efSmrgfor it; only the canonical form of the option will be seen in those 42810d565efSmrgplaces. 42910d565efSmrg 43010d565efSmrg@item NegativeAlias 43110d565efSmrgFor an option marked with @code{Alias(@var{opt})}, the option is 43210d565efSmrgconsidered to be an alias for the positive form of @option{-@var{opt}} 43310d565efSmrgif negated and for the negative form of @option{-@var{opt}} if not 43410d565efSmrgnegated. @code{NegativeAlias} may not be used with the forms of 43510d565efSmrg@code{Alias} taking more than one argument. 43610d565efSmrg 43710d565efSmrg@item Ignore 43810d565efSmrgThis option is ignored apart from printing any warning specified using 43910d565efSmrg@code{Warn}. The option will not be seen by specs and no @samp{OPT_} 44010d565efSmrgenumeration value is defined for it. 44110d565efSmrg 44210d565efSmrg@item SeparateAlias 44310d565efSmrgFor an option marked with @code{Joined}, @code{Separate} and 44410d565efSmrg@code{Alias}, the option only acts as an alias when passed a separate 44510d565efSmrgargument; with a joined argument it acts as a normal option, with an 44610d565efSmrg@samp{OPT_} enumeration value. This is for compatibility with the 44710d565efSmrgJava @option{-d} option and should not be used for new options. 44810d565efSmrg 44910d565efSmrg@item Warn(@var{message}) 45010d565efSmrgIf this option is used, output the warning @var{message}. 45110d565efSmrg@var{message} is a format string, either taking a single operand with 45210d565efSmrga @samp{%qs} format which is the option name, or not taking any 45310d565efSmrgoperands, which is passed to the @samp{warning} function. If an alias 45410d565efSmrgis marked @code{Warn}, the target of the alias must not also be marked 45510d565efSmrg@code{Warn}. 45610d565efSmrg 45710d565efSmrg@item Report 45810d565efSmrgThe state of the option should be printed by @option{-fverbose-asm}. 45910d565efSmrg 46010d565efSmrg@item Warning 46110d565efSmrgThis is a warning option and should be shown as such in 46210d565efSmrg@option{--help} output. This flag does not currently affect anything 46310d565efSmrgother than @option{--help}. 46410d565efSmrg 46510d565efSmrg@item Optimization 46610d565efSmrgThis is an optimization option. It should be shown as such in 46710d565efSmrg@option{--help} output, and any associated variable named using 46810d565efSmrg@code{Var} should be saved and restored when the optimization level is 46910d565efSmrgchanged with @code{optimize} attributes. 47010d565efSmrg 47110d565efSmrg@item PerFunction 47210d565efSmrgThis is an option that can be overridden on a per-function basis. 47310d565efSmrg@code{Optimization} implies @code{PerFunction}, but options that do not 47410d565efSmrgaffect executable code generation may use this flag instead, so that the 47510d565efSmrgoption is not taken into account in ways that might affect executable 47610d565efSmrgcode generation. 47710d565efSmrg 478*ec02198aSmrg@item Param 479*ec02198aSmrgThis is an option that is a parameter. 480*ec02198aSmrg 48110d565efSmrg@item Undocumented 48210d565efSmrgThe option is deliberately missing documentation and should not 48310d565efSmrgbe included in the @option{--help} output. 48410d565efSmrg 48510d565efSmrg@item Condition(@var{cond}) 48610d565efSmrgThe option should only be accepted if preprocessor condition 48710d565efSmrg@var{cond} is true. Note that any C declarations associated with the 48810d565efSmrgoption will be present even if @var{cond} is false; @var{cond} simply 48910d565efSmrgcontrols whether the option is accepted and whether it is printed in 49010d565efSmrgthe @option{--help} output. 49110d565efSmrg 49210d565efSmrg@item Save 49310d565efSmrgBuild the @code{cl_target_option} structure to hold a copy of the 49410d565efSmrgoption, add the functions @code{cl_target_option_save} and 49510d565efSmrg@code{cl_target_option_restore} to save and restore the options. 49610d565efSmrg 49710d565efSmrg@item SetByCombined 49810d565efSmrgThe option may also be set by a combined option such as 49910d565efSmrg@option{-ffast-math}. This causes the @code{gcc_options} struct to 50010d565efSmrghave a field @code{frontend_set_@var{name}}, where @code{@var{name}} 50110d565efSmrgis the name of the field holding the value of this option (without the 50210d565efSmrgleading @code{x_}). This gives the front end a way to indicate that 50310d565efSmrgthe value has been set explicitly and should not be changed by the 50410d565efSmrgcombined option. For example, some front ends use this to prevent 50510d565efSmrg@option{-ffast-math} and @option{-fno-fast-math} from changing the 50610d565efSmrgvalue of @option{-fmath-errno} for languages that do not use 50710d565efSmrg@code{errno}. 50810d565efSmrg 50910d565efSmrg@item EnabledBy(@var{opt}) 51010d565efSmrg@itemx EnabledBy(@var{opt} || @var{opt2}) 51110d565efSmrg@itemx EnabledBy(@var{opt} && @var{opt2}) 51210d565efSmrgIf not explicitly set, the option is set to the value of 51310d565efSmrg@option{-@var{opt}}; multiple options can be given, separated by 51410d565efSmrg@code{||}. The third form using @code{&&} specifies that the option is 51510d565efSmrgonly set if both @var{opt} and @var{opt2} are set. The options @var{opt} 51610d565efSmrgand @var{opt2} must have the @code{Common} property; otherwise, use 51710d565efSmrg@code{LangEnabledBy}. 51810d565efSmrg 51910d565efSmrg@item LangEnabledBy(@var{language}, @var{opt}) 52010d565efSmrg@itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg}) 52110d565efSmrgWhen compiling for the given language, the option is set to the value 52210d565efSmrgof @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list 52310d565efSmrgof @code{||} separated options. In the second form, if 52410d565efSmrg@var{opt} is used in the positive form then @var{posarg} is considered 52510d565efSmrgto be passed to the option, and if @var{opt} is used in the negative 52610d565efSmrgform then @var{negarg} is considered to be passed to the option. It 52710d565efSmrgis possible to specify several different languages. Each 52810d565efSmrg@var{language} must have been declared by an earlier @code{Language} 52910d565efSmrgrecord. @xref{Option file format}. 53010d565efSmrg 53110d565efSmrg@item NoDWARFRecord 53210d565efSmrgThe option is omitted from the producer string written by 53310d565efSmrg@option{-grecord-gcc-switches}. 53410d565efSmrg 53510d565efSmrg@item PchIgnore 53610d565efSmrgEven if this is a target option, this option will not be recorded / compared 53710d565efSmrgto determine if a precompiled header file matches. 53810d565efSmrg 53910d565efSmrg@item CPP(@var{var}) 54010d565efSmrgThe state of this option should be kept in sync with the preprocessor 54110d565efSmrgoption @var{var}. If this property is set, then properties @code{Var} 54210d565efSmrgand @code{Init} must be set as well. 54310d565efSmrg 54410d565efSmrg@item CppReason(@var{CPP_W_Enum}) 54510d565efSmrgThis warning option corresponds to @code{cpplib.h} warning reason code 54610d565efSmrg@var{CPP_W_Enum}. This should only be used for warning options of the 54710d565efSmrgC-family front-ends. 54810d565efSmrg 54910d565efSmrg@end table 550