gcc/doc/options.texi

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