gcc41 removal: Part 1 of 2: makefiles
[dragonfly.git] / contrib / gcc-4.1 / gcc / doc / options.texi
1 @c Copyright (C) 2003, 2004, 2005 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{opts.sh}
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 An option definition record.  These records have the following fields:
39
40 @enumerate
41 @item
42 the name of the option, with the leading ``-'' removed
43 @item
44 a space-separated list of option properties (@pxref{Option properties})
45 @item
46 the help text to use for @option{--help} (omitted if the second field
47 contains the @code{Undocumented} property).
48 @end enumerate
49
50 By default, all options beginning with ``f'', ``W'' or ``m'' are
51 implicitly assumed to take a ``no-'' form.  This form should not be
52 listed separately.  If an option beginning with one of these letters
53 does not have a ``no-'' form, you can use the @code{RejectNegative}
54 property to reject it.
55
56 The help text is automatically line-wrapped before being displayed.
57 Normally the name of the option is printed on the left-hand side of
58 the output and the help text is printed on the right.  However, if the
59 help text contains a tab character, the text to the left of the tab is
60 used instead of the option's name and the text to the right of the
61 tab forms the help text.  This allows you to elaborate on what type
62 of argument the option takes.
63
64 @item
65 A target mask record.  These records have one field of the form
66 @samp{Mask(@var{x})}.  The options-processing script will automatically
67 allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
68 each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
69 appropriate bitmask.  It will also declare a @code{TARGET_@var{x}}
70 macro that has the value 1 when bit @code{MASK_@var{x}} is set and
71 0 otherwise.
72
73 They are primarily intended to declare target masks that are not
74 associated with user options, either because these masks represent
75 internal switches or because the options are not available on all
76 configurations and yet the masks always need to be defined.
77 @end itemize
78
79 @node Option properties
80 @section Option properties
81
82 The second field of an option record can specify the following properties:
83
84 @table @code
85 @item Common
86 The option is available for all languages and targets.
87
88 @item Target
89 The option is available for all languages but is target-specific.
90
91 @item @var{language}
92 The option is available when compiling for the given language.
93
94 It is possible to specify several different languages for the same
95 option.  Each @var{language} must have been declared by an earlier
96 @code{Language} record.  @xref{Option file format}.
97
98 @item RejectNegative
99 The option does not have a ``no-'' form.  All options beginning with
100 ``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
101 property is used.
102
103 @item Joined
104 @itemx Separate
105 The option takes a mandatory argument.  @code{Joined} indicates
106 that the option and argument can be included in the same @code{argv}
107 entry (as with @code{-mflush-func=@var{name}}, for example).
108 @code{Separate} indicates that the option and argument can be
109 separate @code{argv} entries (as with @code{-o}).  An option is
110 allowed to have both of these properties.
111
112 @item JoinedOrMissing
113 The option takes an optional argument.  If the argument is given,
114 it will be part of the same @code{argv} entry as the option itself.
115
116 This property cannot be used alongside @code{Joined} or @code{Separate}.
117
118 @item UInteger
119 The option's argument is a non-negative integer.  The option parser
120 will check and convert the argument before passing it to the relevant
121 option handler.
122
123 @item Var(@var{var})
124 The state of this option should be stored in variable @var{var}.
125 The way that the state is stored depends on the type of option:
126
127 @itemize @bullet
128 @item
129 If the option uses the @code{Mask} or @code{InverseMask} properties,
130 @var{var} is the integer variable that contains the mask.
131
132 @item
133 If the option is a normal on/off switch, @var{var} is an integer
134 variable that is nonzero when the option is enabled.  The options
135 parser will set the variable to 1 when the positive form of the
136 option is used and 0 when the ``no-'' form is used.
137
138 @item
139 If the option takes an argument and has the @code{UInteger} property,
140 @var{var} is an integer variable that stores the value of the argument.
141
142 @item
143 Otherwise, if the option takes an argument, @var{var} is a pointer to
144 the argument string.  The pointer will be null if the argument is optional
145 and wasn't given.
146 @end itemize
147
148 The option-processing script will usually declare @var{var} in
149 @file{options.c} and leave it to be zero-initialized at start-up time.
150 You can modify this behavior using @code{VarExists} and @code{Init}.
151
152 @item Var(@var{var}, @var{set})
153 The option controls an integer variable @var{var} and is active when
154 @var{var} equals @var{set}.  The option parser will set @var{var} to
155 @var{set} when the positive form of the option is used and @code{!@var{set}}
156 when the ``no-'' form is used.
157
158 @var{var} is declared in the same way as for the single-argument form
159 described above.
160
161 @item VarExists
162 The variable specified by the @code{Var} property already exists.
163 No definition should be added to @file{options.c} in response to
164 this option record.
165
166 You should use this property if an earlier option has already declared
167 the variable or if the variable is declared outside @file{options.c}.
168
169 @item Init(@var{value})
170 The variable specified by the @code{Var} property should be statically
171 initialized to @var{value}.
172
173 @item Mask(@var{name})
174 The option is associated with a bit in the @code{target_flags}
175 variable (@pxref{Run-time Target}) and is active when that bit is set.
176 You may also specify @code{Var} to select a variable other than
177 @code{target_flags}.
178
179 The options-processing script will automatically allocate a unique bit
180 for the option.  If the option is attached to @samp{target_flags},
181 the script will set the macro @code{MASK_@var{name}} to the appropriate
182 bitmask.  It will also declare a @code{TARGET_@var{name}} macro that has
183 the value 1 when the option is active and 0 otherwise.  If you use @code{Var}
184 to attach the option to a different variable, the associated macros are
185 called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
186
187 You can disable automatic bit allocation using @code{MaskExists}.
188
189 @item InverseMask(@var{othername})
190 @itemx InverseMask(@var{othername}, @var{thisname})
191 The option is the inverse of another option that has the
192 @code{Mask(@var{othername})} property.  If @var{thisname} is given,
193 the options-processing script will declare a @code{TARGET_@var{thisname}}
194 macro that is 1 when the option is active and 0 otherwise.
195
196 @item MaskExists
197 The mask specified by the @code{Mask} property already exists.
198 No @code{MASK} or @code{TARGET} definitions should be added to
199 @file{options.h} in response to this option record.
200
201 The main purpose of this property is to support synonymous options.
202 The first option should use @samp{Mask(@var{name})} and the others
203 should use @samp{Mask(@var{name}) MaskExists}.
204
205 @item Report
206 The state of the option should be printed by @option{-fverbose-asm}.
207
208 @item Undocumented
209 The option is deliberately missing documentation and should not
210 be included in the @option{--help} output.
211
212 @item Condition(@var{cond})
213 The option should only be accepted if preprocessor condition
214 @var{cond} is true.  Note that any C declarations associated with the
215 option will be present even if @var{cond} is false; @var{cond} simply
216 controls whether the option is accepted and whether it is printed in
217 the @option{--help} output.
218 @end table