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, both of user interfaces and of internals, must be maintained and kept up to date. In particular:
tree and RTL data
structures and interfaces must be kept complete and up to date.GCC requires ChangeLog entries for documentation changes (see message), though for changes to the GCC web pages (as opposed to the java and libstdc++-v3 ones) there is no appropriate ChangeLog file and the CVS logs suffice.
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.
There is no established convention on when ChangeLog entries are to be made for testsuite changes; see messages 1 and 2.
There are strict requirements for portability of code in GCC to
older systems whose compilers do not implement the ISO C standard.
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.
touch should never be used in GCC Makefiles. Instead
of touch foo always use $(STAMP) foo.
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 GNATS. There are some copyright guidelines on what can be included in the testsuite.
Code should generally use abort () rather than
assert () for tests for "can't happen" conditions; see message.
Such conditions should not be generated by invalid user input. If the
checks are expensive or the compiler can reasonably carry on after the
error, they may be conditioned on --enable-checking.
Code in GCC should use the following formatting conventions:
| Use... | ...instead of |
|---|---|
!x | ! x |
~x | ~ x |
-x (unary minus) | - x |
(foo) x (cast) |
(foo)x |
*x (pointer dereference) |
* x |
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.
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:
| Use... | ...instead of | Rationale |
|---|---|---|
| American spelling (in particular -ize, -or) | British spelling (in particular -ise, -our) | |
| "32-bit" (adjective) | "32 bit" | |
| "back end" (noun) | "back-end" or "backend" | |
| "back-end" (adjective) | "back end" or "backend" | |
| "bit-field" | "bit field" or "bitfield" | Spelling used in C and C++ standards |
| "built-in" as an adjective ("built-in function") or "built in" | "builtin" | "builtin" isn't a word |
| "dependent" (adjective), "dependence", "dependency" | "dependant", "dependance", "dependancy" | |
| "front end" (noun) | "front-end" or "frontend" | |
| "front-end" (adjective) | "front end" or "frontend" | |
| "H8S" | "H8/S" | |
| "MIPS" | "Mips" or "mips" | |
| "nonzero" | "non-zero" or "non zero" | |
| "Objective-C" | "Objective C" | |
| "PowerPC" | "powerpc", "powerPC" or "PowerPc" | |
| "SPARC" | "Sparc" or "sparc" | |
| "VAX", "VAXen", "MicroVAX" | "vax" or "Vax", "vaxen" or "vaxes", "microvax" or "microVAX" |
"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:
` 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{}.@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{}.@r{} so that it is printed in a
non-fixed-width font.@: 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.)Some files and packages in the CVS 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: