From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/doc/options.texi | 452 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 452 insertions(+) create mode 100644 gcc/doc/options.texi (limited to 'gcc/doc/options.texi') diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi new file mode 100644 index 000000000..e39d79e1c --- /dev/null +++ b/gcc/doc/options.texi @@ -0,0 +1,452 @@ +@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +@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 +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 +A variable record to define a variable used to store option +information. These records have two fields: the string +@samp{TargetVariable}, and a declaration of the type and name of the +variable, optionally with an initializer (but without any trailing +@samp{;}). @samp{TargetVariable} is a combination of @samp{Variable} +and @samp{TargetSave} records in that the variable is defined in the +@code{gcc_options} structure, but these variables are also stored in +the @code{cl_target_option} structure. The variables are saved in the +target save code and restored in the target restore code. + +@item +A variable record to record any additional files that the +@file{options.h} file should include. This is useful to provide +enumeration or structure definitions needed for target variables. +These records have two fields: the string @samp{HeaderInclude} and the +name of the include file. + +@item +A variable record to record any additional files that the +@file{options.c} file should include. This is useful to provide +inline functions needed for target variables and/or @code{#ifdef} +sequences to properly set up the initialization. These records have +two fields: the string @samp{SourceInclude} and the name of the +include file. + +@item +An enumeration record to define a set of strings that may be used as +arguments to an option or options. These records have three fields: +the string @samp{Enum}, a space-separated list of properties and help +text used to describe the set of strings in @option{--help} output. +Properties use the same format as option properties; the following are +valid: +@table @code +@item Name(@var{name}) +This property is required; @var{name} must be a name (suitable for use +in C identifiers) used to identify the set of strings in @code{Enum} +option properties. + +@item Type(@var{type}) +This property is required; @var{type} is the C type for variables set +by options using this enumeration together with @code{Var}. + +@item UnknownError(@var{message}) +The message @var{message} will be used as an error message if the +argument is invalid; for enumerations without @code{UnknownError}, a +generic error message is used. @var{message} should contain a single +@samp{%qs} format, which will be used to format the invalid argument. +@end table + +@item +An enumeration value record to define one of the strings in a set +given in an @samp{Enum} record. These records have two fields: the +string @samp{EnumValue} and a space-separated list of properties. +Properties use the same format as option properties; the following are +valid: +@table @code +@item Enum(@var{name}) +This property is required; @var{name} says which @samp{Enum} record +this @samp{EnumValue} record corresponds to. + +@item String(@var{string}) +This property is required; @var{string} is the string option argument +being described by this record. + +@item Value(@var{value}) +This property is required; it says what value (representable as +@code{int}) should be used for the given string. + +@item Canonical +This property is optional. If present, it says the present string is +the canonical one among all those with the given value. Other strings +yielding that value will be mapped to this one so specs do not need to +handle them. + +@item DriverOnly +This property is optional. If present, the present string will only +be accepted by the driver. This is used for cases such as +@option{-march=native} that are processed by the driver so that +@samp{gcc -v} shows how the options chosen depended on the system on +which the compiler was run. +@end table + +@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 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. + +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 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 +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 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 Args(@var{n}) +For an option marked @code{Separate}, indicate that it takes @var{n} +arguments. The default is 1. + +@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 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 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: + +@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 +If the option takes an argument and has the @code{Enum} property, +@var{var} is a variable (type given in the @code{Type} property of the +@samp{Enum} record whose @code{Name} property has the same argument as +the @code{Enum} property of this option) that stores the value of the +argument. + +@item +If the option has the @code{Defer} property, @var{var} is a pointer to +a @code{VEC(cl_deferred_option,heap)} that stores the option for later +processing. (@var{var} is declared with type @code{void *} and needs +to be cast to @code{VEC(cl_deferred_option,heap)} before use.) + +@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} 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 Init(@var{value}) +The variable specified by the @code{Var} property should be statically +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} +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 Enum(@var{name}) +The option's argument is a string from the set of strings associated +with the corresponding @samp{Enum} record. The string is checked and +converted to the integer specified in the corresponding +@samp{EnumValue} record before being passed to option handlers. + +@item Defer +The option should be stored in a vector, specified with @code{Var}, +for later processing. + +@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}. + +@item Warning +This is a warning option and should be shown as such in +@option{--help} output. This flag does not currently affect anything +other than @option{--help}. + +@item Optimization +This is an optimization option. It should be shown as such in +@option{--help} output, and any associated variable named using +@code{Var} should be saved and restored when the optimization level is +changed with @code{optimize} attributes. + +@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. + +@item SetByCombined +The option may also be set by a combined option such as +@option{-ffast-math}. This causes the @code{gcc_options} struct to +have a field @code{frontend_set_@var{name}}, where @code{@var{name}} +is the name of the field holding the value of this option (without the +leading @code{x_}). This gives the front end a way to indicate that +the value has been set explicitly and should not be changed by the +combined option. For example, some front ends use this to prevent +@option{-ffast-math} and @option{-fno-fast-math} from changing the +value of @option{-fmath-errno} for languages that do not use +@code{errno}. + +@end table -- cgit v1.2.3