Mercurial > hg > CbC > CbC_gcc
annotate gcc/doc/options.texi @ 63:b7f97abdc517 gcc-4.6-20100522
update gcc from gcc-4.5.0 to gcc-4.6
| author | ryoma <e075725@ie.u-ryukyu.ac.jp> |
|---|---|
| date | Mon, 24 May 2010 12:47:05 +0900 |
| parents | 77e2b8dfacca |
| children | f6334be47118 |
| rev | line source |
|---|---|
| 0 | 1 @c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 |
| 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 An option definition record. These records have the following fields: | |
| 45 @enumerate | |
| 46 @item | |
| 47 the name of the option, with the leading ``-'' removed | |
| 48 @item | |
| 49 a space-separated list of option properties (@pxref{Option properties}) | |
| 50 @item | |
| 51 the help text to use for @option{--help} (omitted if the second field | |
| 52 contains the @code{Undocumented} property). | |
| 53 @end enumerate | |
| 54 | |
| 55 By default, all options beginning with ``f'', ``W'' or ``m'' are | |
| 56 implicitly assumed to take a ``no-'' form. This form should not be | |
| 57 listed separately. If an option beginning with one of these letters | |
| 58 does not have a ``no-'' form, you can use the @code{RejectNegative} | |
| 59 property to reject it. | |
| 60 | |
| 61 The help text is automatically line-wrapped before being displayed. | |
| 62 Normally the name of the option is printed on the left-hand side of | |
| 63 the output and the help text is printed on the right. However, if the | |
| 64 help text contains a tab character, the text to the left of the tab is | |
| 65 used instead of the option's name and the text to the right of the | |
| 66 tab forms the help text. This allows you to elaborate on what type | |
| 67 of argument the option takes. | |
| 68 | |
| 69 @item | |
| 70 A target mask record. These records have one field of the form | |
| 71 @samp{Mask(@var{x})}. The options-processing script will automatically | |
| 72 allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for | |
| 73 each mask name @var{x} and set the macro @code{MASK_@var{x}} to the | |
| 74 appropriate bitmask. It will also declare a @code{TARGET_@var{x}} | |
| 75 macro that has the value 1 when bit @code{MASK_@var{x}} is set and | |
| 76 0 otherwise. | |
| 77 | |
| 78 They are primarily intended to declare target masks that are not | |
| 79 associated with user options, either because these masks represent | |
| 80 internal switches or because the options are not available on all | |
| 81 configurations and yet the masks always need to be defined. | |
| 82 @end itemize | |
| 83 | |
| 84 @node Option properties | |
| 85 @section Option properties | |
| 86 | |
|
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
87 The second field of an option record can specify any of the following |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
88 properties. When an option takes an argument, it is enclosed in parentheses |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
89 following the option property name. The parser that handles option files |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
90 is quite simplistic, and will be tricked by any nested parentheses within |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
91 the argument text itself; in this case, the entire option argument can |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
92 be wrapped in curly braces within the parentheses to demarcate it, e.g.: |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
93 |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
94 @smallexample |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
95 Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@}) |
|
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
96 @end smallexample |
| 0 | 97 |
| 98 @table @code | |
| 99 @item Common | |
| 100 The option is available for all languages and targets. | |
| 101 | |
| 102 @item Target | |
| 103 The option is available for all languages but is target-specific. | |
| 104 | |
| 105 @item @var{language} | |
| 106 The option is available when compiling for the given language. | |
| 107 | |
| 108 It is possible to specify several different languages for the same | |
| 109 option. Each @var{language} must have been declared by an earlier | |
| 110 @code{Language} record. @xref{Option file format}. | |
| 111 | |
| 112 @item RejectNegative | |
| 113 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 | |
| 115 property is used. | |
| 116 | |
| 117 @item Negative(@var{othername}) | |
|
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
118 The option will turn off another option @var{othername}, which is |
| 0 | 119 the option name with the leading ``-'' removed. This chain action will |
| 120 propagate through the @code{Negative} property of the option to be | |
| 121 turned off. | |
| 122 | |
| 123 @item Joined | |
| 124 @itemx Separate | |
| 125 The option takes a mandatory argument. @code{Joined} indicates | |
| 126 that the option and argument can be included in the same @code{argv} | |
| 127 entry (as with @code{-mflush-func=@var{name}}, for example). | |
| 128 @code{Separate} indicates that the option and argument can be | |
| 129 separate @code{argv} entries (as with @code{-o}). An option is | |
| 130 allowed to have both of these properties. | |
| 131 | |
| 132 @item JoinedOrMissing | |
| 133 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. | |
| 135 | |
| 136 This property cannot be used alongside @code{Joined} or @code{Separate}. | |
| 137 | |
| 138 @item UInteger | |
| 139 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 | |
| 141 option handler. @code{UInteger} should also be used on options like | |
| 142 @code{-falign-loops} where both @code{-falign-loops} and | |
| 143 @code{-falign-loops}=@var{n} are supported to make sure the saved | |
| 144 options are given a full integer. | |
| 145 | |
| 146 @item Var(@var{var}) | |
| 147 The state of this option should be stored in variable @var{var}. | |
| 148 The way that the state is stored depends on the type of option: | |
| 149 | |
| 150 @itemize @bullet | |
| 151 @item | |
| 152 If the option uses the @code{Mask} or @code{InverseMask} properties, | |
| 153 @var{var} is the integer variable that contains the mask. | |
| 154 | |
| 155 @item | |
| 156 If the option is a normal on/off switch, @var{var} is an integer | |
| 157 variable that is nonzero when the option is enabled. The options | |
| 158 parser will set the variable to 1 when the positive form of the | |
| 159 option is used and 0 when the ``no-'' form is used. | |
| 160 | |
| 161 @item | |
| 162 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. | |
| 164 | |
| 165 @item | |
| 166 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 | |
| 168 and wasn't given. | |
| 169 @end itemize | |
| 170 | |
| 171 The option-processing script will usually declare @var{var} in | |
| 172 @file{options.c} and leave it to be zero-initialized at start-up time. | |
| 173 You can modify this behavior using @code{VarExists} and @code{Init}. | |
| 174 | |
| 175 @item Var(@var{var}, @var{set}) | |
| 176 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 | |
| 178 @var{set} when the positive form of the option is used and @code{!@var{set}} | |
| 179 when the ``no-'' form is used. | |
| 180 | |
| 181 @var{var} is declared in the same way as for the single-argument form | |
| 182 described above. | |
| 183 | |
| 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}) | |
| 193 The variable specified by the @code{Var} property should be statically | |
| 194 initialized to @var{value}. | |
| 195 | |
| 196 @item Mask(@var{name}) | |
| 197 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. | |
| 199 You may also specify @code{Var} to select a variable other than | |
| 200 @code{target_flags}. | |
| 201 | |
| 202 The options-processing script will automatically allocate a unique bit | |
| 203 for the option. If the option is attached to @samp{target_flags}, | |
| 204 the script will set the macro @code{MASK_@var{name}} to the appropriate | |
| 205 bitmask. It will also declare a @code{TARGET_@var{name}} macro that has | |
| 206 the value 1 when the option is active and 0 otherwise. If you use @code{Var} | |
| 207 to attach the option to a different variable, the associated macros are | |
| 208 called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively. | |
| 209 | |
| 210 You can disable automatic bit allocation using @code{MaskExists}. | |
| 211 | |
| 212 @item InverseMask(@var{othername}) | |
| 213 @itemx InverseMask(@var{othername}, @var{thisname}) | |
| 214 The option is the inverse of another option that has the | |
| 215 @code{Mask(@var{othername})} property. If @var{thisname} is given, | |
| 216 the options-processing script will declare a @code{TARGET_@var{thisname}} | |
| 217 macro that is 1 when the option is active and 0 otherwise. | |
| 218 | |
| 219 @item MaskExists | |
| 220 The mask specified by the @code{Mask} property already exists. | |
| 221 No @code{MASK} or @code{TARGET} definitions should be added to | |
| 222 @file{options.h} in response to this option record. | |
| 223 | |
| 224 The main purpose of this property is to support synonymous options. | |
| 225 The first option should use @samp{Mask(@var{name})} and the others | |
| 226 should use @samp{Mask(@var{name}) MaskExists}. | |
| 227 | |
| 228 @item Report | |
| 229 The state of the option should be printed by @option{-fverbose-asm}. | |
| 230 | |
| 231 @item Undocumented | |
| 232 The option is deliberately missing documentation and should not | |
| 233 be included in the @option{--help} output. | |
| 234 | |
| 235 @item Condition(@var{cond}) | |
| 236 The option should only be accepted if preprocessor condition | |
| 237 @var{cond} is true. Note that any C declarations associated with the | |
| 238 option will be present even if @var{cond} is false; @var{cond} simply | |
| 239 controls whether the option is accepted and whether it is printed in | |
| 240 the @option{--help} output. | |
| 241 | |
| 242 @item Save | |
| 243 Build the @code{cl_target_option} structure to hold a copy of the | |
| 244 option, add the functions @code{cl_target_option_save} and | |
| 245 @code{cl_target_option_restore} to save and restore the options. | |
| 246 @end table |