[project @ 2000-04-03 12:47:08 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / gone_wrong.sgml

<Chapter id="wrong">
<Title>What to do when something goes wrong
</Title>

<Para>
<IndexTerm><Primary>problems</Primary></IndexTerm>
</Para>

<Para>
If you still have a problem after consulting this section, then you
may have found a <Emphasis>bug</Emphasis>&mdash;please report it!  See <XRef LinkEnd="bug-reports"> for a
list of things we'd like to know about your bug.  If in doubt, send a
report&mdash;we love mail from irate users :-!
</Para>

<Para>
(<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
Haskell's shortcomings vs.&nbsp;the Haskell language definition, may also
be of interest.)
</Para>

<Sect1 id="wrong-compiler">
<Title>When the compiler &ldquo;does the wrong thing&rdquo;
</Title>

<Para>
<IndexTerm><Primary>compiler problems</Primary></IndexTerm>
<IndexTerm><Primary>problems with the compiler</Primary></IndexTerm>
</Para>

<Para>
<VariableList>

<VarListEntry>
<Term>&ldquo;Help! The compiler crashed (or `panic'd)!&rdquo;</Term>
<ListItem>
<Para>
These events are <Emphasis>always</Emphasis> bugs in the GHC system&mdash;please report them.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;The compiler ran out of heap (or stack) when compiling itself!&rdquo;</Term>
<ListItem>
<Para>
It happens.  We try to supply reasonable <Option>-H&lt;n&gt;</Option> flags for
<Filename>ghc/compiler/</Filename> and <Filename>ghc/lib/</Filename>, but GHC's memory consumption
can vary by platform (e.g., on a 64-bit machine).
</Para>

<Para>
Just say <Command>make all EXTRA&lowbar;HC&lowbar;OPTS=-H&lt;a reasonable number&gt;</Command> and see
how you get along.
</Para>

<Para>
Note that this is less likely to happen if you are compiling with GHC
4.00 or later, since the introduction of the dynamically expanding
heap.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;The compiler died with a pattern-matching error.&rdquo;</Term>
<ListItem>
<Para>
This is a bug just as surely as a &ldquo;panic.&rdquo; Please report it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;This is a terrible error message.&rdquo;</Term>
<ListItem>
<Para>
If you think that GHC could have produced a better error message,
please report it as a bug.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;What about these `trace' messages from GHC?&rdquo;</Term>
<ListItem>
<Para>
Almost surely not a problem.  About some specific cases&hellip;
<VariableList>

<VarListEntry>
<Term>Simplifier still going after N iterations:</Term>
<ListItem>
<Para>
Sad, but harmless.  You can change the number with a
<Option>-fmax-simplifier-iterations&lt;N&gt;</Option><IndexTerm><Primary>-fmax-simplifier-iterations&lt;N&gt; option</Primary></IndexTerm> option (no space);
and you can see what actions took place in each iteration by
turning on the <Option>-fshow-simplifier-progress</Option>
<IndexTerm><Primary>-fshow-simplifier-progress option</Primary></IndexTerm> option.
</Para>

<Para>
If the simplifier definitely seems to be &ldquo;looping,&rdquo; please report
it.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;What about this warning from the C compiler?&rdquo;</Term>
<ListItem>
<Para>
For example: &ldquo;&hellip;warning: `Foo' declared `static' but never defined.&rdquo;
Unsightly, but shouldn't be a problem.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Sensitivity to <Filename>.hi</Filename> interface files:</Term>
<ListItem>
<Para>
GHC is very sensitive about interface files.  For example, if it picks
up a non-standard <Filename>Prelude.hi</Filename> file, pretty terrible things will
happen.  If you turn on
<Option>-fno-implicit-prelude</Option><IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>, the
compiler will almost surely die, unless you know what you are doing.
</Para>

<Para>
Furthermore, as sketched below, you may have big problems
running programs compiled using unstable interfaces.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;I think GHC is producing incorrect code&rdquo;:</Term>
<ListItem>
<Para>
Unlikely :-) A useful be-more-paranoid option to give to GHC is
<Option>-dcore-lint</Option><IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>; this causes a &ldquo;lint&rdquo;
pass to check for errors (notably type errors) after each Core-to-Core
transformation pass.  We run with <Option>-dcore-lint</Option> on all the time; it
costs about 5&percnt; in compile time.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;Why did I get a link error?&rdquo;</Term>
<ListItem>
<Para>
If the linker complains about not finding <Literal>&lowbar;&lt;something&gt;&lowbar;fast</Literal>, then
something is inconsistent: you probably didn't compile modules in the
proper dependency order.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;What's a `consistency error'?&rdquo;</Term>
<ListItem>
<Para>
(These are reported just after linking your program.)
</Para>

<Para>
You tried to link incompatible object files, e.g., normal ones
(registerised, Appel garbage-collector) with profiling ones (two-space
collector).  Or those compiled by a previous version of GHC
with an incompatible newer version.
</Para>

<Para>
If you run <Command>nm -o *.o &verbar; egrep 't (cc&verbar;hsc)\.'</Command> (or, on
unregisterised files: <Command>what *.o</Command>), you'll see all the consistency
tags/strings in your object files.  They must all be the same!
(ToDo: tell you what they mean&hellip;)
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;Is this line number right?&rdquo;</Term>
<ListItem>
<Para>
On this score, GHC usually does pretty well, especially
if you &ldquo;allow&rdquo; it to be off by one or two.  In the case of an
instance or class declaration, the line number
may only point you to the declaration, not to a specific method.
</Para>

<Para>
Please report line-number errors that you find particularly unhelpful.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

</Sect1>

<Sect1 id="wrong-compilee">
<Title>When your program &ldquo;does the wrong thing&rdquo;
</Title>

<Para>
<IndexTerm><Primary>problems running your program</Primary></IndexTerm>
</Para>

<Para>
(For advice about overly slow or memory-hungry Haskell programs,
please see <XRef LinkEnd="sooner-faster-quicker">).
</Para>

<Para>
<VariableList>

<VarListEntry>
<Term>&ldquo;Help! My program crashed!&rdquo;</Term>
<ListItem>
<Para>
(e.g., a `segmentation fault' or `core dumped')
<IndexTerm><Primary>segmentation fault</Primary></IndexTerm>
</Para>

<Para>
If your program has no <Function>&lowbar;ccall&lowbar;</Function>s/<Function>&lowbar;casm&lowbar;</Function>s in it, then a crash is
always a BUG in the GHC system, except in one case: If your program is
made of several modules, each module must have been compiled after any
modules on which it depends (unless you use <Filename>.hi-boot</Filename> files, in which
case these <Emphasis>must</Emphasis> be correct with respect to the module source). 
</Para>

<Para>
For example, if an interface is lying about the type of an imported
value then GHC may well generate duff code for the importing module.
<Emphasis>This applies to pragmas inside interfaces too!</Emphasis>  If the pragma is
lying (e.g., about the &ldquo;arity&rdquo; of a value), then duff code may result.
Furthermore, arities may change even if types do not.
</Para>

<Para>
In short, if you compile a module and its interface changes, then all
the modules that import that interface <Emphasis>must</Emphasis> be re-compiled.
</Para>

<Para>
A useful option to alert you when interfaces change is
<Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>.  It will run <Command>diff</Command> on the
changed interface file, before and after, when applicable.
</Para>

<Para>
If you are using <Command>make</Command>, a useful tool to make sure that every module
<Emphasis>is</Emphasis> up-to-date with respect to its imported interfaces is
<Command>mkdependHS</Command> (which comes with GHC).  Please see <XRef LinkEnd="mkdependHS">.
</Para>

<Para>
If you are down to your last-compile-before-a-bug-report, we would
recommend that you add a <Option>-dcore-lint</Option> option (for extra checking) to your compilation options.
</Para>

<Para>
So, before you report a bug because of a core dump, you should probably:

<Screen>
% rm *.o        # scrub your object files
% make my_prog  # re-make your program; use -hi-diffs to highlight changes;
                # as mentioned above, use -dcore-lint to be more paranoid
% ./my_prog ... # retry...
</Screen>

</Para>

<Para>
Of course, if you have <Function>&lowbar;ccall&lowbar;</Function>s/<Function>&lowbar;casm&lowbar;</Function>s in your program then all
bets are off, because you can trash the heap, the stack, or whatever.
</Para>

<Para>
If you are interested in hard-core debugging of a crashing
GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;My program entered an `absent' argument.&rdquo;</Term>
<ListItem>
<Para>
This is definitely caused by a bug in GHC. Please report it.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>&ldquo;What's with this `arithmetic (or `floating') exception' &rdquo;?</Term>
<ListItem>
<Para>
<Literal>Int</Literal>, <Literal>Float</Literal>, and <Literal>Double</Literal> arithmetic is <Emphasis>unchecked</Emphasis>.
Overflows, underflows and loss of precision are either silent or
reported as an exception by the operating system (depending on the
architecture).  Divide-by-zero <Emphasis>may</Emphasis> cause an untrapped
exception (please report it if it does).
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

</Sect1>

<Sect1 id="bug-reports">
<Title>How to report a bug in the GHC system
</Title>

<Para>
<IndexTerm><Primary>bug reports</Primary></IndexTerm>
</Para>

<Para>
Glasgow Haskell is a changing system so there are sure to be bugs in
it.  Please report them to
<Email>glasgow-haskell-bugs@haskell.org</Email>!  (However, please
check the earlier part of this section to be sure it's not a known
not-really-a problem.)
</Para>

<Para>
The name of the bug-reporting game is: facts, facts, facts.
Don't omit them because &ldquo;Oh, they won't be interested&hellip;&rdquo;
</Para>

<Para>

<OrderedList>
<ListItem>

<Para>
What kind of machine are you running on, and exactly what version of
the operating system are you using? (<Command>uname -a</Command> or
<Command>cat /etc/motd</Command> will show the desired information.)

</Para>
</ListItem>
<ListItem>

<Para>
 What version of GCC are you using? <Command>gcc -v</Command> will tell you.

</Para>
</ListItem>
<ListItem>

<Para>
 Run the sequence of compiles/runs that caused the offending
behaviour, capturing all the input/output in a &ldquo;script&rdquo; (a UNIX
command) or in an Emacs shell window.  We'd prefer to see the whole
thing.

</Para>
</ListItem>
<ListItem>

<Para>
 Be sure any Haskell compilations are run with a <Option>-v</Option> (verbose)
flag, so we can see exactly what was run, what versions of things you
have, etc.

</Para>
</ListItem>
<ListItem>

<Para>
 What is the program behaviour that is wrong, in your opinion?

</Para>
</ListItem>
<ListItem>

<Para>
 If practical, please send enough source files for us to duplicate the
 problem.

</Para>
</ListItem>
<ListItem>

<Para>
 If you are a Hero and track down the problem in the
compilation-system sources, please send us patches relative to a known
released version of GHC, or whole files if you prefer.

</Para>
</ListItem>

</OrderedList>

</Para>

</Sect1>

<Sect1 id="hard-core-debug">
<Title>Hard-core debugging of GHC-compiled programs
</Title>

<Para>
<IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
</Para>

<Para>
If your program is crashing, you should almost surely file a bug
report, as outlined in previous sections.
</Para>

<Para>
This section suggests ways to Make Further Progress Anyway.
</Para>

<Para>
The first thing to establish is: Is it a garbage-collection (GC) bug?
Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
flag.

<ItemizedList>
<ListItem>

<Para>
If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
definitely <Emphasis>not</Emphasis> a GC bug.
</Para>
</ListItem>
<ListItem>

<Para>
If you can make it crash with one heap size but not with another, then
it <Emphasis>probably is</Emphasis> a GC bug.
</Para>
</ListItem>
<ListItem>

<Para>
If it crashes with the normal collector, but not when you force
two-space collection (<Option>-G1</Option> runtime flag), then it
<Emphasis>probably is</Emphasis> a GC bug.
</Para>
</ListItem>

</ItemizedList>

</Para>

<Para>
If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by
using a particular heap size or by using a <Option>-G1</Option>
runtime flag.  (But don't forget to report the bug!!!)
</Para>

<Para>
ToDo: more here?
</Para>

</Sect1>

</Chapter>