GCC Coding Conventions

There are some additional coding conventions for code in GCC, beyond those in the GNU Coding Standards. Some existing code may not follow these conventions, but they must be used for new code. If changing existing code to follow these conventions, it is best to send changes to follow the conventions separately from any other changes to the code.

Documentation

Documentation, both of user interfaces and of internals, must be maintained and kept up to date. In particular:

• All command-line options (including all --param arguments) must be documented in the GCC manual.
• Any change to documented behavior (for example, the behavior of a command-line option or a GNU language extension) must include the necessary changes to the manual.
• All target macros must be documented in the GCC manual.
• The documentation of the tree and RTL data structures and interfaces must be kept complete and up to date.
• In general, the documentation of all documented aspects of the front-end and back-end interfaces must be kept up to date, and the opportunity should be taken where possible to remedy gaps in or limitations of the documentation.

ChangeLogs

GCC requires ChangeLog entries for documentation changes; for the web pages (apart from java/ and libstdc++/) the CVS commit logs are sufficient.

See also what the GNU Coding Standards have to say about what goes in ChangeLogs; in particular, descriptions of the purpose of code and changes should go in comments rather than the ChangeLog, though a single line overall description of the changes may be useful above the ChangeLog entry for a large batch of changes.

For changes that are ported from another branch, we recommend to use a single entry whose body contains a verbatim copy of the original entries describing the changes on that branch, possibly preceded by a single-line overall description of the changes.

There is no established convention on when ChangeLog entries are to be made for testsuite changes; see messages 1 and 2.

If your change fixes a PR, put PR java/58 (where java/58 is the actual number of the PR) at the top of the ChangeLog entry.

Portability

There are strict requirements for portability of code in GCC to older systems whose compilers do not implement all of the ISO C standard. GCC requires at least an ANSI C89 or ISO C90 host compiler, and code should avoid pre-standard style function definitions, unnecessary function prototypes and use of the now deprecated @code{PARAMS} macro. See README.Portability for details of some of the portability problems that may arise. Some of these problems are warned about by gcc -Wtraditional, which is included in the default warning options in a bootstrap. (Code outside the C front end is only compiled by GCC, so such requirements do not apply to it.)

The programs included in GCC are linked with the libiberty library, which will replace some standard library functions if not present on the system used, so those functions may be freely used in GCC. In particular, the ISO C string functions memcmp, memcpy, memmove, memset, strchr and strrchr are preferred to the old functions bcmp, bcopy, bzero, index and rindex; see messages 1 and 2. The older functions must no longer be used in GCC; apart from index, these identifiers are poisoned to prevent their use.

Machine-independent files may contain conditionals on features of a particular system, but should never contain conditionals such as #ifdef __hpux__ on the name or version of a particular system. Exceptions may be made to this on a release branch late in the release cycle, to reduce the risk involved in fixing a problem that only shows up on one particular system.

Avoid the use of identifiers or idioms that would prevent code compiling with a C++ compiler. Identifiers such as new or class, that are reserved words in C++, should not be used as variables or field names. Explicit casts should be used to convert between void* and other pointer types.

Function prototypes for extern functions should only occur in header files. Functions should be ordered within source files to minimize the number of function prototypes, by defining them before their first use. Function prototypes should only be used when necessary, to break mutually recursive cycles.

Makefiles

touch should never be used in GCC Makefiles. Instead of touch foo always use $(STAMP) foo.

Testsuite Conventions

Every language or library feature, whether standard or a GNU extension, and every warning GCC can give, should have testcases thoroughly covering both its specification and its implementation. Every bug fixed should have a testcase to detect if the bug recurs.

The testsuite READMEs discuss the requirement to use abort () for runtime failures and exit (0) for success. For compile-time tests, a trick taken from autoconf may be used to evaluate expressions: a declaration extern char x[(EXPR) ? 1 : -1]; will compile successfully if and only if EXPR is nonzero.

Where appropriate, testsuite entries should include comments giving their origin: the people who added them or submitted the bug report they relate to, possibly with a reference to a PR in our bug tracking system. There are some copyright guidelines on what can be included in the testsuite.

If a testcase itself is incorrect, but there's a possibility that an improved testcase might fail on some platform where the incorrect testcase passed, the old testcase should be removed and a new testcase (with a different name) should be added. This helps automated regression-checkers distinguish a true regression from an improvement to the test suite.

Miscellaneous Conventions

Code should use gcc_assert(EXPR) to check invariants. Use gcc_unreachable() to mark places that should never be reachable (such as an unreachable default case of a switch). Do not use gcc_assert(0) for such purposes, as gcc_unreachable gives the compiler more information. The assertions are enabled unless explicitly configured off with --enable-checking=none. Do not use abort. User input should never be validated by either gcc_assert or gcc_unreachable. If the checks are expensive or the compiler can reasonably carry on after the error, they may be conditioned on --enable-checking.

Code testing properties of characters from user source code should use macros such as ISALPHA from safe-ctype.h instead of the standard functions such as isalpha from <ctype.h> to avoid any locale-dependency of the language accepted.

Code in GCC should use the following formatting conventions:

Macros names should be in ALL_CAPS when it's important to be aware that it's a macro (e.g. accessors and simple predicates), but in lowercase (e.g., size_int) where the macro is a wrapper for efficiency that should be considered as a function; see messages 1 and 2.

Testing for ERROR_MARKs should be done by comparing against error_mark_node rather than by comparing the TREE_CODE against ERROR_MARK; see message.

Internal numeric parameters that may affect generated code should be controlled by --param rather than being hardcoded.

Spelling, terminology and markup

