Mercurial > hg > CbC > CbC_gcc
comparison gcc/doc/options.texi @ 67:f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
author | nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Tue, 22 Mar 2011 17:18:12 +0900 |
parents | 77e2b8dfacca |
children | 04ced10e8804 |
comparison
equal
deleted
inserted
replaced
65:65488c3d617d | 67:f6334be47118 |
---|---|
1 @c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 | 1 @c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 |
2 @c Free Software Foundation, Inc. | 2 @c Free Software Foundation, Inc. |
3 @c This is part of the GCC manual. | 3 @c This is part of the GCC manual. |
4 @c For copying conditions, see the file gcc.texi. | 4 @c For copying conditions, see the file gcc.texi. |
5 | 5 |
6 @node Options | 6 @node Options |
37 | 37 |
38 @item | 38 @item |
39 A target specific save record to save additional information. These | 39 A target specific save record to save additional information. These |
40 records have two fields: the string @samp{TargetSave}, and a | 40 records have two fields: the string @samp{TargetSave}, and a |
41 declaration type to go in the @code{cl_target_option} structure. | 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 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 | |
42 | 136 |
43 @item | 137 @item |
44 An option definition record. These records have the following fields: | 138 An option definition record. These records have the following fields: |
45 @enumerate | 139 @enumerate |
46 @item | 140 @item |
100 The option is available for all languages and targets. | 194 The option is available for all languages and targets. |
101 | 195 |
102 @item Target | 196 @item Target |
103 The option is available for all languages but is target-specific. | 197 The option is available for all languages but is target-specific. |
104 | 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 | |
105 @item @var{language} | 203 @item @var{language} |
106 The option is available when compiling for the given language. | 204 The option is available when compiling for the given language. |
107 | 205 |
108 It is possible to specify several different languages for the same | 206 It is possible to specify several different languages for the same |
109 option. Each @var{language} must have been declared by an earlier | 207 option. Each @var{language} must have been declared by an earlier |
110 @code{Language} record. @xref{Option file format}. | 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. | |
111 | 213 |
112 @item RejectNegative | 214 @item RejectNegative |
113 The option does not have a ``no-'' form. All options beginning with | 215 The option does not have a ``no-'' form. All options beginning with |
114 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this | 216 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this |
115 property is used. | 217 property is used. |
133 The option takes an optional argument. If the argument is given, | 235 The option takes an optional argument. If the argument is given, |
134 it will be part of the same @code{argv} entry as the option itself. | 236 it will be part of the same @code{argv} entry as the option itself. |
135 | 237 |
136 This property cannot be used alongside @code{Joined} or @code{Separate}. | 238 This property cannot be used alongside @code{Joined} or @code{Separate}. |
137 | 239 |
240 @item MissingArgError(@var{message}) | |
241 For an option marked @code{Joined} or @code{Separate}, the message | |
242 @var{message} will be used as an error message if the mandatory | |
243 argument is missing; for options without @code{MissingArgError}, a | |
244 generic error message is used. @var{message} should contain a single | |
245 @samp{%qs} format, which will be used to format the name of the option | |
246 passed. | |
247 | |
248 @item Args(@var{n}) | |
249 For an option marked @code{Separate}, indicate that it takes @var{n} | |
250 arguments. The default is 1. | |
251 | |
138 @item UInteger | 252 @item UInteger |
139 The option's argument is a non-negative integer. The option parser | 253 The option's argument is a non-negative integer. The option parser |
140 will check and convert the argument before passing it to the relevant | 254 will check and convert the argument before passing it to the relevant |
141 option handler. @code{UInteger} should also be used on options like | 255 option handler. @code{UInteger} should also be used on options like |
142 @code{-falign-loops} where both @code{-falign-loops} and | 256 @code{-falign-loops} where both @code{-falign-loops} and |
143 @code{-falign-loops}=@var{n} are supported to make sure the saved | 257 @code{-falign-loops}=@var{n} are supported to make sure the saved |
144 options are given a full integer. | 258 options are given a full integer. |
145 | 259 |
260 @item NoDriverArg | |
261 For an option marked @code{Separate}, the option only takes an | |
262 argument in the compiler proper, not in the driver. This is for | |
263 compatibility with existing options that are used both directly and | |
264 via @option{-Wp,}; new options should not have this property. | |
265 | |
146 @item Var(@var{var}) | 266 @item Var(@var{var}) |
147 The state of this option should be stored in variable @var{var}. | 267 The state of this option should be stored in variable @var{var} |
268 (actually a macro for @code{global_options.x_@var{var}}). | |
148 The way that the state is stored depends on the type of option: | 269 The way that the state is stored depends on the type of option: |
149 | 270 |
150 @itemize @bullet | 271 @itemize @bullet |
151 @item | 272 @item |
152 If the option uses the @code{Mask} or @code{InverseMask} properties, | 273 If the option uses the @code{Mask} or @code{InverseMask} properties, |
161 @item | 282 @item |
162 If the option takes an argument and has the @code{UInteger} property, | 283 If the option takes an argument and has the @code{UInteger} property, |
163 @var{var} is an integer variable that stores the value of the argument. | 284 @var{var} is an integer variable that stores the value of the argument. |
164 | 285 |
165 @item | 286 @item |
287 If the option takes an argument and has the @code{Enum} property, | |
288 @var{var} is a variable (type given in the @code{Type} property of the | |
289 @samp{Enum} record whose @code{Name} property has the same argument as | |
290 the @code{Enum} property of this option) that stores the value of the | |
291 argument. | |
292 | |
293 @item | |
294 If the option has the @code{Defer} property, @var{var} is a pointer to | |
295 a @code{VEC(cl_deferred_option,heap)} that stores the option for later | |
296 processing. (@var{var} is declared with type @code{void *} and needs | |
297 to be cast to @code{VEC(cl_deferred_option,heap)} before use.) | |
298 | |
299 @item | |
166 Otherwise, if the option takes an argument, @var{var} is a pointer to | 300 Otherwise, if the option takes an argument, @var{var} is a pointer to |
167 the argument string. The pointer will be null if the argument is optional | 301 the argument string. The pointer will be null if the argument is optional |
168 and wasn't given. | 302 and wasn't given. |
169 @end itemize | 303 @end itemize |
170 | 304 |
171 The option-processing script will usually declare @var{var} in | 305 The option-processing script will usually zero-initialize @var{var}. |
172 @file{options.c} and leave it to be zero-initialized at start-up time. | 306 You can modify this behavior using @code{Init}. |
173 You can modify this behavior using @code{VarExists} and @code{Init}. | |
174 | 307 |
175 @item Var(@var{var}, @var{set}) | 308 @item Var(@var{var}, @var{set}) |
176 The option controls an integer variable @var{var} and is active when | 309 The option controls an integer variable @var{var} and is active when |
177 @var{var} equals @var{set}. The option parser will set @var{var} to | 310 @var{var} equals @var{set}. The option parser will set @var{var} to |
178 @var{set} when the positive form of the option is used and @code{!@var{set}} | 311 @var{set} when the positive form of the option is used and @code{!@var{set}} |
179 when the ``no-'' form is used. | 312 when the ``no-'' form is used. |
180 | 313 |
181 @var{var} is declared in the same way as for the single-argument form | 314 @var{var} is declared in the same way as for the single-argument form |
182 described above. | 315 described above. |
183 | 316 |
184 @item VarExists | |
185 The variable specified by the @code{Var} property already exists. | |
186 No definition should be added to @file{options.c} in response to | |
187 this option record. | |
188 | |
189 You should use this property only if the variable is declared outside | |
190 @file{options.c}. | |
191 | |
192 @item Init(@var{value}) | 317 @item Init(@var{value}) |
193 The variable specified by the @code{Var} property should be statically | 318 The variable specified by the @code{Var} property should be statically |
194 initialized to @var{value}. | 319 initialized to @var{value}. If more than one option using the same |
320 variable specifies @code{Init}, all must specify the same initializer. | |
195 | 321 |
196 @item Mask(@var{name}) | 322 @item Mask(@var{name}) |
197 The option is associated with a bit in the @code{target_flags} | 323 The option is associated with a bit in the @code{target_flags} |
198 variable (@pxref{Run-time Target}) and is active when that bit is set. | 324 variable (@pxref{Run-time Target}) and is active when that bit is set. |
199 You may also specify @code{Var} to select a variable other than | 325 You may also specify @code{Var} to select a variable other than |
223 | 349 |
224 The main purpose of this property is to support synonymous options. | 350 The main purpose of this property is to support synonymous options. |
225 The first option should use @samp{Mask(@var{name})} and the others | 351 The first option should use @samp{Mask(@var{name})} and the others |
226 should use @samp{Mask(@var{name}) MaskExists}. | 352 should use @samp{Mask(@var{name}) MaskExists}. |
227 | 353 |
354 @item Enum(@var{name}) | |
355 The option's argument is a string from the set of strings associated | |
356 with the corresponding @samp{Enum} record. The string is checked and | |
357 converted to the integer specified in the corresponding | |
358 @samp{EnumValue} record before being passed to option handlers. | |
359 | |
360 @item Defer | |
361 The option should be stored in a vector, specified with @code{Var}, | |
362 for later processing. | |
363 | |
364 @item Alias(@var{opt}) | |
365 @itemx Alias(@var{opt}, @var{arg}) | |
366 @itemx Alias(@var{opt}, @var{posarg}, @var{negarg}) | |
367 The option is an alias for @option{-@var{opt}}. In the first form, | |
368 any argument passed to the alias is considered to be passed to | |
369 @option{-@var{opt}}, and @option{-@var{opt}} is considered to be | |
370 negated if the alias is used in negated form. In the second form, the | |
371 alias may not be negated or have an argument, and @var{posarg} is | |
372 considered to be passed as an argument to @option{-@var{opt}}. In the | |
373 third form, the alias may not have an argument, if the alias is used | |
374 in the positive form then @var{posarg} is considered to be passed to | |
375 @option{-@var{opt}}, and if the alias is used in the negative form | |
376 then @var{negarg} is considered to be passed to @option{-@var{opt}}. | |
377 | |
378 Aliases should not specify @code{Var} or @code{Mask} or | |
379 @code{UInteger}. Aliases should normally specify the same languages | |
380 as the target of the alias; the flags on the target will be used to | |
381 determine any diagnostic for use of an option for the wrong language, | |
382 while those on the alias will be used to identify what command-line | |
383 text is the option and what text is any argument to that option. | |
384 | |
385 When an @code{Alias} definition is used for an option, driver specs do | |
386 not need to handle it and no @samp{OPT_} enumeration value is defined | |
387 for it; only the canonical form of the option will be seen in those | |
388 places. | |
389 | |
390 @item Ignore | |
391 This option is ignored apart from printing any warning specified using | |
392 @code{Warn}. The option will not be seen by specs and no @samp{OPT_} | |
393 enumeration value is defined for it. | |
394 | |
395 @item SeparateAlias | |
396 For an option marked with @code{Joined}, @code{Separate} and | |
397 @code{Alias}, the option only acts as an alias when passed a separate | |
398 argument; with a joined argument it acts as a normal option, with an | |
399 @samp{OPT_} enumeration value. This is for compatibility with the | |
400 Java @option{-d} option and should not be used for new options. | |
401 | |
402 @item Warn(@var{message}) | |
403 If this option is used, output the warning @var{message}. | |
404 @var{message} is a format string, either taking a single operand with | |
405 a @samp{%qs} format which is the option name, or not taking any | |
406 operands, which is passed to the @samp{warning} function. If an alias | |
407 is marked @code{Warn}, the target of the alias must not also be marked | |
408 @code{Warn}. | |
409 | |
228 @item Report | 410 @item Report |
229 The state of the option should be printed by @option{-fverbose-asm}. | 411 The state of the option should be printed by @option{-fverbose-asm}. |
412 | |
413 @item Warning | |
414 This is a warning option and should be shown as such in | |
415 @option{--help} output. This flag does not currently affect anything | |
416 other than @option{--help}. | |
417 | |
418 @item Optimization | |
419 This is an optimization option. It should be shown as such in | |
420 @option{--help} output, and any associated variable named using | |
421 @code{Var} should be saved and restored when the optimization level is | |
422 changed with @code{optimize} attributes. | |
230 | 423 |
231 @item Undocumented | 424 @item Undocumented |
232 The option is deliberately missing documentation and should not | 425 The option is deliberately missing documentation and should not |
233 be included in the @option{--help} output. | 426 be included in the @option{--help} output. |
234 | 427 |
241 | 434 |
242 @item Save | 435 @item Save |
243 Build the @code{cl_target_option} structure to hold a copy of the | 436 Build the @code{cl_target_option} structure to hold a copy of the |
244 option, add the functions @code{cl_target_option_save} and | 437 option, add the functions @code{cl_target_option_save} and |
245 @code{cl_target_option_restore} to save and restore the options. | 438 @code{cl_target_option_restore} to save and restore the options. |
439 | |
440 @item SetByCombined | |
441 The option may also be set by a combined option such as | |
442 @option{-ffast-math}. This causes the @code{gcc_options} struct to | |
443 have a field @code{frontend_set_@var{name}}, where @code{@var{name}} | |
444 is the name of the field holding the value of this option (without the | |
445 leading @code{x_}). This gives the front end a way to indicate that | |
446 the value has been set explicitly and should not be changed by the | |
447 combined option. For example, some front ends use this to prevent | |
448 @option{-ffast-math} and @option{-fno-fast-math} from changing the | |
449 value of @option{-fmath-errno} for languages that do not use | |
450 @code{errno}. | |
451 | |
246 @end table | 452 @end table |