gcc/doc/options.texi

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