[project @ 2005-03-30 16:24:04 by simonmar]
[ghc-hetmet.git] / 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>What Happens When</h2>
74     <p>
75       Inside the Haskell compiler proper (<code>hsc</code>), a whole series of
76       stages (``passes'') are executed in order to transform your Haskell program
77       into C or native code.  This process is orchestrated by
78       <code>main/HscMain.hscMain</code> and its relative
79       <code>hscReComp</code>.  The latter directly invokes, in order,
80       the parser, the renamer, the typechecker, the desugarer, the
81       simplifier (Core2Core), the CoreTidy pass, the CorePrep pass,
82       conversion to STG (CoreToStg), the interface generator
83       (MkFinalIface), the code generator, and code output.  The
84       simplifier is the most complex of these, and is made up of many
85       sub-passes.  These are controlled by <code>buildCoreToDo</code>,
86       as described below.
87
88     <h2>Scheduling Optimisations Phases</h2>
89     <p>
90       GHC has a large variety of optimisations at its disposal, many of which
91       have subtle interdependencies.  The overall plan for program
92       optimisation is fixed in <a
93       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/DriverState.hs"><code>DriverState.hs</code></a>.
94       First of all, there is the variable <code>hsc_minusNoO_flags</code> that
95       determines the <code>-f</code> options that you get without
96       <code>-O</code> (aka optimisation level 0) as well as
97       <code>hsc_minusO_flags</code> and <code>hsc_minusO2_flags</code> for
98       <code>-O</code> and <code>-O2</code>.
99     <p>
100       However, most of the strategic decisions about optimisations on the
101       intermediate language Core are encoded in the value produced by
102       <code>buildCoreToDo</code>, which is a list with elements of type
103       <code>CoreToDo</code>.  Each element of this list specifies one step in
104       the sequence of core optimisations executed by the <a
105       href="simplifier.html">Mighty Simplifier</a>.  The type
106       <code>CoreToDo</code> is defined in <a
107       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/main/CmdLineOpts.lhs"><code>CmdLineOpts.lhs</code></a>.
108       The actual execution of the optimisation plan produced by
109       <code>buildCoreToDo</code> is performed by <a
110       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/simplCore/SimplCore.lhs"><code>SimpleCore</code></a><code>.doCorePasses</code>.
111       Core optimisation plans consist of a number of simplification phases
112       (currently, three for optimisation levels of 1 or higher) with
113       decreasing phase numbers (the lowest, corresponding to the last phase,
114       namely 0).  Before and after these phases, optimisations such as
115       specialisation, let floating, worker/wrapper, and so on are executed.
116       The sequence of phases is such that the synergistic effect of the phases
117       is maximised -- however, this is a fairly fragile arrangement.
118     <p>
119       There is a similar construction for optimisations on STG level stored in
120       the variable <code>buildStgToDo :: [StgToDo]</code>.  However, this is a
121       lot less complex than the arrangement for Core optimisations.
122
123     <h2>Linking the <code>RTS</code> and <code>libHSstd</code></h2>
124     <p>
125       Since the RTS and HSstd refer to each other, there is a Cunning
126       Hack to avoid putting them each on the command-line twice or
127       thrice (aside: try asking for `plaice and chips thrice' in a
128       fish and chip shop; bet you only get two lots).  The hack involves 
129       adding
130       the symbols that the RTS needs from libHSstd, such as
131       <code>PrelWeak_runFinalizzerBatch_closure</code> and
132       <code>__stginit_Prelude</code>, to the link line with the
133       <code>-u</code> flag.  The standard library appears before the
134       RTS on the link line, and these options cause the corresponding
135       symbols to be picked up even so the linked might not have seen them
136       being used as the RTS appears later on the link line.  As a result,
137       when the RTS is also scanned, these symbols are already resolved. This
138       avoids the linker having to read the standard library and RTS
139       multiple times.
140     </p>
141     <p>
142       This does, however, leads to a complication.  Normal Haskell
143       programs do not have a <code>main()</code> function, so this is
144       supplied by the RTS (in the file 
145       <a href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/rts/Main.c"><code>Main.c</code></a>).
146       It calls <code>startupHaskell</code>, which
147       itself calls <code>__stginit_PrelMain</code>, which is therefore,
148       since it occurs in the standard library, one of the symbols
149       passed to the linker using the <code>-u</code> option.  This is fine
150       for standalone Haskell programs, but as soon as the Haskell code is only
151       used as part of a program implemented in a foreign language, the
152       <code>main()</code> function of that foreign language should be used
153       instead of that of the Haskell runtime.  In this case, the previously
154       described arrangement unfortunately fails as 
155       <code>__stginit_PrelMain</code> had better not be linked in,
156       because it tries to call <code>__stginit_Main</code>, which won't
157       exist.  In other words, the RTS's <code>main()</code> refers to 
158       <code>__stginit_PrelMain</code> which in turn refers to
159       <code>__stginit_Main</code>.  Although the RTS's <code>main()</code> 
160       might not be linked in if the program provides its own, the driver 
161       will normally force <code>__stginit_PrelMain</code> to be linked in anyway,
162       using <code>-u</code>, because it's a back-reference from the
163       RTS to HSstd.  This case is coped with by the <code>-no-hs-main</code>
164       flag, which suppresses passing the corresonding <code>-u</code> option
165       to the linker -- although in some versions of the compiler (e.g., 5.00.2)
166       it didn't work.  In addition, the driver generally places the C program 
167       providing the <code>main()</code> that we want to use before the RTS
168       on the link line.  Therefore, the RTS's main is never used and
169       without the <code>-u</code> the label <code>__stginit_PrelMain</code> 
170       will not be linked.
171     </p>
172     
173     <p><small>
174 <!-- hhmts start -->
175 Last modified: Tue Feb 19 11:09:00 UTC 2002
176 <!-- hhmts end -->
177     </small>
178   </body>
179 </html>