Subversion Repositories scarts

@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

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 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 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.

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