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