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">
<Title>Debugging the compiler
</Title>
<Para>
<IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm>
</Para>
<Para>
HACKER TERRITORY. HACKER TERRITORY.
(You were warned.)
</Para>
<Sect2 id="dumping-output">
<Title>Dumping out compiler intermediate structures
</Title>
<Para>
<IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm>
<IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm>
</Para>
<Para>
<VariableList>
<VarListEntry>
<Term><Option>-hi</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-hi option</Primary></IndexTerm>
<Emphasis>Do</Emphasis> generate an interface file. This would normally be used in
conjunction with <Option>-noC</Option>, which turns off interface generation;
thus: <Option>-noC -hi</Option>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dshow-passes</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
Prints a message to stderr as each pass starts. Gives a warm but
undoubtedly misleading feeling that GHC is telling you what's
happening.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-&lt;pass&gt;</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-&lt;pass&gt; options</Primary></IndexTerm>
Make a debugging dump after pass <Literal>&lt;pass&gt;</Literal> (may be common enough to
need a short form&hellip;). You can get all of these at once (<Emphasis>lots</Emphasis> of
output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>.
Some of the most useful ones are:
</Para>
<Para>
<VariableList>
<VarListEntry>
<Term><Option>-ddump-parsed</Option>:</Term>
<ListItem>
<Para>
parser output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-rn</Option>:</Term>
<ListItem>
<Para>
renamer output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-tc</Option>:</Term>
<ListItem>
<Para>
typechecker output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-types</Option>:</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>:</Term>
<ListItem>
<Para>
derived instances
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-ds</Option>:</Term>
<ListItem>
<Para>
desugarer output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-spec</Option>:</Term>
<ListItem>
<Para>
output of specialisation pass
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-rules</Option>:</Term>
<ListItem>
<Para>
dumps all rewrite rules (including those generated by the specialisation pass)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-simpl</Option>:</Term>
<ListItem>
<Para>
simplifer output (Core-to-Core passes)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-usagesp</Option>:</Term>
<ListItem>
<Para>
UsageSP inference pre-inf and output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-cpranal</Option>:</Term>
<ListItem>
<Para>
CPR analyser output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-stranal</Option>:</Term>
<ListItem>
<Para>
strictness analyser output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-workwrap</Option>:</Term>
<ListItem>
<Para>
worker/wrapper split output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-occur-anal</Option>:</Term>
<ListItem>
<Para>
`occurrence analysis' output
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-stg</Option>:</Term>
<ListItem>
<Para>
output of STG-to-STG passes
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-absC</Option>:</Term>
<ListItem>
<Para>
<Emphasis>un</Emphasis>flattened Abstract&nbsp;C
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-flatC</Option>:</Term>
<ListItem>
<Para>
<Emphasis>flattened</Emphasis> Abstract&nbsp;C
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-realC</Option>:</Term>
<ListItem>
<Para>
same as what goes to the C compiler
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-asm</Option>:</Term>
<ListItem>
<Para>
assembly language from the native-code generator
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm>
<IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
<ListItem>
<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>
<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></term>
<indexterm><primary><option>-ddump</option> options</primary></indexterm>
<listitem>
<para>Make a debugging dump after pass
<literal>&lt;pass&gt;</literal> (may be common enough to need
a short form&hellip;). You can get all of these at once
(<emphasis>lots</emphasis> of output) by using
<option>-ddump-all</option>, or most of them with
<option>-ddump-most</option>. Some of the most useful ones
are:</para>
<variablelist>
<varlistentry>
<term><option>-ddump-parsed</option>:</term>
<listitem>
<para>parser output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-rn</option>:</term>
<listitem>
<para>renamer output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-tc</option>:</term>
<listitem>
<para>typechecker output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-types</option>:</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>:</term>
<listitem>
<para>derived instances</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-ds</option>:</term>
<listitem>
<para>desugarer output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-spec</option>:</term>
<listitem>
<para>output of specialisation pass</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-rules</option>:</term>
<listitem>
<para>dumps all rewrite rules (including those generated
by the specialisation pass)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-simpl</option>:</term>
<listitem>
<para>simplifer output (Core-to-Core passes)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-inlinings</option>:</term>
<listitem>
<para>inlining info from the simplifier</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-usagesp</option>:</term>
<listitem>
<para>UsageSP inference pre-inf and output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-cpranal</option>:</term>
<listitem>
<para>CPR analyser output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-stranal</option>:</term>
<listitem>
<para>strictness analyser output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-cse</option>:</term>
<listitem>
<para>CSE pass output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-workwrap</option>:</term>
<listitem>
<para>worker/wrapper split output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-occur-anal</option>:</term>
<listitem>
<para>`occurrence analysis' output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-sat</option>:</term>
<listitem>
<para>output of &ldquo;saturate&rdquo; pass</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-stg</option>:</term>
<listitem>
<para>output of STG-to-STG passes</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-absC</option>:</term>
<listitem>
<para><emphasis>un</emphasis>flattened Abstract&nbsp;C</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-flatC</option>:</term>
<listitem>
<para><emphasis>flattened</emphasis> Abstract&nbsp;C</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-realC</option>:</term>
<listitem>
<para>same as what goes to the C compiler</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-stix</option>:</term>
<listitem>
<para>native-code generator intermediate form</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-asm</option>:</term>
<listitem>
<para>assembly language from the native-code generator</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-bcos</option>:</term>
<listitem>
<para>byte code compiler output</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ddump-foreign</option>:</term>
<listitem>
<para>dump foreign export stubs</para>
</listitem>
</varlistentry>
</variablelist>
<indexterm><primary><option>-ddump-absC</option></primary></indexterm>
<indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
<indexterm><primary><option>-ddump-cpranal</option></primary></indexterm>
<indexterm><primary><option>-ddump-cse</option></primary></indexterm>
<indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
<indexterm><primary><option>-ddump-ds</option></primary></indexterm>
<indexterm><primary><option>-ddump-flatC</option></primary></indexterm>
<indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
<indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
<indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
<indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
<indexterm><primary><option>-ddump-realC</option></primary></indexterm>
<indexterm><primary><option>-ddump-rn</option></primary></indexterm>
<indexterm><primary><option>-ddump-rules</option></primary></indexterm>
<indexterm><primary><option>-ddump-sat</option></primary></indexterm>
<indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
<indexterm><primary><option>-ddump-spec</option></primary></indexterm>
<indexterm><primary><option>-ddump-stg</option></primary></indexterm>
<indexterm><primary><option>-ddump-stix</option></primary></indexterm>
<indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
<indexterm><primary><option>-ddump-tc</option></primary></indexterm>
<indexterm><primary><option>-ddump-usagesp</option></primary></indexterm>
<indexterm><primary><option>-ddump-workwrap</option></primary></indexterm>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-dverbose-core2core</option></term>
<term><option>-dverbose-stg2stg</option></term>
<indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
<indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
<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-simpl -dcore-lint Foo.hs
</Screen>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-simpl-iterations</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm>
Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of
the simplifier has a maximum number of iterations, normally 4). Used
when even <Option>-dverbose-simpl</Option> doesn't cut it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dppr-&lcub;user,debug</Option>&rcub;:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dppr-user option</Primary></IndexTerm>
<IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm>
Debugging output is in one of several &ldquo;styles.&rdquo; Take the printing
of types, for example. In the &ldquo;user&rdquo; style, the compiler's internal
ideas about types are presented in Haskell source-level syntax,
insofar as possible. In the &ldquo;debug&rdquo; 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).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-simpl-stats</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm>
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-raw-asm</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm>
Dump out the assembly-language stuff, before the &ldquo;mangler&rdquo; gets it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-ddump-rn-trace</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
Make the renamer be *real* chatty about what it is upto.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dshow-rn-stats</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
Print out summary of what kind of information the renamer had to bring
in.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dshow-unused-imports</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
Have the renamer report what imports does not contribute.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect2>
<Sect2 id="checking-consistency">
<Title>Checking for consistency
</Title>
<Para>
<IndexTerm><Primary>consistency checks</Primary></IndexTerm>
<IndexTerm><Primary>lint</Primary></IndexTerm>
</Para>
<Para>
<VariableList>
<VarListEntry>
<Term><Option>-dcore-lint</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
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>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
Ditto for STG level.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Option>-dusagesp-lint</Option>:</Term>
<ListItem>
<Para>
<IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
Turn on checks around UsageSP inference (<Option>-fusagesp</Option>). 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.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect2>