diff options
Diffstat (limited to 'ghc/docs/users_guide/debugging.vsgml')
| -rw-r--r-- | ghc/docs/users_guide/debugging.vsgml | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/ghc/docs/users_guide/debugging.vsgml b/ghc/docs/users_guide/debugging.vsgml deleted file mode 100644 index f3fed156e4..0000000000 --- a/ghc/docs/users_guide/debugging.vsgml +++ /dev/null @@ -1,337 +0,0 @@ -%************************************************************************ -%* * -<sect1>Debugging the compiler -<label id="options-debugging"> -<p> -<nidx>debugging options (for GHC)</nidx> -%* * -%************************************************************************ - -HACKER TERRITORY. HACKER TERRITORY. -(You were warned.) - -%---------------------------------------------------------------------- -<sect2>Replacing the program for one or more phases. -<label id="replacing-phases"> -<p> -<nidx>GHC phases, changing</nidx> -<nidx>phases, changing GHC</nidx> - -You may specify that a different program be used for one of the phases -of the compilation system, in place of whatever the driver @ghc@ has -wired into it. For example, you might want to try a different -assembler. The -@-pgm<phase-code><program-name>@<nidx>-pgm<phase><stuff> -option</nidx> option to @ghc@ will cause it to use @<program-name>@ -for phase @<phase-code>@, where the codes to indicate the phases are: - -<tabular ca="ll"> -<bf>code</bf> | <bf>phase</bf> @@ -@@ -L | literate pre-processor @@ -P | C pre-processor (if -cpp only) @@ -C | Haskell compiler @@ -c | C compiler@@ -a | assembler @@ -l | linker @@ -dep | Makefile dependency generator @@ -</tabular> - -%---------------------------------------------------------------------- -<sect2>Forcing options to a particular phase. -<label id="forcing-options-through"> -<p> -<nidx>forcing GHC-phase options</nidx> - -The preceding sections describe driver options that are mostly -applicable to one particular phase. You may also <em>force</em> a -specific option @<option>@ to be passed to a particular phase -@<phase-code>@ by feeding the driver the option -@-opt<phase-code><option>@.<nidx>-opt<phase><stuff> -option</nidx> The codes to indicate the phases are the same as in the -previous section. - -So, for example, to force an @-Ewurble@ option to the assembler, you -would tell the driver @-opta-Ewurble@ (the dash before the E is -required). - -Besides getting options to the Haskell compiler with @-optC<blah>@, -you can get options through to its runtime system with -@-optCrts<blah>@<nidx>-optCrts<blah> option</nidx>. - -So, for example: when I want to use my normal driver but with my -profiled compiler binary, I use this script: -<tscreen><verb> -#! /bin/sh -exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \ - -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \ - -optCrts-i0.5 \ - -optCrts-PT \ - "$@" -</verb></tscreen> - -%---------------------------------------------------------------------- -<sect2>Dumping out compiler intermediate structures -<label id="dumping-output"> -<p> -<nidx>dumping GHC intermediates</nidx> -<nidx>intermediate passes, output</nidx> - -<descrip> -<tag>@-noC@:</tag> -<nidx>-noC option</nidx> -Don't bother generating C output <em>or</em> an interface file. Usually -used in conjunction with one or more of the @-ddump-*@ options; for -example: @ghc -noC -ddump-simpl Foo.hs@ - -<tag>@-hi@:</tag> -<nidx>-hi option</nidx> -<em>Do</em> generate an interface file. This would normally be used in -conjunction with @-noC@, which turns off interface generation; -thus: @-noC -hi@. - -<tag>@-dshow-passes@:</tag> -<nidx>-dshow-passes option</nidx> -Prints a message to stderr as each pass starts. Gives a warm but -undoubtedly misleading feeling that GHC is telling you what's -happening. - -<tag>@-ddump-<pass>@:</tag> -<nidx>-ddump-<pass> options</nidx> -Make a debugging dump after pass @<pass>@ (may be common enough to -need a short form...). You can get all of these at once (<em/lots/ of -output) by using @-ddump-all@, or most of them with @-ddump-most@. -Some of the most useful ones are: - -<descrip> -<tag>@-ddump-parsed@:</tag> parser output -<tag>@-ddump-rn@:</tag> renamer output -<tag>@-ddump-tc@:</tag> typechecker output -<tag>@-ddump-deriv@:</tag> derived instances -<tag>@-ddump-ds@:</tag> desugarer output -<tag>@-ddump-spec@:</tag> output of specialisation pass -<tag>@-ddump-rules@:</tag> dumps all rewrite rules (including those generated by the specialisation pass) -<tag>@-ddump-simpl@:</tag> simplifer output (Core-to-Core passes) -<tag>@-ddump-usagesp@:</tag> UsageSP inference pre-inf and output -<tag>@-ddump-cpranal@:</tag> CPR analyser output -<tag>@-ddump-stranal@:</tag> strictness analyser output -<tag>@-ddump-workwrap@:</tag> worker/wrapper split output -<tag>@-ddump-occur-anal@:</tag> `occurrence analysis' output -<tag>@-ddump-stg@:</tag> output of STG-to-STG passes -<tag>@-ddump-absC@:</tag> <em>un</em>flattened Abstract~C -<tag>@-ddump-flatC@:</tag> <em>flattened</em> Abstract~C -<tag>@-ddump-realC@:</tag> same as what goes to the C compiler -<tag>@-ddump-asm@:</tag> assembly language from the native-code generator -<tag>@-ddump-most@:</tag> most of the above, plus @-dshow-passes@, @-dsource-stats@, @-ddump-simpl-stats@, -<tag>@-ddump-all@:</tag> all the above, plus @-ddump-inlinings@, -@-ddump-simpl-iterations@, @-ddump-rn-trace@, -@-ddump-verbose-simpl@, @-ddump-verbose-stg@. -</descrip> - -<nidx>-ddump-all option</nidx>% -<nidx>-ddump-most option</nidx>% -<nidx>-ddump-parsed option</nidx>% -<nidx>-ddump-rn option</nidx>% -<nidx>-ddump-tc option</nidx>% -<nidx>-ddump-deriv option</nidx>% -<nidx>-ddump-ds option</nidx>% -<nidx>-ddump-simpl option</nidx>% -<nidx>-ddump-cpranal option</nidx>% -<nidx>-ddump-workwrap option</nidx>% -<nidx>-ddump-rules option</nidx>% -<nidx>-ddump-usagesp option</nidx>% -<nidx>-ddump-stranal option</nidx>% -<nidx>-ddump-occur-anal option</nidx>% -<nidx>-ddump-spec option</nidx>% -<nidx>-ddump-stg option</nidx>% -<nidx>-ddump-absC option</nidx>% -<nidx>-ddump-flatC option</nidx>% -<nidx>-ddump-realC option</nidx>% -<nidx>-ddump-asm option</nidx> - -%For any other @-ddump-*@ options: consult the source, notably -%@ghc/compiler/main/CmdLineOpts.lhs@. - -<tag>@-dverbose-simpl@ and @-dverbose-stg@:</tag> -<nidx>-dverbose-simpl option</nidx> -<nidx>-dverbose-stg option</nidx> -Show the output of the intermediate Core-to-Core and STG-to-STG -passes, respectively. (<em>Lots</em> of output!) So: when we're -really desperate: -<tscreen><verb> -% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs -</verb></tscreen> - -<tag>@-ddump-simpl-iterations@:</tag> -<nidx>-ddump-simpl-iterations option</nidx> -Show the output of each <em/iteration/ of the simplifier (each run of -the simplifier has a maximum number of iterations, normally 4). Used -when even @-dverbose-simpl@ doesn't cut it. - -<tag>@-dppr-{user,debug@}:</tag> -<nidx>-dppr-user option</nidx> -<nidx>-dppr-debug option</nidx> -Debugging output is in one of several ``styles.'' Take the printing -of types, for example. In the ``user'' style, the compiler's internal -ideas about types are presented in Haskell source-level syntax, -insofar as possible. In the ``debug'' style (which is the default for -debugging output), the types are printed in with -explicit foralls, and variables have their unique-id attached (so you -can check for things that look the same but aren't). - -<tag>@-ddump-simpl-stats@:</tag> -<nidx>-ddump-simpl-stats option</nidx> -Dump statistics about how many of each kind -of transformation too place. If you add @-dppr-debug@ you get more detailed information. - -<tag>@-ddump-raw-asm@:</tag> -<nidx>-ddump-raw-asm option</nidx> -Dump out the assembly-language stuff, before the ``mangler'' gets it. - -<tag>@-ddump-rn-trace@:</tag> -<nidx>-ddump-rn-trace</nidx> -Make the renamer be *real* chatty about what it is upto. - -<tag>@-dshow-rn-stats@:</tag> -<nidx>-dshow-rn-stats</nidx> -Print out summary of what kind of information the renamer had to bring -in. -<tag>@-dshow-unused-imports@:</tag> -<nidx>-dshow-unused-imports</nidx> -Have the renamer report what imports does not contribute. - -% -%<tag>@-dgc-debug@:</tag> -%<nidx>-dgc-debug option</nidx> -%Enables some debugging code related to the garbage-collector. -</descrip> - -%ToDo: -ddump-asm-insn-counts -%-ddump-asm-globals-info - -%---------------------------------------------------------------------- -<sect2>Checking for consistency -<label id="checking-consistency"> -<p> -<nidx>consistency checks</nidx> -<nidx>lint</nidx> - -<descrip> -<tag>@-dcore-lint@:</tag> -<nidx>-dcore-lint option</nidx> -Turn on heavyweight intra-pass sanity-checking within GHC, at Core -level. (It checks GHC's sanity, not yours.) - -<tag>@-dstg-lint@:</tag> -<nidx>-dstg-lint option</nidx> -Ditto for STG level. - -<tag>@-dusagesp-lint@:</tag> -<nidx>-dstg-lint option</nidx> -Turn on checks around UsageSP inference (@-fusagesp@). This verifies -various simple properties of the results of the inference, and also -warns if any identifier with a used-once annotation before the -inference has a used-many annotation afterwards; this could indicate a -non-worksafe transformation is being applied. -</descrip> - -%---------------------------------------------------------------------- -<sect2>How to read Core syntax (from some @-ddump-*@ flags) -<p> -<nidx>reading Core syntax</nidx> -<nidx>Core syntax, how to read</nidx> - -Let's do this by commenting an example. It's from doing -@-ddump-ds@ on this code: -<tscreen><verb> -skip2 m = m : skip2 (m+2) -</verb></tscreen> - -Before we jump in, a word about names of things. Within GHC, -variables, type constructors, etc., are identified by their -``Uniques.'' These are of the form `letter' plus `number' (both -loosely interpreted). The `letter' gives some idea of where the -Unique came from; e.g., @_@ means ``built-in type variable''; -@t@ means ``from the typechecker''; @s@ means ``from the -simplifier''; and so on. The `number' is printed fairly compactly in -a `base-62' format, which everyone hates except me (WDP). - -Remember, everything has a ``Unique'' and it is usually printed out -when debugging, in some form or another. So here we go... - -<tscreen><verb> -Desugared: -Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4] - ---# `r1L6' is the Unique for Main.skip2; ---# `_4' is the Unique for the type-variable (template) `a' ---# `{{Num a$_4}}' is a dictionary argument - -_NI_ - ---# `_NI_' means "no (pragmatic) information" yet; it will later ---# evolve into the GHC_PRAGMA info that goes into interface files. - -Main.skip2{-r1L6-} = - /\ _4 -> \ d.Num.t4Gt -> - let { - {- CoRec -} - +.t4Hg :: _4 -> _4 -> _4 - _NI_ - +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt - - fromInt.t4GS :: Int{-2i-} -> _4 - _NI_ - fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt - ---# The `+' class method (Unique: r3JH) selects the addition code ---# from a `Num' dictionary (now an explicit lamba'd argument). ---# Because Core is 2nd-order lambda-calculus, type applications ---# and lambdas (/\) are explicit. So `+' is first applied to a ---# type (`_4'), then to a dictionary, yielding the actual addition ---# function that we will use subsequently... - ---# We play the exact same game with the (non-standard) class method ---# `fromInt'. Unsurprisingly, the type `Int' is wired into the ---# compiler. - - lit.t4Hb :: _4 - _NI_ - lit.t4Hb = - let { - ds.d4Qz :: Int{-2i-} - _NI_ - ds.d4Qz = I#! 2# - } in fromInt.t4GS ds.d4Qz - ---# `I# 2#' is just the literal Int `2'; it reflects the fact that ---# GHC defines `data Int = I# Int#', where Int# is the primitive ---# unboxed type. (see relevant info about unboxed types elsewhere...) - ---# The `!' after `I#' indicates that this is a *saturated* ---# application of the `I#' data constructor (i.e., not partially ---# applied). - - skip2.t3Ja :: _4 -> [_4] - _NI_ - skip2.t3Ja = - \ m.r1H4 -> - let { ds.d4QQ :: [_4] - _NI_ - ds.d4QQ = - let { - ds.d4QY :: _4 - _NI_ - ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb - } in skip2.t3Ja ds.d4QY - } in - :! _4 m.r1H4 ds.d4QQ - - {- end CoRec -} - } in skip2.t3Ja -</verb></tscreen> - -(``It's just a simple functional language'' is an unregisterised -trademark of Peyton Jones Enterprises, plc.) - -%---------------------------------------------------------------------- |