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-usagesp@ | UsageSP inference pre-inf and output @@
 113 @-ddump-occur-anal@ | `occurrence analysis' output @@
 114 @-ddump-spec@ | dump specialisation info @@
 115 @-ddump-stg@ | output of STG-to-STG passes @@
 116 @-ddump-absC@ | <em>un</em>flattened Abstract~C @@
 117 @-ddump-flatC@ | <em>flattened</em> Abstract~C @@
 118 @-ddump-realC@ | same as what goes to the C compiler @@
 119 @-ddump-asm@ | assembly language from the native-code generator @@
 120 </tabular>
 121
 122 <nidx>-ddump-rdr option</nidx>%
 123 <nidx>-ddump-rn option</nidx>%
 124 <nidx>-ddump-tc option</nidx>%
 125 <nidx>-ddump-deriv option</nidx>%
 126 <nidx>-ddump-ds option</nidx>%
 127 <nidx>-ddump-simpl option</nidx>%
 128 <nidx>-ddump-usagesp option</nidx>%
 129 <nidx>-ddump-stranal option</nidx>%
 130 <nidx>-ddump-occur-anal option</nidx>%
 131 <nidx>-ddump-spec option</nidx>%
 132 <nidx>-ddump-stg option</nidx>%
 133 <nidx>-ddump-absC option</nidx>%
 134 <nidx>-ddump-flatC option</nidx>%
 135 <nidx>-ddump-realC option</nidx>%
 136 <nidx>-ddump-asm option</nidx>
 137
 138 %For any other @-ddump-*@ options: consult the source, notably
 139 %@ghc/compiler/main/CmdLineOpts.lhs@.
 140
 141 <tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag>
 142 <nidx>-dverbose-simpl option</nidx>
 143 <nidx>-dverbose-stg option</nidx>
 144 Show the output of the intermediate Core-to-Core and STG-to-STG
 145 passes, respectively.  (<em>Lots</em> of output!) So: when we're
 146 really desperate:
 147 <tscreen><verb>
 148 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
 149 </verb></tscreen>
 150
 151 <tag>@-ddump-simpl-iterations@:</tag>
 152 <nidx>-ddump-simpl-iterations option</nidx>
 153 Show the output of each <em/iteration/ of the simplifier (each run of
 154 the simplifier has a maximum number of iterations, normally 4).  Used
 155 when even @-dverbose-simpl@ doesn't cut it.
 156
 157 <tag>@-dppr-{user,debug,all@}:</tag>
 158 <nidx>-dppr-user option</nidx>
 159 <nidx>-dppr-debug option</nidx>
 160 <nidx>-dppr-all option</nidx>
 161 Debugging output is in one of several ``styles.''  Take the printing
 162 of types, for example.  In the ``user'' style, the compiler's internal
 163 ideas about types are presented in Haskell source-level syntax,
 164 insofar as possible.  In the ``debug'' style (which is the default for
 165 debugging output), the types are printed in the most-often-desired
 166 form, with explicit foralls, etc.  In the ``show all'' style, very
 167 verbose information about the types (e.g., the Uniques on the
 168 individual type variables) is displayed.
 169
 170 <tag>@-ddump-raw-asm@:</tag>
 171 <nidx>-ddump-raw-asm option</nidx>
 172 Dump out the assembly-language stuff, before the ``mangler'' gets it.
 173
 174 <tag>@-ddump-rn-trace@:</tag>
 175 <nidx>-ddump-rn-trace</nidx>
 176 Make the renamer be *real* chatty about what it is upto.
 177
 178 <tag>@-dshow-rn-stats@:</tag>
 179 <nidx>-dshow-rn-stats</nidx>
 180 Print out summary of what kind of information the renamer had to bring
 181 in.
 182 <tag>@-dshow-unused-imports@:</tag>
 183 <nidx>-dshow-unused-imports</nidx>
 184 Have the renamer report what imports does not contribute.
 185
 186 %
 187 %<tag>@-dgc-debug@:</tag>
 188 %<nidx>-dgc-debug option</nidx>
 189 %Enables some debugging code related to the garbage-collector.
 190 </descrip>
 191
 192 %ToDo: -ddump-asm-insn-counts
 193 %-ddump-asm-globals-info
 194
 195 %----------------------------------------------------------------------
 196 <sect2>Checking for consistency
 197 <label id="checking-consistency">
 198 <p>
 199 <nidx>consistency checks</nidx>
 200 <nidx>lint</nidx>
 201
 202 <descrip>
 203 <tag>@-dcore-lint@:</tag>
 204 <nidx>-dcore-lint option</nidx>
 205 Turn on heavyweight intra-pass sanity-checking within GHC, at Core
 206 level.  (It checks GHC's sanity, not yours.)
 207
 208 <tag>@-dstg-lint@:</tag>
 209 <nidx>-dstg-lint option</nidx>
 210 Ditto for STG level.
 211
 212 <tag>@-dusagesp-lint@:</tag>
 213 <nidx>-dstg-lint option</nidx>
 214 Turn on checks around UsageSP inference (@-fusagesp@).  This verifies
 215 various simple properties of the results of the inference, and also
 216 warns if any identifier with a used-once annotation before the
 217 inference has a used-many annotation afterwards; this could indicate a
 218 non-worksafe transformation is being applied.
 219 </descrip>
 220
 221 %----------------------------------------------------------------------
 222 <sect2>How to read Core syntax (from some @-ddump-*@ flags)
 223 <p>
 224 <nidx>reading Core syntax</nidx>
 225 <nidx>Core syntax, how to read</nidx>
 226
 227 Let's do this by commenting an example.  It's from doing
 228 @-ddump-ds@ on this code:
 229 <tscreen><verb>
 230 skip2 m = m : skip2 (m+2)
 231 </verb></tscreen>
 232
 233 Before we jump in, a word about names of things.  Within GHC,
 234 variables, type constructors, etc., are identified by their
 235 ``Uniques.''  These are of the form `letter' plus `number' (both
 236 loosely interpreted).  The `letter' gives some idea of where the
 237 Unique came from; e.g., @_@ means ``built-in type variable'';
 238 @t@ means ``from the typechecker''; @s@ means ``from the
 239 simplifier''; and so on.  The `number' is printed fairly compactly in
 240 a `base-62' format, which everyone hates except me (WDP).
 241
 242 Remember, everything has a ``Unique'' and it is usually printed out
 243 when debugging, in some form or another.  So here we go...
 244
 245 <tscreen><verb>
 246 Desugared:
 247 Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
 248
 249 --# `r1L6' is the Unique for Main.skip2;
 250 --# `_4' is the Unique for the type-variable (template) `a'
 251 --# `{{Num a$_4}}' is a dictionary argument
 252
 253 _NI_
 254
 255 --# `_NI_' means "no (pragmatic) information" yet; it will later
 256 --# evolve into the GHC_PRAGMA info that goes into interface files.
 257
 258 Main.skip2{-r1L6-} =
 259     /\ _4 -> \ d.Num.t4Gt ->
 260         let {
 261           {- CoRec -}
 262           +.t4Hg :: _4 -> _4 -> _4
 263           _NI_
 264           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 265
 266           fromInt.t4GS :: Int{-2i-} -> _4
 267           _NI_
 268           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 269
 270 --# The `+' class method (Unique: r3JH) selects the addition code
 271 --# from a `Num' dictionary (now an explicit lamba'd argument).
 272 --# Because Core is 2nd-order lambda-calculus, type applications
 273 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 274 --# type (`_4'), then to a dictionary, yielding the actual addition
 275 --# function that we will use subsequently...
 276
 277 --# We play the exact same game with the (non-standard) class method
 278 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 279 --# compiler.
 280
 281           lit.t4Hb :: _4
 282           _NI_
 283           lit.t4Hb =
 284               let {
 285                 ds.d4Qz :: Int{-2i-}
 286                 _NI_
 287                 ds.d4Qz = I#! 2#
 288               } in  fromInt.t4GS ds.d4Qz
 289
 290 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 291 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 292 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 293
 294 --# The `!' after `I#' indicates that this is a *saturated*
 295 --# application of the `I#' data constructor (i.e., not partially
 296 --# applied).
 297
 298           skip2.t3Ja :: _4 -> [_4]
 299           _NI_
 300           skip2.t3Ja =
 301               \ m.r1H4 ->
 302                   let { ds.d4QQ :: [_4]
 303                         _NI_
 304                         ds.d4QQ =
 305                     let {
 306                       ds.d4QY :: _4
 307                       _NI_
 308                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 309                     } in  skip2.t3Ja ds.d4QY
 310                   } in
 311                   :! _4 m.r1H4 ds.d4QQ
 312
 313           {- end CoRec -}
 314         } in  skip2.t3Ja
 315 </verb></tscreen>
 316
 317 (``It's just a simple functional language'' is an unregisterised
 318 trademark of Peyton Jones Enterprises, plc.)
 319
 320 %----------------------------------------------------------------------
 321 <sect2>Command line options in source files
 322 <label id="source-file-options">
 323 <p>
 324 <nidx>source-file options</nidx>
 325
 326 Sometimes it is useful to make the connection between a source file
 327 and the command-line options it requires quite tight. For instance,
 328 if a (Glasgow) Haskell source file uses @casm@s, the C back-end
 329 often needs to be told about which header files to include. Rather than
 330 maintaining the list of files the source depends on in a
 331 @Makefile@ (using the @-#include@ command-line option), it is
 332 possible to do this directly in the source file using the @OPTIONS@
 333 pragma <nidx>OPTIONS pragma</nidx>:
 334
 335 <tscreen><verb>
 336 {-# OPTIONS -#include "foo.h" #-}
 337 module X where
 338
 339 ...
 340 </verb></tscreen>
 341
 342 @OPTIONS@ pragmas are only looked for at the top of your source
 343 files, upto the first (non-literate,non-empty) line not containing
 344 @OPTIONS@. Multiple @OPTIONS@ pragmas are recognised. Note
 345 that your command shell does not get to the source file options, they
 346 are just included literally in the array of command-line arguments
 347 the compiler driver maintains internally, so you'll be desperately
 348 disappointed if you try to glob etc. inside @OPTIONS@.
 349
 350 NOTE: the contents of OPTIONS are prepended to the command-line
 351 options, so you *do* have the ability to override OPTIONS settings
 352 via the command line.
 353
 354 It is not recommended to move all the contents of your Makefiles into
 355 your source files, but in some circumstances, the @OPTIONS@ pragma
 356 is the Right Thing. (If you use @-keep-hc-file-too@ and have OPTION
 357 flags in your module, the OPTIONS will get put into the generated .hc
 358 file).
 359
 360 %----------------------------------------------------------------------