summaryrefslogtreecommitdiff
path: root/gcc/doc/options.texi
diff options
context:
space:
mode:
authorrsandifo <rsandifo@138bc75d-0d04-0410-961f-82ee72b054a4>2005-03-14 20:18:43 +0000
committerrsandifo <rsandifo@138bc75d-0d04-0410-961f-82ee72b054a4>2005-03-14 20:18:43 +0000
commitff05e09e2d0d3b01e2dbc1d0d6d869cd0b1ce745 (patch)
tree93e6840750fcec57ca9299b96d2ddd12e82c2805 /gcc/doc/options.texi
parent3d2931b52bc6e77b35fac2cabaf7e5e91db63f9a (diff)
downloadgcc-ff05e09e2d0d3b01e2dbc1d0d6d869cd0b1ce745.tar.gz
* config.gcc (extra_options): New variable for listing option files.
Add ${cpu_type}/${cpu_type}.opt to it if that file exists. * configure.ac (extra_opt_files): New AC_SUBST variable. (tm_file_list, tm_include_list): Include options.h first. * configure: Regenerate. * Makefile.in (extra_opt_files, ALL_OPT_FILES): New variables. (s-options): Use $(ALL_OPT_FILES) instead of $(lang_opt_files) (s-options-h): New rule. (options.h): Depend on it. (TEXI_GCCINT_FILES): Add options.texi. * hooks.h (hook_bool_size_t_constcharptr_int_true): Declare. * hooks.c (hook_bool_size_t_constcharptr_int_true): New function. * target.h (gcc_target): Add default_target_flags and handle_option. * target-def.h (TARGET_DEFAULT_TARGET_FLAGS) (TARGET_HANDLE_OPTION): New macros. (TARGET_INITIALIZER): Include them. * opt-functions.awk (opt_args, nth_arg): New functions. (switch_flags): Handle the "Target" flag. (var_args): Delete. (var_name): Use opt_args and nth_arg. (var_set, var_ref): Likewise. Handle "Mask" and "InverseMask". * opth-gen.awk: Declare target_flags. Declare MASK_* and TARGET_* macros for the "Mask" and "InverseMask" options. * opts.h (cl_var_cond): New enum. (cl_option): Replace the "has_set_value" and "set_value" fields with "var_cond" and "var_value". (CL_TARGET): New macro. (option_enabled, print_filtered_help): Declare. (decode_options): Move definition. * opts.c (handle_option): Search for the original option before removing any "no-" prefix. Handle CL_TARGET. Adjust for the new var_cond and var_value fields. Use targetm.handle_option to handle target options. (decode_options): Set target_flags to targetm.default_target_flags. (print_filtered_help): Make global. Handle CL_TARGET. (option_enabled): New function. * toplev.c (target_switches): Guard with #ifdef TARGET_SWITCHES. (display_target_options, set_target_switch, print_switch_values) (default_pch_valid_p): Guard uses of target_switches with #ifdef TARGET_SWITCHES. Also... (display_target_options): Display the CL_TARGET entries in cl_options. (set_target_option): Don't complain about the "" option when TARGET_SWITCHES is undefined. (print_switch_values): Use option_enabled. (default_pch_valid_p): Check cl_options[] when looking for something that has changed the value of target_flags. * c.opt: Remove documentation from top of file. * doc/gccint.texi: Add an "Options" chapter. Include options.texi. * doc/sourecebuild.texi: Refer to the new options documentation instead of c.opt. Document machine-specific .opt files. * doc/tm.texi (target_flags): Say that this variable is declared by options.h. (TARGET_DEFAULT_TARGET_FLAGS, TARGET_HANDLE_OPTION): Document. (TARGET_SWITCHES, TARGET_OPTIONS): Refer to the option files as an alternative. * doc/options.texi: New file. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@96448 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'gcc/doc/options.texi')
-rw-r--r--gcc/doc/options.texi161
1 files changed, 161 insertions, 0 deletions
diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
new file mode 100644
index 00000000000..138ebdb838d
--- /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