options.texi revision 169689
1169689Skan@c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. 2169689Skan@c This is part of the GCC manual. 3169689Skan@c For copying conditions, see the file gcc.texi. 4169689Skan 5169689Skan@node Options 6169689Skan@chapter Option specification files 7169689Skan@cindex option specification files 8169689Skan@cindex @samp{opts.sh} 9169689Skan 10169689SkanMost GCC command-line options are described by special option 11169689Skandefinition files, the names of which conventionally end in 12169689Skan@code{.opt}. This chapter describes the format of these files. 13169689Skan 14169689Skan@menu 15169689Skan* Option file format:: The general layout of the files 16169689Skan* Option properties:: Supported option properties 17169689Skan@end menu 18169689Skan 19169689Skan@node Option file format 20169689Skan@section Option file format 21169689Skan 22169689SkanOption files are a simple list of records in which each field occupies 23169689Skanits own line and in which the records themselves are separated by 24169689Skanblank lines. Comments may appear on their own line anywhere within 25169689Skanthe file and are preceded by semicolons. Whitespace is allowed before 26169689Skanthe semicolon. 27169689Skan 28169689SkanThe files can contain the following types of record: 29169689Skan 30169689Skan@itemize @bullet 31169689Skan@item 32169689SkanA language definition record. �These records have two fields: the 33169689Skanstring @samp{Language} and the name of the language. �Once a language 34169689Skanhas been declared in this way, it can be used as an option property. 35169689Skan@xref{Option properties}. 36169689Skan 37169689Skan@item 38169689SkanAn option definition record. �These records have the following fields: 39169689Skan 40169689Skan@enumerate 41169689Skan@item 42169689Skanthe name of the option, with the leading ``-'' removed 43169689Skan@item 44169689Skana space-separated list of option properties (@pxref{Option properties}) 45169689Skan@item 46169689Skanthe help text to use for @option{--help} (omitted if the second field 47169689Skancontains the @code{Undocumented} property). 48169689Skan@end enumerate 49169689Skan 50169689SkanBy default, all options beginning with ``f'', ``W'' or ``m'' are 51169689Skanimplicitly assumed to take a ``no-'' form. This form should not be 52169689Skanlisted separately. If an option beginning with one of these letters 53169689Skandoes not have a ``no-'' form, you can use the @code{RejectNegative} 54169689Skanproperty to reject it. 55169689Skan 56169689SkanThe help text is automatically line-wrapped before being displayed. 57169689SkanNormally the name of the option is printed on the left-hand side of 58169689Skanthe output and the help text is printed on the right. However, if the 59169689Skanhelp text contains a tab character, the text to the left of the tab is 60169689Skanused instead of the option's name and the text to the right of the 61169689Skantab forms the help text. This allows you to elaborate on what type 62169689Skanof argument the option takes. 63169689Skan 64169689Skan@item 65169689SkanA target mask record. �These records have one field of the form 66169689Skan@samp{Mask(@var{x})}. �The options-processing script will automatically 67169689Skanallocate a bit in @code{target_flags} (@pxref{Run-time Target}) for 68169689Skaneach mask name @var{x} and set the macro @code{MASK_@var{x}} to the 69169689Skanappropriate bitmask. �It will also declare a @code{TARGET_@var{x}} 70169689Skanmacro that has the value 1 when bit @code{MASK_@var{x}} is set and 71169689Skan0 otherwise. 72169689Skan 73169689SkanThey are primarily intended to declare target masks that are not 74169689Skanassociated with user options, either because these masks represent 75169689Skaninternal switches or because the options are not available on all 76169689Skanconfigurations and yet the masks always need to be defined. 77169689Skan@end itemize 78169689Skan 79169689Skan@node Option properties 80169689Skan@section Option properties 81169689Skan 82169689SkanThe second field of an option record can specify the following properties: 83169689Skan 84169689Skan@table @code 85169689Skan@item Common 86169689SkanThe option is available for all languages and targets. 87169689Skan 88169689Skan@item Target 89169689SkanThe option is available for all languages but is target-specific. 90169689Skan 91169689Skan@item @var{language} 92169689SkanThe option is available when compiling for the given language. 93169689Skan 94169689SkanIt is possible to specify several different languages for the same 95169689Skanoption. Each @var{language} must have been declared by an earlier 96169689Skan@code{Language} record. @xref{Option file format}. 97169689Skan 98169689Skan@item RejectNegative 99169689SkanThe option does not have a ``no-'' form. All options beginning with 100169689Skan``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this 101169689Skanproperty is used. 102169689Skan 103169689Skan@item Negative(@var{othername}) 104169689SkanThe option will turn off another option @var{othername}, which is the 105169689Skanthe option name with the leading ``-'' removed. This chain action will 106169689Skanpropagate through the @code{Negative} property of the option to be 107169689Skanturned off. 108169689Skan 109169689Skan@item Joined 110169689Skan@itemx Separate 111169689SkanThe option takes a mandatory argument. @code{Joined} indicates 112169689Skanthat the option and argument can be included in the same @code{argv} 113169689Skanentry (as with @code{-mflush-func=@var{name}}, for example). 114169689Skan@code{Separate} indicates that the option and argument can be 115169689Skanseparate @code{argv} entries (as with @code{-o}). An option is 116169689Skanallowed to have both of these properties. 117169689Skan 118169689Skan@item JoinedOrMissing 119169689SkanThe option takes an optional argument. If the argument is given, 120169689Skanit will be part of the same @code{argv} entry as the option itself. 121169689Skan 122169689SkanThis property cannot be used alongside @code{Joined} or @code{Separate}. 123169689Skan 124169689Skan@item UInteger 125169689SkanThe option's argument is a non-negative integer. The option parser 126169689Skanwill check and convert the argument before passing it to the relevant 127169689Skanoption handler. 128169689Skan 129169689Skan@item Var(@var{var}) 130169689SkanThe state of this option should be stored in variable @var{var}. 131169689SkanThe way that the state is stored depends on the type of option: 132169689Skan 133169689Skan@itemize @bullet 134169689Skan@item 135169689SkanIf the option uses the @code{Mask} or @code{InverseMask} properties, 136169689Skan@var{var} is the integer variable that contains the mask. 137169689Skan 138169689Skan@item 139169689SkanIf the option is a normal on/off switch, @var{var} is an integer 140169689Skanvariable that is nonzero when the option is enabled. The options 141169689Skanparser will set the variable to 1 when the positive form of the 142169689Skanoption is used and 0 when the ``no-'' form is used. 143169689Skan 144169689Skan@item 145169689SkanIf the option takes an argument and has the @code{UInteger} property, 146169689Skan@var{var} is an integer variable that stores the value of the argument. 147169689Skan 148169689Skan@item 149169689SkanOtherwise, if the option takes an argument, @var{var} is a pointer to 150169689Skanthe argument string. The pointer will be null if the argument is optional 151169689Skanand wasn't given. 152169689Skan@end itemize 153169689Skan 154169689SkanThe option-processing script will usually declare @var{var} in 155169689Skan@file{options.c} and leave it to be zero-initialized at start-up time. 156169689SkanYou can modify this behavior using @code{VarExists} and @code{Init}. 157169689Skan 158169689Skan@item Var(@var{var}, @var{set}) 159169689SkanThe option controls an integer variable @var{var} and is active when 160169689Skan@var{var} equals @var{set}. The option parser will set @var{var} to 161169689Skan@var{set} when the positive form of the option is used and @code{!@var{set}} 162169689Skanwhen the ``no-'' form is used. 163169689Skan 164169689Skan@var{var} is declared in the same way as for the single-argument form 165169689Skandescribed above. 166169689Skan 167169689Skan@item VarExists 168169689SkanThe variable specified by the @code{Var} property already exists. 169169689SkanNo definition should be added to @file{options.c} in response to 170169689Skanthis option record. 171169689Skan 172169689SkanYou should use this property only if the variable is declared outside 173169689Skan@file{options.c}. 174169689Skan 175169689Skan@item Init(@var{value}) 176169689SkanThe variable specified by the @code{Var} property should be statically 177169689Skaninitialized to @var{value}. 178169689Skan 179169689Skan@item Mask(@var{name}) 180169689SkanThe option is associated with a bit in the @code{target_flags} 181169689Skanvariable (@pxref{Run-time Target}) and is active when that bit is set. 182169689SkanYou may also specify @code{Var} to select a variable other than 183169689Skan@code{target_flags}. 184169689Skan 185169689SkanThe options-processing script will automatically allocate a unique bit 186169689Skanfor the option. If the option is attached to @samp{target_flags}, 187169689Skanthe script will set the macro @code{MASK_@var{name}} to the appropriate 188169689Skanbitmask. It will also declare a @code{TARGET_@var{name}} macro that has 189169689Skanthe value 1 when the option is active and 0 otherwise. If you use @code{Var} 190169689Skanto attach the option to a different variable, the associated macros are 191169689Skancalled @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively. 192169689Skan 193169689SkanYou can disable automatic bit allocation using @code{MaskExists}. 194169689Skan 195169689Skan@item InverseMask(@var{othername}) 196169689Skan@itemx InverseMask(@var{othername}, @var{thisname}) 197169689SkanThe option is the inverse of another option that has the 198169689Skan@code{Mask(@var{othername})} property. If @var{thisname} is given, 199169689Skanthe options-processing script will declare a @code{TARGET_@var{thisname}} 200169689Skanmacro that is 1 when the option is active and 0 otherwise. 201169689Skan 202169689Skan@item MaskExists 203169689SkanThe mask specified by the @code{Mask} property already exists. 204169689SkanNo @code{MASK} or @code{TARGET} definitions should be added to 205169689Skan@file{options.h} in response to this option record. 206169689Skan 207169689SkanThe main purpose of this property is to support synonymous options. 208169689SkanThe first option should use @samp{Mask(@var{name})} and the others 209169689Skanshould use @samp{Mask(@var{name}) MaskExists}. 210169689Skan 211169689Skan@item Report 212169689SkanThe state of the option should be printed by @option{-fverbose-asm}. 213169689Skan 214169689Skan@item Undocumented 215169689SkanThe option is deliberately missing documentation and should not 216169689Skanbe included in the @option{--help} output. 217169689Skan 218169689Skan@item Condition(@var{cond}) 219169689SkanThe option should only be accepted if preprocessor condition 220169689Skan@var{cond} is true. Note that any C declarations associated with the 221169689Skanoption will be present even if @var{cond} is false; @var{cond} simply 222169689Skancontrols whether the option is accepted and whether it is printed in 223169689Skanthe @option{--help} output. 224169689Skan@end table 225