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.
7 @chapter Option specification files
8 @cindex option specification files
9 @cindex @samp{optc-gen.awk}
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.
16 * Option file format:: The general layout of the files
17 * Option properties:: Supported option properties
20 @node Option file format
21 @section Option file format
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
29 The files can contain the following types of record:
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}.
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.
44 An option definition record. These records have the following fields:
47 the name of the option, with the leading ``-'' removed
49 a space-separated list of option properties (@pxref{Option properties})
51 the help text to use for @option{--help} (omitted if the second field
52 contains the @code{Undocumented} property).
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.
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.
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
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.
84 @node Option properties
85 @section Option properties
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.:
95 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
100 The option is available for all languages and targets.
103 The option is available for all languages but is target-specific.
106 The option is handled by the compiler driver using code not shared
107 with the compilers proper (@file{cc1} etc.).
110 The option is available when compiling for the given language.
112 It is possible to specify several different languages for the same
113 option. Each @var{language} must have been declared by an earlier
114 @code{Language} record. @xref{Option file format}.
117 The option is only handled by the compilers proper (@file{cc1} etc.)@:
118 and should not be accepted by the driver.
121 The option does not have a ``no-'' form. All options beginning with
122 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
125 @item Negative(@var{othername})
126 The option will turn off another option @var{othername}, which is
127 the option name with the leading ``-'' removed. This chain action will
128 propagate through the @code{Negative} property of the option to be
133 The option takes a mandatory argument. @code{Joined} indicates
134 that the option and argument can be included in the same @code{argv}
135 entry (as with @code{-mflush-func=@var{name}}, for example).
136 @code{Separate} indicates that the option and argument can be
137 separate @code{argv} entries (as with @code{-o}). An option is
138 allowed to have both of these properties.
140 @item JoinedOrMissing
141 The option takes an optional argument. If the argument is given,
142 it will be part of the same @code{argv} entry as the option itself.
144 This property cannot be used alongside @code{Joined} or @code{Separate}.
146 @item MissingArgError(@var{message})
147 For an option marked @code{Joined} or @code{Separate}, the message
148 @var{message} will be used as an error message if the mandatory
149 argument is missing; for options without @code{MissingArgError}, a
150 generic error message is used. @var{message} should contain a single
151 @samp{%qs} format, which will be used to format the name of the option
155 The option's argument is a non-negative integer. The option parser
156 will check and convert the argument before passing it to the relevant
157 option handler. @code{UInteger} should also be used on options like
158 @code{-falign-loops} where both @code{-falign-loops} and
159 @code{-falign-loops}=@var{n} are supported to make sure the saved
160 options are given a full integer.
163 The state of this option should be stored in variable @var{var}.
164 The way that the state is stored depends on the type of option:
168 If the option uses the @code{Mask} or @code{InverseMask} properties,
169 @var{var} is the integer variable that contains the mask.
172 If the option is a normal on/off switch, @var{var} is an integer
173 variable that is nonzero when the option is enabled. The options
174 parser will set the variable to 1 when the positive form of the
175 option is used and 0 when the ``no-'' form is used.
178 If the option takes an argument and has the @code{UInteger} property,
179 @var{var} is an integer variable that stores the value of the argument.
182 Otherwise, if the option takes an argument, @var{var} is a pointer to
183 the argument string. The pointer will be null if the argument is optional
187 The option-processing script will usually declare @var{var} in
188 @file{options.c} and leave it to be zero-initialized at start-up time.
189 You can modify this behavior using @code{VarExists} and @code{Init}.
191 @item Var(@var{var}, @var{set})
192 The option controls an integer variable @var{var} and is active when
193 @var{var} equals @var{set}. The option parser will set @var{var} to
194 @var{set} when the positive form of the option is used and @code{!@var{set}}
195 when the ``no-'' form is used.
197 @var{var} is declared in the same way as for the single-argument form
201 The variable specified by the @code{Var} property already exists.
202 No definition should be added to @file{options.c} in response to
205 You should use this property only if the variable is declared outside
208 @item Init(@var{value})
209 The variable specified by the @code{Var} property should be statically
210 initialized to @var{value}.
212 @item Mask(@var{name})
213 The option is associated with a bit in the @code{target_flags}
214 variable (@pxref{Run-time Target}) and is active when that bit is set.
215 You may also specify @code{Var} to select a variable other than
218 The options-processing script will automatically allocate a unique bit
219 for the option. If the option is attached to @samp{target_flags},
220 the script will set the macro @code{MASK_@var{name}} to the appropriate
221 bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
222 the value 1 when the option is active and 0 otherwise. If you use @code{Var}
223 to attach the option to a different variable, the associated macros are
224 called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
226 You can disable automatic bit allocation using @code{MaskExists}.
228 @item InverseMask(@var{othername})
229 @itemx InverseMask(@var{othername}, @var{thisname})
230 The option is the inverse of another option that has the
231 @code{Mask(@var{othername})} property. If @var{thisname} is given,
232 the options-processing script will declare a @code{TARGET_@var{thisname}}
233 macro that is 1 when the option is active and 0 otherwise.
236 The mask specified by the @code{Mask} property already exists.
237 No @code{MASK} or @code{TARGET} definitions should be added to
238 @file{options.h} in response to this option record.
240 The main purpose of this property is to support synonymous options.
241 The first option should use @samp{Mask(@var{name})} and the others
242 should use @samp{Mask(@var{name}) MaskExists}.
245 The state of the option should be printed by @option{-fverbose-asm}.
248 The option is deliberately missing documentation and should not
249 be included in the @option{--help} output.
251 @item Condition(@var{cond})
252 The option should only be accepted if preprocessor condition
253 @var{cond} is true. Note that any C declarations associated with the
254 option will be present even if @var{cond} is false; @var{cond} simply
255 controls whether the option is accepted and whether it is printed in
256 the @option{--help} output.
259 Build the @code{cl_target_option} structure to hold a copy of the
260 option, add the functions @code{cl_target_option_save} and
261 @code{cl_target_option_restore} to save and restore the options.