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