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