27.2.1 Option Names ¶

Please follow existing conventions for option naming. Target-specific options should begin with ‘-m’, general code generation and optimization options with ‘-f’, options controlling diagnostic messages with ‘-W’, and options controlling debug output with ‘-g’. In each of these four categories there is a corresponding negative form for each option beginning with ‘-mno-’, ‘-fno-’, ‘-Wno-’, or ‘-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 ‘RejectNegative’ attribute on the definition in the .opt file. If you want to add an option that only has a negative form (perhaps to disable a positive-form multiple-choice option that takes an argument), list it in the .opt file in its ‘no-’ form and also add ‘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.

27.2.2 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 #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 (see Option Summary in 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 ‘Undocumented’ property in the .opt file definition so it is clear to other maintainers that the lack of user-facing documentation is deliberate.

Parameters (‘--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 ‘Undocumented’.

27.2.3 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 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:

• Add the option to the appropriate table in the Option Summary section (see Option Summary in 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.
• 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.
• Add index entries for both the positive and negative forms just before the detailed documentation.

Sometimes options become obsolete. There are several choices of what to do here.

• You can remove the entry entirely from the .opt file. This typically causes a generic error if GCC is invoked with that option.
• You can add the ‘WarnRemoved’ attribute to the option definition. This results in a more specific error message and is usually a better choice than completely removing it.
• You can add the ‘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.
• You can add the ‘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.

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 ‘make regenerate-opt-urls’ in the 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.