1@c Copyright (C) 2003-2020 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@node Options 6@chapter Option specification files 7@cindex option specification files 8@cindex @samp{optc-gen.awk} 9 10Most GCC command-line options are described by special option 11definition files, the names of which conventionally end in 12@code{.opt}. This chapter describes the format of these files. 13 14@menu 15* Option file format:: The general layout of the files 16* Option properties:: Supported option properties 17@end menu 18 19@node Option file format 20@section Option file format 21 22Option files are a simple list of records in which each field occupies 23its own line and in which the records themselves are separated by 24blank lines. Comments may appear on their own line anywhere within 25the file and are preceded by semicolons. Whitespace is allowed before 26the semicolon. 27 28The files can contain the following types of record: 29 30@itemize @bullet 31@item 32A language definition record. These records have two fields: the 33string @samp{Language} and the name of the language. Once a language 34has been declared in this way, it can be used as an option property. 35@xref{Option properties}. 36 37@item 38A target specific save record to save additional information. These 39records have two fields: the string @samp{TargetSave}, and a 40declaration type to go in the @code{cl_target_option} structure. 41 42@item 43A variable record to define a variable used to store option 44information. These records have two fields: the string 45@samp{Variable}, and a declaration of the type and name of the 46variable, optionally with an initializer (but without any trailing 47@samp{;}). These records may be used for variables used for many 48options where declaring the initializer in a single option definition 49record, or duplicating it in many records, would be inappropriate, or 50for variables set in option handlers rather than referenced by 51@code{Var} properties. 52 53@item 54A variable record to define a variable used to store option 55information. These records have two fields: the string 56@samp{TargetVariable}, and a declaration of the type and name of the 57variable, optionally with an initializer (but without any trailing 58@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable} 59and @samp{TargetSave} records in that the variable is defined in the 60@code{gcc_options} structure, but these variables are also stored in 61the @code{cl_target_option} structure. The variables are saved in the 62target save code and restored in the target restore code. 63 64@item 65A variable record to record any additional files that the 66@file{options.h} file should include. This is useful to provide 67enumeration or structure definitions needed for target variables. 68These records have two fields: the string @samp{HeaderInclude} and the 69name of the include file. 70 71@item 72A variable record to record any additional files that the 73@file{options.c} or @file{options-save.c} file should include. This 74is useful to provide 75inline functions needed for target variables and/or @code{#ifdef} 76sequences to properly set up the initialization. These records have 77two fields: the string @samp{SourceInclude} and the name of the 78include file. 79 80@item 81An enumeration record to define a set of strings that may be used as 82arguments to an option or options. These records have three fields: 83the string @samp{Enum}, a space-separated list of properties and help 84text used to describe the set of strings in @option{--help} output. 85Properties use the same format as option properties; the following are 86valid: 87@table @code 88@item Name(@var{name}) 89This property is required; @var{name} must be a name (suitable for use 90in C identifiers) used to identify the set of strings in @code{Enum} 91option properties. 92 93@item Type(@var{type}) 94This property is required; @var{type} is the C type for variables set 95by options using this enumeration together with @code{Var}. 96 97@item UnknownError(@var{message}) 98The message @var{message} will be used as an error message if the 99argument is invalid; for enumerations without @code{UnknownError}, a 100generic error message is used. @var{message} should contain a single 101@samp{%qs} format, which will be used to format the invalid argument. 102@end table 103 104@item 105An enumeration value record to define one of the strings in a set 106given in an @samp{Enum} record. These records have two fields: the 107string @samp{EnumValue} and a space-separated list of properties. 108Properties use the same format as option properties; the following are 109valid: 110@table @code 111@item Enum(@var{name}) 112This property is required; @var{name} says which @samp{Enum} record 113this @samp{EnumValue} record corresponds to. 114 115@item String(@var{string}) 116This property is required; @var{string} is the string option argument 117being described by this record. 118 119@item Value(@var{value}) 120This property is required; it says what value (representable as 121@code{int}) should be used for the given string. 122 123@item Canonical 124This property is optional. If present, it says the present string is 125the canonical one among all those with the given value. Other strings 126yielding that value will be mapped to this one so specs do not need to 127handle them. 128 129@item DriverOnly 130This property is optional. If present, the present string will only 131be accepted by the driver. This is used for cases such as 132@option{-march=native} that are processed by the driver so that 133@samp{gcc -v} shows how the options chosen depended on the system on 134which the compiler was run. 135@end table 136 137@item 138An option definition record. These records have the following fields: 139@enumerate 140@item 141the name of the option, with the leading ``-'' removed 142@item 143a space-separated list of option properties (@pxref{Option properties}) 144@item 145the help text to use for @option{--help} (omitted if the second field 146contains the @code{Undocumented} property). 147@end enumerate 148 149By default, all options beginning with ``f'', ``W'' or ``m'' are 150implicitly assumed to take a ``no-'' form. This form should not be 151listed separately. If an option beginning with one of these letters 152does not have a ``no-'' form, you can use the @code{RejectNegative} 153property to reject it. 154 155The help text is automatically line-wrapped before being displayed. 156Normally the name of the option is printed on the left-hand side of 157the output and the help text is printed on the right. However, if the 158help text contains a tab character, the text to the left of the tab is 159used instead of the option's name and the text to the right of the 160tab forms the help text. This allows you to elaborate on what type 161of argument the option takes. 162 163@item 164A target mask record. These records have one field of the form 165@samp{Mask(@var{x})}. The options-processing script will automatically 166allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for 167each mask name @var{x} and set the macro @code{MASK_@var{x}} to the 168appropriate bitmask. It will also declare a @code{TARGET_@var{x}} 169macro that has the value 1 when bit @code{MASK_@var{x}} is set and 1700 otherwise. 171 172They are primarily intended to declare target masks that are not 173associated with user options, either because these masks represent 174internal switches or because the options are not available on all 175configurations and yet the masks always need to be defined. 176@end itemize 177 178@node Option properties 179@section Option properties 180 181The second field of an option record can specify any of the following 182properties. When an option takes an argument, it is enclosed in parentheses 183following the option property name. The parser that handles option files 184is quite simplistic, and will be tricked by any nested parentheses within 185the argument text itself; in this case, the entire option argument can 186be wrapped in curly braces within the parentheses to demarcate it, e.g.: 187 188@smallexample 189Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@}) 190@end smallexample 191 192@table @code 193@item Common 194The option is available for all languages and targets. 195 196@item Target 197The option is available for all languages but is target-specific. 198 199@item Driver 200The option is handled by the compiler driver using code not shared 201with the compilers proper (@file{cc1} etc.). 202 203@item @var{language} 204The option is available when compiling for the given language. 205 206It is possible to specify several different languages for the same 207option. Each @var{language} must have been declared by an earlier 208@code{Language} record. @xref{Option file format}. 209 210@item RejectDriver 211The option is only handled by the compilers proper (@file{cc1} etc.)@: 212and should not be accepted by the driver. 213 214@item RejectNegative 215The option does not have a ``no-'' form. All options beginning with 216``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this 217property is used. 218 219@item Negative(@var{othername}) 220The option will turn off another option @var{othername}, which is 221the option name with the leading ``-'' removed. This chain action will 222propagate through the @code{Negative} property of the option to be 223turned off. The driver will prune options, removing those that are 224turned off by some later option. This pruning is not done for options 225with @code{Joined} or @code{JoinedOrMissing} properties, unless the 226options have either @code{RejectNegative} property or the @code{Negative} 227property mentions an option other than itself. 228 229As a consequence, if you have a group of mutually-exclusive 230options, their @code{Negative} properties should form a circular chain. 231For example, if options @option{-@var{a}}, @option{-@var{b}} and 232@option{-@var{c}} are mutually exclusive, their respective @code{Negative} 233properties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})} 234and @samp{Negative(@var{a})}. 235 236@item Joined 237@itemx Separate 238The option takes a mandatory argument. @code{Joined} indicates 239that the option and argument can be included in the same @code{argv} 240entry (as with @code{-mflush-func=@var{name}}, for example). 241@code{Separate} indicates that the option and argument can be 242separate @code{argv} entries (as with @code{-o}). An option is 243allowed to have both of these properties. 244 245@item JoinedOrMissing 246The option takes an optional argument. If the argument is given, 247it will be part of the same @code{argv} entry as the option itself. 248 249This property cannot be used alongside @code{Joined} or @code{Separate}. 250 251@item MissingArgError(@var{message}) 252For an option marked @code{Joined} or @code{Separate}, the message 253@var{message} will be used as an error message if the mandatory 254argument is missing; for options without @code{MissingArgError}, a 255generic error message is used. @var{message} should contain a single 256@samp{%qs} format, which will be used to format the name of the option 257passed. 258 259@item Args(@var{n}) 260For an option marked @code{Separate}, indicate that it takes @var{n} 261arguments. The default is 1. 262 263@item UInteger 264The option's argument is a non-negative integer consisting of either 265decimal or hexadecimal digits interpreted as @code{int}. Hexadecimal 266integers may optionally start with the @code{0x} or @code{0X} prefix. 267The option parser validates and converts the argument before passing 268it to the relevant option handler. @code{UInteger} should also be used 269with options like @code{-falign-loops} where both @code{-falign-loops} 270and @code{-falign-loops}=@var{n} are supported to make sure the saved 271options are given a full integer. Positive values of the argument in 272excess of @code{INT_MAX} wrap around zero. 273 274@item Host_Wide_Int 275The option's argument is a non-negative integer consisting of either 276decimal or hexadecimal digits interpreted as the widest integer type 277on the host. As with an @code{UInteger} argument, hexadecimal integers 278may optionally start with the @code{0x} or @code{0X} prefix. The option 279parser validates and converts the argument before passing it to 280the relevant option handler. @code{Host_Wide_Int} should be used with 281options that need to accept very large values. Positive values of 282the argument in excess of @code{HOST_WIDE_INT_M1U} are assigned 283@code{HOST_WIDE_INT_M1U}. 284 285@item IntegerRange(@var{n}, @var{m}) 286The options's arguments are integers of type @code{int}. The option's 287parser validates that the value of an option integer argument is within 288the closed range [@var{n}, @var{m}]. 289 290@item ByteSize 291A property applicable only to @code{UInteger} or @code{Host_Wide_Int} 292arguments. The option's integer argument is interpreted as if in infinite 293precision using saturation arithmetic in the corresponding type. The argument 294may be followed by a @samp{byte-size} suffix designating a multiple of bytes 295such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively, 296@code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and @code{GiB} 297for gigabyte and gigibyte, and so on. @code{ByteSize} should be used for 298with options that take a very large argument representing a size in bytes, 299such as @option{-Wlarger-than=}. 300 301@item ToLower 302The option's argument should be converted to lowercase as part of 303putting it in canonical form, and before comparing with the strings 304indicated by any @code{Enum} property. 305 306@item NoDriverArg 307For an option marked @code{Separate}, the option only takes an 308argument in the compiler proper, not in the driver. This is for 309compatibility with existing options that are used both directly and 310via @option{-Wp,}; new options should not have this property. 311 312@item Var(@var{var}) 313The state of this option should be stored in variable @var{var} 314(actually a macro for @code{global_options.x_@var{var}}). 315The way that the state is stored depends on the type of option: 316 317@item WarnRemoved 318The option is removed and every usage of such option will 319result in a warning. We use it option backward compatibility. 320 321@item Var(@var{var}, @var{set}) 322The option controls an integer variable @var{var} and is active when 323@var{var} equals @var{set}. The option parser will set @var{var} to 324@var{set} when the positive form of the option is used and @code{!@var{set}} 325when the ``no-'' form is used. 326 327@var{var} is declared in the same way as for the single-argument form 328described above. 329 330@itemize @bullet 331@item 332If the option uses the @code{Mask} or @code{InverseMask} properties, 333@var{var} is the integer variable that contains the mask. 334 335@item 336If the option is a normal on/off switch, @var{var} is an integer 337variable that is nonzero when the option is enabled. The options 338parser will set the variable to 1 when the positive form of the 339option is used and 0 when the ``no-'' form is used. 340 341@item 342If the option takes an argument and has the @code{UInteger} property, 343@var{var} is an integer variable that stores the value of the argument. 344 345@item 346If the option takes an argument and has the @code{Enum} property, 347@var{var} is a variable (type given in the @code{Type} property of the 348@samp{Enum} record whose @code{Name} property has the same argument as 349the @code{Enum} property of this option) that stores the value of the 350argument. 351 352@item 353If the option has the @code{Defer} property, @var{var} is a pointer to 354a @code{VEC(cl_deferred_option,heap)} that stores the option for later 355processing. (@var{var} is declared with type @code{void *} and needs 356to be cast to @code{VEC(cl_deferred_option,heap)} before use.) 357 358@item 359Otherwise, if the option takes an argument, @var{var} is a pointer to 360the argument string. The pointer will be null if the argument is optional 361and wasn't given. 362@end itemize 363 364The option-processing script will usually zero-initialize @var{var}. 365You can modify this behavior using @code{Init}. 366 367@item Init(@var{value}) 368The variable specified by the @code{Var} property should be statically 369initialized to @var{value}. If more than one option using the same 370variable specifies @code{Init}, all must specify the same initializer. 371 372@item Mask(@var{name}) 373The option is associated with a bit in the @code{target_flags} 374variable (@pxref{Run-time Target}) and is active when that bit is set. 375You may also specify @code{Var} to select a variable other than 376@code{target_flags}. 377 378The options-processing script will automatically allocate a unique bit 379for the option. If the option is attached to @samp{target_flags}, 380the script will set the macro @code{MASK_@var{name}} to the appropriate 381bitmask. It will also declare a @code{TARGET_@var{name}} macro that has 382the value 1 when the option is active and 0 otherwise. If you use @code{Var} 383to attach the option to a different variable, the bitmask macro with be 384called @code{OPTION_MASK_@var{name}}. 385 386@item InverseMask(@var{othername}) 387@itemx InverseMask(@var{othername}, @var{thisname}) 388The option is the inverse of another option that has the 389@code{Mask(@var{othername})} property. If @var{thisname} is given, 390the options-processing script will declare a @code{TARGET_@var{thisname}} 391macro that is 1 when the option is active and 0 otherwise. 392 393@item Enum(@var{name}) 394The option's argument is a string from the set of strings associated 395with the corresponding @samp{Enum} record. The string is checked and 396converted to the integer specified in the corresponding 397@samp{EnumValue} record before being passed to option handlers. 398 399@item Defer 400The option should be stored in a vector, specified with @code{Var}, 401for later processing. 402 403@item Alias(@var{opt}) 404@itemx Alias(@var{opt}, @var{arg}) 405@itemx Alias(@var{opt}, @var{posarg}, @var{negarg}) 406The option is an alias for @option{-@var{opt}} (or the negative form 407of that option, depending on @code{NegativeAlias}). In the first form, 408any argument passed to the alias is considered to be passed to 409@option{-@var{opt}}, and @option{-@var{opt}} is considered to be 410negated if the alias is used in negated form. In the second form, the 411alias may not be negated or have an argument, and @var{posarg} is 412considered to be passed as an argument to @option{-@var{opt}}. In the 413third form, the alias may not have an argument, if the alias is used 414in the positive form then @var{posarg} is considered to be passed to 415@option{-@var{opt}}, and if the alias is used in the negative form 416then @var{negarg} is considered to be passed to @option{-@var{opt}}. 417 418Aliases should not specify @code{Var} or @code{Mask} or 419@code{UInteger}. Aliases should normally specify the same languages 420as the target of the alias; the flags on the target will be used to 421determine any diagnostic for use of an option for the wrong language, 422while those on the alias will be used to identify what command-line 423text is the option and what text is any argument to that option. 424 425When an @code{Alias} definition is used for an option, driver specs do 426not need to handle it and no @samp{OPT_} enumeration value is defined 427for it; only the canonical form of the option will be seen in those 428places. 429 430@item NegativeAlias 431For an option marked with @code{Alias(@var{opt})}, the option is 432considered to be an alias for the positive form of @option{-@var{opt}} 433if negated and for the negative form of @option{-@var{opt}} if not 434negated. @code{NegativeAlias} may not be used with the forms of 435@code{Alias} taking more than one argument. 436 437@item Ignore 438This option is ignored apart from printing any warning specified using 439@code{Warn}. The option will not be seen by specs and no @samp{OPT_} 440enumeration value is defined for it. 441 442@item SeparateAlias 443For an option marked with @code{Joined}, @code{Separate} and 444@code{Alias}, the option only acts as an alias when passed a separate 445argument; with a joined argument it acts as a normal option, with an 446@samp{OPT_} enumeration value. This is for compatibility with the 447Java @option{-d} option and should not be used for new options. 448 449@item Warn(@var{message}) 450If this option is used, output the warning @var{message}. 451@var{message} is a format string, either taking a single operand with 452a @samp{%qs} format which is the option name, or not taking any 453operands, which is passed to the @samp{warning} function. If an alias 454is marked @code{Warn}, the target of the alias must not also be marked 455@code{Warn}. 456 457@item Report 458The state of the option should be printed by @option{-fverbose-asm}. 459 460@item Warning 461This is a warning option and should be shown as such in 462@option{--help} output. This flag does not currently affect anything 463other than @option{--help}. 464 465@item Optimization 466This is an optimization option. It should be shown as such in 467@option{--help} output, and any associated variable named using 468@code{Var} should be saved and restored when the optimization level is 469changed with @code{optimize} attributes. 470 471@item PerFunction 472This is an option that can be overridden on a per-function basis. 473@code{Optimization} implies @code{PerFunction}, but options that do not 474affect executable code generation may use this flag instead, so that the 475option is not taken into account in ways that might affect executable 476code generation. 477 478@item Param 479This is an option that is a parameter. 480 481@item Undocumented 482The option is deliberately missing documentation and should not 483be included in the @option{--help} output. 484 485@item Condition(@var{cond}) 486The option should only be accepted if preprocessor condition 487@var{cond} is true. Note that any C declarations associated with the 488option will be present even if @var{cond} is false; @var{cond} simply 489controls whether the option is accepted and whether it is printed in 490the @option{--help} output. 491 492@item Save 493Build the @code{cl_target_option} structure to hold a copy of the 494option, add the functions @code{cl_target_option_save} and 495@code{cl_target_option_restore} to save and restore the options. 496 497@item SetByCombined 498The option may also be set by a combined option such as 499@option{-ffast-math}. This causes the @code{gcc_options} struct to 500have a field @code{frontend_set_@var{name}}, where @code{@var{name}} 501is the name of the field holding the value of this option (without the 502leading @code{x_}). This gives the front end a way to indicate that 503the value has been set explicitly and should not be changed by the 504combined option. For example, some front ends use this to prevent 505@option{-ffast-math} and @option{-fno-fast-math} from changing the 506value of @option{-fmath-errno} for languages that do not use 507@code{errno}. 508 509@item EnabledBy(@var{opt}) 510@itemx EnabledBy(@var{opt} || @var{opt2}) 511@itemx EnabledBy(@var{opt} && @var{opt2}) 512If not explicitly set, the option is set to the value of 513@option{-@var{opt}}; multiple options can be given, separated by 514@code{||}. The third form using @code{&&} specifies that the option is 515only set if both @var{opt} and @var{opt2} are set. The options @var{opt} 516and @var{opt2} must have the @code{Common} property; otherwise, use 517@code{LangEnabledBy}. 518 519@item LangEnabledBy(@var{language}, @var{opt}) 520@itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg}) 521When compiling for the given language, the option is set to the value 522of @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list 523of @code{||} separated options. In the second form, if 524@var{opt} is used in the positive form then @var{posarg} is considered 525to be passed to the option, and if @var{opt} is used in the negative 526form then @var{negarg} is considered to be passed to the option. It 527is possible to specify several different languages. Each 528@var{language} must have been declared by an earlier @code{Language} 529record. @xref{Option file format}. 530 531@item NoDWARFRecord 532The option is omitted from the producer string written by 533@option{-grecord-gcc-switches}. 534 535@item PchIgnore 536Even if this is a target option, this option will not be recorded / compared 537to determine if a precompiled header file matches. 538 539@item CPP(@var{var}) 540The state of this option should be kept in sync with the preprocessor 541option @var{var}. If this property is set, then properties @code{Var} 542and @code{Init} must be set as well. 543 544@item CppReason(@var{CPP_W_Enum}) 545This warning option corresponds to @code{cpplib.h} warning reason code 546@var{CPP_W_Enum}. This should only be used for warning options of the 547C-family front-ends. 548 549@end table 550