ghc/docs/users_guide/debugging.vsgml

   1 %************************************************************************
   2 %*                                                                      *
   3 <sect1>Debugging the compiler
   4 <label id="options-debugging">
   5 <p>
   6 <nidx>debugging options (for GHC)</nidx>
   7 %*                                                                      *
   8 %************************************************************************
   9
  10 HACKER TERRITORY. HACKER TERRITORY.
  11 (You were warned.)
  12
  13 %----------------------------------------------------------------------
  14 <sect2>Replacing the program for one or more phases.
  15 <label id="replacing-phases">
  16 <p>
  17 <nidx>GHC phases, changing</nidx>
  18 <nidx>phases, changing GHC</nidx>
  19
  20 You may specify that a different program be used for one of the phases
  21 of the compilation system, in place of whatever the driver @ghc@ has
  22 wired into it.  For example, you might want to try a different
  23 assembler.  The
  24 @-pgm<phase-code><program-name>@<nidx>-pgm&lt;phase&gt;&lt;stuff&gt;
  25 option</nidx> option to @ghc@ will cause it to use @<program-name>@
  26 for phase @<phase-code>@, where the codes to indicate the phases are:
  27
  28 <tabular ca="ll">
  29 <bf>code</bf> | <bf>phase</bf> @@
  30 @@
  31 L    | literate pre-processor @@
  32 P    | C pre-processor (if -cpp only) @@
  33 C    | Haskell compiler @@
  34 c    | C compiler@@
  35 a    | assembler @@
  36 l    | linker @@
  37 dep  | Makefile dependency generator @@
  38 </tabular>
  39
  40 %----------------------------------------------------------------------
  41 <sect2>Forcing options to a particular phase.
  42 <label id="forcing-options-through">
  43 <p>
  44 <nidx>forcing GHC-phase options</nidx>
  45
  46 The preceding sections describe driver options that are mostly
  47 applicable to one particular phase.  You may also <em>force</em> a
  48 specific option @<option>@ to be passed to a particular phase
  49 @<phase-code>@ by feeding the driver the option
  50 @-opt<phase-code><option>@.<nidx>-opt&lt;phase&gt;&lt;stuff&gt;
  51 option</nidx> The codes to indicate the phases are the same as in the
  52 previous section.
  53
  54 So, for example, to force an @-Ewurble@ option to the assembler, you
  55 would tell the driver @-opta-Ewurble@ (the dash before the E is
  56 required).
  57
  58 Besides getting options to the Haskell compiler with @-optC<blah>@,
  59 you can get options through to its runtime system with
  60 @-optCrts<blah>@<nidx>-optCrts&lt;blah&gt; option</nidx>.
  61
  62 So, for example: when I want to use my normal driver but with my
  63 profiled compiler binary, I use this script:
  64 <tscreen><verb>
  65 #! /bin/sh
  66 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
  67      -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
  68      -optCrts-i0.5 \
  69      -optCrts-PT \
  70      "$@"
  71 </verb></tscreen>
  72
  73 %----------------------------------------------------------------------
  74 <sect2>Dumping out compiler intermediate structures
  75 <label id="dumping-output">
  76 <p>
  77 <nidx>dumping GHC intermediates</nidx>
  78 <nidx>intermediate passes, output</nidx>
  79
  80 <descrip>
  81 <tag>@-noC@:</tag>
  82 <nidx>-noC option</nidx>
  83 Don't bother generating C output <em>or</em> an interface file.  Usually
  84 used in conjunction with one or more of the @-ddump-*@ options; for
  85 example: @ghc -noC -ddump-simpl Foo.hs@
  86
  87 <tag>@-hi@:</tag>
  88 <nidx>-hi option</nidx>
  89 <em>Do</em> generate an interface file.  This would normally be used in
  90 conjunction with @-noC@, which turns off interface generation;
  91 thus: @-noC -hi@.
  92
  93 <tag>@-dshow-passes@:</tag>
  94 <nidx>-dshow-passes option</nidx>
  95 Prints a message to stderr as each pass starts.  Gives a warm but
  96 undoubtedly misleading feeling that GHC is telling you what's
  97 happening.
  98
  99 <tag>@-ddump-<pass>@:</tag>
 100 <nidx>-ddump-&lt;pass&gt; options</nidx>
 101 Make a debugging dump after pass @<pass>@ (may be common enough to
 102 need a short form...).  Some of the most useful ones are:
 103
 104 <tabular ca="ll">
 105 @-ddump-rdr@ | reader output (earliest stuff in the compiler) @@
 106 @-ddump-rn@ | renamer output @@
 107 @-ddump-tc@ | typechecker output @@
 108 @-ddump-deriv@ | derived instances @@
 109 @-ddump-ds@ | desugarer output @@
 110 @-ddump-simpl@ | simplifer output (Core-to-Core passes) @@
 111 @-ddump-stranal@ | strictness analyser output @@
 112 @-ddump-occur-anal@ | `occurrence analysis' output @@
 113 @-ddump-spec@ | dump specialisation info @@
 114 @-ddump-stg@ | output of STG-to-STG passes @@
 115 @-ddump-absC@ | <em>un</em>flattened Abstract~C @@
 116 @-ddump-flatC@ | <em>flattened</em> Abstract~C @@
 117 @-ddump-realC@ | same as what goes to the C compiler @@
 118 @-ddump-asm@ | assembly language from the native-code generator @@
 119 </tabular>
 120
 121 <nidx>-ddump-rdr option</nidx>%
 122 <nidx>-ddump-rn option</nidx>%
 123 <nidx>-ddump-tc option</nidx>%
 124 <nidx>-ddump-deriv option</nidx>%
 125 <nidx>-ddump-ds option</nidx>%
 126 <nidx>-ddump-simpl option</nidx>%
 127 <nidx>-ddump-stranal option</nidx>%
 128 <nidx>-ddump-occur-anal option</nidx>%
 129 <nidx>-ddump-spec option</nidx>%
 130 <nidx>-ddump-stg option</nidx>%
 131 <nidx>-ddump-absC option</nidx>%
 132 <nidx>-ddump-flatC option</nidx>%
 133 <nidx>-ddump-realC option</nidx>%
 134 <nidx>-ddump-asm option</nidx>
 135
 136 %For any other @-ddump-*@ options: consult the source, notably
 137 %@ghc/compiler/main/CmdLineOpts.lhs@.
 138
 139 <tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag>
 140 <nidx>-dverbose-simpl option</nidx>
 141 <nidx>-dverbose-stg option</nidx>
 142 Show the output of the intermediate Core-to-Core and STG-to-STG
 143 passes, respectively.  (<em>Lots</em> of output!) So: when we're
 144 really desperate:
 145 <tscreen><verb>
 146 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
 147 </verb></tscreen>
 148
 149 <tag>@-ddump-simpl-iterations@:</tag>
 150 <nidx>-ddump-simpl-iterations option</nidx>
 151 Show the output of each <em/iteration/ of the simplifier (each run of
 152 the simplifier has a maximum number of iterations, normally 4).  Used
 153 when even @-dverbose-simpl@ doesn't cut it.
 154
 155 <tag>@-dppr-{user,debug,all@}:</tag>
 156 <nidx>-dppr-user option</nidx>
 157 <nidx>-dppr-debug option</nidx>
 158 <nidx>-dppr-all option</nidx>
 159 Debugging output is in one of several ``styles.''  Take the printing
 160 of types, for example.  In the ``user'' style, the compiler's internal
 161 ideas about types are presented in Haskell source-level syntax,
 162 insofar as possible.  In the ``debug'' style (which is the default for
 163 debugging output), the types are printed in the most-often-desired
 164 form, with explicit foralls, etc.  In the ``show all'' style, very
 165 verbose information about the types (e.g., the Uniques on the
 166 individual type variables) is displayed.
 167
 168 <tag>@-ddump-raw-asm@:</tag>
 169 <nidx>-ddump-raw-asm option</nidx>
 170 Dump out the assembly-language stuff, before the ``mangler'' gets it.
 171
 172 <tag>@-ddump-rn-trace@:</tag>
 173 <nidx>-ddump-rn-trace</nidx>
 174 Make the renamer be *real* chatty about what it is upto.
 175
 176 <tag>@-dshow-rn-stats@:</tag>
 177 <nidx>-dshow-rn-stats</nidx>
 178 Print out summary of what kind of information the renamer had to bring
 179 in.
 180 <tag>@-dshow-unused-imports@:</tag>
 181 <nidx>-dshow-unused-imports</nidx>
 182 Have the renamer report what imports does not contribute.
 183
 184 %
 185 %<tag>@-dgc-debug@:</tag>
 186 %<nidx>-dgc-debug option</nidx>
 187 %Enables some debugging code related to the garbage-collector.
 188 </descrip>
 189
 190 %ToDo: -ddump-asm-insn-counts
 191 %-ddump-asm-globals-info
 192
 193 %----------------------------------------------------------------------
 194 <sect2>How to read Core syntax (from some @-ddump-*@ flags)
 195 <p>
 196 <nidx>reading Core syntax</nidx>
 197 <nidx>Core syntax, how to read</nidx>
 198
 199 Let's do this by commenting an example.  It's from doing
 200 @-ddump-ds@ on this code:
 201 <tscreen><verb>
 202 skip2 m = m : skip2 (m+2)
 203 </verb></tscreen>
 204
 205 Before we jump in, a word about names of things.  Within GHC,
 206 variables, type constructors, etc., are identified by their
 207 ``Uniques.''  These are of the form `letter' plus `number' (both
 208 loosely interpreted).  The `letter' gives some idea of where the
 209 Unique came from; e.g., @_@ means ``built-in type variable'';
 210 @t@ means ``from the typechecker''; @s@ means ``from the
 211 simplifier''; and so on.  The `number' is printed fairly compactly in
 212 a `base-62' format, which everyone hates except me (WDP).
 213
 214 Remember, everything has a ``Unique'' and it is usually printed out
 215 when debugging, in some form or another.  So here we go...
 216
 217 <tscreen><verb>
 218 Desugared:
 219 Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
 220
 221 --# `r1L6' is the Unique for Main.skip2;
 222 --# `_4' is the Unique for the type-variable (template) `a'
 223 --# `{{Num a$_4}}' is a dictionary argument
 224
 225 _NI_
 226
 227 --# `_NI_' means "no (pragmatic) information" yet; it will later
 228 --# evolve into the GHC_PRAGMA info that goes into interface files.
 229
 230 Main.skip2{-r1L6-} =
 231     /\ _4 -> \ d.Num.t4Gt ->
 232         let {
 233           {- CoRec -}
 234           +.t4Hg :: _4 -> _4 -> _4
 235           _NI_
 236           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 237
 238           fromInt.t4GS :: Int{-2i-} -> _4
 239           _NI_
 240           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 241
 242 --# The `+' class method (Unique: r3JH) selects the addition code
 243 --# from a `Num' dictionary (now an explicit lamba'd argument).
 244 --# Because Core is 2nd-order lambda-calculus, type applications
 245 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 246 --# type (`_4'), then to a dictionary, yielding the actual addition
 247 --# function that we will use subsequently...
 248
 249 --# We play the exact same game with the (non-standard) class method
 250 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 251 --# compiler.
 252
 253           lit.t4Hb :: _4
 254           _NI_
 255           lit.t4Hb =
 256               let {
 257                 ds.d4Qz :: Int{-2i-}
 258                 _NI_
 259                 ds.d4Qz = I#! 2#
 260               } in  fromInt.t4GS ds.d4Qz
 261
 262 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 263 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 264 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 265
 266 --# The `!' after `I#' indicates that this is a *saturated*
 267 --# application of the `I#' data constructor (i.e., not partially
 268 --# applied).
 269
 270           skip2.t3Ja :: _4 -> [_4]
 271           _NI_
 272           skip2.t3Ja =
 273               \ m.r1H4 ->
 274                   let { ds.d4QQ :: [_4]
 275                         _NI_
 276                         ds.d4QQ =
 277                     let {
 278                       ds.d4QY :: _4
 279                       _NI_
 280                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 281                     } in  skip2.t3Ja ds.d4QY
 282                   } in
 283                   :! _4 m.r1H4 ds.d4QQ
 284
 285           {- end CoRec -}
 286         } in  skip2.t3Ja
 287 </verb></tscreen>
 288
 289 (``It's just a simple functional language'' is an unregisterised
 290 trademark of Peyton Jones Enterprises, plc.)
 291
 292 %----------------------------------------------------------------------
 293 <sect2>Command line options in source files
 294 <label id="source-file-options">
 295 <p>
 296 <nidx>source-file options</nidx>
 297
 298 Sometimes it is useful to make the connection between a source file
 299 and the command-line options it requires quite tight. For instance,
 300 if a (Glasgow) Haskell source file uses @casm@s, the C back-end
 301 often needs to be told about which header files to include. Rather than
 302 maintaining the list of files the source depends on in a
 303 @Makefile@ (using the @-#include@ command-line option), it is
 304 possible to do this directly in the source file using the @OPTIONS@
 305 pragma <nidx>OPTIONS pragma</nidx>:
 306
 307 <tscreen><verb>
 308 {-# OPTIONS -#include "foo.h" #-}
 309 module X where
 310
 311 ...
 312 </verb></tscreen>
 313
 314 @OPTIONS@ pragmas are only looked for at the top of your source
 315 files, upto the first (non-literate,non-empty) line not containing
 316 @OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note
 317 that your command shell does not get to the source file options, they
 318 are just included literally in the array of command-line arguments
 319 the compiler driver maintains internally, so you'll be desperately
 320 disappointed if you try to glob etc. inside @OPTIONS@.
 321
 322 NOTE: the contents of OPTIONS are prepended to the command-line
 323 options, so you *do* have the ability to override OPTIONS settings
 324 via the command line.
 325
 326 It is not recommended to move all the contents of your Makefiles into
 327 your source files, but in some circumstances, the @OPTIONS@ pragma
 328 is the Right Thing. (If you use @-keep-hc-file-too@ and have OPTION
 329 flags in your module, the OPTIONS will get put into the generated .hc
 330 file).
 331
 332 %----------------------------------------------------------------------