1 @c Copyright (C) 2003-2014 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Option specification files
7 @cindex option specification files
8 @cindex @samp{optc-gen.awk}
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.
15 * Option file format:: The general layout of the files
16 * Option properties:: Supported option properties
19 @node Option file format
20 @section Option file format
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
28 The files can contain the following types of record:
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}.
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.
43 A variable record to define a variable used to store option
44 information. These records have two fields: the string
45 @samp{Variable}, and a declaration of the type and name of the
46 variable, optionally with an initializer (but without any trailing
47 @samp{;}). These records may be used for variables used for many
48 options where declaring the initializer in a single option definition
49 record, or duplicating it in many records, would be inappropriate, or
50 for variables set in option handlers rather than referenced by
51 @code{Var} properties.
54 A variable record to define a variable used to store option
55 information. These records have two fields: the string
56 @samp{TargetVariable}, and a declaration of the type and name of the
57 variable, optionally with an initializer (but without any trailing
58 @samp{;}). @samp{TargetVariable} is a combination of @samp{Variable}
59 and @samp{TargetSave} records in that the variable is defined in the
60 @code{gcc_options} structure, but these variables are also stored in
61 the @code{cl_target_option} structure. The variables are saved in the
62 target save code and restored in the target restore code.
65 A variable record to record any additional files that the
66 @file{options.h} file should include. This is useful to provide
67 enumeration or structure definitions needed for target variables.
68 These records have two fields: the string @samp{HeaderInclude} and the
69 name of the include file.
72 A variable record to record any additional files that the
73 @file{options.c} or @file{options-save.c} file should include. This
75 inline functions needed for target variables and/or @code{#ifdef}
76 sequences to properly set up the initialization. These records have
77 two fields: the string @samp{SourceInclude} and the name of the
81 An enumeration record to define a set of strings that may be used as
82 arguments to an option or options. These records have three fields:
83 the string @samp{Enum}, a space-separated list of properties and help
84 text used to describe the set of strings in @option{--help} output.
85 Properties use the same format as option properties; the following are
88 @item Name(@var{name})
89 This property is required; @var{name} must be a name (suitable for use
90 in C identifiers) used to identify the set of strings in @code{Enum}
93 @item Type(@var{type})
94 This property is required; @var{type} is the C type for variables set
95 by options using this enumeration together with @code{Var}.
97 @item UnknownError(@var{message})
98 The message @var{message} will be used as an error message if the
99 argument is invalid; for enumerations without @code{UnknownError}, a
100 generic error message is used. @var{message} should contain a single
101 @samp{%qs} format, which will be used to format the invalid argument.
105 An enumeration value record to define one of the strings in a set
106 given in an @samp{Enum} record. These records have two fields: the
107 string @samp{EnumValue} and a space-separated list of properties.
108 Properties use the same format as option properties; the following are
111 @item Enum(@var{name})
112 This property is required; @var{name} says which @samp{Enum} record
113 this @samp{EnumValue} record corresponds to.
115 @item String(@var{string})
116 This property is required; @var{string} is the string option argument
117 being described by this record.
119 @item Value(@var{value})
120 This property is required; it says what value (representable as
121 @code{int}) should be used for the given string.
124 This property is optional. If present, it says the present string is
125 the canonical one among all those with the given value. Other strings
126 yielding that value will be mapped to this one so specs do not need to
130 This property is optional. If present, the present string will only
131 be accepted by the driver. This is used for cases such as
132 @option{-march=native} that are processed by the driver so that
133 @samp{gcc -v} shows how the options chosen depended on the system on
134 which the compiler was run.
138 An option definition record. These records have the following fields:
141 the name of the option, with the leading ``-'' removed
143 a space-separated list of option properties (@pxref{Option properties})
145 the help text to use for @option{--help} (omitted if the second field
146 contains the @code{Undocumented} property).
149 By default, all options beginning with ``f'', ``W'' or ``m'' are
150 implicitly assumed to take a ``no-'' form. This form should not be
151 listed separately. If an option beginning with one of these letters
152 does not have a ``no-'' form, you can use the @code{RejectNegative}
153 property to reject it.
155 The help text is automatically line-wrapped before being displayed.
156 Normally the name of the option is printed on the left-hand side of
157 the output and the help text is printed on the right. However, if the
158 help text contains a tab character, the text to the left of the tab is
159 used instead of the option's name and the text to the right of the
160 tab forms the help text. This allows you to elaborate on what type
161 of argument the option takes.
164 A target mask record. These records have one field of the form
165 @samp{Mask(@var{x})}. The options-processing script will automatically
166 allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
167 each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
168 appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
169 macro that has the value 1 when bit @code{MASK_@var{x}} is set and
172 They are primarily intended to declare target masks that are not
173 associated with user options, either because these masks represent
174 internal switches or because the options are not available on all
175 configurations and yet the masks always need to be defined.
178 @node Option properties
179 @section Option properties
181 The second field of an option record can specify any of the following
182 properties. When an option takes an argument, it is enclosed in parentheses
183 following the option property name. The parser that handles option files
184 is quite simplistic, and will be tricked by any nested parentheses within
185 the argument text itself; in this case, the entire option argument can
186 be wrapped in curly braces within the parentheses to demarcate it, e.g.:
189 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
194 The option is available for all languages and targets.
197 The option is available for all languages but is target-specific.
200 The option is handled by the compiler driver using code not shared
201 with the compilers proper (@file{cc1} etc.).
204 The option is available when compiling for the given language.
206 It is possible to specify several different languages for the same
207 option. Each @var{language} must have been declared by an earlier
208 @code{Language} record. @xref{Option file format}.
211 The option is only handled by the compilers proper (@file{cc1} etc.)@:
212 and should not be accepted by the driver.
215 The option does not have a ``no-'' form. All options beginning with
216 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
219 @item Negative(@var{othername})
220 The option will turn off another option @var{othername}, which is
221 the option name with the leading ``-'' removed. This chain action will
222 propagate through the @code{Negative} property of the option to be
225 As a consequence, if you have a group of mutually-exclusive
226 options, their @code{Negative} properties should form a circular chain.
227 For example, if options @option{-@var{a}}, @option{-@var{b}} and
228 @option{-@var{c}} are mutually exclusive, their respective @code{Negative}
229 properties should be @samp{Negative(@var{b})}, @samp{Negative(@var{c})}
230 and @samp{Negative(@var{a})}.
234 The option takes a mandatory argument. @code{Joined} indicates
235 that the option and argument can be included in the same @code{argv}
236 entry (as with @code{-mflush-func=@var{name}}, for example).
237 @code{Separate} indicates that the option and argument can be
238 separate @code{argv} entries (as with @code{-o}). An option is
239 allowed to have both of these properties.
241 @item JoinedOrMissing
242 The option takes an optional argument. If the argument is given,
243 it will be part of the same @code{argv} entry as the option itself.
245 This property cannot be used alongside @code{Joined} or @code{Separate}.
247 @item MissingArgError(@var{message})
248 For an option marked @code{Joined} or @code{Separate}, the message
249 @var{message} will be used as an error message if the mandatory
250 argument is missing; for options without @code{MissingArgError}, a
251 generic error message is used. @var{message} should contain a single
252 @samp{%qs} format, which will be used to format the name of the option
256 For an option marked @code{Separate}, indicate that it takes @var{n}
257 arguments. The default is 1.
260 The option's argument is a non-negative integer. The option parser
261 will check and convert the argument before passing it to the relevant
262 option handler. @code{UInteger} should also be used on options like
263 @code{-falign-loops} where both @code{-falign-loops} and
264 @code{-falign-loops}=@var{n} are supported to make sure the saved
265 options are given a full integer.
268 The option's argument should be converted to lowercase as part of
269 putting it in canonical form, and before comparing with the strings
270 indicated by any @code{Enum} property.
273 For an option marked @code{Separate}, the option only takes an
274 argument in the compiler proper, not in the driver. This is for
275 compatibility with existing options that are used both directly and
276 via @option{-Wp,}; new options should not have this property.
279 The state of this option should be stored in variable @var{var}
280 (actually a macro for @code{global_options.x_@var{var}}).
281 The way that the state is stored depends on the type of option:
285 If the option uses the @code{Mask} or @code{InverseMask} properties,
286 @var{var} is the integer variable that contains the mask.
289 If the option is a normal on/off switch, @var{var} is an integer
290 variable that is nonzero when the option is enabled. The options
291 parser will set the variable to 1 when the positive form of the
292 option is used and 0 when the ``no-'' form is used.
295 If the option takes an argument and has the @code{UInteger} property,
296 @var{var} is an integer variable that stores the value of the argument.
299 If the option takes an argument and has the @code{Enum} property,
300 @var{var} is a variable (type given in the @code{Type} property of the
301 @samp{Enum} record whose @code{Name} property has the same argument as
302 the @code{Enum} property of this option) that stores the value of the
306 If the option has the @code{Defer} property, @var{var} is a pointer to
307 a @code{VEC(cl_deferred_option,heap)} that stores the option for later
308 processing. (@var{var} is declared with type @code{void *} and needs
309 to be cast to @code{VEC(cl_deferred_option,heap)} before use.)
312 Otherwise, if the option takes an argument, @var{var} is a pointer to
313 the argument string. The pointer will be null if the argument is optional
317 The option-processing script will usually zero-initialize @var{var}.
318 You can modify this behavior using @code{Init}.
320 @item Var(@var{var}, @var{set})
321 The option controls an integer variable @var{var} and is active when
322 @var{var} equals @var{set}. The option parser will set @var{var} to
323 @var{set} when the positive form of the option is used and @code{!@var{set}}
324 when the ``no-'' form is used.
326 @var{var} is declared in the same way as for the single-argument form
329 @item Init(@var{value})
330 The variable specified by the @code{Var} property should be statically
331 initialized to @var{value}. If more than one option using the same
332 variable specifies @code{Init}, all must specify the same initializer.
334 @item Mask(@var{name})
335 The option is associated with a bit in the @code{target_flags}
336 variable (@pxref{Run-time Target}) and is active when that bit is set.
337 You may also specify @code{Var} to select a variable other than
340 The options-processing script will automatically allocate a unique bit
341 for the option. If the option is attached to @samp{target_flags},
342 the script will set the macro @code{MASK_@var{name}} to the appropriate
343 bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
344 the value 1 when the option is active and 0 otherwise. If you use @code{Var}
345 to attach the option to a different variable, the bitmask macro with be
346 called @code{OPTION_MASK_@var{name}}.
348 @item InverseMask(@var{othername})
349 @itemx InverseMask(@var{othername}, @var{thisname})
350 The option is the inverse of another option that has the
351 @code{Mask(@var{othername})} property. If @var{thisname} is given,
352 the options-processing script will declare a @code{TARGET_@var{thisname}}
353 macro that is 1 when the option is active and 0 otherwise.
355 @item Enum(@var{name})
356 The option's argument is a string from the set of strings associated
357 with the corresponding @samp{Enum} record. The string is checked and
358 converted to the integer specified in the corresponding
359 @samp{EnumValue} record before being passed to option handlers.
362 The option should be stored in a vector, specified with @code{Var},
363 for later processing.
365 @item Alias(@var{opt})
366 @itemx Alias(@var{opt}, @var{arg})
367 @itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
368 The option is an alias for @option{-@var{opt}} (or the negative form
369 of that option, depending on @code{NegativeAlias}). In the first form,
370 any argument passed to the alias is considered to be passed to
371 @option{-@var{opt}}, and @option{-@var{opt}} is considered to be
372 negated if the alias is used in negated form. In the second form, the
373 alias may not be negated or have an argument, and @var{posarg} is
374 considered to be passed as an argument to @option{-@var{opt}}. In the
375 third form, the alias may not have an argument, if the alias is used
376 in the positive form then @var{posarg} is considered to be passed to
377 @option{-@var{opt}}, and if the alias is used in the negative form
378 then @var{negarg} is considered to be passed to @option{-@var{opt}}.
380 Aliases should not specify @code{Var} or @code{Mask} or
381 @code{UInteger}. Aliases should normally specify the same languages
382 as the target of the alias; the flags on the target will be used to
383 determine any diagnostic for use of an option for the wrong language,
384 while those on the alias will be used to identify what command-line
385 text is the option and what text is any argument to that option.
387 When an @code{Alias} definition is used for an option, driver specs do
388 not need to handle it and no @samp{OPT_} enumeration value is defined
389 for it; only the canonical form of the option will be seen in those
393 For an option marked with @code{Alias(@var{opt})}, the option is
394 considered to be an alias for the positive form of @option{-@var{opt}}
395 if negated and for the negative form of @option{-@var{opt}} if not
396 negated. @code{NegativeAlias} may not be used with the forms of
397 @code{Alias} taking more than one argument.
400 This option is ignored apart from printing any warning specified using
401 @code{Warn}. The option will not be seen by specs and no @samp{OPT_}
402 enumeration value is defined for it.
405 For an option marked with @code{Joined}, @code{Separate} and
406 @code{Alias}, the option only acts as an alias when passed a separate
407 argument; with a joined argument it acts as a normal option, with an
408 @samp{OPT_} enumeration value. This is for compatibility with the
409 Java @option{-d} option and should not be used for new options.
411 @item Warn(@var{message})
412 If this option is used, output the warning @var{message}.
413 @var{message} is a format string, either taking a single operand with
414 a @samp{%qs} format which is the option name, or not taking any
415 operands, which is passed to the @samp{warning} function. If an alias
416 is marked @code{Warn}, the target of the alias must not also be marked
420 The state of the option should be printed by @option{-fverbose-asm}.
423 This is a warning option and should be shown as such in
424 @option{--help} output. This flag does not currently affect anything
425 other than @option{--help}.
428 This is an optimization option. It should be shown as such in
429 @option{--help} output, and any associated variable named using
430 @code{Var} should be saved and restored when the optimization level is
431 changed with @code{optimize} attributes.
434 The option is deliberately missing documentation and should not
435 be included in the @option{--help} output.
437 @item Condition(@var{cond})
438 The option should only be accepted if preprocessor condition
439 @var{cond} is true. Note that any C declarations associated with the
440 option will be present even if @var{cond} is false; @var{cond} simply
441 controls whether the option is accepted and whether it is printed in
442 the @option{--help} output.
445 Build the @code{cl_target_option} structure to hold a copy of the
446 option, add the functions @code{cl_target_option_save} and
447 @code{cl_target_option_restore} to save and restore the options.
450 The option may also be set by a combined option such as
451 @option{-ffast-math}. This causes the @code{gcc_options} struct to
452 have a field @code{frontend_set_@var{name}}, where @code{@var{name}}
453 is the name of the field holding the value of this option (without the
454 leading @code{x_}). This gives the front end a way to indicate that
455 the value has been set explicitly and should not be changed by the
456 combined option. For example, some front ends use this to prevent
457 @option{-ffast-math} and @option{-fno-fast-math} from changing the
458 value of @option{-fmath-errno} for languages that do not use
461 @item EnabledBy(@var{opt})
462 @itemx EnabledBy(@var{opt} && @var{opt2})
463 If not explicitly set, the option is set to the value of
464 @option{-@var{opt}}. The second form specifies that the option is
465 only set if both @var{opt} and @var{opt2} are set.
467 @item LangEnabledBy(@var{language}, @var{opt})
468 @itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg})
469 When compiling for the given language, the option is set to the value
470 of @option{-@var{opt}}, if not explicitly set. In the second form, if
471 @var{opt} is used in the positive form then @var{posarg} is considered
472 to be passed to the option, and if @var{opt} is used in the negative
473 form then @var{negarg} is considered to be passed to the option. It
474 is possible to specify several different languages. Each
475 @var{language} must have been declared by an earlier @code{Language}
476 record. @xref{Option file format}.
479 The option is omitted from the producer string written by
480 @option{-grecord-gcc-switches}.
483 Even if this is a target option, this option will not be recorded / compared
484 to determine if a precompiled header file matches.
487 The state of this option should be kept in sync with the preprocessor