path: root/gcc/doc/options.texi

@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Options
@chapter Option specification files
@cindex option specification files
@cindex @samp{optc-gen.awk}

Most GCC command-line options are described by special option
definition files, the names of which conventionally end in
@code{.opt}.  This chapter describes the format of these files.

@menu
* Option file format::   The general layout of the files
* Option properties::    Supported option properties
@end menu

@node Option file format
@section Option file format

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
blank lines.  Comments may appear on their own line anywhere within
the file and are preceded by semicolons.  Whitespace is allowed before
the semicolon.

The files can contain the following types of record:

@itemize @bullet
@item
A language definition record.  These records have two fields: the
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.
@xref{Option properties}.

@item
A target specific save record to save additional information. These
records have two fields: the string @samp{TargetSave}, and a
declaration type to go in the @code{cl_target_option} structure.

@item
An option definition record.  These records have the following fields:
@enumerate
@item
the name of the option, with the leading ``-'' removed
@item
a space-separated list of option properties (@pxref{Option properties})
@item
the help text to use for @option{--help} (omitted if the second field
contains the @code{Undocumented} property).
@end enumerate

By default, all options beginning with ``f'', ``W'' or ``m'' are
implicitly assumed to take a ``no-'' form.  This form should not be
listed separately.  If an option beginning with one of these letters
does not have a ``no-'' form, you can use the @code{RejectNegative}
property to reject it.

The help text is automatically line-wrapped before being displayed.
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
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
tab forms the help text.  This allows you to elaborate on what type
of argument the option takes.

@item
A target mask record.  These records have one field of the form
@samp{Mask(@var{x})}.  The options-processing script will automatically
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
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
0 otherwise.

They are primarily intended to declare target masks that are not
associated with user options, either because these masks represent
internal switches or because the options are not available on all
configurations and yet the masks always need to be defined.
@end itemize

@node Option properties
@section Option properties

The second field of an option record can specify any of the following
properties.  When an option takes an argument, it is enclosed in parentheses
following the option property name.  The parser that handles option files
is quite simplistic, and will be tricked by any nested parentheses within
the argument text itself; in this case, the entire option argument can
be wrapped in curly braces within the parentheses to demarcate it, e.g.:

@smallexample
Condition(@{defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)@})
@end smallexample

@table @code
@item Common
The option is available for all languages and targets.

@item Target
The option is available for all languages but is target-specific.

@item @var{language}
The option is available when compiling for the given language.

It is possible to specify several different languages for the same
option.  Each @var{language} must have been declared by an earlier
@code{Language} record.  @xref{Option file format}.

@item RejectNegative
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
property is used.

@item Negative(@var{othername})
The option will turn off another option @var{othername}, which is
the option name with the leading ``-'' removed.  This chain action will
propagate through the @code{Negative} property of the option to be
turned off.

@item Joined
@itemx Separate
The option takes a mandatory argument.  @code{Joined} indicates
that the option and argument can be included in the same @code{argv}
entry (as with @code{-mflush-func=@var{name}}, for example).
@code{Separate} indicates that the option and argument can be
separate @code{argv} entries (as with @code{-o}).  An option is
allowed to have both of these properties.

@item JoinedOrMissing
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.

This property cannot be used alongside @code{Joined} or @code{Separate}.

@item UInteger
The option's argument is a non-negative integer.  The option parser
will check and convert the argument before passing it to the relevant
option handler.  @code{UInteger} should also be used on options like
@code{-falign-loops} where both @code{-falign-loops} and
@code{-falign-loops}=@var{n} are supported to make sure the saved
options are given a full integer.

@item Var(@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:

@itemize @bullet
@item
If the option uses the @code{Mask} or @code{InverseMask} properties,
@var{var} is the integer variable that contains the mask.

@item
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
parser will set the variable to 1 when the positive form of the
option is used and 0 when the ``no-'' form is used.

@item
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.

@item
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
and wasn't given.
@end itemize

The option-processing script will usually declare @var{var} in
@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}.

@item Var(@var{var}, @var{set})
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{set} when the positive form of the option is used and @code{!@var{set}}
when the ``no-'' form is used.

@var{var} is declared in the same way as for the single-argument form
described above.

@item VarExists
The variable specified by the @code{Var} property already exists.
No definition should be added to @file{options.c} in response to
this option record.

You should use this property only if the variable is declared outside
@file{options.c}.

@item Init(@var{value})
The variable specified by the @code{Var} property should be statically
initialized to @var{value}.

@item Mask(@var{name})
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.
You may also specify @code{Var} to select a variable other than
@code{target_flags}.

The options-processing script will automatically allocate a unique bit
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
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}
to attach the option to a different variable, the associated macros are
called @code{OPTION_MASK_@var{name}} and @code{OPTION_@var{name}} respectively.

You can disable automatic bit allocation using @code{MaskExists}.

@item InverseMask(@var{othername})
@itemx InverseMask(@var{othername}, @var{thisname})
The option is the inverse of another option that has the
@code{Mask(@var{othername})} property.  If @var{thisname} is given,
the options-processing script will declare a @code{TARGET_@var{thisname}}
macro that is 1 when the option is active and 0 otherwise.

@item MaskExists
The mask specified by the @code{Mask} property already exists.
No @code{MASK} or @code{TARGET} definitions should be added to
@file{options.h} in response to this option record.

The main purpose of this property is to support synonymous options.
The first option should use @samp{Mask(@var{name})} and the others
should use @samp{Mask(@var{name}) MaskExists}.

@item Report
The state of the option should be printed by @option{-fverbose-asm}.

@item Undocumented
The option is deliberately missing documentation and should not
be included in the @option{--help} output.

@item Condition(@var{cond})
The option should only be accepted if preprocessor condition
@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
controls whether the option is accepted and whether it is printed in
the @option{--help} output.

@item Save
Build the @code{cl_target_option} structure to hold a copy of the
option, add the functions @code{cl_target_option_save} and
@code{cl_target_option_restore} to save and restore the options.
@end table