From b094d6c4bf572654a031ecc4afe675154c886dc5 Mon Sep 17 00:00:00 2001 From: Jing Yu Date: Thu, 22 Jul 2010 14:03:48 -0700 Subject: commit gcc-4.4.3 which is used to build gcc-4.4.3 Android toolchain in master. The source is based on fsf gcc-4.4.3 and contains local patches which are recorded in gcc-4.4.3/README.google. Change-Id: Id8c6d6927df274ae9749196a1cc24dbd9abc9887 --- gcc-4.4.3/gcc/doc/options.texi | 237 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 gcc-4.4.3/gcc/doc/options.texi (limited to 'gcc-4.4.3/gcc/doc/options.texi') diff --git a/gcc-4.4.3/gcc/doc/options.texi b/gcc-4.4.3/gcc/doc/options.texi new file mode 100644 index 000000000..a05a6b2c3 --- /dev/null +++ b/gcc-4.4.3/gcc/doc/options.texi @@ -0,0 +1,237 @@ +@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 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 Negative(@var{othername}) +The option will turn off another option @var{othername}, which is the +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 -- cgit v1.2.3