gcc/doc/options.texi

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