1 files changed, 161 insertions, 0 deletions
diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
new file mode 100644
index 0000000..138ebdb
--- /dev/null
+++ b/gcc/doc/options.texi
@@ -0,0 +1,161 @@
+@c Copyright (C) 2003, 2004, 2005 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}
+
+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 two types of record: language definitions and
+option definitions.
+
+A language definition record has 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}.
+
+An option definition record has 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.
+
+@node Option properties
+@section Option properties
+
+The second field of an option record can specify the following properties:
+
+@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 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.
+
+@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 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 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}.
+
+@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.
+
+The options-processing script will automatically allocate a unique
+bit for the option and 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.
+
+@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 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.
+@end table