ghc/docs/comm/the-beast/driver.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 - The Glorious Driver</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>The GHC Commentary - The Glorious Driver</h1>
  10     <p>
  11       The Glorious Driver (GD) is the part of GHC that orchestrates the
  12       interaction of all the other pieces that make up GHC.  It supersedes the
  13       <em>Evil Driver (ED),</em> which was a Perl script that served the same
  14       purpose and was in use until version 4.08.1 of GHC.  Simon Marlow
  15       eventually slayed the ED and instated the GD.  The GD is usually called
  16       the <em>Compilation Manager</em> these days.
  17     </p>
  18     <p>
  19       The GD has been substantially extended for GHCi, i.e., the interactive
  20       variant of GHC that integrates the compiler with a (meta-circular)
  21       interpreter since version 5.00.  Most of the driver is located in the
  22       directory
  23       <a
  24       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/"><code>fptools/ghc/compiler/main/</code></a>.
  25     </p>
  26
  27     <h2>Command Line Options</h2>
  28     <p>
  29       GHC's many flavours of command line options make the code interpreting
  30       them rather involved.  The following provides a brief overview of the
  31       processing of these options.  Since the addition of the interactive
  32       front-end to GHC, there are two kinds of options: <em>static
  33       options</em> and <em>dynamic options.</em> The former can only be set
  34       when the system is invoked, whereas the latter can be altered in the
  35       course of an interactive session.  A brief explanation on the difference
  36       between these options and related matters is at the start of the module
  37       <a
  38       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/CmdLineOpts.lhs"><code>CmdLineOpts</code></a>.
  39       The same module defines the enumeration <code>DynFlag</code>, which
  40       contains all dynamic flags.  Moreover, there is the labelled record
  41       <code>DynFlags</code> that collects all the flag-related information
  42       that is passed by the compilation manager to the compiler proper,
  43       <code>hsc</code>, whenever a compilation is triggered.  If you like to
  44       find out whether an option is static, use the predicate
  45       <code>isStaticHscFlag</code> in the same module.
  46     <p>
  47       The second module that contains a lot of code related to the management
  48       of flags is <a
  49       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/DriverFlags.hs"><code>DriverFlags.hs</code></a>.
  50       In particular, the module contains two association lists that map the
  51       textual representation of the various flags to a data structure that
  52       tells the driver how to parse the flag (e.g., whether it has any
  53       arguments) and provides its internal representation.  All static flags
  54       are contained in <code>static_flags</code>.  A whole range of
  55       <code>-f</code> flags can be negated by adding a <code>-f-no-</code>
  56       prefix.  These flags are contained in the association list
  57       <code>fFlags</code>.
  58     <p>
  59       The driver uses a nasty hack based on <code>IORef</code>s that permits
  60       the rest of the compiler to access static flags as CAFs; i.e., there is
  61       a family of toplevel variable definitions in
  62       <a
  63       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/CmdLineOpts.lhs"><code>CmdLineOpts</code></a>,
  64       below the literate section heading <i>Static options</i>, each of which
  65       contains the value of one static option.  This is essentially realised
  66       via global variables (in the sense of C-style, updatable, global
  67       variables) defined via an evil pre-processor macro named
  68       <code>GLOBAL_VAR</code>, which is defined in a particularly ugly corner
  69       of GHC, namely the C header file
  70       <a
  71       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/HsVersions.h"><code>HsVersions.h</code></a>.
  72
  73     <h2>Scheduling Optimisations Phases</h2>
  74     <p>
  75       GHC has a large variety of optimisations at its disposal, many of which
  76       have subtle interdependencies.  The overall plan for program
  77       optimisation is fixed in <a
  78       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/DriverState.hs"><code>DriverState.hs</code></a>.
  79       First of all, there is the variable <code>hsc_minusNoO_flags</code> that
  80       determines the <code>-f</code> options that you get without
  81       <code>-O</code> (aka optimisation level 0) as well as
  82       <code>hsc_minusO_flags</code> and <code>hsc_minusO2_flags</code> for
  83       <code>-O</code> and <code>-O2</code>.
  84     <p>
  85       However, most of the strategic decisions about optimisations on the
  86       intermediate language Core are encoded in the value produced by
  87       <code>buildCoreToDo</code>, which is a list with elements of type
  88       <code>CoreToDo</code>.  Each element of this list specifies one step in
  89       the sequence of core optimisations executed by the <a
  90       href="simplifier.html">Mighty Simplifier</a>.  The type
  91       <code>CoreToDo</code> is defined in <a
  92       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/CmdLineOpts.lhs"><code>CmdLineOpts.lhs</code></a>.
  93       The actual execution of the optimisation plan produced by
  94       <code>buildCoreToDo</code> is performed by <a
  95       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/simplCore/SimplCore.lhs"><code>SimpleCore</code></a><code>.doCorePasses</code>.
  96       Core optimisation plans consist of a number of simplification phases
  97       (currently, three for optimisation levels of 1 or higher) with
  98       decreasing phase numbers (the lowest, corresponding to the last phase,
  99       namely 0).  Before and after these phases, optimisations such as
 100       specialisation, let floating, worker/wrapper, and so on are executed.
 101       The sequence of phases is such that the synergistic effect of the phases
 102       is maximised -- however, this is a fairly fragile arrangement.
 103     <p>
 104       There is a similar construction for optimisations on STG level stored in
 105       the variable <code>buildStgToDo :: [StgToDo]</code>.  However, this is a
 106       lot less complex than the arrangement for Core optimisations.
 107
 108     <h2>Linking the <code>RTS</code> and <code>libHSstd</code></h2>
 109     <p>
 110       Since the RTS and HSstd refer to each other, there is a Cunning
 111       Hack to avoid putting them each on the command-line twice or
 112       thrice (aside: try asking for `plaice and chips thrice' in a
 113       fish and chip shop; bet you only get two lots).  The hack involves
 114       adding
 115       the symbols that the RTS needs from libHSstd, such as
 116       <code>PrelWeak_runFinalizzerBatch_closure</code> and
 117       <code>__stginit_Prelude</code>, to the link line with the
 118       <code>-u</code> flag.  The standard library appears before the
 119       RTS on the link line, and these options cause the corresponding
 120       symbols to be picked up even so the linked might not have seen them
 121       being used as the RTS appears later on the link line.  As a result,
 122       when the RTS is also scanned, these symbols are already resolved. This
 123       avoids the linker having to read the standard library and RTS
 124       multiple times.
 125     </p>
 126     <p>
 127       This does, however, leads to a complication.  Normal Haskell
 128       programs do not have a <code>main()</code> function, so this is
 129       supplied by the RTS (in the file
 130       <a href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/rts/Main.c"><code>Main.c</code></a>).
 131       It calls <code>startupHaskell</code>, which
 132       itself calls <code>__stginit_PrelMain</code>, which is therefore,
 133       since it occurs in the standard library, one of the symbols
 134       passed to the linker using the <code>-u</code> option.  This is fine
 135       for standalone Haskell programs, but as soon as the Haskell code is only
 136       used as part of a program implemented in a foreign language, the
 137       <code>main()</code> function of that foreign language should be used
 138       instead of that of the Haskell runtime.  In this case, the previously
 139       described arrangement unfortunately fails as
 140       <code>__stginit_PrelMain</code> had better not be linked in,
 141       because it tries to call <code>__stginit_Main</code>, which won't
 142       exist.  In other words, the RTS's <code>main()</code> refers to
 143       <code>__stginit_PrelMain</code> which in turn refers to
 144       <code>__stginit_Main</code>.  Although the RTS's <code>main()</code>
 145       might not be linked in if the program provides its own, the driver
 146       will normally force <code>__stginit_PrelMain</code> to be linked in anyway,
 147       using <code>-u</code>, because it's a back-reference from the
 148       RTS to HSstd.  This case is coped with by the <code>-no-hs-main</code>
 149       flag, which suppresses passing the corresonding <code>-u</code> option
 150       to the linker -- although in some versions of the compiler (e.g., 5.00.2)
 151       it didn't work.  In addition, the driver generally places the C program
 152       providing the <code>main()</code> that we want to use before the RTS
 153       on the link line.  Therefore, the RTS's main is never used and
 154       without the <code>-u</code> the label <code>__stginit_PrelMain</code>
 155       will not be linked.
 156     </p>
 157
 158     <p><small>
 159 <!-- hhmts start -->
 160 Last modified: Tue Nov  6 16:08:59 EST 2001
 161 <!-- hhmts end -->
 162     </small>
 163   </body>
 164 </html>