gcc/doc/options.texi

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