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 A variable record to define a variable used to store option
45 information. These records have two fields: the string
46 @samp{Variable}, and a declaration of the type and name of the
47 variable, optionally with an initializer (but without any trailing
48 @samp{;}). These records may be used for variables used for many
49 options where declaring the initializer in a single option definition
50 record, or duplicating it in many records, would be inappropriate, or
51 for variables set in option handlers rather than referenced by
52 @code{Var} properties.
55 An option definition record. These records have the following fields:
58 the name of the option, with the leading ``-'' removed
60 a space-separated list of option properties (@pxref{Option properties})
62 the help text to use for @option{--help} (omitted if the second field
63 contains the @code{Undocumented} property).
66 By default, all options beginning with ``f'', ``W'' or ``m'' are
67 implicitly assumed to take a ``no-'' form. This form should not be
68 listed separately. If an option beginning with one of these letters
69 does not have a ``no-'' form, you can use the @code{RejectNegative}
70 property to reject it.
72 The help text is automatically line-wrapped before being displayed.
73 Normally the name of the option is printed on the left-hand side of
74 the output and the help text is printed on the right. However, if the
75 help text contains a tab character, the text to the left of the tab is
76 used instead of the option's name and the text to the right of the
77 tab forms the help text. This allows you to elaborate on what type
78 of argument the option takes.
81 A target mask record. These records have one field of the form
82 @samp{Mask(@var{x})}. The options-processing script will automatically
83 allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
84 each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
85 appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
86 macro that has the value 1 when bit @code{MASK_@var{x}} is set and
89 They are primarily intended to declare target masks that are not
90 associated with user options, either because these masks represent
91 internal switches or because the options are not available on all
92 configurations and yet the masks always need to be defined.
95 @node Option properties
96 @section Option properties
98 The second field of an option record can specify any of the following
99 properties. When an option takes an argument, it is enclosed in parentheses
100 following the option property name. The parser that handles option files
101 is quite simplistic, and will be tricked by any nested parentheses within
102 the argument text itself; in this case, the entire option argument can
103 be wrapped in curly braces within the parentheses to demarcate it, e.g.:
106 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
111 The option is available for all languages and targets.
114 The option is available for all languages but is target-specific.
117 The option is handled by the compiler driver using code not shared
118 with the compilers proper (@file{cc1} etc.).
121 The option is available when compiling for the given language.
123 It is possible to specify several different languages for the same
124 option. Each @var{language} must have been declared by an earlier
125 @code{Language} record. @xref{Option file format}.
128 The option is only handled by the compilers proper (@file{cc1} etc.)@:
129 and should not be accepted by the driver.
132 The option does not have a ``no-'' form. All options beginning with
133 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
136 @item Negative(@var{othername})
137 The option will turn off another option @var{othername}, which is
138 the option name with the leading ``-'' removed. This chain action will
139 propagate through the @code{Negative} property of the option to be
144 The option takes a mandatory argument. @code{Joined} indicates
145 that the option and argument can be included in the same @code{argv}
146 entry (as with @code{-mflush-func=@var{name}}, for example).
147 @code{Separate} indicates that the option and argument can be
148 separate @code{argv} entries (as with @code{-o}). An option is
149 allowed to have both of these properties.
151 @item JoinedOrMissing
152 The option takes an optional argument. If the argument is given,
153 it will be part of the same @code{argv} entry as the option itself.
155 This property cannot be used alongside @code{Joined} or @code{Separate}.
157 @item MissingArgError(@var{message})
158 For an option marked @code{Joined} or @code{Separate}, the message
159 @var{message} will be used as an error message if the mandatory
160 argument is missing; for options without @code{MissingArgError}, a
161 generic error message is used. @var{message} should contain a single
162 @samp{%qs} format, which will be used to format the name of the option
166 For an option marked @code{Separate}, indicate that it takes @var{n}
167 arguments. The default is 1.
170 The option's argument is a non-negative integer. The option parser
171 will check and convert the argument before passing it to the relevant
172 option handler. @code{UInteger} should also be used on options like
173 @code{-falign-loops} where both @code{-falign-loops} and
174 @code{-falign-loops}=@var{n} are supported to make sure the saved
175 options are given a full integer.
178 For an option marked @code{Separate}, the option only takes an
179 argument in the compiler proper, not in the driver. This is for
180 compatibility with existing options that are used both directly and
181 via @option{-Wp,}; new options should not have this property.
184 The state of this option should be stored in variable @var{var}
185 (actually a macro for @code{global_options.x_@var{var}}).
186 The way that the state is stored depends on the type of option:
190 If the option uses the @code{Mask} or @code{InverseMask} properties,
191 @var{var} is the integer variable that contains the mask.
194 If the option is a normal on/off switch, @var{var} is an integer
195 variable that is nonzero when the option is enabled. The options
196 parser will set the variable to 1 when the positive form of the
197 option is used and 0 when the ``no-'' form is used.
200 If the option takes an argument and has the @code{UInteger} property,
201 @var{var} is an integer variable that stores the value of the argument.
204 Otherwise, if the option takes an argument, @var{var} is a pointer to
205 the argument string. The pointer will be null if the argument is optional
209 The option-processing script will usually zero-initialize @var{var}.
210 You can modify this behavior using @code{Init}.
212 @item Var(@var{var}, @var{set})
213 The option controls an integer variable @var{var} and is active when
214 @var{var} equals @var{set}. The option parser will set @var{var} to
215 @var{set} when the positive form of the option is used and @code{!@var{set}}
216 when the ``no-'' form is used.
218 @var{var} is declared in the same way as for the single-argument form
221 @item Init(@var{value})
222 The variable specified by the @code{Var} property should be statically
223 initialized to @var{value}. If more than one option using the same
224 variable specifies @code{Init}, all must specify the same initializer.
226 @item Mask(@var{name})
227 The option is associated with a bit in the @code{target_flags}
228 variable (@pxref{Run-time Target}) and is active when that bit is set.
229 You may also specify @code{Var} to select a variable other than
232 The options-processing script will automatically allocate a unique bit
233 for the option. If the option is attached to @samp{target_flags},
234 the script will set the macro @code{MASK_@var{name}} to the appropriate
235 bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
236 the value 1 when the option is active and 0 otherwise. If you use @code{Var}
237 to attach the option to a different variable, the associated macros are
238 called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
240 You can disable automatic bit allocation using @code{MaskExists}.
242 @item InverseMask(@var{othername})
243 @itemx InverseMask(@var{othername}, @var{thisname})
244 The option is the inverse of another option that has the
245 @code{Mask(@var{othername})} property. If @var{thisname} is given,
246 the options-processing script will declare a @code{TARGET_@var{thisname}}
247 macro that is 1 when the option is active and 0 otherwise.
250 The mask specified by the @code{Mask} property already exists.
251 No @code{MASK} or @code{TARGET} definitions should be added to
252 @file{options.h} in response to this option record.
254 The main purpose of this property is to support synonymous options.
255 The first option should use @samp{Mask(@var{name})} and the others
256 should use @samp{Mask(@var{name}) MaskExists}.
258 @item Alias(@var{opt})
259 @itemx Alias(@var{opt}, @var{arg})
260 @itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
261 The option is an alias for @option{-@var{opt}}. In the first form,
262 any argument passed to the alias is considered to be passed to
263 @option{-@var{opt}}, and @option{-@var{opt}} is considered to be
264 negated if the alias is used in negated form. In the second form, the
265 alias may not be negated or have an argument, and @var{posarg} is
266 considered to be passed as an argument to @option{-@var{opt}}. In the
267 third form, the alias may not have an argument, if the alias is used
268 in the positive form then @var{posarg} is considered to be passed to
269 @option{-@var{opt}}, and if the alias is used in the negative form
270 then @var{negarg} is considered to be passed to @option{-@var{opt}}.
272 Aliases should not specify @code{Var} or @code{Mask} or
273 @code{UInteger}. Aliases should normally specify the same languages
274 as the target of the alias; the flags on the target will be used to
275 determine any diagnostic for use of an option for the wrong language,
276 while those on the alias will be used to identify what command-line
277 text is the option and what text is any argument to that option.
279 When an @code{Alias} definition is used for an option, driver specs do
280 not need to handle it and no @samp{OPT_} enumeration value is defined
281 for it; only the canonical form of the option will be seen in those
285 This option is ignored apart from printing any warning specified using
286 @code{Warn}. The option will not be seen by specs and no @samp{OPT_}
287 enumeration value is defined for it.
290 For an option marked with @code{Joined}, @code{Separate} and
291 @code{Alias}, the option only acts as an alias when passed a separate
292 argument; with a joined argument it acts as a normal option, with an
293 @samp{OPT_} enumeration value. This is for compatibility with the
294 Java @option{-d} option and should not be used for new options.
296 @item Warn(@var{message})
297 If this option is used, output the warning @var{message}.
298 @var{message} is a format string, either taking a single operand with
299 a @samp{%qs} format which is the option name, or not taking any
300 operands, which is passed to the @samp{warning} function. If an alias
301 is marked @code{Warn}, the target of the alias must not also be marked
305 The state of the option should be printed by @option{-fverbose-asm}.
308 The option is deliberately missing documentation and should not
309 be included in the @option{--help} output.
311 @item Condition(@var{cond})
312 The option should only be accepted if preprocessor condition
313 @var{cond} is true. Note that any C declarations associated with the
314 option will be present even if @var{cond} is false; @var{cond} simply
315 controls whether the option is accepted and whether it is printed in
316 the @option{--help} output.
319 Build the @code{cl_target_option} structure to hold a copy of the
320 option, add the functions @code{cl_target_option_save} and
321 @code{cl_target_option_restore} to save and restore the options.