Changes between Version 34 and Version 35 of Commentary/CodingStyle


Ignore:
Timestamp:
Apr 24, 2011 10:05:04 PM (3 years ago)
Author:
megacz
Comment:

yet more restructuring

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v34 v35  
    163163If the module can be compiled multiple ways (eg. GHCI vs. non-GHCI), make sure the imports are properly `#ifdefed` too, so as to avoid spurious unused import warnings.  
    164164 
    165  
    166 == Literate Haskell == 
    167  
    168 In GHC we use a mixture of literate ({{{.lhs}}}) and non-literate ({{{.hs}}}) source. I (Simon M.) prefer to use non-literate style, because I think the {{{\begin{code}..\end{code}}}} clutter up the source too much, and I like to use Haddock-style comments (we haven't tried processing the whole of GHC with Haddock yet, though).  
    169  
    170 == The C Preprocessor (CPP) == 
    171  
    172 Currently we pass all the compiler sources through CPP. The -cpp flag is always added by the build system.  
    173 However, whenever possible we try to avoid using CPP, as it can hide code from the compiler (which means changes that work on one platform can break the build on another) and code using CPP can be harder to understand. 
    174  
    175 The following CPP symbols are used throughout the compiler:  
    176  
    177  '''DEBUG'''::  
    178   Used to enables extra checks and debugging output in the compiler. The ASSERT macro (see {{{HsVersions.h}}}) provides assertions which disappear when DEBUG is not defined.  
    179  
    180  However, whenever possible, it is better to us `debugIsOn` from the `Util` module, which is defined to be `True` when `DEBUG` is defined and `False` otherwise.  The ideal way to provide debugging output is to use a Haskell expression "`when debugIsOn $ ...`" to arrange that the compiler will be silent when `DEBUG` is off (unless of course something goes wrong or the verbosity level is nonzero). When option `-O` is used, GHC will easily sweep away the unreachable code. 
    181  
    182  As a last resort, debugging code can be placed inside `#ifdef DEBUG`, but since this strategy guarantees that only a fraction of the code is seen be the compiler on any one compilation, it is to be avoided when possible. 
    183  
    184  Regarding performance, a good rule of thumb is that `DEBUG` shouldn't add more than about 10-20% to the compilation time. This is the case at the moment. If it gets too expensive, we won't use it. For more expensive runtime checks, consider adding a flag - see for example `-dcore-lint`. 
    185  
    186 '''Trap, pitfall for using the ASSERT macro''': 
    187  
    188 The ASSERT macro uses CPP, and if you are unwise enough to try to write assertions using primed variables ({{{ASSERT (not $ intersectsBlockEnv b b')}}}), one possible outcome is that CPP silently fails to expand the ASSERT, and you get this very baffling error message: 
    189 {{{ 
    190 Not in scope: data constructor `ASSERT' 
    191 }}} 
    192 Now you can Google for this error message :-) 
    193  
    194  
    195  '''GHCI'''::  
    196   Enables GHCi support, including the byte code generator and interactive user interface. This isn't the default, because the compiler needs to be bootstrapped with itself in order for GHCi to work properly. The reason is that the byte-code compiler and linker are quite closely tied to the runtime system, so it is essential that GHCi is linked with the most up-to-date RTS. Another reason is that the representation of certain datatypes must be consistent between GHCi and its libraries, and if these were inconsistent then disaster could follow.  
    197  
    198165== Compiler versions and language extensions == 
    199166 
     
    220187}}} 
    221188 
     189 
     190 
     191=== Literate Haskell === 
     192 
     193In GHC we use a mixture of literate ({{{.lhs}}}) and non-literate ({{{.hs}}}) source. I (Simon M.) prefer to use non-literate style, because I think the {{{\begin{code}..\end{code}}}} clutter up the source too much, and I like to use Haddock-style comments (we haven't tried processing the whole of GHC with Haddock yet, though).  
     194 
     195=== The C Preprocessor (CPP) === 
     196 
     197Currently we pass all the compiler sources through CPP. The -cpp flag is always added by the build system.  
     198However, whenever possible we try to avoid using CPP, as it can hide code from the compiler (which means changes that work on one platform can break the build on another) and code using CPP can be harder to understand. 
     199 
     200The following CPP symbols are used throughout the compiler:  
     201 
     202 '''DEBUG'''::  
     203  Used to enables extra checks and debugging output in the compiler. The ASSERT macro (see {{{HsVersions.h}}}) provides assertions which disappear when DEBUG is not defined.  
     204 
     205 However, whenever possible, it is better to us `debugIsOn` from the `Util` module, which is defined to be `True` when `DEBUG` is defined and `False` otherwise.  The ideal way to provide debugging output is to use a Haskell expression "`when debugIsOn $ ...`" to arrange that the compiler will be silent when `DEBUG` is off (unless of course something goes wrong or the verbosity level is nonzero). When option `-O` is used, GHC will easily sweep away the unreachable code. 
     206 
     207 As a last resort, debugging code can be placed inside `#ifdef DEBUG`, but since this strategy guarantees that only a fraction of the code is seen be the compiler on any one compilation, it is to be avoided when possible. 
     208 
     209 Regarding performance, a good rule of thumb is that `DEBUG` shouldn't add more than about 10-20% to the compilation time. This is the case at the moment. If it gets too expensive, we won't use it. For more expensive runtime checks, consider adding a flag - see for example `-dcore-lint`. 
     210 
     211'''Trap, pitfall for using the ASSERT macro''': 
     212 
     213The ASSERT macro uses CPP, and if you are unwise enough to try to write assertions using primed variables ({{{ASSERT (not $ intersectsBlockEnv b b')}}}), one possible outcome is that CPP silently fails to expand the ASSERT, and you get this very baffling error message: 
     214{{{ 
     215Not in scope: data constructor `ASSERT' 
     216}}} 
     217Now you can Google for this error message :-) 
     218 
     219 
     220 '''GHCI'''::  
     221  Enables GHCi support, including the byte code generator and interactive user interface. This isn't the default, because the compiler needs to be bootstrapped with itself in order for GHCi to work properly. The reason is that the byte-code compiler and linker are quite closely tied to the runtime system, so it is essential that GHCi is linked with the most up-to-date RTS. Another reason is that the representation of certain datatypes must be consistent between GHCi and its libraries, and if these were inconsistent then disaster could follow.  
     222