diff options
author | rsandifo <rsandifo@138bc75d-0d04-0410-961f-82ee72b054a4> | 2005-03-14 20:18:43 +0000 |
---|---|---|
committer | rsandifo <rsandifo@138bc75d-0d04-0410-961f-82ee72b054a4> | 2005-03-14 20:18:43 +0000 |
commit | ff05e09e2d0d3b01e2dbc1d0d6d869cd0b1ce745 (patch) | |
tree | 93e6840750fcec57ca9299b96d2ddd12e82c2805 /gcc/doc/options.texi | |
parent | 3d2931b52bc6e77b35fac2cabaf7e5e91db63f9a (diff) | |
download | gcc-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.texi | 161 |
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 |