--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <title>The GHC Commentary - Style Guidelines for RTS C code</title>
+ </head>
+
+<body>
+<H1>The GHC Commentary - Style Guidelines for RTS C code</h1>
+
+<h2>Comments</h2>
+
+<p>These coding style guidelines are mainly intended for use in
+<tt>ghc/rts</tt> and <tt>ghc/includes</tt>.
+
+<p>NB These are just suggestions. They're not set in stone. Some of
+them are probably misguided. If you disagree with them, feel free to
+modify this document (and make your commit message reasonably
+informative) or mail someone (eg. <a
+href="glasgow-haskell-users@haskell.org">The GHC mailing list</a>)
+
+<h2>References</h2>
+
+If you haven't read them already, you might like to check the following.
+Where they conflict with our suggestions, they're probably right.
+
+<ul>
+
+<li>
+The C99 standard. One reasonable reference is <a
+href="http://home.tiscalinet.ch/t_wolf/tw/c/c9x_changes.html">here</a>.
+
+<p><li>
+Writing Solid Code, Microsoft Press. (Highly recommended. Possibly
+the only Microsoft Press book that's worth reading.)
+
+<p><li>
+Autoconf documentation.
+See also <a href="http://peti.gmd.de/autoconf-archive/">The autoconf macro archive</a> and
+<a href="http://www.cyclic.com/cyclic-pages/autoconf.html">Cyclic Software's description</a>
+
+<p><li> <a
+href="http://www.cs.umd.edu/users/cml/cstyle/indhill-cstyle.html">Indian
+Hill C Style and Coding Standards</a>.
+
+<p><li>
+<a href="http://www.cs.umd.edu/users/cml/cstyle/">A list of C programming style links</a>
+
+<p><li>
+<a href="http://www.lysator.liu.se/c/c-www.html">A very large list of C programming links</a>
+
+<p><li>
+<a href="http://www.geek-girl.com/unix.html">A list of Unix programming links</a>
+
+</ul>
+
+
+<h2>Portability issues</h2>
+
+<ul>
+<p><li> We try to stick to C99 where possible. We use the following
+C99 features relative to C89, some of which were previously GCC
+extensions (possibly with different syntax):
+
+<ul>
+<p><li>Variable length arrays as the last field of a struct. GCC has
+a similar extension, but the syntax is slightly different: in GCC you
+would declare the array as <tt>arr[0]</tt>, whereas in C99 it is
+declared as <tt>arr[]</tt>.
+
+<p><li>Inline annotations on functions (see later)
+
+<p><li>Labeled elements in initialisers. Again, GCC has a slightly
+different syntax from C99 here, and we stick with the GCC syntax until
+GCC implements the C99 proposal.
+
+<p><li>C++-style comments. These are part of the C99 standard, and we
+prefer to use them whenever possible.
+</ul>
+
+<p>In addition we use ANSI-C-style function declarations and
+prototypes exclusively. Every function should have a prototype;
+static function prototypes may be placed near the top of the file in
+which they are declared, and external prototypes are usually placed in
+a header file with the same basename as the source file (although there
+are exceptions to this rule, particularly when several source files
+together implement a subsystem which is described by a single external
+header file).
+
+<p><li>We use the following GCC extensions, but surround them with
+<tt>#ifdef __GNUC__</tt>:
+
+<ul>
+<p><li>Function attributes (mostly just <code>no_return</code> and
+<code>unused</code>)
+<p><li>Inline assembly.
+</ul>
+
+<p><li>
+char can be signed or unsigned - always say which you mean
+
+<p><li>Our POSIX policy: try to write code that only uses POSIX (IEEE
+Std 1003.1) interfaces and APIs. We used to define
+<code>POSIX_SOURCE</code> by default, but found that this caused more
+problems than it solved, so now we require any code that is
+POSIX-compliant to explicitly say so by having <code>#include
+"PosixSource.h"</code> at the top. Try to do this whenever possible.
+
+<p><li> Some architectures have memory alignment constraints. Others
+don't have any constraints but go faster if you align things. These
+macros (from <tt>ghcconfig.h</tt>) tell you which alignment to use
+
+<pre>
+ /* minimum alignment of unsigned int */
+ #define ALIGNMENT_UNSIGNED_INT 4
+
+ /* minimum alignment of long */
+ #define ALIGNMENT_LONG 4
+
+ /* minimum alignment of float */
+ #define ALIGNMENT_FLOAT 4
+
+ /* minimum alignment of double */
+ #define ALIGNMENT_DOUBLE 4
+</pre>
+
+<p><li> Use <tt>StgInt</tt>, <tt>StgWord</tt> and <tt>StgPtr</tt> when
+reading/writing ints and ptrs to the stack or heap. Note that, by
+definition, <tt>StgInt</tt>, <tt>StgWord</tt> and <tt>StgPtr</tt> are
+the same size and have the same alignment constraints even if
+<code>sizeof(int) != sizeof(ptr)</code> on that platform.
+
+<p><li> Use <tt>StgInt8</tt>, <tt>StgInt16</tt>, etc when you need a
+certain minimum number of bits in a type. Use <tt>int</tt> and
+<tt>nat</tt> when there's no particular constraint. ANSI C only
+guarantees that ints are at least 16 bits but within GHC we assume
+they are 32 bits.
+
+<p><li> Use <tt>StgFloat</tt> and <tt>StgDouble</tt> for floating
+point values which will go on/have come from the stack or heap. Note
+that <tt>StgDouble</tt> may occupy more than one <tt>StgWord</tt>, but
+it will always be a whole number multiple.
+
+<p>
+Use <code>PK_FLT(addr)</code>, <code>PK_DBL(addr)</code> to read
+<tt>StgFloat</tt> and <tt>StgDouble</tt> values from the stack/heap,
+and <code>ASSIGN_FLT(val,addr)</code> /
+<code>ASSIGN_DBL(val,addr)</code> to assign StgFloat/StgDouble values
+to heap/stack locations. These macros take care of alignment
+restrictions.
+
+<p>
+Heap/Stack locations are always <tt>StgWord</tt> aligned; the
+alignment requirements of an <tt>StgDouble</tt> may be more than that
+of <tt>StgWord</tt>, but we don't pad misaligned <tt>StgDoubles</tt>
+because doing so would be too much hassle (see <code>PK_DBL</code> &
+co above).
+
+<p><li>
+Avoid conditional code like this:
+
+<pre>
+ #ifdef solaris_host_OS
+ // do something solaris specific
+ #endif
+</pre>
+
+Instead, add an appropriate test to the configure.ac script and use
+the result of that test instead.
+
+<pre>
+ #ifdef HAVE_BSD_H
+ // use a BSD library
+ #endif
+</pre>
+
+<p>The problem is that things change from one version of an OS to another
+- things get added, things get deleted, things get broken, some things
+are optional extras. Using "feature tests" instead of "system tests"
+makes things a lot less brittle. Things also tend to get documented
+better.
+
+</ul>
+
+<h2>Debugging/robustness tricks</h2>
+
+
+Anyone who has tried to debug a garbage collector or code generator
+will tell you: "If a program is going to crash, it should crash as
+soon, as noisily and as often as possible." There's nothing worse
+than trying to find a bug which only shows up when running GHC on
+itself and doesn't manifest itself until 10 seconds after the actual
+cause of the problem.
+
+<p>We put all our debugging code inside <tt>#ifdef DEBUG</tt>. The
+general policy is we don't ship code with debugging checks and
+assertions in it, but we do run with those checks in place when
+developing and testing. Anything inside <tt>#ifdef DEBUG</tt> should
+not slow down the code by more than a factor of 2.
+
+<p>We also have more expensive "sanity checking" code for hardcore
+debugging - this can slow down the code by a large factor, but is only
+enabled on demand by a command-line flag. General sanity checking in
+the RTS is currently enabled with the <tt>-DS</tt> RTS flag.
+
+<p>There are a number of RTS flags which control debugging output and
+sanity checking in various parts of the system when <tt>DEBUG</tt> is
+defined. For example, to get the scheduler to be verbose about what
+it is doing, you would say <tt>+RTS -Ds -RTS</tt>. See
+<tt>includes/RtsFlags.h</tt> and <tt>rts/RtsFlags.c</tt> for the full
+set of debugging flags. To check one of these flags in the code,
+write:
+
+<pre>
+ IF_DEBUG(gc, fprintf(stderr, "..."));
+</pre>
+
+would check the <tt>gc</tt> flag before generating the output (and the
+code is removed altogether if <tt>DEBUG</tt> is not defined).
+
+<p>All debugging output should go to <tt>stderr</tt>.
+
+<p>
+Particular guidelines for writing robust code:
+
+<ul>
+<p><li>
+Use assertions. Use lots of assertions. If you write a comment
+that says "takes a +ve number" add an assertion. If you're casting
+an int to a nat, add an assertion. If you're casting an int to a char,
+add an assertion. We use the <tt>ASSERT</tt> macro for writing
+assertions; it goes away when <tt>DEBUG</tt> is not defined.
+
+<p><li>
+Write special debugging code to check the integrity of your data structures.
+(Most of the runtime checking code is in <tt>rts/Sanity.c</tt>)
+Add extra assertions which call this code at the start and end of any
+code that operates on your data structures.
+
+<p><li>
+When you find a hard-to-spot bug, try to think of some assertions,
+sanity checks or whatever that would have made the bug easier to find.
+
+<p><li>
+When defining an enumeration, it's a good idea not to use 0 for normal
+values. Instead, make 0 raise an internal error. The idea here is to
+make it easier to detect pointer-related errors on the assumption that
+random pointers are more likely to point to a 0 than to anything else.
+
+<pre>
+typedef enum
+ { i_INTERNAL_ERROR /* Instruction 0 raises an internal error */
+ , i_PANIC /* irrefutable pattern match failed! */
+ , i_ERROR /* user level error */
+
+ ...
+</pre>
+
+<p><li> Use <tt>#warning</tt> or <tt>#error</tt> whenever you write a
+piece of incomplete/broken code.
+
+<p><li> When testing, try to make infrequent things happen often.
+ For example, make a context switch/gc/etc happen every time a
+ context switch/gc/etc can happen. The system will run like a
+ pig but it'll catch a lot of bugs.
+
+</ul>
+
+<h2>Syntactic details</h2>
+
+<ul>
+<p><li><b>Important:</b> Put "redundant" braces or parens in your code.
+Omitting braces and parens leads to very hard to spot bugs -
+especially if you use macros (and you might have noticed that GHC does
+this a lot!)
+
+<p>
+In particular:
+<ul>
+<p><li>
+Put braces round the body of for loops, while loops, if statements, etc.
+even if they "aren't needed" because it's really hard to find the resulting
+bug if you mess up. Indent them any way you like but put them in there!
+</ul>
+
+<p><li>
+When defining a macro, always put parens round args - just in case.
+For example, write:
+<pre>
+ #define add(x,y) ((x)+(y))
+</pre>
+instead of
+<pre>
+ #define add(x,y) x+y
+</pre>
+
+<p><li> Don't declare and initialize variables at the same time.
+Separating the declaration and initialization takes more lines, but
+make the code clearer.
+
+<p><li>
+Use inline functions instead of macros if possible - they're a lot
+less tricky to get right and don't suffer from the usual problems
+of side effects, evaluation order, multiple evaluation, etc.
+
+<ul>
+<p><li>Inline functions get the naming issue right. E.g. they
+ can have local variables which (in an expression context)
+ macros can't.
+
+<p><li> Inline functions have call-by-value semantics whereas macros
+ are call-by-name. You can be bitten by duplicated computation
+ if you aren't careful.
+
+<p><li> You can use inline functions from inside gdb if you compile with
+ -O0 or -fkeep-inline-functions. If you use macros, you'd better
+ know what they expand to.
+</ul>
+
+However, note that macros can serve as both l-values and r-values and
+can be "polymorphic" as these examples show:
+<pre>
+ // you can use this as an l-value or an l-value
+ #define PROF_INFO(cl) (((StgClosure*)(cl))->header.profInfo)
+
+ // polymorphic case
+ // but note that min(min(1,2),3) does 3 comparisions instead of 2!!
+ #define min(x,y) (((x)<=(y)) ? (x) : (y))
+</pre>
+
+<p><li>
+Inline functions should be "static inline" because:
+<ul>
+<p><li>
+gcc will delete static inlines if not used or theyre always inlined.
+
+<p><li>
+ if they're externed, we could get conflicts between 2 copies of the
+ same function if, for some reason, gcc is unable to delete them.
+ If they're static, we still get multiple copies but at least they don't conflict.
+</ul>
+
+OTOH, the gcc manual says this
+so maybe we should use extern inline?
+
+<pre>
+ When a function is both inline and `static', if all calls to the
+function are integrated into the caller, and the function's address is
+never used, then the function's own assembler code is never referenced.
+In this case, GNU CC does not actually output assembler code for the
+function, unless you specify the option `-fkeep-inline-functions'.
+Some calls cannot be integrated for various reasons (in particular,
+calls that precede the function's definition cannot be integrated, and
+neither can recursive calls within the definition). If there is a
+nonintegrated call, then the function is compiled to assembler code as
+usual. The function must also be compiled as usual if the program
+refers to its address, because that can't be inlined.
+
+ When an inline function is not `static', then the compiler must
+assume that there may be calls from other source files; since a global
+symbol can be defined only once in any program, the function must not
+be defined in the other source files, so the calls therein cannot be
+integrated. Therefore, a non-`static' inline function is always
+compiled on its own in the usual fashion.
+
+ If you specify both `inline' and `extern' in the function
+definition, then the definition is used only for inlining. In no case
+is the function compiled on its own, not even if you refer to its
+address explicitly. Such an address becomes an external reference, as
+if you had only declared the function, and had not defined it.
+
+ This combination of `inline' and `extern' has almost the effect of a
+macro. The way to use it is to put a function definition in a header
+file with these keywords, and put another copy of the definition
+(lacking `inline' and `extern') in a library file. The definition in
+the header file will cause most calls to the function to be inlined.
+If any uses of the function remain, they will refer to the single copy
+in the library.
+</pre>
+
+<p><li>
+Don't define macros that expand to a list of statements.
+You could just use braces as in:
+
+<pre>
+ #define ASSIGN_CC_ID(ccID) \
+ { \
+ ccID = CC_ID; \
+ CC_ID++; \
+ }
+</pre>
+
+(but it's usually better to use an inline function instead - see above).
+
+<p><li>
+Don't even write macros that expand to 0 statements - they can mess you
+up as well. Use the doNothing macro instead.
+<pre>
+ #define doNothing() do { } while (0)
+</pre>
+
+<p><li>
+This code
+<pre>
+int* p, q;
+</pre>
+looks like it declares two pointers but, in fact, only p is a pointer.
+It's safer to write this:
+<pre>
+int* p;
+int* q;
+</pre>
+You could also write this:
+<pre>
+int *p, *q;
+</pre>
+but it is preferrable to split the declarations.
+
+<p><li>
+Try to use ANSI C's enum feature when defining lists of constants of
+the same type. Among other benefits, you'll notice that gdb uses the
+name instead of its (usually inscrutable) number when printing values
+with enum types and gdb will let you use the name in expressions you
+type.
+
+<p>
+Examples:
+<pre>
+ typedef enum { /* N.B. Used as indexes into arrays */
+ NO_HEAP_PROFILING,
+ HEAP_BY_CC,
+ HEAP_BY_MOD,
+ HEAP_BY_GRP,
+ HEAP_BY_DESCR,
+ HEAP_BY_TYPE,
+ HEAP_BY_TIME
+ } ProfilingFlags;
+</pre>
+instead of
+<pre>
+ # define NO_HEAP_PROFILING 0 /* N.B. Used as indexes into arrays */
+ # define HEAP_BY_CC 1
+ # define HEAP_BY_MOD 2
+ # define HEAP_BY_GRP 3
+ # define HEAP_BY_DESCR 4
+ # define HEAP_BY_TYPE 5
+ # define HEAP_BY_TIME 6
+</pre>
+and
+<pre>
+ typedef enum {
+ CCchar = 'C',
+ MODchar = 'M',
+ GRPchar = 'G',
+ DESCRchar = 'D',
+ TYPEchar = 'Y',
+ TIMEchar = 'T'
+ } ProfilingTag;
+</pre>
+instead of
+<pre>
+ # define CCchar 'C'
+ # define MODchar 'M'
+ # define GRPchar 'G'
+ # define DESCRchar 'D'
+ # define TYPEchar 'Y'
+ # define TIMEchar 'T'
+</pre>
+
+<p><li> Please keep to 80 columns: the line has to be drawn somewhere,
+and by keeping it to 80 columns we can ensure that code looks OK on
+everyone's screen. Long lines are hard to read, and a sign that the
+code needs to be restructured anyway.
+
+<p><li> When commenting out large chunks of code, use <code>#ifdef 0
+... #endif</code> rather than <code>/* ... */</code> because C doesn't
+have nested comments.
+
+<p><li>When declaring a typedef for a struct, give the struct a name
+as well, so that other headers can forward-reference the struct name
+and it becomes possible to have opaque pointers to the struct. Our
+convention is to name the struct the same as the typedef, but add a
+leading underscore. For example:
+
+<pre>
+ typedef struct _Foo {
+ ...
+ } Foo;
+</pre>
+
+<p><li>Do not use <tt>!</tt> instead of explicit comparison against
+<tt>NULL</tt> or <tt>'\0'</tt>; the latter is much clearer.
+
+<p><li> We don't care too much about your indentation style but, if
+you're modifying a function, please try to use the same style as the
+rest of the function (or file). If you're writing new code, a
+tab width of 4 is preferred.
+
+</ul>
+
+<h2>CVS issues</h2>
+
+<ul>
+<p><li>
+Don't be tempted to reindent or reorganise large chunks of code - it
+generates large diffs in which it's hard to see whether anything else
+was changed.
+<p>
+If you must reindent or reorganise, don't include any functional
+changes that commit and give advance warning that you're about to do
+it in case anyone else is changing that file.
+</ul>
+
+
+</body>
+</html>
projects / ghc-hetmet.git / blobdiff