@c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
|
@c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
|
@c This is part of the GCC manual.
|
@c This is part of the GCC manual.
|
@c For copying conditions, see the file gcc.texi.
|
@c For copying conditions, see the file gcc.texi.
|
|
|
@node Options
|
@node Options
|
@chapter Option specification files
|
@chapter Option specification files
|
@cindex option specification files
|
@cindex option specification files
|
@cindex @samp{opts.sh}
|
@cindex @samp{opts.sh}
|
|
|
Most GCC command-line options are described by special option
|
Most GCC command-line options are described by special option
|
definition files, the names of which conventionally end in
|
definition files, the names of which conventionally end in
|
@code{.opt}. This chapter describes the format of these files.
|
@code{.opt}. This chapter describes the format of these files.
|
|
|
@menu
|
@menu
|
* Option file format:: The general layout of the files
|
* Option file format:: The general layout of the files
|
* Option properties:: Supported option properties
|
* Option properties:: Supported option properties
|
@end menu
|
@end menu
|
|
|
@node Option file format
|
@node Option file format
|
@section Option file format
|
@section Option file format
|
|
|
Option files are a simple list of records in which each field occupies
|
Option files are a simple list of records in which each field occupies
|
its own line and in which the records themselves are separated by
|
its own line and in which the records themselves are separated by
|
blank lines. Comments may appear on their own line anywhere within
|
blank lines. Comments may appear on their own line anywhere within
|
the file and are preceded by semicolons. Whitespace is allowed before
|
the file and are preceded by semicolons. Whitespace is allowed before
|
the semicolon.
|
the semicolon.
|
|
|
The files can contain the following types of record:
|
The files can contain the following types of record:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
A language definition record. These records have two fields: the
|
A language definition record. These records have two fields: the
|
string @samp{Language} and the name of the language. Once a language
|
string @samp{Language} and the name of the language. Once a language
|
has been declared in this way, it can be used as an option property.
|
has been declared in this way, it can be used as an option property.
|
@xref{Option properties}.
|
@xref{Option properties}.
|
|
|
@item
|
@item
|
An option definition record. These records have the following fields:
|
An option definition record. These records have the following fields:
|
|
|
@enumerate
|
@enumerate
|
@item
|
@item
|
the name of the option, with the leading ``-'' removed
|
the name of the option, with the leading ``-'' removed
|
@item
|
@item
|
a space-separated list of option properties (@pxref{Option properties})
|
a space-separated list of option properties (@pxref{Option properties})
|
@item
|
@item
|
the help text to use for @option{--help} (omitted if the second field
|
the help text to use for @option{--help} (omitted if the second field
|
contains the @code{Undocumented} property).
|
contains the @code{Undocumented} property).
|
@end enumerate
|
@end enumerate
|
|
|
By default, all options beginning with ``f'', ``W'' or ``m'' are
|
By default, all options beginning with ``f'', ``W'' or ``m'' are
|
implicitly assumed to take a ``no-'' form. This form should not be
|
implicitly assumed to take a ``no-'' form. This form should not be
|
listed separately. If an option beginning with one of these letters
|
listed separately. If an option beginning with one of these letters
|
does not have a ``no-'' form, you can use the @code{RejectNegative}
|
does not have a ``no-'' form, you can use the @code{RejectNegative}
|
property to reject it.
|
property to reject it.
|
|
|
The help text is automatically line-wrapped before being displayed.
|
The help text is automatically line-wrapped before being displayed.
|
Normally the name of the option is printed on the left-hand side of
|
Normally the name of the option is printed on the left-hand side of
|
the output and the help text is printed on the right. However, if the
|
the output and the help text is printed on the right. However, if the
|
help text contains a tab character, the text to the left of the tab is
|
help text contains a tab character, the text to the left of the tab is
|
used instead of the option's name and the text to the right of the
|
used instead of the option's name and the text to the right of the
|
tab forms the help text. This allows you to elaborate on what type
|
tab forms the help text. This allows you to elaborate on what type
|
of argument the option takes.
|
of argument the option takes.
|
|
|
@item
|
@item
|
A target mask record. These records have one field of the form
|
A target mask record. These records have one field of the form
|
@samp{Mask(@var{x})}. The options-processing script will automatically
|
@samp{Mask(@var{x})}. The options-processing script will automatically
|
allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
|
allocate a bit in @code{target_flags} (@pxref{Run-time Target}) for
|
each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
|
each mask name @var{x} and set the macro @code{MASK_@var{x}} to the
|
appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
|
appropriate bitmask. It will also declare a @code{TARGET_@var{x}}
|
macro that has the value 1 when bit @code{MASK_@var{x}} is set and
|
macro that has the value 1 when bit @code{MASK_@var{x}} is set and
|
0 otherwise.
|
0 otherwise.
|
|
|
They are primarily intended to declare target masks that are not
|
They are primarily intended to declare target masks that are not
|
associated with user options, either because these masks represent
|
associated with user options, either because these masks represent
|
internal switches or because the options are not available on all
|
internal switches or because the options are not available on all
|
configurations and yet the masks always need to be defined.
|
configurations and yet the masks always need to be defined.
|
@end itemize
|
@end itemize
|
|
|
@node Option properties
|
@node Option properties
|
@section Option properties
|
@section Option properties
|
|
|
The second field of an option record can specify the following properties:
|
The second field of an option record can specify the following properties:
|
|
|
@table @code
|
@table @code
|
@item Common
|
@item Common
|
The option is available for all languages and targets.
|
The option is available for all languages and targets.
|
|
|
@item Target
|
@item Target
|
The option is available for all languages but is target-specific.
|
The option is available for all languages but is target-specific.
|
|
|
@item @var{language}
|
@item @var{language}
|
The option is available when compiling for the given language.
|
The option is available when compiling for the given language.
|
|
|
It is possible to specify several different languages for the same
|
It is possible to specify several different languages for the same
|
option. Each @var{language} must have been declared by an earlier
|
option. Each @var{language} must have been declared by an earlier
|
@code{Language} record. @xref{Option file format}.
|
@code{Language} record. @xref{Option file format}.
|
|
|
@item RejectNegative
|
@item RejectNegative
|
The option does not have a ``no-'' form. All options beginning with
|
The option does not have a ``no-'' form. All options beginning with
|
``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
|
``f'', ``W'' or ``m'' are assumed to have a ``no-'' form unless this
|
property is used.
|
property is used.
|
|
|
@item Negative(@var{othername})
|
@item Negative(@var{othername})
|
The option will turn off another option @var{othername}, which is the
|
The option will turn off another option @var{othername}, which is the
|
the option name with the leading ``-'' removed. This chain action will
|
the option name with the leading ``-'' removed. This chain action will
|
propagate through the @code{Negative} property of the option to be
|
propagate through the @code{Negative} property of the option to be
|
turned off.
|
turned off.
|
|
|
@item Joined
|
@item Joined
|
@itemx Separate
|
@itemx Separate
|
The option takes a mandatory argument. @code{Joined} indicates
|
The option takes a mandatory argument. @code{Joined} indicates
|
that the option and argument can be included in the same @code{argv}
|
that the option and argument can be included in the same @code{argv}
|
entry (as with @code{-mflush-func=@var{name}}, for example).
|
entry (as with @code{-mflush-func=@var{name}}, for example).
|
@code{Separate} indicates that the option and argument can be
|
@code{Separate} indicates that the option and argument can be
|
separate @code{argv} entries (as with @code{-o}). An option is
|
separate @code{argv} entries (as with @code{-o}). An option is
|
allowed to have both of these properties.
|
allowed to have both of these properties.
|
|
|
@item JoinedOrMissing
|
@item JoinedOrMissing
|
The option takes an optional argument. If the argument is given,
|
The option takes an optional argument. If the argument is given,
|
it will be part of the same @code{argv} entry as the option itself.
|
it will be part of the same @code{argv} entry as the option itself.
|
|
|
This property cannot be used alongside @code{Joined} or @code{Separate}.
|
This property cannot be used alongside @code{Joined} or @code{Separate}.
|
|
|
@item UInteger
|
@item UInteger
|
The option's argument is a non-negative integer. The option parser
|
The option's argument is a non-negative integer. The option parser
|
will check and convert the argument before passing it to the relevant
|
will check and convert the argument before passing it to the relevant
|
option handler.
|
option handler.
|
|
|
@item Var(@var{var})
|
@item Var(@var{var})
|
The state of this option should be stored in variable @var{var}.
|
The state of this option should be stored in variable @var{var}.
|
The way that the state is stored depends on the type of option:
|
The way that the state is stored depends on the type of option:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
If the option uses the @code{Mask} or @code{InverseMask} properties,
|
If the option uses the @code{Mask} or @code{InverseMask} properties,
|
@var{var} is the integer variable that contains the mask.
|
@var{var} is the integer variable that contains the mask.
|
|
|
@item
|
@item
|
If the option is a normal on/off switch, @var{var} is an integer
|
If the option is a normal on/off switch, @var{var} is an integer
|
variable that is nonzero when the option is enabled. The options
|
variable that is nonzero when the option is enabled. The options
|
parser will set the variable to 1 when the positive form of the
|
parser will set the variable to 1 when the positive form of the
|
option is used and 0 when the ``no-'' form is used.
|
option is used and 0 when the ``no-'' form is used.
|
|
|
@item
|
@item
|
If the option takes an argument and has the @code{UInteger} property,
|
If the option takes an argument and has the @code{UInteger} property,
|
@var{var} is an integer variable that stores the value of the argument.
|
@var{var} is an integer variable that stores the value of the argument.
|
|
|
@item
|
@item
|
Otherwise, if the option takes an argument, @var{var} is a pointer to
|
Otherwise, if the option takes an argument, @var{var} is a pointer to
|
the argument string. The pointer will be null if the argument is optional
|
the argument string. The pointer will be null if the argument is optional
|
and wasn't given.
|
and wasn't given.
|
@end itemize
|
@end itemize
|
|
|
The option-processing script will usually declare @var{var} in
|
The option-processing script will usually declare @var{var} in
|
@file{options.c} and leave it to be zero-initialized at start-up time.
|
@file{options.c} and leave it to be zero-initialized at start-up time.
|
You can modify this behavior using @code{VarExists} and @code{Init}.
|
You can modify this behavior using @code{VarExists} and @code{Init}.
|
|
|
@item Var(@var{var}, @var{set})
|
@item Var(@var{var}, @var{set})
|
The option controls an integer variable @var{var} and is active when
|
The option controls an integer variable @var{var} and is active when
|
@var{var} equals @var{set}. The option parser will set @var{var} to
|
@var{var} equals @var{set}. The option parser will set @var{var} to
|
@var{set} when the positive form of the option is used and @code{!@var{set}}
|
@var{set} when the positive form of the option is used and @code{!@var{set}}
|
when the ``no-'' form is used.
|
when the ``no-'' form is used.
|
|
|
@var{var} is declared in the same way as for the single-argument form
|
@var{var} is declared in the same way as for the single-argument form
|
described above.
|
described above.
|
|
|
@item VarExists
|
@item VarExists
|
The variable specified by the @code{Var} property already exists.
|
The variable specified by the @code{Var} property already exists.
|
No definition should be added to @file{options.c} in response to
|
No definition should be added to @file{options.c} in response to
|
this option record.
|
this option record.
|
|
|
You should use this property only if the variable is declared outside
|
You should use this property only if the variable is declared outside
|
@file{options.c}.
|
@file{options.c}.
|
|
|
@item Init(@var{value})
|
@item Init(@var{value})
|
The variable specified by the @code{Var} property should be statically
|
The variable specified by the @code{Var} property should be statically
|
initialized to @var{value}.
|
initialized to @var{value}.
|
|
|
@item Mask(@var{name})
|
@item Mask(@var{name})
|
The option is associated with a bit in the @code{target_flags}
|
The option is associated with a bit in the @code{target_flags}
|
variable (@pxref{Run-time Target}) and is active when that bit is set.
|
variable (@pxref{Run-time Target}) and is active when that bit is set.
|
You may also specify @code{Var} to select a variable other than
|
You may also specify @code{Var} to select a variable other than
|
@code{target_flags}.
|
@code{target_flags}.
|
|
|
The options-processing script will automatically allocate a unique bit
|
The options-processing script will automatically allocate a unique bit
|
for the option. If the option is attached to @samp{target_flags},
|
for the option. If the option is attached to @samp{target_flags},
|
the script will set the macro @code{MASK_@var{name}} to the appropriate
|
the script will set the macro @code{MASK_@var{name}} to the appropriate
|
bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
|
bitmask. It will also declare a @code{TARGET_@var{name}} macro that has
|
the value 1 when the option is active and 0 otherwise. If you use @code{Var}
|
the value 1 when the option is active and 0 otherwise. If you use @code{Var}
|
to attach the option to a different variable, the associated macros are
|
to attach the option to a different variable, the associated macros are
|
called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
|
called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.
|
|
|
You can disable automatic bit allocation using @code{MaskExists}.
|
You can disable automatic bit allocation using @code{MaskExists}.
|
|
|
@item InverseMask(@var{othername})
|
@item InverseMask(@var{othername})
|
@itemx InverseMask(@var{othername}, @var{thisname})
|
@itemx InverseMask(@var{othername}, @var{thisname})
|
The option is the inverse of another option that has the
|
The option is the inverse of another option that has the
|
@code{Mask(@var{othername})} property. If @var{thisname} is given,
|
@code{Mask(@var{othername})} property. If @var{thisname} is given,
|
the options-processing script will declare a @code{TARGET_@var{thisname}}
|
the options-processing script will declare a @code{TARGET_@var{thisname}}
|
macro that is 1 when the option is active and 0 otherwise.
|
macro that is 1 when the option is active and 0 otherwise.
|
|
|
@item MaskExists
|
@item MaskExists
|
The mask specified by the @code{Mask} property already exists.
|
The mask specified by the @code{Mask} property already exists.
|
No @code{MASK} or @code{TARGET} definitions should be added to
|
No @code{MASK} or @code{TARGET} definitions should be added to
|
@file{options.h} in response to this option record.
|
@file{options.h} in response to this option record.
|
|
|
The main purpose of this property is to support synonymous options.
|
The main purpose of this property is to support synonymous options.
|
The first option should use @samp{Mask(@var{name})} and the others
|
The first option should use @samp{Mask(@var{name})} and the others
|
should use @samp{Mask(@var{name}) MaskExists}.
|
should use @samp{Mask(@var{name}) MaskExists}.
|
|
|
@item Report
|
@item Report
|
The state of the option should be printed by @option{-fverbose-asm}.
|
The state of the option should be printed by @option{-fverbose-asm}.
|
|
|
@item Undocumented
|
@item Undocumented
|
The option is deliberately missing documentation and should not
|
The option is deliberately missing documentation and should not
|
be included in the @option{--help} output.
|
be included in the @option{--help} output.
|
|
|
@item Condition(@var{cond})
|
@item Condition(@var{cond})
|
The option should only be accepted if preprocessor condition
|
The option should only be accepted if preprocessor condition
|
@var{cond} is true. Note that any C declarations associated with the
|
@var{cond} is true. Note that any C declarations associated with the
|
option will be present even if @var{cond} is false; @var{cond} simply
|
option will be present even if @var{cond} is false; @var{cond} simply
|
controls whether the option is accepted and whether it is printed in
|
controls whether the option is accepted and whether it is printed in
|
the @option{--help} output.
|
the @option{--help} output.
|
@end table
|
@end table
|
|
|
