Commit 05dfbd74 authored by simonmar's avatar simonmar
Browse files

[project @ 2001-02-16 17:35:01 by simonmar]

Today's doc hacking.
parent 8487ac4c
<Sect1 id="options-debugging"> <sect1 id="options-debugging">
<Title>Debugging the compiler <title>Debugging the compiler</title>
</Title>
<indexterm><primary>debugging options (for GHC)</primary></indexterm>
<Para>
<IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm> <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para>
</Para>
<Sect2 id="dumping-output">
<Para> <title>Dumping out compiler intermediate structures</title>
HACKER TERRITORY. HACKER TERRITORY.
(You were warned.) <indexterm><primary>dumping GHC intermediates</primary></indexterm>
</Para> <indexterm><primary>intermediate passes, output</primary></indexterm>
<variablelist>
<Sect2 id="dumping-output"> <varlistentry>
<Title>Dumping out compiler intermediate structures <term><option>-ddump-</option><replaceable>pass</replaceable></term>
</Title> <indexterm><primary><option>-ddump</option> options</primary></indexterm>
<listitem>
<Para> <para>Make a debugging dump after pass
<IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm> <literal>&lt;pass&gt;</literal> (may be common enough to need
<IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm> a short form&hellip;). You can get all of these at once
</Para> (<emphasis>lots</emphasis> of output) by using
<option>-ddump-all</option>, or most of them with
<Para> <option>-ddump-most</option>. Some of the most useful ones
<VariableList> are:</para>
<VarListEntry> <variablelist>
<Term><Option>-hi</Option>:</Term> <varlistentry>
<ListItem> <term><option>-ddump-parsed</option>:</term>
<Para> <listitem>
<IndexTerm><Primary>-hi option</Primary></IndexTerm> <para>parser output</para>
<Emphasis>Do</Emphasis> generate an interface file. This would normally be used in </listitem>
conjunction with <Option>-noC</Option>, which turns off interface generation; </varlistentry>
thus: <Option>-noC -hi</Option>.
</Para> <varlistentry>
</ListItem> <term><option>-ddump-rn</option>:</term>
</VarListEntry> <listitem>
<VarListEntry> <para>renamer output</para>
<Term><Option>-dshow-passes</Option>:</Term> </listitem>
<ListItem> </varlistentry>
<Para>
<IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm> <varlistentry>
Prints a message to stderr as each pass starts. Gives a warm but <term><option>-ddump-tc</option>:</term>
undoubtedly misleading feeling that GHC is telling you what's <listitem>
happening. <para>typechecker output</para>
</Para> </listitem>
</ListItem> </varlistentry>
</VarListEntry>
<VarListEntry> <varlistentry>
<Term><Option>-ddump-&lt;pass&gt;</Option>:</Term> <term><option>-ddump-types</option>:</term>
<ListItem> <listitem>
<Para> <para>Dump a type signature for each value defined at
<IndexTerm><Primary>-ddump-&lt;pass&gt; options</Primary></IndexTerm> the top level of the module. The list is sorted
Make a debugging dump after pass <Literal>&lt;pass&gt;</Literal> (may be common enough to alphabetically. Using <option>-dppr-debug</option>
need a short form&hellip;). You can get all of these at once (<Emphasis>lots</Emphasis> of dumps a type signature for all the imported and
output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>. system-defined things as well; useful for debugging the
Some of the most useful ones are: compiler.</para>
</Para> </listitem>
</varlistentry>
<Para>
<VariableList> <varlistentry>
<term><option>-ddump-deriv</option>:</term>
<VarListEntry> <listitem>
<Term><Option>-ddump-parsed</Option>:</Term> <para>derived instances</para>
<ListItem> </listitem>
<Para> </varlistentry>
parser output
</Para> <varlistentry>
</ListItem> <term><option>-ddump-ds</option>:</term>
</VarListEntry> <listitem>
<para>desugarer output</para>
<VarListEntry> </listitem>
<Term><Option>-ddump-rn</Option>:</Term> </varlistentry>
<ListItem>
<Para> <varlistentry>
renamer output <term><option>-ddump-spec</option>:</term>
</Para> <listitem>
</ListItem> <para>output of specialisation pass</para>
</VarListEntry> </listitem>
</varlistentry>
<VarListEntry>
<Term><Option>-ddump-tc</Option>:</Term> <varlistentry>
<ListItem> <term><option>-ddump-rules</option>:</term>
<Para> <listitem>
typechecker output <para>dumps all rewrite rules (including those generated
</Para> by the specialisation pass)</para>
</ListItem> </listitem>
</VarListEntry> </varlistentry>
<VarListEntry> <varlistentry>
<Term><Option>-ddump-types</Option>:</Term> <term><option>-ddump-simpl</option>:</term>
<ListItem> <listitem>
<Para> <para>simplifer output (Core-to-Core passes)</para>
Dump a type signature for each value defined at the top level </listitem>
of the module. The list is sorted alphabetically. </varlistentry>
Using <Option>-dppr-debug</Option> dumps a type signature for
all the imported and system-defined things as well; useful <varlistentry>
for debugging the compiler. <term><option>-ddump-inlinings</option>:</term>
</Para> <listitem>
</ListItem> <para>inlining info from the simplifier</para>
</VarListEntry> </listitem>
</varlistentry>
<VarListEntry>
<Term><Option>-ddump-deriv</Option>:</Term> <varlistentry>
<ListItem> <term><option>-ddump-usagesp</option>:</term>
<Para> <listitem>
derived instances <para>UsageSP inference pre-inf and output</para>
</Para> </listitem>
</ListItem> </varlistentry>
</VarListEntry>
<VarListEntry> <varlistentry>
<Term><Option>-ddump-ds</Option>:</Term> <term><option>-ddump-cpranal</option>:</term>
<ListItem> <listitem>
<Para> <para>CPR analyser output</para>
desugarer output </listitem>
</Para> </varlistentry>
</ListItem>
</VarListEntry> <varlistentry>
<VarListEntry> <term><option>-ddump-stranal</option>:</term>
<Term><Option>-ddump-spec</Option>:</Term> <listitem>
<ListItem> <para>strictness analyser output</para>
<Para> </listitem>
output of specialisation pass </varlistentry>
</Para>
</ListItem> <varlistentry>
</VarListEntry> <term><option>-ddump-cse</option>:</term>
<VarListEntry> <listitem>
<Term><Option>-ddump-rules</Option>:</Term> <para>CSE pass output</para>
<ListItem> </listitem>
<Para> </varlistentry>
dumps all rewrite rules (including those generated by the specialisation pass)
</Para> <varlistentry>
</ListItem> <term><option>-ddump-workwrap</option>:</term>
</VarListEntry> <listitem>
<VarListEntry> <para>worker/wrapper split output</para>
<Term><Option>-ddump-simpl</Option>:</Term> </listitem>
<ListItem> </varlistentry>
<Para>
simplifer output (Core-to-Core passes) <varlistentry>
</Para> <term><option>-ddump-occur-anal</option>:</term>
</ListItem> <listitem>
</VarListEntry> <para>`occurrence analysis' output</para>
<VarListEntry> </listitem>
<Term><Option>-ddump-usagesp</Option>:</Term> </varlistentry>
<ListItem>
<Para> <varlistentry>
UsageSP inference pre-inf and output <term><option>-ddump-sat</option>:</term>
</Para> <listitem>
</ListItem> <para>output of &ldquo;saturate&rdquo; pass</para>
</VarListEntry> </listitem>
<VarListEntry> </varlistentry>
<Term><Option>-ddump-cpranal</Option>:</Term>
<ListItem> <varlistentry>
<Para> <term><option>-ddump-stg</option>:</term>
CPR analyser output <listitem>
</Para> <para>output of STG-to-STG passes</para>
</ListItem> </listitem>
</VarListEntry> </varlistentry>
<VarListEntry>
<Term><Option>-ddump-stranal</Option>:</Term> <varlistentry>
<ListItem> <term><option>-ddump-absC</option>:</term>
<Para> <listitem>
strictness analyser output <para><emphasis>un</emphasis>flattened Abstract&nbsp;C</para>
</Para> </listitem>
</ListItem> </varlistentry>
</VarListEntry>
<VarListEntry> <varlistentry>
<Term><Option>-ddump-workwrap</Option>:</Term> <term><option>-ddump-flatC</option>:</term>
<ListItem> <listitem>
<Para> <para><emphasis>flattened</emphasis> Abstract&nbsp;C</para>
worker/wrapper split output </listitem>
</Para> </varlistentry>
</ListItem>
</VarListEntry> <varlistentry>
<VarListEntry> <term><option>-ddump-realC</option>:</term>
<Term><Option>-ddump-occur-anal</Option>:</Term> <listitem>
<ListItem> <para>same as what goes to the C compiler</para>
<Para> </listitem>
`occurrence analysis' output </varlistentry>
</Para>
</ListItem> <varlistentry>
</VarListEntry> <term><option>-ddump-stix</option>:</term>
<VarListEntry> <listitem>
<Term><Option>-ddump-stg</Option>:</Term> <para>native-code generator intermediate form</para>
<ListItem> </listitem>
<Para> </varlistentry>
output of STG-to-STG passes
</Para> <varlistentry>
</ListItem> <term><option>-ddump-asm</option>:</term>
</VarListEntry> <listitem>
<VarListEntry> <para>assembly language from the native-code generator</para>
<Term><Option>-ddump-absC</Option>:</Term> </listitem>
<ListItem> </varlistentry>
<Para>
<Emphasis>un</Emphasis>flattened Abstract&nbsp;C <varlistentry>
</Para> <term><option>-ddump-bcos</option>:</term>
</ListItem> <listitem>
</VarListEntry> <para>byte code compiler output</para>
<VarListEntry> </listitem>
<Term><Option>-ddump-flatC</Option>:</Term> </varlistentry>
<ListItem>
<Para> <varlistentry>
<Emphasis>flattened</Emphasis> Abstract&nbsp;C <term><option>-ddump-foreign</option>:</term>
</Para> <listitem>
</ListItem> <para>dump foreign export stubs</para>
</VarListEntry> </listitem>
<VarListEntry> </varlistentry>
<Term><Option>-ddump-realC</Option>:</Term>
<ListItem> </variablelist>
<Para>
same as what goes to the C compiler <indexterm><primary><option>-ddump-absC</option></primary></indexterm>
</Para> <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
</ListItem> <indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
</VarListEntry> <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
<VarListEntry>
<Term><Option>-ddump-asm</Option>:</Term> <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
<ListItem> <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
<Para> <indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
assembly language from the native-code generator <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
</Para> <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
</ListItem> <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
</VarListEntry> <indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
</VariableList> <indexterm><primary><option>-ddump-realC</option></primary></indexterm>
<IndexTerm><Primary>-ddump-all option</Primary></IndexTerm> <indexterm><primary><option>-ddump-rn</option></primary></indexterm>
<IndexTerm><Primary>-ddump-most option</Primary></IndexTerm> <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
<IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm> <indexterm><primary><option>-ddump-sat</option></primary></indexterm>
<IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm> <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
<IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm> <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
<IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm> <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
<IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm> <indexterm><primary><option>-ddump-stix</option></primary></indexterm>
<IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm> <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
<IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm> <indexterm><primary><option>-ddump-tc</option></primary></indexterm>
<IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm> <indexterm><primary><option>-ddump-usagesp</option></primary></indexterm>
<IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm> <indexterm><primary><option>-ddump-workwrap</option></primary></indexterm>
<IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm> </listitem>
<IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm> </varlistentry>
<IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm> <varlistentry>
<IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm> <term><option>-dverbose-core2core</option></term>
<IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm> <term><option>-dverbose-stg2stg</option></term>
<IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm> <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
<IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm> <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
</Para> <listitem>
</ListItem> <para>Show the output of the intermediate Core-to-Core and
</VarListEntry> STG-to-STG passes, respectively. (<emphasis>Lots</emphasis>
<VarListEntry> of output!) So: when we're really desperate:</para>
<Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
<ListItem> <Screen>
<Para>
<IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
<IndexTerm><Primary>-dverbose-stg option</Primary></IndexTerm>
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:
<Screen>
% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
</Screen> </Screen>
</Para> </listitem>
</ListItem> </varlistentry>
</VarListEntry>
<VarListEntry> <varlistentry>
<Term><Option>-ddump-simpl-iterations</Option>:</Term> <term><option>-ddump-simpl-iterations</option>:</term>
<ListItem> <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
<Para> <listitem>
<IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm> <para>Show the output of each <emphasis>iteration</emphasis>
Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of of the simplifier (each run of the simplifier has a maximum
the simplifier has a maximum number of iterations, normally 4). Used number of iterations, normally 4). Used when even
when even <Option>-dverbose-simpl</Option> doesn't cut it. <option>-dverbose-simpl</option> doesn't cut it.</para>
</Para> </listitem>
</ListItem> </varlistentry>
</VarListEntry>
<VarListEntry> <varlistentry>
<Term><Option>-dppr-&lcub;user,debug</Option>&rcub;:</Term> <term><option>-dppr-debug</option></term>
<ListItem> <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
<Para> <listitem>
<IndexTerm><Primary>-dppr-user option</Primary></IndexTerm> <para>Debugging output is in one of several
<IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm> &ldquo;styles.&rdquo; Take the printing of types, for
Debugging output is in one of several &ldquo;styles.&rdquo; Take the printing example. In the &ldquo;user&rdquo; style (the default), the
of types, for example. In the &ldquo;user&rdquo; style, the compiler's internal compiler's internal ideas about types are presented in
ideas about types are presented in Haskell source-level syntax, Haskell source-level syntax, insofar as possible. In the
insofar as possible. In the &ldquo;debug&rdquo; style (which is the default for &ldquo;debug&rdquo; style (which is the default for
debugging output), the types are printed in with debugging output), the types are printed in with explicit
explicit foralls, and variables have their unique-id attached (so you foralls, and variables have their unique-id attached (so you
can check for things that look the same but aren't). can check for things that look the same but aren't). This
</Para> flag makes debugging output appear in the more verbose debug
</ListItem> style.</para>
</VarListEntry> </listitem>
<VarListEntry> </varlistentry>
<Term><Option>-ddump-simpl-stats</Option>:</Term>
<ListItem> <varlistentry>
<Para> <term><option>-dppr-user-length</option></term>
<IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm> <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
Dump statistics about how many of each kind <listitem>
of transformation too place. If you add <Option>-dppr-debug</Option> you get more detailed information. <para>In error messages, expressions are printed to a
</Para> certain &ldquo;depth&rdquo;, with subexpressions beyond the
</ListItem> depth replaced by ellipses. This flag sets the
</VarListEntry> depth.</para>
<VarListEntry> </listitem>
<Term><Option>-ddump-raw-asm</Option>:</Term> </varlistentry>
<ListItem>
<Para> <varlistentry>
<IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm> <term><option>-ddump-simpl-stats</option></term>
Dump out the assembly-language stuff, before the &ldquo;mangler&rdquo; gets it. <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
</Para> <listitem>
</ListItem> <para>Dump statistics about how many of each kind of
</VarListEntry> transformation too place. If you add
<VarListEntry> <option>-dppr-debug</option> you get more detailed
<Term><Option>-ddump-rn-trace</Option>:</Term> information.</para>
<ListItem> </listitem>
<Para> </varlistentry>
<IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
Make the renamer be *real* chatty about what it is upto. <varlistentry>
</Para> <term><option>-ddump-rn-trace</option></term>
</ListItem> <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
</VarListEntry> <listitem>
<VarListEntry> <para>Make the renamer be *real* chatty about what it is
<Term><Option>-dshow-rn-stats</Option>:</Term> upto.</para>
<ListItem> </listitem>
<Para> </varlistentry>
<IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
Print out summary of what kind of information the renamer had to bring <varlistentry>
in. <term><option>-ddump-rn-stats</option></term>
</Para> <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
</ListItem> <listitem>
</VarListEntry> <para>Print out summary of what kind of information the renamer
<VarListEntry> had to bring in.</para>
<Term><Option>-dshow-unused-imports</Option>:</Term> </listitem>
<ListItem> </varlistentry>
<Para>
<IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm> <varlistentry>
Have the renamer report what imports does not contribute. <term><option>-dshow-unused-imports</option></term>
</Para> <indexterm><primary><option>-dshow-unused-imports</option></primary></indexterm>
</ListItem> <listitem>
</VarListEntry> <para>Have the renamer report what imports does not
</VariableList> contribute.</para>
</Para> </listitem>
</varlistentry>
</Sect2> </variablelist>
</sect2>
<Sect2 id="checking-consistency">
<Title>Checking for consistency <sect2 id="checking-consistency">
</Title> <title>Checking for consistency</title>
<Para> <indexterm><primary>consistency checks</primary></indexterm>
<IndexTerm><Primary>consistency checks</Primary></IndexTerm> <indexterm><primary>lint</primary></indexterm>
<IndexTerm><Primary>lint</Primary></IndexTerm>
</Para> <variablelist>
<Para> <varlistentry>
<VariableList> <term><option>-dcore-lint</option></term>
<indexterm><primary><option>-dcore-lint</option></primary></indexterm>
<VarListEntry> <listitem>
<Term><Option>-dcore-lint</Option>:</Term> <para>Turn on heavyweight intra-pass sanity-checking within
<ListItem> GHC, at Core level. (It checks GHC's sanity, not yours.)</para>
<Para>