| @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 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 |
| 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. |
| |
| @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. |
| @end table |