1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
5 <title>The GHC Commentary - Coding Style Guidelines</title>
8 <body BGCOLOR="FFFFFF">
9 <h1>The GHC Commentary - Coding Style Guidelines</h1>
11 <p>This is a rough description of some of the coding practices and
12 style that we use for Haskell code inside <tt>ghc/compiler</tt>.
14 <p>The general rule is to stick to the same coding style as is
15 already used in the file you're editing. If you must make
16 stylistic changes, commit them separately from functional changes,
17 so that someone looking back through the change logs can easily
20 <h2>To literate or not to literate?</h2>
22 <p>In GHC we use a mixture of literate (<tt>.lhs</tt>) and
23 non-literate (<tt>.hs</tt>) source. I (Simon M.) prefer to use
24 non-literate style, because I think the
25 <tt>\begin{code}..\end{code}</tt> clutter up the source too much,
26 and I like to use Haddock-style comments (we haven't tried
27 processing the whole of GHC with Haddock yet, though).
29 <h2>To CPP or not to CPP?</h2>
31 <p>We pass all the compiler sources through CPP. The
32 <tt>-cpp</tt> flag is always added by the build system.
34 <p>The following CPP symbols are used throughout the compiler:
37 <dt><tt>DEBUG</tt></dt>
39 <dd>Used to enables extra checks and debugging output in the
40 compiler. The <tt>ASSERT</tt> macro (see <tt>HsVersions.h</tt>)
41 provides assertions which disappear when <tt>DEBUG</tt> is not
44 <p>All debugging output should be placed inside <tt>#ifdef
45 DEBUG</tt>; we generally use this to provide warnings about
46 strange cases and things that might warrant investigation. When
47 <tt>DEBUG</tt> is off, the compiler should normally be silent
48 unless something goes wrong (exception when the verbosity level
49 is greater than zero).
51 <p>A good rule of thumb is that <tt>DEBUG</tt> shouldn't add
52 more than about 10-20% to the compilation time. This is the case
53 at the moment. If it gets too expensive, we won't use it. For
54 more expensive runtime checks, consider adding a flag - see for
55 example <tt>-dcore-lint</tt>.
58 <dt><tt>GHCI</tt></dt>
60 <dd>Enables GHCi support, including the byte code generator and
61 interactive user interface. This isn't the default, because the
62 compiler needs to be bootstrapped with itself in order for GHCi
63 to work properly. The reason is that the byte-code compiler and
64 linker are quite closely tied to the runtime system, so it is
65 essential that GHCi is linked with the most up-to-date RTS.
66 Another reason is that the representation of certain datatypes
67 must be consistent between GHCi and its libraries, and if these
68 were inconsistent then disaster could follow.
73 <h2>Platform tests</h2>
75 <p>There are three platforms of interest to GHC:
78 <li>The <b>Build</b> platform. This is the platform on which we
79 are building GHC.</li>
80 <li>The <b>Host</b> platform. This is the platform on which we
81 are going to run this GHC binary, and associated tools.</li>
82 <li>The <b>Target</b> platform. This is the platform for which
83 this GHC binary will generate code.</li>
86 <p>At the moment, there is very limited support for having
87 different values for buil, host, and target. In particular:</p>
90 <li>The build platform is currently always the same as the host
91 platform. The build process needs to use some of the tools in
92 the source tree, for example <tt>ghc-pkg</tt> and
95 <li>If the target platform differs from the host platform, then
96 this is generally for the purpose of building <tt>.hc</tt> files
97 from Haskell source for porting GHC to the target platform.
98 Full cross-compilation isn't supported (yet).</li>
101 <p>In the compiler's source code, you may make use of the
102 following CPP symbols:</p>
105 <li><em>xxx</em><tt>_TARGET_ARCH</tt></li>
106 <li><em>xxx</em><tt>_TARGET_VENDOR</tt></li>
107 <li><em>xxx</em><tt>_TARGET_OS</tt></li>
108 <li><em>xxx</em><tt>_HOST_ARCH</tt></li>
109 <li><em>xxx</em><tt>_HOST_VENDOR</tt></li>
110 <li><em>xxx</em><tt>_HOST_OS</tt></li>
113 <p>where <em>xxx</em> is the appropriate value:
114 eg. <tt>i386_TARGET_ARCH</tt>.
116 <h2>Compiler versions</h2>
118 <p>GHC must be compilable by every major version of GHC from 5.02
119 onwards, and itself. It isn't necessary for it to be compilable
120 by every intermediate development version (that includes last
123 <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
124 below) where possible, and try to avoid using <tt>#ifdef</tt> in
127 <h2>The source file</h2>
129 <p>We now describe a typical source file, annotating stylistic
136 <p>An <tt>OPTIONS</tt> pragma is optional, but if present it
137 should go right at the top of the file. Things you might want to
138 put in <tt>OPTIONS</tt> include:
141 <li><tt>-#include</tt> options to bring into scope prototypes
142 for FFI declarations</li>
143 <li><tt>-fvia-C</tt> if you know that
144 this module won't compile with the native code generator.
147 <p>Don't bother putting <tt>-cpp</tt> or <tt>-fglasgow-exts</tt>
148 in the <tt>OPTIONS</tt> pragma; these are already added to the
149 command line by the build system.
159 <p>We usually (99% of the time) include an export list. The only
160 exceptions are perhaps where the export list would list absolutely
161 everything in the module, and even then sometimes we do it anyway.
163 <p>It's helpful to give type signatures inside comments in the
164 export list, but hard to keep them consistent, so we don't always
168 #include "HsVersions.h"
171 <p><tt>HsVersions.h</tt> is a CPP header file containing a number
172 of macros that help smooth out the differences between compiler
173 versions. It defines, for example, macros for library module
174 names which have moved between versions. Take a look.
182 import Id ( idName, idType )
186 import DATA_IOREF ( newIORef, readIORef )
189 import List ( partition )
190 import Maybe ( fromJust )
193 <p>List imports in the following order:
196 <li>Local to this subsystem (or directory) first</li>
198 <li>Compiler imports, generally ordered from specific to generic
199 (ie. modules from <tt>utils/</tt> and <tt>basicTypes/</tt>
200 usually come last)</li>
202 <li>Library imports</li>
204 <li>Standard Haskell 98 imports last</li>
207 <p>Import library modules from the <tt>base</tt> and
208 <tt>haskell98</tt> packages only. Use <tt>#defines</tt> in
209 <tt>HsVersions.h</tt> when the modules names differ between
210 versions of GHC (eg. <tt>DATA_IOREF</tt> in the example above).
211 For code inside <tt>#ifdef GHCI</tt>, don't need to worry about GHC
212 versioning (because we are bootstrapped).
214 <p>We usually use import specs to give an explicit list of the
215 entities imported from a module. The main reason for doing this is
216 so that you can search the file for an entity and find which module
217 it comes from. However, huge import lists can be a pain to
218 maintain, so we often omit the import specs when they start to get
219 long (actually I start omitting them when they don't fit on one
220 line --Simon M.). Tip: use GHC's <tt>-fwarn-unused-imports</tt>
221 flag so that you get notified when an import isn't being used any
224 <p>If the module can be compiled multiple ways (eg. GHCI
225 vs. non-GHCI), make sure the imports are properly <tt>#ifdefed</tt>
226 too, so as to avoid spurious unused import warnings.
228 <p><em>ToDo: finish this</em>