On Tue, 2026-01-27 at 17:03 -0700, Sandra Loosemore wrote:
> After working through PR122243, it seems appropriate to write down
> some guidelines for adding/maintaining options and options
> documentation so that we can at least point to procedures to keep
> things from getting out of sync again.
Thanks! Overall this looks great, but some thoughts inline below:
>
> gcc/ChangeLog
> * doc/options.texi (Options): Point to the "user experience"
> documentation.
> * doc/ux.texi (Guidelines for Options): Add some.
> ---
> gcc/doc/options.texi | 2 ++
> gcc/doc/ux.texi | 80
> +++++++++++++++++++++++++++++++++++++++++++-
> 2 files changed, 81 insertions(+), 1 deletion(-)
>
> diff --git a/gcc/doc/options.texi b/gcc/doc/options.texi
> index 2201423f4f3..2a1d7e32fbd 100644
> --- a/gcc/doc/options.texi
> +++ b/gcc/doc/options.texi
> @@ -10,6 +10,8 @@
> 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.
> +For information about managing GCC options and the user experience,
> +@ref{Guidelines for Options}.
>
> @menu
> * Option file format:: The general layout of the files
> diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi
> index 3251e115746..ddc857e8fd4 100644
> --- a/gcc/doc/ux.texi
> +++ b/gcc/doc/ux.texi
> @@ -748,4 +748,82 @@ generated patches.
> @cindex options, guidelines for
> @cindex guidelines for options
>
> -@c TODO
> +@xref{Options}, for information about how GCC command-line options
> are
> +defined in @code{.opt} files.
> +
> +Please follow existing conventions for option naming. Target-
> specific
> +options should begin with @samp{-m}, general code generation and
> +optimization options with @samp{-f}, options controlling diagnostic
> +messages with @samp{-W}, and options controlling debug output with
> +@samp{-g}. In each of these four categories there is a
> corresponding
> +negative form for each option beginning with @samp{-mno-},
> +@samp{-fno-}, @samp{-Wno-}, or @samp{-gno-} (respectively), which
> +allow users to override a positive form of the option earlier on the
> +command line.
We might want to clarify what to do for the case where something is
enabled by default, but the user can supply e.g. "-fno-frobnicate" do
disable the "frobnication" (whatever that is) that usually happens.
Consider a Makefile rule that adds -fno-frobnicate to the C flags for
all source files, and then wanting to override it back for a specific
foo.c, where -ffrobnicate would go after, giving.
-fno-frobnicate -ffrobnicate
and thus re-enabling frobnication where the last one wins.
This seems like a valid idiom (used in various places in our options).
> +
> +For options that take an argument, the negative form often does not
> +make sense; in this case, specify the @samp{RejectNegative}
> attribute
> +on the definition in the @code{.opt} file. If you want to add an
> +option that @emph{only} has a negative form (perhaps to disable a
> +positive-form multiple-choice option that takes an argument), list
> it
> +in the @code{.opt} file in its @samp{no-} form and also add
> +@samp{RejectNegative}.
FWIW my initial reading of the paragraph above in the patch made me
think that we were ruling out the dueling "-fno-frobnicate -
ffrobnicate" options I mention in my comment above but on re-reading, I
realize that it's referring to something else.
> +
> +When you add a new option that is intended to be visible to users,
> +you should add documentation for it in the same commit. C language
> +family and language-independent options are documented in the main
> GCC
> +manual (in @file{invoke.texi} or files included by it), while
> +options specific to the front ends for other languages, like
> Fortran,
> +are documented in the corresponding manual.
> +
> +For options documented in the GCC manual, the required documentation
> is:
> +
> +@itemize @bullet{}
> +@item Add the option to the appropriate table in the Option Summary
> section
> +(@pxref{Option Summary,,Option Summary,gcc,Using the GNU Compiler
> Collection}).
> +Only add one of the positive or negative forms here.
> +Use two spaces to separate options listed on the same line.
> +@item Add detailed documentation to the corresponding subsection.
> It is
> +only necessary to document one of the positive or negative forms,
> but sometimes
> +it's appropriate to list both.
> +@item Add index entries for @emph{both} the positive and negative
> forms just
> +before the detailed documentation.
> +@end itemize
> +
> +If an option is not intended to be user visible (for example, it's
> used only
> +to support testing, back-end debugging, or to experiment with new
> features
> +that are not ready or stable enough for general use), you should
> explicitly
> +specify the @samp{Undocumented} property in the @code{.opt} file
> definition
> +so it is clear to other maintainers that the lack of documentation
> is
> +deliberate.
Might want to also mention "Developer Options"; something like:
"If you need to add a feature intended for debugging GCC itself, please
add an option to control it, rather than commenting it out, or guarding
it with @code{#if 0}. This way debugging options are available at the
user's site without needing to rebuild GCC, which historically has
proven invaluable. Such options should be added to the "Developer
Options" section of the manual."
perhaps?
> +
> +Parameters (@samp{--param=}) are special options that allow control
> +over constants affecting GCC's internal behavior. Since these are
> also
> +not intended to be user-visible, they need not be documented or
> explicitly
> +marked as @samp{Undocumented}.
> +
> +Sometimes options become obsolete. There are several choices of
> what to do
> +here.
> +@itemize @bullet{}
> +@item You can remove the entry entirely from the @code{.opt} file.
> This
> +typically causes a generic error if GCC is invoked with that option.
> +@item You can add the @samp{WarnRemoved} attribute to the option
> definition.
> +This results in a more specific error message.
> +@item You can add the @samp{Warn} attribute to the option
> definition. For
> +example, you can use this if you want to warn that an option is
> deprecated,
> +rather than remove it completely.
> +@item You can add the @samp{Ignore} attribute to the option
> definition to
> +silently ignore it and do nothing if it is passed. This has the
> advantage
> +that it won't break old makefiles, but is only appropriate if the
> default
> +behavior without the option is consistent with the previous behavior
> with
> +the option and doesn't conflict with user expectations.
> +@end itemize
> +
> +In all of these cases, you should remove the user documentation for
> an option
> +at the same time you remove, disable, or deprecate it.
> +
> +If you add, remove, or modify options documentation, you must also
> run
> +@samp{make regenerate-opt-urls} in the @file{gcc} directory of your
> +build tree, and check in the resulting changes. This updates the
> +database used to insert links to the online documentation for
> options
> +that are mentioned in diagnostic messages.
Looks great, thanks!
Dave
