docs/comm/the-beast/coding-style.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
   5     <title>The GHC Commentary - Coding Style Guidelines</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>The GHC Commentary - Coding Style Guidelines</h1>
  10
  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>.
  13
  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
  18     distinguish them.
  19
  20     <h2>To literate or not to literate?</h2>
  21
  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).
  28
  29     <h2>To CPP or not to CPP?</h2>
  30
  31     <p>We pass all the compiler sources through CPP.  The
  32     <tt>-cpp</tt> flag is always added by the build system.
  33
  34     <p>The following CPP symbols are used throughout the compiler:
  35
  36     <dl>
  37       <dt><tt>DEBUG</tt></dt>
  38
  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
  42       defined.
  43
  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).
  50
  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>.
  56       </dd>
  57
  58       <dt><tt>GHCI</tt></dt>
  59
  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.
  69       </dd>
  70
  71     </dl>
  72
  73     <h2>Platform tests</h2>
  74
  75     <p>There are three platforms of interest to GHC:
  76
  77     <ul>
  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>
  84     </ul>
  85
  86     <p>At the moment, there is very limited support for having
  87     different values for buil, host, and target.  In particular:</p>
  88
  89     <ul>
  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
  93       <tt>hsc2hs</tt>.</li>
  94
  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>
  99     </ul>
 100
 101     <p>In the compiler's source code, you may make use of the
 102     following CPP symbols:</p>
 103
 104     <ul>
 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>
 111     </ul>
 112
 113     <p>where <em>xxx</em> is the appropriate value:
 114     eg. <tt>i386_TARGET_ARCH</tt>.
 115
 116     <h2>Compiler versions</h2>
 117
 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
 121     week's CVS sources).
 122
 123     <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
 124     below) where possible, and try to avoid using <tt>#ifdef</tt> in
 125     the source itself.
 126
 127     <h2>The source file</h2>
 128
 129     <p>We now describe a typical source file, annotating stylistic
 130     choices as we go.
 131
 132 <pre>
 133 {-# OPTIONS ... #-}
 134 </pre>
 135
 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:
 139
 140     <ul>
 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.
 145     </ul>
 146
 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.
 150
 151
 152 <pre>
 153 module Foo (
 154    T(..),
 155    foo,      -- :: T -> T
 156  ) where
 157 </pre>
 158
 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.
 162
 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
 165     do that.
 166
 167 <pre>
 168 #include "HsVersions.h"
 169 </pre>
 170
 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.
 175
 176 <pre>
 177 -- friends
 178 import SimplMonad
 179
 180 -- GHC
 181 import CoreSyn
 182 import Id           ( idName, idType )
 183 import BasicTypes
 184
 185 -- libraries
 186 import DATA_IOREF   ( newIORef, readIORef )
 187
 188 -- std
 189 import List         ( partition )
 190 import Maybe        ( fromJust )
 191 </pre>
 192
 193    <p>List imports in the following order:
 194
 195    <ul>
 196      <li>Local to this subsystem (or directory) first</li>
 197
 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>
 201
 202      <li>Library imports</li>
 203
 204      <li>Standard Haskell 98 imports last</li>
 205    </ul>
 206
 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).
 213
 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
 222    more.
 223
 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.
 227
 228    <p><em>ToDo: finish this</em>
 229   </body>
 230 </html>