diff options
Diffstat (limited to 'docs/users_guide/debugging.xml')
| -rw-r--r-- | docs/users_guide/debugging.xml | 681 |
1 files changed, 0 insertions, 681 deletions
diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml deleted file mode 100644 index fd12e1d79a..0000000000 --- a/docs/users_guide/debugging.xml +++ /dev/null @@ -1,681 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<sect1 id="options-debugging"> - <title>Debugging the compiler</title> - - <indexterm><primary>debugging options (for GHC)</primary></indexterm> - - <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para> - - <sect2 id="dumping-output"> - <title>Dumping out compiler intermediate structures</title> - - <indexterm><primary>dumping GHC intermediates</primary></indexterm> - <indexterm><primary>intermediate passes, output</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-ddump-</option><replaceable>pass</replaceable> - <indexterm><primary><option>-ddump</option> options</primary></indexterm> - </term> - <listitem> - <para>Make a debugging dump after pass - <literal><pass></literal> (may be common enough to need - a short form…). You can get all of these at once - (<emphasis>lots</emphasis> of output) by using - <option>-v5</option>, or most of them with - <option>-v4</option>. You can prevent them from clogging up - your standard output by passing <option>-ddump-to-file</option>. - Some of the most useful ones are:</para> - - <variablelist> - <varlistentry> - <term> - <option>-ddump-parsed</option>: - <indexterm><primary><option>-ddump-parsed</option></primary></indexterm> - </term> - <listitem> - <para>parser output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn</option>: - <indexterm><primary><option>-ddump-rn</option></primary></indexterm> - </term> - <listitem> - <para>renamer output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-tc</option>: - <indexterm><primary><option>-ddump-tc</option></primary></indexterm> - </term> - <listitem> - <para>typechecker output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-splices</option>: - <indexterm><primary><option>-ddump-splices</option></primary></indexterm> - </term> - <listitem> - <para>Dump Template Haskell expressions that we splice in, - and what Haskell code the expression evaluates to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-types</option>: - <indexterm><primary><option>-ddump-types</option></primary></indexterm> - </term> - <listitem> - <para>Dump a type signature for each value defined at - the top level of the module. The list is sorted - alphabetically. Using <option>-dppr-debug</option> - dumps a type signature for all the imported and - system-defined things as well; useful for debugging the - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-deriv</option>: - <indexterm><primary><option>-ddump-deriv</option></primary></indexterm> - </term> - <listitem> - <para>derived instances</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-ds</option>: - <indexterm><primary><option>-ddump-ds</option></primary></indexterm> - </term> - <listitem> - <para>desugarer output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-spec</option>: - <indexterm><primary><option>-ddump-spec</option></primary></indexterm> - </term> - <listitem> - <para>output of specialisation pass</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rules</option>: - <indexterm><primary><option>-ddump-rules</option></primary></indexterm> - </term> - <listitem> - <para>dumps all rewrite rules specified in this module; - see <xref linkend="controlling-rules"/>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rule-firings</option>: - <indexterm><primary><option>-ddump-rule-firings</option></primary></indexterm> - </term> - <listitem> - <para>dumps the names of all rules that fired in this module</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rule-rewrites</option>: - <indexterm><primary><option>-ddump-rule-rewrites</option></primary></indexterm> - </term> - <listitem> - <para>dumps detailed information about all rules that fired in - this module - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-vect</option>: - <indexterm><primary><option>-ddump-vect</option></primary></indexterm> - </term> - <listitem> - <para>dumps the output of the vectoriser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl</option>: - <indexterm><primary><option>-ddump-simpl</option></primary></indexterm> - </term> - <listitem> - <para>simplifier output (Core-to-Core passes)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-inlinings</option>: - <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm> - </term> - <listitem> - <para>inlining info from the simplifier</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-stranal</option>: - <indexterm><primary><option>-ddump-stranal</option></primary></indexterm> - </term> - <listitem> - <para>strictness analyser output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-strsigs</option>: - <indexterm><primary><option>-ddump-strsigs</option></primary></indexterm> - </term> - <listitem> - <para>strictness signatures</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-cse</option>: - <indexterm><primary><option>-ddump-cse</option></primary></indexterm> - </term> - <listitem> - <para>CSE pass output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-worker-wrapper</option>: - <indexterm><primary><option>-ddump-worker-wrapper</option></primary></indexterm> - </term> - <listitem> - <para>worker/wrapper split output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-occur-anal</option>: - <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm> - </term> - <listitem> - <para>`occurrence analysis' output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-prep</option>: - <indexterm><primary><option>-ddump-prep</option></primary></indexterm> - </term> - <listitem> - <para>output of core preparation pass</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-stg</option>: - <indexterm><primary><option>-ddump-stg</option></primary></indexterm> - </term> - <listitem> - <para>output of STG-to-STG passes</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-cmm</option>: - <indexterm><primary><option>-ddump-cmm</option></primary></indexterm> - </term> - <listitem> - <para>Print the C-- code out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-opt-cmm</option>: - <indexterm><primary><option>-ddump-opt-cmm</option></primary></indexterm> - </term> - <listitem> - <para>Dump the results of C-- to C-- optimising passes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-asm</option>: - <indexterm><primary><option>-ddump-asm</option></primary></indexterm> - </term> - <listitem> - <para>assembly language from the - <link linkend="native-code-gen">native code generator</link></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-llvm</option>: - <indexterm><primary><option>-ddump-llvm</option></primary></indexterm> - </term> - <listitem> - <para>LLVM code from the <link linkend="llvm-code-gen">LLVM code - generator</link></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-bcos</option>: - <indexterm><primary><option>-ddump-bcos</option></primary></indexterm> - </term> - <listitem> - <para>byte code compiler output</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-foreign</option>: - <indexterm><primary><option>-ddump-foreign</option></primary></indexterm> - </term> - <listitem> - <para>dump foreign export stubs</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl-iterations</option>: - <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm> - </term> - <listitem> - <para>Show the output of each <emphasis>iteration</emphasis> - of the simplifier (each run of the simplifier has a maximum - number of iterations, normally 4). This outputs even more information - than <option>-ddump-simpl-phases</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-simpl-stats</option> - <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm> - </term> - <listitem> - <para>Dump statistics about how many of each kind of - transformation too place. If you add - <option>-dppr-debug</option> you get more detailed - information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-if-trace</option> - <indexterm><primary><option>-ddump-if-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the interface loader be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-tc-trace</option> - <indexterm><primary><option>-ddump-tc-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the type checker be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-vt-trace</option> - <indexterm><primary><option>-ddump-tv-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the vectoriser be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn-trace</option> - <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm> - </term> - <listitem> - <para>Make the renamer be *real* chatty about what it is - up to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-rn-stats</option> - <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm> - </term> - <listitem> - <para>Print out summary of what kind of information the renamer - had to bring in.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dverbose-core2core</option> - <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm> - </term> - <term> - <option>-dverbose-stg2stg</option> - <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm> - </term> - <listitem> - <para>Show the output of the intermediate Core-to-Core and - STG-to-STG passes, respectively. (<emphasis>Lots</emphasis> - of output!) So: when we're really desperate:</para> - - <screen> -% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs -</screen> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dshow-passes</option> - <indexterm><primary><option>-dshow-passes</option></primary></indexterm> - </term> - <listitem> - <para>Print out each pass name as it happens.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ddump-core-stats</option> - <indexterm><primary><option>-ddump-core-stats</option></primary></indexterm> - </term> - <listitem> - <para>Print a one-line summary of the size of the Core program - at the end of the optimisation pipeline.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dfaststring-stats</option> - <indexterm><primary><option>-dfaststring-stats</option></primary></indexterm> - </term> - <listitem> - <para>Show statistics for the usage of fast strings by the - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-debug</option> - <indexterm><primary><option>-dppr-debug</option></primary></indexterm> - </term> - <listitem> - <para>Debugging output is in one of several - “styles.” Take the printing of types, for - example. In the “user” style (the default), 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). This - flag makes debugging output appear in the more verbose debug - style.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="formatting dumps"> - <title>Formatting dumps</title> - - <indexterm><primary>formatting dumps</primary></indexterm> - - <variablelist> - <varlistentry> - <term> - <option>-dppr-user-length</option> - <indexterm><primary><option>-dppr-user-length</option></primary></indexterm> - </term> - <listitem> - <para>In error messages, expressions are printed to a - certain “depth”, with subexpressions beyond the - depth replaced by ellipses. This flag sets the - depth. Its default value is 5.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-colsNNN</option> - <indexterm><primary><option>-dppr-colsNNN</option></primary></indexterm> - </term> - <listitem> - <para>Set the width of debugging output. Use this if your code is wrapping too much. - For example: <option>-dppr-cols200</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dppr-case-as-let</option> - <indexterm><primary><option>-dppr-case-as-let</option></primary></indexterm> - </term> - <listitem> - <para>Print single alternative case expressions as though they were strict - let expressions. This is helpful when your code does a lot of unboxing.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dno-debug-output</option> - <indexterm><primary><option>-dno-debug-output</option></primary></indexterm> - </term> - <listitem> - <para>Suppress any unsolicited debugging output. When GHC - has been built with the <literal>DEBUG</literal> option it - occasionally emits debug output of interest to developers. - The extra output can confuse the testing framework and - cause bogus test failures, so this flag is provided to - turn it off.</para> - </listitem> - </varlistentry> - </variablelist> - - </sect2> - - <sect2 id="suppression"> - <title>Suppressing unwanted information</title> - - <indexterm><primary>suppression</primary></indexterm> - - Core dumps contain a large amount of information. Depending on what you are doing, not all of it will be useful. - Use these flags to suppress the parts that you are not interested in. - - <variablelist> - <varlistentry> - <term> - <option>-dsuppress-all</option> - <indexterm><primary><option>-dsuppress-all</option></primary></indexterm> - </term> - <listitem> - <para>Suppress everything that can be suppressed, except for unique ids as this often - makes the printout ambiguous. If you just want to see the overall structure of - the code, then start here.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-uniques</option> - <indexterm><primary><option>-dsuppress-uniques</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of uniques. This may make - the printout ambiguous (e.g. unclear where an occurrence of 'x' is bound), but - it makes the output of two compiler runs have many fewer gratuitous differences, - so you can realistically apply <command>diff</command>. Once <command>diff</command> - has shown you where to look, you can try again without <option>-dsuppress-uniques</option></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-idinfo</option> - <indexterm><primary><option>-dsuppress-idinfo</option></primary></indexterm> - </term> - <listitem> - <para>Suppress extended information about identifiers where they are bound. This includes - strictness information and inliner templates. Using this flag can cut the size - of the core dump in half, due to the lack of inliner templates</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-unfoldings</option> - <indexterm><primary><option>-dsuppress-unfoldings</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of the stable unfolding of a variable at its binding site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-module-prefixes</option> - <indexterm><primary><option>-dsuppress-module-prefixes</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of module qualification prefixes. - This is the <constant>Data.List</constant> in <constant>Data.List.length</constant>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-type-signatures</option> - <indexterm><primary><option>-dsuppress-type-signatures</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type signatures.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-type-applications</option> - <indexterm><primary><option>-dsuppress-type-applications</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type applications.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dsuppress-coercions</option> - <indexterm><primary><option>-dsuppress-coercions</option></primary></indexterm> - </term> - <listitem> - <para>Suppress the printing of type coercions.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="checking-consistency"> - <title>Checking for consistency</title> - - <indexterm><primary>consistency checks</primary></indexterm> - <indexterm><primary>lint</primary></indexterm> - - <variablelist> - - <varlistentry> - <term> - <option>-dcore-lint</option> - <indexterm><primary><option>-dcore-lint</option></primary></indexterm> - </term> - <listitem> - <para>Turn on heavyweight intra-pass sanity-checking within - GHC, at Core level. (It checks GHC's sanity, not yours.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dstg-lint</option>: - <indexterm><primary><option>-dstg-lint</option></primary></indexterm> - </term> - <listitem> - <para>Ditto for STG level. (NOTE: currently doesn't work).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dcmm-lint</option>: - <indexterm><primary><option>-dcmm-lint</option></primary></indexterm> - </term> - <listitem> - <para>Ditto for C-- level.</para> - </listitem> - </varlistentry> - - </variablelist> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; End: *** - --> |