1@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 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 44An option definition record. These records have the following fields: 45@enumerate 46@item 47the name of the option, with the leading ``-'' removed 48@item 49a space-separated list of option properties (@pxref{Option properties}) 50@item 51the help text to use for @option{--help} (omitted if the second field 52contains the @code{Undocumented} property). 53@end enumerate 54 55By default, all options beginning with ``f'', ``W'' or ``m'' are 56implicitly assumed to take a ``no-'' form. This form should not be 57listed separately. If an option beginning with one of these letters 58does not have a ``no-'' form, you can use the @code{RejectNegative} 59property to reject it. 60 61The help text is automatically line-wrapped before being displayed. 62Normally the name of the option is printed on the left-hand side of 63the output and the help text is printed on the right. However, if the 64help text contains a tab character, the text to the left of the tab is 65used instead of the option's name and the text to the right of the 66tab forms the help text. This allows you to elaborate on what type 67of argument the option takes. 68 69@item 70A target mask record. These records have one field of the form 71@samp{Mask(@var{x})}. The options-processing script will automatically 72allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for 73each mask name @var{x} and set the macro @code{MASK_@var{x}} to the 74appropriate bitmask. It will also declare a @code{TARGET_@var{x}} 75macro that has the value 1 when bit @code{MASK_@var{x}} is set and 760 otherwise. 77 78They are primarily intended to declare target masks that are not 79associated with user options, either because these masks represent 80internal switches or because the options are not available on all 81configurations and yet the masks always need to be defined. 82@end itemize 83 84@node Option properties 85@section Option properties 86 87The second field of an option record can specify any of the following 88properties. When an option takes an argument, it is enclosed in parentheses 89following the option property name. The parser that handles option files 90is quite simplistic, and will be tricked by any nested parentheses within 91the argument text itself; in this case, the entire option argument can 92be wrapped in curly braces within the parentheses to demarcate it, e.g.: 93 94@smallexample 95Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@}) 96@end smallexample 97 98@table @code 99@item Common 100The option is available for all languages and targets. 101 102@item Target 103The option is available for all languages but is target-specific. 104 105@item @var{language} 106The option is available when compiling for the given language. 107 108It is possible to specify several different languages for the same 109option. Each @var{language} must have been declared by an earlier 110@code{Language} record. @xref{Option file format}. 111 112@item RejectNegative 113The option does not have a ``no-'' form. All options beginning with 114``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this 115property is used. 116 117@item Negative(@var{othername}) 118The option will turn off another option @var{othername}, which is 119the option name with the leading ``-'' removed. This chain action will 120propagate through the @code{Negative} property of the option to be 121turned off. 122 123@item Joined 124@itemx Separate 125The option takes a mandatory argument. @code{Joined} indicates 126that the option and argument can be included in the same @code{argv} 127entry (as with @code{-mflush-func=@var{name}}, for example). 128@code{Separate} indicates that the option and argument can be 129separate @code{argv} entries (as with @code{-o}). An option is 130allowed to have both of these properties. 131 132@item JoinedOrMissing 133The option takes an optional argument. If the argument is given, 134it will be part of the same @code{argv} entry as the option itself. 135 136This property cannot be used alongside @code{Joined} or @code{Separate}. 137 138@item UInteger 139The option's argument is a non-negative integer. The option parser 140will check and convert the argument before passing it to the relevant 141option handler. @code{UInteger} should also be used on options like 142@code{-falign-loops} where both @code{-falign-loops} and 143@code{-falign-loops}=@var{n} are supported to make sure the saved 144options are given a full integer. 145 146@item Var(@var{var}) 147The state of this option should be stored in variable @var{var}. 148The way that the state is stored depends on the type of option: 149 150@itemize @bullet 151@item 152If the option uses the @code{Mask} or @code{InverseMask} properties, 153@var{var} is the integer variable that contains the mask. 154 155@item 156If the option is a normal on/off switch, @var{var} is an integer 157variable that is nonzero when the option is enabled. The options 158parser will set the variable to 1 when the positive form of the 159option is used and 0 when the ``no-'' form is used. 160 161@item 162If the option takes an argument and has the @code{UInteger} property, 163@var{var} is an integer variable that stores the value of the argument. 164 165@item 166Otherwise, if the option takes an argument, @var{var} is a pointer to 167the argument string. The pointer will be null if the argument is optional 168and wasn't given. 169@end itemize 170 171The option-processing script will usually declare @var{var} in 172@file{options.c} and leave it to be zero-initialized at start-up time. 173You can modify this behavior using @code{VarExists} and @code{Init}. 174 175@item Var(@var{var}, @var{set}) 176The option controls an integer variable @var{var} and is active when 177@var{var} equals @var{set}. The option parser will set @var{var} to 178@var{set} when the positive form of the option is used and @code{!@var{set}} 179when the ``no-'' form is used. 180 181@var{var} is declared in the same way as for the single-argument form 182described above. 183 184@item VarExists 185The variable specified by the @code{Var} property already exists. 186No definition should be added to @file{options.c} in response to 187this option record. 188 189You should use this property only if the variable is declared outside 190@file{options.c}. 191 192@item Init(@var{value}) 193The variable specified by the @code{Var} property should be statically 194initialized to @var{value}. 195 196@item Mask(@var{name}) 197The option is associated with a bit in the @code{target_flags} 198variable (@pxref{Run-time Target}) and is active when that bit is set. 199You may also specify @code{Var} to select a variable other than 200@code{target_flags}. 201 202The options-processing script will automatically allocate a unique bit 203for the option. If the option is attached to @samp{target_flags}, 204the script will set the macro @code{MASK_@var{name}} to the appropriate 205bitmask. It will also declare a @code{TARGET_@var{name}} macro that has 206the value 1 when the option is active and 0 otherwise. If you use @code{Var} 207to attach the option to a different variable, the associated macros are 208called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively. 209 210You can disable automatic bit allocation using @code{MaskExists}. 211 212@item InverseMask(@var{othername}) 213@itemx InverseMask(@var{othername}, @var{thisname}) 214The option is the inverse of another option that has the 215@code{Mask(@var{othername})} property. If @var{thisname} is given, 216the options-processing script will declare a @code{TARGET_@var{thisname}} 217macro that is 1 when the option is active and 0 otherwise. 218 219@item MaskExists 220The mask specified by the @code{Mask} property already exists. 221No @code{MASK} or @code{TARGET} definitions should be added to 222@file{options.h} in response to this option record. 223 224The main purpose of this property is to support synonymous options. 225The first option should use @samp{Mask(@var{name})} and the others 226should use @samp{Mask(@var{name}) MaskExists}. 227 228@item Report 229The state of the option should be printed by @option{-fverbose-asm}. 230 231@item Undocumented 232The option is deliberately missing documentation and should not 233be included in the @option{--help} output. 234 235@item Condition(@var{cond}) 236The option should only be accepted if preprocessor condition 237@var{cond} is true. Note that any C declarations associated with the 238option will be present even if @var{cond} is false; @var{cond} simply 239controls whether the option is accepted and whether it is printed in 240the @option{--help} output. 241 242@item Save 243Build the @code{cl_target_option} structure to hold a copy of the 244option, add the functions @code{cl_target_option_save} and 245@code{cl_target_option_restore} to save and restore the options. 246@end table 247