The following conventions of spelling and terminology apply throughout GCC, including the manuals, web pages, diagnostics, comments, and (except where they require spaces or hyphens to be used) function and variable names, although consistency in user-visible documentation and diagnostics is more important than that in comments and code. The following table lists some simple cases:

"GCC" should be used for the GNU Compiler Collection, both generally and as the GNU C Compiler in the context of compiling C; "G++" for the C++ compiler; "gcc" and "g++" (lowercase), marked up with @command when in Texinfo, for the commands for compilation when the emphasis is on those; "GNU C" and "GNU C++" for language dialects; and try to avoid the older term "GNU CC".

Use a comma after "e.g." or "i.e." if and only if it is appropriate in the context and the slight pause a comma means helps the reader; do not add them automatically in all cases just because some style guides say so. (In Texinfo manuals, @: should to be used after "e.g." and "i.e." when a comma isn't used.)

In Texinfo manuals, Texinfo 4.0 features may be used, and should be used where appropriate. URLs should be marked up with @uref; email addresses with @email; command-line options with @option; names of commands with @command; environment variables with @env. NULL should be written as @code{NULL}. Tables of contents should come just after the title page; printed manuals will be formatted (for example, by make dvi) using texi2dvi which reruns TeX until cross-references stabilize, so there is no need for a table of contents to go at the end for it to have correct page numbers. The @refill feature is obsolete and should not be used. All manuals should use @dircategory and @direntry to provide Info directory information for install-info.

It is useful to read the Texinfo manual. Some general Texinfo style issues discussed in that manual should be noted:

• For proper formatting of the printed manual, TeX quotes (matched ` or `` and ' or '') should be used; neutral ASCII double quotes ("...") should not be. Similarly, TeX dashes (-- (two hyphens) for an en dash and --- (three hyphens) for an em dash) should be used; normally these dashes should not have whitespace on either side. Minus signs should be written as @minus{}.
• For an ellipsis, @dots{} should be used; for a literal sequence of three dots in a programming language, the dots should be written as such (...) rather than as @dots{}.
• English text in programming language comments in examples should be enclosed in @r{} so that it is printed in a non-fixed-width font.
• Full stops that end sentences should be followed by two spaces or by end of line. Full stops that are preceded by a lower-case letter but do not end a sentence should be followed by @: if they are not followed by other punctuation such as a comma; full stops, question marks and exclamation marks that end a sentence but are preceded by an upper-case letter should be written as "@.", "@?" and "@!", respectively. (This is not required if the capital letter is within @code or @samp.)

Upstream packages

Some files and packages in the GCC source tree are imported from elsewhere, and we want to minimize divergence from their upstream sources. The following files should be updated only according to the rules set below:

• config.guess, config.sub: The master copy of these files is at ftp://ftp.gnu.org/pub/gnu/config. Proposed changes should be e-mailed to config-patches@gnu.org. Only after the change makes it to the FTP site should the new files be installed in the GCC source tree, so that their version numbers remain meaningful and unique. Don't install the patch, install the whole file.
• ltconfig, ltmain.sh, libtool.m4, ltcf-c.sh, ltcf-cxx.sh, ltcf-gcj.sh: The master copy of these files is the CVS repository of GNU libtool. Patches should be posted to libtool-patches@gnu.org. Only after the change makes it to the libtool CVS tree should the new files be installed in the GCC source tree. ltconfig and ltmain.sh are generated files from ltconfig.in and ltmain.in, respectively, so, when you post the patch, make sure you're patching the source file, not the generated one. When you update these generated files in the GCC repository, make sure they report the same timestamp and version number, and note this version number in the ChangeLog.
• Top-level configure.in, configure, Makefile.in, config-ml.in, config.if and most other top-level shell-scripts: Please try to keep these files in sync with the corresponding files in the src repository at sourceware.org. Some people hope to eventually merge these trees into a single repository; keeping them in sync helps this goal. When you check in a patch to one of these files, please check it in the src tree too, or ask someone else with write access there to do so.
• Top-level compile, depcomp, install-sh, missing, mkinstalldirs, symlink-tree and ylwrap: These are copied from mainline automake, using automake --add-missing --copy --force-missing.
• gcc/config/soft-fp: The master sources (except for t-softfp) are in CVS glibc, and changes should go into CVS glibc before going into GCC.
• fastjar: The master sources were at fastjar.sourceforge.net. However, the upstream source seems to be dead, so fastjar is essentially maintained in the GCC source tree.
• boehm-gc: The master sources are at www.hpl.hp.com/personal/Hans_Boehm/gc/. Patches should be sent to boehm@acm.org, but it's acceptable to check them in the GCC source tree before getting them installed in the master tree.
• libjava/classpath: The master sources come from GNU Classpath. New versions of Classpath are periodically imported into the GCC source tree. In general local modifications are prohibited, but they can be checked in for emergencies, such as fixing bootstrap.
• zlib: The master sources come from zlib.net. However, the autoconf-based configury is a local GCC invention. Changes to zlib outside the build system are discouraged, and should be sent upstream first.
• libstdc++-v3: In docs/doxygen, comments in *.cfg.in are partially autogenerated from the Doxygen tool. In docs/html, the ext/lwg-* files are copied from the C++ committee homepage, the 27_io/binary_iostream_* files are copies of Usenet postings, and most of the files in 17_intro are either copied from elsewhere in GCC or the FSF website, or are autogenerated. These files should not be changed without prior permission, if at all.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

These pages are maintained by the GCC team.

For questions related to the use of GCC, please consult these web pages and the GCC manuals. If that fails, the gcc-help@gcc.gnu.org mailing list might help.
Please send comments on these web pages and the development of GCC to our developer mailing list at gcc@gnu.org or gcc@gcc.gnu.org. All of our lists have public archives.

Copyright (C) Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Last modified 2007-02-01