OSDN Git Service

8c5c6399316cd48d2c719946a72979335ab392dd
[pf3gnuchains/gcc-fork.git] / gcc / doc / options.texi
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.
5
6 @node Options
7 @chapter Option specification files
8 @cindex option specification files
9 @cindex @samp{optc-gen.awk}
10
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.
14
15 @menu
16 * Option file format::   The general layout of the files
17 * Option properties::    Supported option properties
18 @end menu
19
20 @node Option file format
21 @section Option file format
22
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
27 the semicolon.
28
29 The files can contain the following types of record:
30
31 @itemize @bullet
32 @item
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}.
37
38 @item
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.
42
43 @item
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.
53
54 @item
55 A variable record to define a variable used to store option
56 information.  These records have two fields: the string
57 @samp{TargetVariable}, and a declaration of the type and name of the
58 variable, optionally with an initializer (but without any trailing
59 @samp{;}).  @samp{TargetVariable} is a combination of @samp{Variable}
60 and @samp{TargetSave} records in that the variable is defined in the
61 @code{gcc_options} structure, but these variables are also stored in
62 the @code{cl_target_option} structure.  The variables are saved in the
63 target save code and restored in the target restore code.
64
65 @item
66 A variable record to record any additional files that the
67 @file{options.h} file should include.  This is useful to provide
68 enumeration or structure definitions needed for target variables.
69 These records have two fields: the string @samp{HeaderInclude} and the
70 name of the include file.
71
72 @item
73 A variable record to record any additional files that the
74 @file{options.c} file should include.  This 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 option definition record.  These records have the following fields:
82 @enumerate
83 @item
84 the name of the option, with the leading ``-'' removed
85 @item
86 a space-separated list of option properties (@pxref{Option properties})
87 @item
88 the help text to use for @option{--help} (omitted if the second field
89 contains the @code{Undocumented} property).
90 @end enumerate
91
92 By default, all options beginning with ``f'', ``W'' or ``m'' are
93 implicitly assumed to take a ``no-'' form.  This form should not be
94 listed separately.  If an option beginning with one of these letters
95 does not have a ``no-'' form, you can use the @code{RejectNegative}
96 property to reject it.
97
98 The help text is automatically line-wrapped before being displayed.
99 Normally the name of the option is printed on the left-hand side of
100 the output and the help text is printed on the right.  However, if the
101 help text contains a tab character, the text to the left of the tab is
102 used instead of the option's name and the text to the right of the
103 tab forms the help text.  This allows you to elaborate on what type
104 of argument the option takes.
105
106 @item
107 A target mask record.  These records have one field of the form
108 @samp{Mask(@var{x})}.  The options-processing script will automatically
109 allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
110 each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
111 appropriate bitmask.  It will also declare a @code{TARGET_@var{x}}
112 macro that has the value 1 when bit @code{MASK_@var{x}} is set and
113 0 otherwise.
114
115 They are primarily intended to declare target masks that are not
116 associated with user options, either because these masks represent
117 internal switches or because the options are not available on all
118 configurations and yet the masks always need to be defined.
119 @end itemize
120
121 @node Option properties
122 @section Option properties
123
124 The second field of an option record can specify any of the following
125 properties.  When an option takes an argument, it is enclosed in parentheses
126 following the option property name.  The parser that handles option files
127 is quite simplistic, and will be tricked by any nested parentheses within
128 the argument text itself; in this case, the entire option argument can
129 be wrapped in curly braces within the parentheses to demarcate it, e.g.:
130
131 @smallexample
132 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
133 @end smallexample
134
135 @table @code
136 @item Common
137 The option is available for all languages and targets.
138
139 @item Target
140 The option is available for all languages but is target-specific.
141
142 @item Driver
143 The option is handled by the compiler driver using code not shared
144 with the compilers proper (@file{cc1} etc.).
145
146 @item @var{language}
147 The option is available when compiling for the given language.
148
149 It is possible to specify several different languages for the same
150 option.  Each @var{language} must have been declared by an earlier
151 @code{Language} record.  @xref{Option file format}.
152
153 @item RejectDriver
154 The option is only handled by the compilers proper (@file{cc1} etc.)@:
155 and should not be accepted by the driver.
156
157 @item RejectNegative
158 The option does not have a ``no-'' form.  All options beginning with
159 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
160 property is used.
161
162 @item Negative(@var{othername})
163 The option will turn off another option @var{othername}, which is
164 the option name with the leading ``-'' removed.  This chain action will
165 propagate through the @code{Negative} property of the option to be
166 turned off.
167
168 @item Joined
169 @itemx Separate
170 The option takes a mandatory argument.  @code{Joined} indicates
171 that the option and argument can be included in the same @code{argv}
172 entry (as with @code{-mflush-func=@var{name}}, for example).
173 @code{Separate} indicates that the option and argument can be
174 separate @code{argv} entries (as with @code{-o}).  An option is
175 allowed to have both of these properties.
176
177 @item JoinedOrMissing
178 The option takes an optional argument.  If the argument is given,
179 it will be part of the same @code{argv} entry as the option itself.
180
181 This property cannot be used alongside @code{Joined} or @code{Separate}.
182
183 @item MissingArgError(@var{message})
184 For an option marked @code{Joined} or @code{Separate}, the message
185 @var{message} will be used as an error message if the mandatory
186 argument is missing; for options without @code{MissingArgError}, a
187 generic error message is used.  @var{message} should contain a single
188 @samp{%qs} format, which will be used to format the name of the option
189 passed.
190
191 @item Args(@var{n})
192 For an option marked @code{Separate}, indicate that it takes @var{n}
193 arguments.  The default is 1.
194
195 @item UInteger
196 The option's argument is a non-negative integer.  The option parser
197 will check and convert the argument before passing it to the relevant
198 option handler.  @code{UInteger} should also be used on options like
199 @code{-falign-loops} where both @code{-falign-loops} and
200 @code{-falign-loops}=@var{n} are supported to make sure the saved
201 options are given a full integer.
202
203 @item NoDriverArg
204 For an option marked @code{Separate}, the option only takes an
205 argument in the compiler proper, not in the driver.  This is for
206 compatibility with existing options that are used both directly and
207 via @option{-Wp,}; new options should not have this property.
208
209 @item Var(@var{var})
210 The state of this option should be stored in variable @var{var}
211 (actually a macro for @code{global_options.x_@var{var}}).
212 The way that the state is stored depends on the type of option:
213
214 @itemize @bullet
215 @item
216 If the option uses the @code{Mask} or @code{InverseMask} properties,
217 @var{var} is the integer variable that contains the mask.
218
219 @item
220 If the option is a normal on/off switch, @var{var} is an integer
221 variable that is nonzero when the option is enabled.  The options
222 parser will set the variable to 1 when the positive form of the
223 option is used and 0 when the ``no-'' form is used.
224
225 @item
226 If the option takes an argument and has the @code{UInteger} property,
227 @var{var} is an integer variable that stores the value of the argument.
228
229 @item
230 If the option has the @code{Defer} property, @var{var} is a pointer to
231 a @code{VEC(cl_deferred_option,heap)} that stores the option for later
232 processing.  (@var{var} is declared with type @code{void *} and needs
233 to be cast to @code{VEC(cl_deferred_option,heap)} before use.)
234
235 @item
236 Otherwise, if the option takes an argument, @var{var} is a pointer to
237 the argument string.  The pointer will be null if the argument is optional
238 and wasn't given.
239 @end itemize
240
241 The option-processing script will usually zero-initialize @var{var}.
242 You can modify this behavior using @code{Init}.
243
244 @item Var(@var{var}, @var{set})
245 The option controls an integer variable @var{var} and is active when
246 @var{var} equals @var{set}.  The option parser will set @var{var} to
247 @var{set} when the positive form of the option is used and @code{!@var{set}}
248 when the ``no-'' form is used.
249
250 @var{var} is declared in the same way as for the single-argument form
251 described above.
252
253 @item Init(@var{value})
254 The variable specified by the @code{Var} property should be statically
255 initialized to @var{value}.  If more than one option using the same
256 variable specifies @code{Init}, all must specify the same initializer.
257
258 @item Mask(@var{name})
259 The option is associated with a bit in the @code{target_flags}
260 variable (@pxref{Run-time Target}) and is active when that bit is set.
261 You may also specify @code{Var} to select a variable other than
262 @code{target_flags}.
263
264 The options-processing script will automatically allocate a unique bit
265 for the option.  If the option is attached to @samp{target_flags},
266 the script will set the macro @code{MASK_@var{name}} to the appropriate
267 bitmask.  It will also declare a @code{TARGET_@var{name}} macro that has
268 the value 1 when the option is active and 0 otherwise.  If you use @code{Var}
269 to attach the option to a different variable, the associated macros are
270 called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
271
272 You can disable automatic bit allocation using @code{MaskExists}.
273
274 @item InverseMask(@var{othername})
275 @itemx InverseMask(@var{othername}, @var{thisname})
276 The option is the inverse of another option that has the
277 @code{Mask(@var{othername})} property.  If @var{thisname} is given,
278 the options-processing script will declare a @code{TARGET_@var{thisname}}
279 macro that is 1 when the option is active and 0 otherwise.
280
281 @item MaskExists
282 The mask specified by the @code{Mask} property already exists.
283 No @code{MASK} or @code{TARGET} definitions should be added to
284 @file{options.h} in response to this option record.
285
286 The main purpose of this property is to support synonymous options.
287 The first option should use @samp{Mask(@var{name})} and the others
288 should use @samp{Mask(@var{name}) MaskExists}.
289
290 @item Defer
291 The option should be stored in a vector, specified with @code{Var},
292 for later processing.
293
294 @item Alias(@var{opt})
295 @itemx Alias(@var{opt}, @var{arg})
296 @itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
297 The option is an alias for @option{-@var{opt}}.  In the first form,
298 any argument passed to the alias is considered to be passed to
299 @option{-@var{opt}}, and @option{-@var{opt}} is considered to be
300 negated if the alias is used in negated form.  In the second form, the
301 alias may not be negated or have an argument, and @var{posarg} is
302 considered to be passed as an argument to @option{-@var{opt}}.  In the
303 third form, the alias may not have an argument, if the alias is used
304 in the positive form then @var{posarg} is considered to be passed to
305 @option{-@var{opt}}, and if the alias is used in the negative form
306 then @var{negarg} is considered to be passed to @option{-@var{opt}}.
307
308 Aliases should not specify @code{Var} or @code{Mask} or
309 @code{UInteger}.  Aliases should normally specify the same languages
310 as the target of the alias; the flags on the target will be used to
311 determine any diagnostic for use of an option for the wrong language,
312 while those on the alias will be used to identify what command-line
313 text is the option and what text is any argument to that option.
314
315 When an @code{Alias} definition is used for an option, driver specs do
316 not need to handle it and no @samp{OPT_} enumeration value is defined
317 for it; only the canonical form of the option will be seen in those
318 places.
319
320 @item Ignore
321 This option is ignored apart from printing any warning specified using
322 @code{Warn}.  The option will not be seen by specs and no @samp{OPT_}
323 enumeration value is defined for it.
324
325 @item SeparateAlias
326 For an option marked with @code{Joined}, @code{Separate} and
327 @code{Alias}, the option only acts as an alias when passed a separate
328 argument; with a joined argument it acts as a normal option, with an
329 @samp{OPT_} enumeration value.  This is for compatibility with the
330 Java @option{-d} option and should not be used for new options.
331
332 @item Warn(@var{message})
333 If this option is used, output the warning @var{message}.
334 @var{message} is a format string, either taking a single operand with
335 a @samp{%qs} format which is the option name, or not taking any
336 operands, which is passed to the @samp{warning} function.  If an alias
337 is marked @code{Warn}, the target of the alias must not also be marked
338 @code{Warn}.
339
340 @item Report
341 The state of the option should be printed by @option{-fverbose-asm}.
342
343 @item Undocumented
344 The option is deliberately missing documentation and should not
345 be included in the @option{--help} output.
346
347 @item Condition(@var{cond})
348 The option should only be accepted if preprocessor condition
349 @var{cond} is true.  Note that any C declarations associated with the
350 option will be present even if @var{cond} is false; @var{cond} simply
351 controls whether the option is accepted and whether it is printed in
352 the @option{--help} output.
353
354 @item Save
355 Build the @code{cl_target_option} structure to hold a copy of the
356 option, add the functions @code{cl_target_option_save} and
357 @code{cl_target_option_restore} to save and restore the options.
358 @end table