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