ghc/docs/users_guide/debugging.sgml

   1 <Sect1 id="options-debugging">
   2 <Title>Debugging the compiler
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm>
   7 </Para>
   8
   9 <Para>
  10 HACKER TERRITORY. HACKER TERRITORY.
  11 (You were warned.)
  12 </Para>
  13
  14
  15 <Sect2 id="dumping-output">
  16 <Title>Dumping out compiler intermediate structures
  17 </Title>
  18
  19 <Para>
  20 <IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm>
  21 <IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm>
  22 </Para>
  23
  24 <Para>
  25 <VariableList>
  26
  27 <VarListEntry>
  28 <Term><Option>-hi</Option>:</Term>
  29 <ListItem>
  30 <Para>
  31 <IndexTerm><Primary>-hi option</Primary></IndexTerm>
  32 <Emphasis>Do</Emphasis> generate an interface file.  This would normally be used in
  33 conjunction with <Option>-noC</Option>, which turns off interface generation;
  34 thus: <Option>-noC -hi</Option>.
  35 </Para>
  36 </ListItem>
  37 </VarListEntry>
  38 <VarListEntry>
  39 <Term><Option>-dshow-passes</Option>:</Term>
  40 <ListItem>
  41 <Para>
  42 <IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
  43 Prints a message to stderr as each pass starts.  Gives a warm but
  44 undoubtedly misleading feeling that GHC is telling you what's
  45 happening.
  46 </Para>
  47 </ListItem>
  48 </VarListEntry>
  49 <VarListEntry>
  50 <Term><Option>-ddump-&lt;pass&gt;</Option>:</Term>
  51 <ListItem>
  52 <Para>
  53 <IndexTerm><Primary>-ddump-&lt;pass&gt; options</Primary></IndexTerm>
  54 Make a debugging dump after pass <Literal>&lt;pass&gt;</Literal> (may be common enough to
  55 need a short form&hellip;).  You can get all of these at once (<Emphasis>lots</Emphasis> of
  56 output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>.
  57 Some of the most useful ones are:
  58 </Para>
  59
  60 <Para>
  61 <VariableList>
  62
  63 <VarListEntry>
  64 <Term><Option>-ddump-parsed</Option>:</Term>
  65 <ListItem>
  66 <Para>
  67 parser output
  68 </Para>
  69 </ListItem>
  70 </VarListEntry>
  71
  72 <VarListEntry>
  73 <Term><Option>-ddump-rn</Option>:</Term>
  74 <ListItem>
  75 <Para>
  76 renamer output
  77 </Para>
  78 </ListItem>
  79 </VarListEntry>
  80
  81 <VarListEntry>
  82 <Term><Option>-ddump-tc</Option>:</Term>
  83 <ListItem>
  84 <Para>
  85 typechecker output
  86 </Para>
  87 </ListItem>
  88 </VarListEntry>
  89
  90 <VarListEntry>
  91 <Term><Option>-ddump-types</Option>:</Term>
  92 <ListItem>
  93 <Para>
  94 Dump a type signature for each value defined at the top level
  95 of the module.  The list is sorted alphabetically.
  96 Using <Option>-dppr-debug</Option> dumps a type signature for
  97 all the imported and system-defined things as well; useful
  98 for debugging the compiler.
  99 </Para>
 100 </ListItem>
 101 </VarListEntry>
 102
 103 <VarListEntry>
 104 <Term><Option>-ddump-deriv</Option>:</Term>
 105 <ListItem>
 106 <Para>
 107 derived instances
 108 </Para>
 109 </ListItem>
 110 </VarListEntry>
 111 <VarListEntry>
 112 <Term><Option>-ddump-ds</Option>:</Term>
 113 <ListItem>
 114 <Para>
 115 desugarer output
 116 </Para>
 117 </ListItem>
 118 </VarListEntry>
 119 <VarListEntry>
 120 <Term><Option>-ddump-spec</Option>:</Term>
 121 <ListItem>
 122 <Para>
 123 output of specialisation pass
 124 </Para>
 125 </ListItem>
 126 </VarListEntry>
 127 <VarListEntry>
 128 <Term><Option>-ddump-rules</Option>:</Term>
 129 <ListItem>
 130 <Para>
 131 dumps all rewrite rules (including those generated by the specialisation pass)
 132 </Para>
 133 </ListItem>
 134 </VarListEntry>
 135 <VarListEntry>
 136 <Term><Option>-ddump-simpl</Option>:</Term>
 137 <ListItem>
 138 <Para>
 139 simplifer output (Core-to-Core passes)
 140 </Para>
 141 </ListItem>
 142 </VarListEntry>
 143 <VarListEntry>
 144 <Term><Option>-ddump-usagesp</Option>:</Term>
 145 <ListItem>
 146 <Para>
 147 UsageSP inference pre-inf and output
 148 </Para>
 149 </ListItem>
 150 </VarListEntry>
 151 <VarListEntry>
 152 <Term><Option>-ddump-cpranal</Option>:</Term>
 153 <ListItem>
 154 <Para>
 155 CPR analyser output
 156 </Para>
 157 </ListItem>
 158 </VarListEntry>
 159 <VarListEntry>
 160 <Term><Option>-ddump-stranal</Option>:</Term>
 161 <ListItem>
 162 <Para>
 163 strictness analyser output
 164 </Para>
 165 </ListItem>
 166 </VarListEntry>
 167 <VarListEntry>
 168 <Term><Option>-ddump-workwrap</Option>:</Term>
 169 <ListItem>
 170 <Para>
 171 worker/wrapper split output
 172 </Para>
 173 </ListItem>
 174 </VarListEntry>
 175 <VarListEntry>
 176 <Term><Option>-ddump-occur-anal</Option>:</Term>
 177 <ListItem>
 178 <Para>
 179 `occurrence analysis' output
 180 </Para>
 181 </ListItem>
 182 </VarListEntry>
 183 <VarListEntry>
 184 <Term><Option>-ddump-stg</Option>:</Term>
 185 <ListItem>
 186 <Para>
 187 output of STG-to-STG passes
 188 </Para>
 189 </ListItem>
 190 </VarListEntry>
 191 <VarListEntry>
 192 <Term><Option>-ddump-absC</Option>:</Term>
 193 <ListItem>
 194 <Para>
 195 <Emphasis>un</Emphasis>flattened Abstract&nbsp;C
 196 </Para>
 197 </ListItem>
 198 </VarListEntry>
 199 <VarListEntry>
 200 <Term><Option>-ddump-flatC</Option>:</Term>
 201 <ListItem>
 202 <Para>
 203 <Emphasis>flattened</Emphasis> Abstract&nbsp;C
 204 </Para>
 205 </ListItem>
 206 </VarListEntry>
 207 <VarListEntry>
 208 <Term><Option>-ddump-realC</Option>:</Term>
 209 <ListItem>
 210 <Para>
 211 same as what goes to the C compiler
 212 </Para>
 213 </ListItem>
 214 </VarListEntry>
 215 <VarListEntry>
 216 <Term><Option>-ddump-asm</Option>:</Term>
 217 <ListItem>
 218 <Para>
 219 assembly language from the native-code generator
 220 </Para>
 221 </ListItem>
 222 </VarListEntry>
 223 </VariableList>
 224 <IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
 225 <IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
 226 <IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
 227 <IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm>
 228 <IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm>
 229 <IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm>
 230 <IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm>
 231 <IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm>
 232 <IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm>
 233 <IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
 234 <IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm>
 235 <IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm>
 236 <IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm>
 237 <IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm>
 238 <IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
 239 <IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm>
 240 <IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm>
 241 <IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm>
 242 <IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm>
 243 <IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm>
 244 </Para>
 245 </ListItem>
 246 </VarListEntry>
 247 <VarListEntry>
 248 <Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
 249 <ListItem>
 250 <Para>
 251 <IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
 252 <IndexTerm><Primary>-dverbose-stg option</Primary></IndexTerm>
 253 Show the output of the intermediate Core-to-Core and STG-to-STG
 254 passes, respectively.  (<Emphasis>Lots</Emphasis> of output!) So: when we're
 255 really desperate:
 256
 257 <Screen>
 258 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
 259 </Screen>
 260
 261 </Para>
 262 </ListItem>
 263 </VarListEntry>
 264 <VarListEntry>
 265 <Term><Option>-ddump-simpl-iterations</Option>:</Term>
 266 <ListItem>
 267 <Para>
 268 <IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm>
 269 Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of
 270 the simplifier has a maximum number of iterations, normally 4).  Used
 271 when even <Option>-dverbose-simpl</Option> doesn't cut it.
 272 </Para>
 273 </ListItem>
 274 </VarListEntry>
 275 <VarListEntry>
 276 <Term><Option>-dppr-&lcub;user,debug</Option>&rcub;:</Term>
 277 <ListItem>
 278 <Para>
 279 <IndexTerm><Primary>-dppr-user option</Primary></IndexTerm>
 280 <IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm>
 281 Debugging output is in one of several &ldquo;styles.&rdquo;  Take the printing
 282 of types, for example.  In the &ldquo;user&rdquo; style, the compiler's internal
 283 ideas about types are presented in Haskell source-level syntax,
 284 insofar as possible.  In the &ldquo;debug&rdquo; style (which is the default for
 285 debugging output), the types are printed in with
 286 explicit foralls, and variables have their unique-id attached (so you
 287 can check for things that look the same but aren't).
 288 </Para>
 289 </ListItem>
 290 </VarListEntry>
 291 <VarListEntry>
 292 <Term><Option>-ddump-simpl-stats</Option>:</Term>
 293 <ListItem>
 294 <Para>
 295 <IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm>
 296 Dump statistics about how many of each kind
 297 of transformation too place.  If you add <Option>-dppr-debug</Option> you get more detailed information.
 298 </Para>
 299 </ListItem>
 300 </VarListEntry>
 301 <VarListEntry>
 302 <Term><Option>-ddump-raw-asm</Option>:</Term>
 303 <ListItem>
 304 <Para>
 305 <IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm>
 306 Dump out the assembly-language stuff, before the &ldquo;mangler&rdquo; gets it.
 307 </Para>
 308 </ListItem>
 309 </VarListEntry>
 310 <VarListEntry>
 311 <Term><Option>-ddump-rn-trace</Option>:</Term>
 312 <ListItem>
 313 <Para>
 314 <IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
 315 Make the renamer be *real* chatty about what it is upto.
 316 </Para>
 317 </ListItem>
 318 </VarListEntry>
 319 <VarListEntry>
 320 <Term><Option>-dshow-rn-stats</Option>:</Term>
 321 <ListItem>
 322 <Para>
 323 <IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
 324 Print out summary of what kind of information the renamer had to bring
 325 in.
 326 </Para>
 327 </ListItem>
 328 </VarListEntry>
 329 <VarListEntry>
 330 <Term><Option>-dshow-unused-imports</Option>:</Term>
 331 <ListItem>
 332 <Para>
 333 <IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
 334 Have the renamer report what imports does not contribute.
 335 </Para>
 336 </ListItem>
 337 </VarListEntry>
 338 </VariableList>
 339 </Para>
 340
 341 </Sect2>
 342
 343 <Sect2 id="checking-consistency">
 344 <Title>Checking for consistency
 345 </Title>
 346
 347 <Para>
 348 <IndexTerm><Primary>consistency checks</Primary></IndexTerm>
 349 <IndexTerm><Primary>lint</Primary></IndexTerm>
 350 </Para>
 351
 352 <Para>
 353 <VariableList>
 354
 355 <VarListEntry>
 356 <Term><Option>-dcore-lint</Option>:</Term>
 357 <ListItem>
 358 <Para>
 359 <IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
 360 Turn on heavyweight intra-pass sanity-checking within GHC, at Core
 361 level.  (It checks GHC's sanity, not yours.)
 362 </Para>
 363 </ListItem>
 364 </VarListEntry>
 365 <VarListEntry>
 366 <Term><Option>-dstg-lint</Option>:</Term>
 367 <ListItem>
 368 <Para>
 369 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
 370 Ditto for STG level.
 371 </Para>
 372 </ListItem>
 373 </VarListEntry>
 374 <VarListEntry>
 375 <Term><Option>-dusagesp-lint</Option>:</Term>
 376 <ListItem>
 377 <Para>
 378 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
 379 Turn on checks around UsageSP inference (<Option>-fusagesp</Option>).  This verifies
 380 various simple properties of the results of the inference, and also
 381 warns if any identifier with a used-once annotation before the
 382 inference has a used-many annotation afterwards; this could indicate a
 383 non-worksafe transformation is being applied.
 384 </Para>
 385 </ListItem>
 386 </VarListEntry>
 387 </VariableList>
 388 </Para>
 389
 390 </Sect2>
 391
 392 <Sect2>
 393 <Title>How to read Core syntax (from some <Option>-ddump-*</Option> flags)</Title>
 394
 395 <Para>
 396 <IndexTerm><Primary>reading Core syntax</Primary></IndexTerm>
 397 <IndexTerm><Primary>Core syntax, how to read</Primary></IndexTerm>
 398 </Para>
 399
 400 <Para>
 401 Let's do this by commenting an example.  It's from doing
 402 <Option>-ddump-ds</Option> on this code:
 403
 404 <ProgramListing>
 405 skip2 m = m : skip2 (m+2)
 406 </ProgramListing>
 407
 408 </Para>
 409
 410 <Para>
 411 Before we jump in, a word about names of things.  Within GHC,
 412 variables, type constructors, etc., are identified by their
 413 &ldquo;Uniques.&rdquo;  These are of the form `letter' plus `number' (both
 414 loosely interpreted).  The `letter' gives some idea of where the
 415 Unique came from; e.g., <Literal>&lowbar;</Literal> means &ldquo;built-in type variable&rdquo;;
 416 <Literal>t</Literal> means &ldquo;from the typechecker&rdquo;; <Literal>s</Literal> means &ldquo;from the
 417 simplifier&rdquo;; and so on.  The `number' is printed fairly compactly in
 418 a `base-62' format, which everyone hates except me (WDP).
 419 </Para>
 420
 421 <Para>
 422 Remember, everything has a &ldquo;Unique&rdquo; and it is usually printed out
 423 when debugging, in some form or another.  So here we go&hellip;
 424 </Para>
 425
 426 <Para>
 427 <ProgramListing>
 428 Desugared:
 429 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
 430
 431 --# `r1L6' is the Unique for Main.skip2;
 432 --# `_4' is the Unique for the type-variable (template) `a'
 433 --# `{{Num a$_4}}' is a dictionary argument
 434
 435 _NI_
 436
 437 --# `_NI_' means "no (pragmatic) information" yet; it will later
 438 --# evolve into the GHC_PRAGMA info that goes into interface files.
 439
 440 Main.skip2{-r1L6-} =
 441     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
 442         let {
 443           {- CoRec -}
 444           +.t4Hg :: _4 -&#62; _4 -&#62; _4
 445           _NI_
 446           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
 447
 448           fromInt.t4GS :: Int{-2i-} -&#62; _4
 449           _NI_
 450           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
 451
 452 --# The `+' class method (Unique: r3JH) selects the addition code
 453 --# from a `Num' dictionary (now an explicit lamba'd argument).
 454 --# Because Core is 2nd-order lambda-calculus, type applications
 455 --# and lambdas (/\) are explicit.  So `+' is first applied to a
 456 --# type (`_4'), then to a dictionary, yielding the actual addition
 457 --# function that we will use subsequently...
 458
 459 --# We play the exact same game with the (non-standard) class method
 460 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
 461 --# compiler.
 462
 463           lit.t4Hb :: _4
 464           _NI_
 465           lit.t4Hb =
 466               let {
 467                 ds.d4Qz :: Int{-2i-}
 468                 _NI_
 469                 ds.d4Qz = I#! 2#
 470               } in  fromInt.t4GS ds.d4Qz
 471
 472 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
 473 --# GHC defines `data Int = I# Int#', where Int# is the primitive
 474 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
 475
 476 --# The `!' after `I#' indicates that this is a *saturated*
 477 --# application of the `I#' data constructor (i.e., not partially
 478 --# applied).
 479
 480           skip2.t3Ja :: _4 -&#62; [_4]
 481           _NI_
 482           skip2.t3Ja =
 483               \ m.r1H4 -&#62;
 484                   let { ds.d4QQ :: [_4]
 485                         _NI_
 486                         ds.d4QQ =
 487                     let {
 488                       ds.d4QY :: _4
 489                       _NI_
 490                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
 491                     } in  skip2.t3Ja ds.d4QY
 492                   } in
 493                   :! _4 m.r1H4 ds.d4QQ
 494
 495           {- end CoRec -}
 496         } in  skip2.t3Ja
 497 </ProgramListing>
 498 </Para>
 499
 500 <Para>
 501 (&ldquo;It's just a simple functional language&rdquo; is an unregisterised
 502 trademark of Peyton Jones Enterprises, plc.)
 503 </Para>
 504
 505 </Sect2>
 506
 507 <Sect2 id="source-file-options">
 508 <Title>Command line options in source files
 509 </Title>
 510
 511 <Para>
 512 <IndexTerm><Primary>source-file options</Primary></IndexTerm>
 513 </Para>
 514
 515 <Para>
 516 Sometimes it is useful to make the connection between a source file
 517 and the command-line options it requires quite tight. For instance,
 518 if a (Glasgow) Haskell source file uses <Literal>casm</Literal>s, the C back-end
 519 often needs to be told about which header files to include. Rather than
 520 maintaining the list of files the source depends on in a
 521 <Filename>Makefile</Filename> (using the <Option>-&num;include</Option> command-line option), it is
 522 possible to do this directly in the source file using the <Literal>OPTIONS</Literal>
 523 pragma <IndexTerm><Primary>OPTIONS pragma</Primary></IndexTerm>:
 524 </Para>
 525
 526 <Para>
 527 <ProgramListing>
 528 {-# OPTIONS -#include "foo.h" #-}
 529 module X where
 530
 531 ...
 532 </ProgramListing>
 533 </Para>
 534
 535 <Para>
 536 <Literal>OPTIONS</Literal> pragmas are only looked for at the top of your source
 537 files, upto the first (non-literate,non-empty) line not containing
 538 <Literal>OPTIONS</Literal>. Multiple <Literal>OPTIONS</Literal> pragmas are recognised. Note
 539 that your command shell does not get to the source file options, they
 540 are just included literally in the array of command-line arguments
 541 the compiler driver maintains internally, so you'll be desperately
 542 disappointed if you try to glob etc. inside <Literal>OPTIONS</Literal>.
 543 </Para>
 544
 545 <Para>
 546 NOTE: the contents of OPTIONS are prepended to the command-line
 547 options, so you <Emphasis>do</Emphasis> have the ability to override OPTIONS settings
 548 via the command line.
 549 </Para>
 550
 551 <Para>
 552 It is not recommended to move all the contents of your Makefiles into
 553 your source files, but in some circumstances, the <Literal>OPTIONS</Literal> pragma
 554 is the Right Thing. (If you use <Option>-keep-hc-file-too</Option> and have OPTION
 555 flags in your module, the OPTIONS will get put into the generated .hc
 556 file).
 557 </Para>
 558
 559 </Sect2>
 560
 561   <sect2 id="unreg">
 562     <title>Unregisterised compilation</title>
 563     <indexterm><primary>unregisterised compilation</primary></indexterm>
 564
 565     <para>The term "unregisterised" really means "compile via vanilla
 566     C", disabling some of the platform-specific tricks that GHC
 567     normally uses to make programs go faster.  When compiling
 568     unregisterised, GHC simply generates a C file which is compiled
 569     via gcc.</para>
 570
 571     <para>Unregisterised compilation can be useful when porting GHC to
 572     a new machine, since it reduces the prerequisite tools to
 573     <command>gcc</command>, <command>as</command>, and
 574     <command>ld</command> and nothing more, and furthermore the amount
 575     of platform-specific code that needs to be written in order to get
 576     unregisterised compilation going is usually fairly small.</para>
 577
 578     <variablelist>
 579       <varlistentry>
 580         <term><option>-unreg</option>:</term>
 581         <indexterm><primary><option>-unreg</option></primary></indexterm>
 582         <listitem>
 583           <para>Compile via vanilla ANSI C only, turning off
 584           platform-specific optimisations.  NOTE: in order to use
 585           <option>-unreg</option>, you need to have a set of libraries
 586           (including the RTS) built for unregisterised compilation.
 587           This amounts to building GHC with way "u" enabled.</para>
 588         </listitem>
 589       </varlistentry>
 590     </variablelist>
 591   </sect2>
 592
 593 </Sect1>
 594
 595 <!-- Emacs stuff:
 596      ;;; Local Variables: ***
 597      ;;; mode: sgml ***
 598      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
 599      ;;; End: ***
 600  -->