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