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