<h2>To CPP or not to CPP?</h2>
<p>We pass all the compiler sources through CPP. The
- <tt>-cpp</tt> flag is always added by the build system. More
- about what you're allowed to do in the way of CPP directives
- later.
+ <tt>-cpp</tt> flag is always added by the build system.
+
+ <p>The following CPP symbols are used throughout the compiler:
+
+ <dl>
+ <dt><tt>DEBUG</tt></dt>
+
+ <dd>Used to enables extra checks and debugging output in the
+ compiler. The <tt>ASSERT</tt> macro (see <tt>HsVersions.h</tt>)
+ provides assertions which disappear when <tt>DEBUG</tt> is not
+ defined.
+
+ <p>All debugging output should be placed inside <tt>#ifdef
+ DEBUG</tt>; we generally use this to provide warnings about
+ strange cases and things that might warrant investigation. When
+ <tt>DEBUG</tt> is off, the compiler should normally be silent
+ unless something goes wrong (exception when the verbosity level
+ is greater than zero).
+
+ <p>A good rule of thumb is that <tt>DEBUG</tt> 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 <tt>-dcore-lint</tt>.
+ </dd>
+
+ <dt><tt>GHCI</tt></dt>
+
+ <dd>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.
+ </dd>
+
+ </dl>
+
+ <h2>Platform tests</h2>
+
+ <p>There are three platforms of interest to GHC:
+
+ <ul>
+ <li>The <b>Build</b> platform. This is the platform on which we
+ are building GHC.</li>
+ <li>The <b>Host</b> platform. This is the platform on which we
+ are going to run this GHC binary, and associated tools.</li>
+ <li>The <b>Target</b> platform. This is the platform for which
+ this GHC binary will generate code.</li>
+ </ul>
+
+ <p>At the moment, there is very limited support for having
+ different values for buil, host, and target. In particular:</p>
+
+ <ul>
+ <li>The build platform is currently always the same as the host
+ platform. The build process needs to use some of the tools in
+ the source tree, for example <tt>ghc-pkg</tt> and
+ <tt>hsc2hs</tt>.</li>
+
+ <li>If the target platform differs from the host platform, then
+ this is generally for the purpose of building <tt>.hc</tt> files
+ from Haskell source for porting GHC to the target platform.
+ Full cross-compilation isn't supported (yet).</li>
+ </ul>
+
+ <p>In the compiler's source code, you may make use of the
+ following CPP symbols:</p>
+
+ <ul>
+ <li><em>xxx</em><tt>_TARGET_ARCH</tt></li>
+ <li><em>xxx</em><tt>_TARGET_VENDOR</tt></li>
+ <li><em>xxx</em><tt>_TARGET_OS</tt></li>
+ <li><em>xxx</em><tt>_HOST_ARCH</tt></li>
+ <li><em>xxx</em><tt>_HOST_VENDOR</tt></li>
+ <li><em>xxx</em><tt>_HOST_OS</tt></li>
+ </ul>
+
+ <p>where <em>xxx</em> is the appropriate value:
+ eg. <tt>i386_TARGET_ARCH</tt>.
<h2>Compiler versions</h2>
- <p>GHC must be compilable by every major version of GHC from 4.08
+ <p>GHC must be compilable by every major version of GHC from 5.02
onwards, and itself. It isn't necessary for it to be compilable
by every intermediate development version (that includes last
- week's CVS sources), but we mustn't lose compatibility with 4.08
- for the time being, because that's the only version which can be
- easily bootstrapped from .hc files.
+ week's CVS sources).
<p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
below) where possible, and try to avoid using <tt>#ifdef</tt> in
projects / ghc-hetmet.git / blobdiff