-@c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
+@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@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{opts.sh}
+@cindex @samp{optc-gen.awk}
Most GCC command-line options are described by special option
definition files, the names of which conventionally end in
@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
+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
-An option definition record. These records have the following fields:
+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
+A variable record to define a variable used to store option
+information. These records have two fields: the string
+@samp{Variable}, and a declaration of the type and name of the
+variable, optionally with an initializer (but without any trailing
+@samp{;}). These records may be used for variables used for many
+options where declaring the initializer in a single option definition
+record, or duplicating it in many records, would be inappropriate, or
+for variables set in option handlers rather than referenced by
+@code{Var} properties.
+
+@item
+An option definition record. These records have the following fields:
@enumerate
@item
the name of the option, with the leading ``-'' removed
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
+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}}
+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.
@node 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 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
@item Target
The option is available for all languages but is target-specific.
+@item Driver
+The option is handled by the compiler driver using code not shared
+with the compilers proper (@file{cc1} etc.).
+
@item @var{language}
The option is available when compiling for the given language.
option. Each @var{language} must have been declared by an earlier
@code{Language} record. @xref{Option file format}.
+@item RejectDriver
+The option is only handled by the compilers proper (@file{cc1} etc.)@:
+and should not be accepted by the driver.
+
@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
This property cannot be used alongside @code{Joined} or @code{Separate}.
+@item MissingArgError(@var{message})
+For an option marked @code{Joined} or @code{Separate}, the message
+@var{message} will be used as an error message if the mandatory
+argument is missing; for options without @code{MissingArgError}, a
+generic error message is used. @var{message} should contain a single
+@samp{%qs} format, which will be used to format the name of the option
+passed.
+
@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.
+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 NoDriverArg
+For an option marked @code{Separate}, the option only takes an
+argument in the compiler proper, not in the driver. This is for
+compatibility with existing options that are used both directly and
+via @option{-Wp,}; new options should not have this property.
@item Var(@var{var})
-The option controls an integer variable @var{var}. If the option has
-the @code{UInteger} property, the option parser will set @var{var} to
-the value of the user-specified argument. Otherwise the option is
-assumed to be an on/off switch that is active when @var{var} is nonzero.
-In this case, the option parser will set @var{var} to 1 when the positive
-form of the option is used and 0 when the ``no-'' form is used.
+The state of this option should be stored in variable @var{var}
+(actually a macro for @code{global_options.x_@var{var}}).
+The way that the state is stored depends on the type of option:
-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}.
+@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 zero-initialize @var{var}.
+You can modify this behavior using @code{Init}.
@item Var(@var{var}, @var{set})
The option controls an integer variable @var{var} and is active when
@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 if an earlier option has already declared
-the variable or 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}.
+initialized to @var{value}. If more than one option using the same
+variable specifies @code{Init}, all must specify the same initializer.
@item Mask(@var{name})
The option is associated with a bit in the @code{target_flags}
The first option should use @samp{Mask(@var{name})} and the others
should use @samp{Mask(@var{name}) MaskExists}.
+@item Alias(@var{opt})
+@itemx Alias(@var{opt}, @var{arg})
+@itemx Alias(@var{opt}, @var{posarg}, @var{negarg})
+The option is an alias for @option{-@var{opt}}. In the first form,
+any argument passed to the alias is considered to be passed to
+@option{-@var{opt}}, and @option{-@var{opt}} is considered to be
+negated if the alias is used in negated form. In the second form, the
+alias may not be negated or have an argument, and @var{posarg} is
+considered to be passed as an argument to @option{-@var{opt}}. In the
+third form, the alias may not have an argument, if the alias is used
+in the positive form then @var{posarg} is considered to be passed to
+@option{-@var{opt}}, and if the alias is used in the negative form
+then @var{negarg} is considered to be passed to @option{-@var{opt}}.
+
+Aliases should not specify @code{Var} or @code{Mask} or
+@code{UInteger}. Aliases should normally specify the same languages
+as the target of the alias; the flags on the target will be used to
+determine any diagnostic for use of an option for the wrong language,
+while those on the alias will be used to identify what command-line
+text is the option and what text is any argument to that option.
+
+When an @code{Alias} definition is used for an option, driver specs do
+not need to handle it and no @samp{OPT_} enumeration value is defined
+for it; only the canonical form of the option will be seen in those
+places.
+
+@item Ignore
+This option is ignored apart from printing any warning specified using
+@code{Warn}. The option will not be seen by specs and no @samp{OPT_}
+enumeration value is defined for it.
+
+@item SeparateAlias
+For an option marked with @code{Joined}, @code{Separate} and
+@code{Alias}, the option only acts as an alias when passed a separate
+argument; with a joined argument it acts as a normal option, with an
+@samp{OPT_} enumeration value. This is for compatibility with the
+Java @option{-d} option and should not be used for new options.
+
+@item Warn(@var{message})
+If this option is used, output the warning @var{message}.
+@var{message} is a format string, either taking a single operand with
+a @samp{%qs} format which is the option name, or not taking any
+operands, which is passed to the @samp{warning} function. If an alias
+is marked @code{Warn}, the target of the alias must not also be marked
+@code{Warn}.
+
@item Report
The state of the option should be printed by @option{-fverbose-asm}.
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
OSDN Git Service
