Movatterモバイル変換

Previous:Guidelines for Diagnostics, Up:User Experience Guidelines   [Contents][Index]

27.2.1 Option Names ¶

Please follow existing conventions for option naming. Target-specificoptions should begin with ‘-m’, general code generation andoptimization options with ‘-f’, options controlling diagnosticmessages with ‘-W’, and options controlling debug output with‘-g’. In each of these four categories there is a correspondingnegative form for each option beginning with ‘-mno-’,‘-fno-’, ‘-Wno-’, or ‘-gno-’ (respectively), whichallow users to override a positive form of the option earlier on thecommand line, or an option that is enabled by default.

For options that take an argument, the negative form often does notmake sense; in this case, specify the ‘RejectNegative’ attributeon the definition in the.opt file. If you want to add anoption thatonly has a negative form (perhaps to disable apositive-form multiple-choice option that takes an argument), list itin the.opt file in its ‘no-’ form and also add‘RejectNegative’.

When adding an option that is specific to a front end, please do notinclude the name of the language in the option name (e.g., as aprefix). It is safe to assume users are aware of the compiler theyare 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, pleaseadd an option to control it, rather than commenting it out, or guardingit with#if 0. This not only keeps the code from getting bit-rotten,it also makes debugging options available at the user’s site withoutneeding to rebuild GCC, which historically has proven invaluable.Such options are documented in the Developer Options section of the manual(seeOption Summary inUsing 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 featuresthat are not ready or stable enough for general use), you shouldexplicitly specify the ‘Undocumented’ property in the.optfile definition so it is clear to other maintainers that the lack ofuser-facing documentation is deliberate.

Parameters (‘--param=’) are special options that allow controlover constants affecting GCC’s internal behavior. For example,traditionally parameters been used in GCC instead of hard-wiredconstants to control things like the maximum number of passes foriterative optimization algorithms. Since these are alsonot intended to be user-visible, they need not be documented or explicitlymarked 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 languagefamily and language-independent options are documented in the main GCCmanual (ininvoke.texi or files included by it), whileoptions 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(seeOption Summary inUsing 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 isonly necessary to document one of the positive or negative forms, but sometimesit’s appropriate to list both.
• Add index entries forboth the positive and negative forms justbefore the detailed documentation.

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

• You can remove the entry entirely from the.opt file. Thistypically 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 betterchoice than completely removing it.
• You can add the ‘Warn’ attribute to the option definition. Forexample, 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 tosilently ignore it and do nothing if it is passed. This has the advantagethat it won’t break old makefiles, but is only appropriate if the defaultbehavior without the option is consistent with the previous behavior withthe option and doesn’t conflict with user expectations.

In all of these cases, you should remove the user documentation for an optionat 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 thegcc directory of yourbuild tree, and check in the resulting changes. This updates thedatabase used to insert links to the online documentation for optionsthat are mentioned in diagnostic messages.