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