1 %************************************************************************
3 <sect1>Debugging the compiler
4 <label id="options-debugging">
6 <nidx>debugging options (for GHC)</nidx>
8 %************************************************************************
10 HACKER TERRITORY. HACKER TERRITORY.
13 %----------------------------------------------------------------------
14 <sect2>Replacing the program for one or more phases.
15 <label id="replacing-phases">
17 <nidx>GHC phases, changing</nidx>
18 <nidx>phases, changing GHC</nidx>
20 You may specify that a different program
21 be used for one of the phases of the compilation system, in place of
22 whatever the driver @ghc@ has wired into it. For example, you
23 might want to try a different assembler. The
24 @-pgm<phase-code><program-name>@<nidx>-pgm<phase><stuff> option</nidx> option to
25 @ghc@ will cause it to use @<program-name>@ for phase
26 @<phase-code>@, where the codes to indicate the phases are:
29 <bf>code</bf> | <bf>phase</bf> @@
31 L | literate pre-processor @@
32 P | C pre-processor (if -cpp only) @@
33 C | Haskell compiler @@
39 %----------------------------------------------------------------------
40 <sect2>Forcing options to a particular phase.
41 <label id="forcing-options-through">
43 <nidx>forcing GHC-phase options</nidx>
45 The preceding sections describe driver options that are mostly
46 applicable to one particular phase. You may also <em>force</em> a
47 specific option @<option>@ to be passed to a particular phase
48 @<phase-code>@ by feeding the driver the option
49 @-opt<phase-code><option>@.<nidx>-opt<phase><stuff> option</nidx> The
50 codes to indicate the phases are the same as in the previous section.
52 So, for example, to force an @-Ewurble@ option to the assembler, you
53 would tell the driver @-opta-Ewurble@ (the dash before the E is
56 Besides getting options to the Haskell compiler with @-optC<blah>@,
57 you can get options through to its runtime system with
58 @-optCrts<blah>@<nidx>-optCrts<blah> option</nidx>.
60 So, for example: when I want to use my normal driver but with my
61 profiled compiler binary, I use this script:
64 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
65 -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
71 %----------------------------------------------------------------------
72 <sect2>Dumping out compiler intermediate structures
73 <label id="dumping-output">
75 <nidx>dumping GHC intermediates</nidx>
76 <nidx>intermediate passes, output</nidx>
80 <nidx>-noC option</nidx>
81 Don't bother generating C output <em>or</em> an interface file. Usually
82 used in conjunction with one or more of the @-ddump-*@ options; for
83 example: @ghc -noC -ddump-simpl Foo.hs@
86 <nidx>-hi option</nidx>
87 <em>Do</em> generate an interface file. This would normally be used in
88 conjunction with @-noC@, which turns off interface generation;
91 <tag>@-dshow-passes@:</tag>
92 <nidx>-dshow-passes option</nidx>
93 Prints a message to stderr as each pass starts. Gives a warm but
94 undoubtedly misleading feeling that GHC is telling you what's
97 <tag>@-ddump-<pass>@:</tag>
98 <nidx>-ddump-<pass> options</nidx>
99 Make a debugging dump after pass @<pass>@ (may be common enough to
100 need a short form...). Some of the most useful ones are:
103 @-ddump-rdr@ | reader output (earliest stuff in the compiler) @@
104 @-ddump-rn@ | renamer output @@
105 @-ddump-tc@ | typechecker output @@
106 @-ddump-deriv@ | derived instances @@
107 @-ddump-ds@ | desugarer output @@
108 @-ddump-simpl@ | simplifer output (Core-to-Core passes) @@
109 @-ddump-stranal@ | strictness analyser output @@
110 @-ddump-occur-anal@ | `occurrence analysis' output @@
111 @-ddump-spec@ | dump specialisation info @@
112 @-ddump-stg@ | output of STG-to-STG passes @@
113 @-ddump-absC@ | <em>un</em>flattened Abstract~C @@
114 @-ddump-flatC@ | <em>flattened</em> Abstract~C @@
115 @-ddump-realC@ | same as what goes to the C compiler @@
116 @-ddump-asm@ | assembly language from the native-code generator @@
119 <nidx>-ddump-rdr option</nidx>%
120 <nidx>-ddump-rn option</nidx>%
121 <nidx>-ddump-tc option</nidx>%
122 <nidx>-ddump-deriv option</nidx>%
123 <nidx>-ddump-ds option</nidx>%
124 <nidx>-ddump-simpl option</nidx>%
125 <nidx>-ddump-stranal option</nidx>%
126 <nidx>-ddump-occur-anal option</nidx>%
127 <nidx>-ddump-spec option</nidx>%
128 <nidx>-ddump-stg option</nidx>%
129 <nidx>-ddump-absC option</nidx>%
130 <nidx>-ddump-flatC option</nidx>%
131 <nidx>-ddump-realC option</nidx>%
132 <nidx>-ddump-asm option</nidx>
134 %For any other @-ddump-*@ options: consult the source, notably
135 %@ghc/compiler/main/CmdLineOpts.lhs@.
137 <tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag>
138 <nidx>-dverbose-simpl option</nidx>
139 <nidx>-dverbose-stg option</nidx>
140 Show the output of the intermediate Core-to-Core and STG-to-STG
141 passes, respectively. (<em>Lots</em> of output!) So: when we're
144 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
147 <tag>@-dppr-{user,debug,all@}:</tag>
148 <nidx>-dppr-user option</nidx>
149 <nidx>-dppr-debug option</nidx>
150 <nidx>-dppr-all option</nidx>
151 Debugging output is in one of several ``styles.'' Take the printing
152 of types, for example. In the ``user'' style, the compiler's internal
153 ideas about types are presented in Haskell source-level syntax,
154 insofar as possible. In the ``debug'' style (which is the default for
155 debugging output), the types are printed in the most-often-desired
156 form, with explicit foralls, etc. In the ``show all'' style, very
157 verbose information about the types (e.g., the Uniques on the
158 individual type variables) is displayed.
160 <tag>@-ddump-raw-asm@:</tag>
161 <nidx>-ddump-raw-asm option</nidx>
162 Dump out the assembly-language stuff, before the ``mangler'' gets it.
164 <tag>@-ddump-rn-trace@:</tag>
165 <nidx>-ddump-rn-trace</nidx>
166 Make the renamer be *real* chatty about what it is upto.
168 <tag>@-dshow-rn-stats@:</tag>
169 <nidx>-dshow-rn-stats</nidx>
170 Print out summary of what kind of information the renamer had to bring
172 <tag>@-dshow-unused-imports@:</tag>
173 <nidx>-dshow-unused-imports</nidx>
174 Have the renamer report what imports does not contribute.
177 %<tag>@-dgc-debug@:</tag>
178 %<nidx>-dgc-debug option</nidx>
179 %Enables some debugging code related to the garbage-collector.
182 %ToDo: -ddump-asm-insn-counts
183 %-ddump-asm-globals-info
185 %----------------------------------------------------------------------
186 <sect2>How to read Core syntax (from some @-ddump-*@ flags)
188 <nidx>reading Core syntax</nidx>
189 <nidx>Core syntax, how to read</nidx>
191 Let's do this by commenting an example. It's from doing
192 @-ddump-ds@ on this code:
194 skip2 m = m : skip2 (m+2)
197 Before we jump in, a word about names of things. Within GHC,
198 variables, type constructors, etc., are identified by their
199 ``Uniques.'' These are of the form `letter' plus `number' (both
200 loosely interpreted). The `letter' gives some idea of where the
201 Unique came from; e.g., @_@ means ``built-in type variable'';
202 @t@ means ``from the typechecker''; @s@ means ``from the
203 simplifier''; and so on. The `number' is printed fairly compactly in
204 a `base-62' format, which everyone hates except me (WDP).
206 Remember, everything has a ``Unique'' and it is usually printed out
207 when debugging, in some form or another. So here we go...
211 Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
213 --# `r1L6' is the Unique for Main.skip2;
214 --# `_4' is the Unique for the type-variable (template) `a'
215 --# `{{Num a$_4}}' is a dictionary argument
219 --# `_NI_' means "no (pragmatic) information" yet; it will later
220 --# evolve into the GHC_PRAGMA info that goes into interface files.
223 /\ _4 -> \ d.Num.t4Gt ->
226 +.t4Hg :: _4 -> _4 -> _4
228 +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
230 fromInt.t4GS :: Int{-2i-} -> _4
232 fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
234 --# The `+' class method (Unique: r3JH) selects the addition code
235 --# from a `Num' dictionary (now an explicit lamba'd argument).
236 --# Because Core is 2nd-order lambda-calculus, type applications
237 --# and lambdas (/\) are explicit. So `+' is first applied to a
238 --# type (`_4'), then to a dictionary, yielding the actual addition
239 --# function that we will use subsequently...
241 --# We play the exact same game with the (non-standard) class method
242 --# `fromInt'. Unsurprisingly, the type `Int' is wired into the
252 } in fromInt.t4GS ds.d4Qz
254 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
255 --# GHC defines `data Int = I# Int#', where Int# is the primitive
256 --# unboxed type. (see relevant info about unboxed types elsewhere...)
258 --# The `!' after `I#' indicates that this is a *saturated*
259 --# application of the `I#' data constructor (i.e., not partially
262 skip2.t3Ja :: _4 -> [_4]
266 let { ds.d4QQ :: [_4]
272 ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
273 } in skip2.t3Ja ds.d4QY
281 (``It's just a simple functional language'' is an unregisterised
282 trademark of Peyton Jones Enterprises, plc.)
284 %----------------------------------------------------------------------
285 <sect2>Command line options in source files
286 <label id="source-file-options">
288 <nidx>source-file options</nidx>
290 Sometimes it is useful to make the connection between a source file
291 and the command-line options it requires quite tight. For instance,
292 if a (Glasgow) Haskell source file uses @casm@s, the C back-end
293 often needs to be told about which header files to include. Rather than
294 maintaining the list of files the source depends on in a
295 @Makefile@ (using the @-#include@ command-line option), it is
296 possible to do this directly in the source file using the @OPTIONS@
297 pragma <nidx>OPTIONS pragma</nidx>:
300 {-# OPTIONS -#include "foo.h" #-}
306 @OPTIONS@ pragmas are only looked for at the top of your source
307 files, upto the first (non-literate,non-empty) line not containing
308 @OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note
309 that your command shell does not get to the source file options, they
310 are just included literally in the array of command-line arguments
311 the compiler driver maintains internally, so you'll be desperately
312 disappointed if you try to glob etc. inside @OPTIONS@.
314 NOTE: the contents of OPTIONS are prepended to the command-line
315 options, so you *do* have the ability to override OPTIONS settings
316 via the command line.
318 It is not recommended to move all the contents of your Makefiles into
319 your source files, but in some circumstances, the @OPTIONS@ pragma
320 is the Right Thing. (If you use @-keep-hc-file-too@ and have OPTION
321 flags in your module, the OPTIONS will get put into the generated .hc
324 %----------------------------------------------------------------------
325 <sect2>How to compile mutually recursive modules
327 <nidx>module system, recursion</nidx>
329 Currently, the compiler does not have proper support for dealing with
330 mutually recursive modules:
352 When compiling either module A and B, the compiler will try (in vain)
353 to look for the interface file of the other. So, to get mutually
354 recursive modules off the ground, you need to hand write an interface
355 file for A or B, so as to break the loop. For the example at hand, the
356 boot interface file for A would like the following:
363 1 newtype A = A PrelBase.Int ;
364 1 f _:_ B.B -> A.A ;;
367 To make sure you get the syntax right, tailoring an existing interface
370 <bf>Note:</bf> This is all a temporary solution, a version of the
371 compiler that handles mutually recursive properly without the manual
372 construction of interface file, is in the works.