On 1/27/26 17:03, 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 to Jose and Dave for their feedback. I've pushed a revised
version of the patch, as attached.
-Sandra
From f0fd8e82642334487932c45f94ad78636b31bb19 Mon Sep 17 00:00:00 2001
From: Sandra Loosemore <[email protected]>
Date: Thu, 29 Jan 2026 16:41:07 +0000
Subject: [PATCH] doc: Add "user experience" documentation for options
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 to [email protected] and [email protected] for their suggestions
to improve this patch.
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 | 103 ++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 104 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..6c91fe944f4 100644
--- a/gcc/doc/ux.texi
+++ b/gcc/doc/ux.texi
@@ -748,4 +748,105 @@ 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.
+
+@subsection Option Names
+
+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, or an option that is enabled by default.
+
+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}.
+
+When adding an option that is specific to a front end, please do not
+include the name of the language in the option name (e.g., as a
+prefix). It is safe to assume users are aware of the compiler they
+are using. Similar considerations apply to back end options.
+
+@subsection Developer Options
+
+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 not only keeps the code from getting bit-rotten,
+it also makes debugging options available at the user's site without
+needing to rebuild GCC, which historically has proven invaluable.
+Such options are documented in the Developer Options section of the manual
+(@pxref{Option Summary,,Option Summary,gcc,Using the GNU Compiler Collection}).
+
+If an option is not intended to be user visible at all (for example,
+it's used only to support testing 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
+user-facing documentation is deliberate.
+
+Parameters (@samp{--param=}) are special options that allow control
+over constants affecting GCC's internal behavior. For example,
+traditionally parameters been used in GCC instead of hard-wired
+constants to control things like the maximum number of passes for
+iterative optimization algorithms. Since these are also
+not intended to be user-visible, they need not be documented or explicitly
+marked as @samp{Undocumented}.
+
+@subsection Documentation Requirements
+
+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
+
+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 and is usually a better
+choice than completely removing it.
+@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.
--
2.39.5
