Merge branch 'vendor/GCC50' - gcc 5.0 snapshot 1 FEB 2015
[dragonfly.git] / contrib / gcc-5.0 / gcc / doc / options.texi
1 @c Copyright (C) 2003-2015 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{optc-gen.awk}
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 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.
41
42 @item
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.
52
53 @item
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.
63
64 @item
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.
70
71 @item
72 A variable record to record any additional files that the
73 @file{options.c} or @file{options-save.c} file should include.  This
74 is useful to provide
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
78 include file.
79
80 @item
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
86 valid:
87 @table @code
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}
91 option properties.
92
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}.
96
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.
102 @end table
103
104 @item
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
109 valid:
110 @table @code
111 @item Enum(@var{name})
112 This property is required; @var{name} says which @samp{Enum} record
113 this @samp{EnumValue} record corresponds to.
114
115 @item String(@var{string})
116 This property is required; @var{string} is the string option argument
117 being described by this record.
118
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.
122
123 @item Canonical
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
127 handle them.
128
129 @item DriverOnly
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.
135 @end table
136
137 @item
138 An option definition record.  These records have the following fields:
139 @enumerate
140 @item
141 the name of the option, with the leading ``-'' removed
142 @item
143 a space-separated list of option properties (@pxref{Option properties})
144 @item
145 the help text to use for @option{--help} (omitted if the second field
146 contains the @code{Undocumented} property).
147 @end enumerate
148
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.
154
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.
162
163 @item
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
170 0 otherwise.
171
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.
176 @end itemize
177
178 @node Option properties
179 @section Option properties
180
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.:
187
188 @smallexample
189 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
190 @end smallexample
191
192 @table @code
193 @item Common
194 The option is available for all languages and targets.
195
196 @item Target
197 The option is available for all languages but is target-specific.
198
199 @item Driver
200 The option is handled by the compiler driver using code not shared
201 with the compilers proper (@file{cc1} etc.).
202
203 @item @var{language}
204 The option is available when compiling for the given language.
205
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}.
209
210 @item RejectDriver
211 The option is only handled by the compilers proper (@file{cc1} etc.)@:
212 and should not be accepted by the driver.
213
214 @item RejectNegative
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
217 property is used.
218
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
223 turned off.
224
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})}.
231
232 @item Joined
233 @itemx Separate
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.
240
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.
244
245 This property cannot be used alongside @code{Joined} or @code{Separate}.
246
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
253 passed.
254
255 @item Args(@var{n})
256 For an option marked @code{Separate}, indicate that it takes @var{n}
257 arguments.  The default is 1.
258
259 @item UInteger
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.
266
267 @item ToLower
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.
271
272 @item NoDriverArg
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.
277
278 @item Var(@var{var})
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:
282
283 @itemize @bullet
284 @item
285 If the option uses the @code{Mask} or @code{InverseMask} properties,
286 @var{var} is the integer variable that contains the mask.
287
288 @item
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.
293
294 @item
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.
297
298 @item
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
303 argument.
304
305 @item
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.)
310
311 @item
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
314 and wasn't given.
315 @end itemize
316
317 The option-processing script will usually zero-initialize @var{var}.
318 You can modify this behavior using @code{Init}.
319
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.
325
326 @var{var} is declared in the same way as for the single-argument form
327 described above.
328
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.
333
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
338 @code{target_flags}.
339
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}}.
347
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.
354
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.
360
361 @item Defer
362 The option should be stored in a vector, specified with @code{Var},
363 for later processing.
364
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}}.
379
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.
386
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
390 places.
391
392 @item NegativeAlias
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.
398
399 @item Ignore
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.
403
404 @item SeparateAlias
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.
410
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
417 @code{Warn}.
418
419 @item Report
420 The state of the option should be printed by @option{-fverbose-asm}.
421
422 @item Warning
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}.
426
427 @item Optimization
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.
432
433 @item Undocumented
434 The option is deliberately missing documentation and should not
435 be included in the @option{--help} output.
436
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.
443
444 @item Save
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.
448
449 @item SetByCombined
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
459 @code{errno}.
460
461 @item EnabledBy(@var{opt})
462 @itemx EnabledBy(@var{opt} || @var{opt2})
463 @itemx EnabledBy(@var{opt} && @var{opt2})
464 If not explicitly set, the option is set to the value of
465 @option{-@var{opt}}; multiple options can be given, separated by
466 @code{||}.  The third form using @code{&&} specifies that the option is
467 only set if both @var{opt} and @var{opt2} are set.
468
469 @item LangEnabledBy(@var{language}, @var{opt})
470 @itemx LangEnabledBy(@var{language}, @var{opt}, @var{posarg}, @var{negarg})
471 When compiling for the given language, the option is set to the value
472 of @option{-@var{opt}}, if not explicitly set. @var{opt} can be also a list
473 of @code{||} separated options. In the second form, if
474 @var{opt} is used in the positive form then @var{posarg} is considered
475 to be passed to the option, and if @var{opt} is used in the negative
476 form then @var{negarg} is considered to be passed to the option.  It
477 is possible to specify several different languages.  Each
478 @var{language} must have been declared by an earlier @code{Language}
479 record.  @xref{Option file format}.
480
481 @item NoDWARFRecord
482 The option is omitted from the producer string written by
483 @option{-grecord-gcc-switches}.
484
485 @item PchIgnore
486 Even if this is a target option, this option will not be recorded / compared
487 to determine if a precompiled header file matches.
488
489 @item CPP(@var{var})
490 The state of this option should be kept in sync with the preprocessor
491 option @var{var}.  If this property is set, then properties @code{Var}
492 and @code{Init} must be set as well.
493
494 @item CppReason(@var{CPP_W_Enum})
495 This warning option corresponds to @code{cpplib.h} warning reason code
496 @var{CPP_W_Enum}.  This should only be used for warning options of the
497 C-family front-ends.
498
499 @end table