[project @ 1996-07-25 20:43:49 by partain]

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

%************************************************************************
%*                                                                      *
\section[wrong]{What to do when something goes wrong}
\index{problems}
%*                                                                      *
%************************************************************************

If you still have a problem after consulting this section, then you
may have found a {\em bug}---please report it!  See
\Sectionref{bug-reports} for a list of things we'd like to know about
your bug.  If in doubt, send a report---we love mail from irate users :-!

(\Sectionref{vs-Haskell-defn}, which describes Glasgow Haskell's
shortcomings vs.~the Haskell language definition, may also be of
interest.)

%************************************************************************
%*                                                                      *
\subsection[wrong-compiler]{When the compiler ``does the wrong thing''}
\index{compiler problems}
\index{problems with the compiler}
%*                                                                      *
%************************************************************************

\begin{description}
%-------------------------------------------------------------------
\item[``Help! The compiler crashed (or `panic'd)!'']
These events are {\em always} bugs in the GHC system---please report
them.

%Known compiler ``panics'':
%\begin{description}
%\item[From SPARC native-code generator:] These tend to say something
%like ``unknown PrimOp;'' you can avoid it by compiling that module
%with \tr{-fvia-C}.\index{-fvia-C option}
%\end{description}

%-------------------------------------------------------------------
\item[``The compiler ran out of heap (or stack) when compiling itself!'']
It happens.  We try to supply reasonable \tr{-H<n>} flags for
\tr{ghc/compiler/} and \tr{ghc/lib/}, but GHC's memory consumption
can vary by platform (e.g., on a 64-bit machine).

Just say \tr{make all EXTRA_HC_OPTS=-H<a reasonable number>} and see
how you get along.

%-------------------------------------------------------------------
\item[``The compiler died with a pattern-matching error.'']
This is a bug just as surely as a ``panic.'' Please report it.

%-------------------------------------------------------------------
% \item[``Some confusion about a value specialised to a type...''  Huh???]
% (A deeply obscure and unfriendly error message.)
% 
% This message crops up when the typechecker sees a reference in an
% interface pragma to a specialisation of an overloaded value
% (function); for example, \tr{elem} specialised for type \tr{[Char]}
% (\tr{String}).  The problem is: it doesn't {\em know} that such a
% specialisation exists!
% 
% The cause of this problem is (please report any other cases...): The
% compiler has imported pragmatic info for the value in question from
% more than one interface, and the multiple interfaces did not agree
% {\em exactly} about the value's pragmatic info.  Since the compiler
% doesn't know whom to believe, it believes none of them.
% 
% The cure is to re-compile the modules that {\em re-export} the
% offending value (after possibly re-compiling its defining module).
% Now the pragmatic info should be exactly the same in every case, and
% things should be fine.

%-------------------------------------------------------------------
% \item[``Can't see the data constructors for a ccall/casm'' Huh?]
% GHC ``unboxes'' C-call arguments and ``reboxes'' C-call results for you.
% To do this, it {\\em has} to be able to see the types fully;
% abstract types won't do!
% 
% Thus, if you say \tr{data Foo = Foo Int#}
% (a cool ``boxed primitive'' type), but then make it abstract
% (only \tr{data Foo} appears in the interface), then GHC can't figure
% out what to do with \tr{Foo} arguments/results to C-calls.
% 
% Solutions: either make the type unabstract, or compile with \tr{-O}.
% With the latter, the constructor info will be passed along in
% the interface pragmas.

%-------------------------------------------------------------------
\item[``This is a terrible error message.'']
If you think that GHC could have produced a better error message,
please report it as a bug.

%-------------------------------------------------------------------
\item[``What about these `trace' messages from GHC?'']
Almost surely not a problem.  About some specific cases...
\begin{description}
\item[Simplifier still going after N iterations:]
Sad, but harmless.  You can change the number with a
\tr{-fmax-simplifier-iterations<N>}\index{-fmax-simplifier-iterations<N> option} option (no space);
and you can see what actions took place in each iteration by
turning on the \tr{-fshow-simplifier-progress}
\index{-fshow-simplifier-progress option} option.

If the simplifier definitely seems to be ``looping,'' please report
it.
\end{description}

%-------------------------------------------------------------------
\item[``What about this warning from the C compiler?'']

For example: ``...warning: `Foo' declared `static' but never defined.''
Unsightly, but not a problem.

%-------------------------------------------------------------------
\item[Sensitivity to \tr{.hi} interface files:]

GHC is very sensitive about interface files.  For example, if it picks
up a non-standard \tr{Prelude.hi} file, pretty terrible things will
happen.  If you turn on
\tr{-fno-implicit-prelude}\index{-fno-implicit-prelude option}, the
compiler will almost surely die, unless you know what you are doing.

Furthermore, as sketched below, you may have big problems
running programs compiled using unstable interfaces.

%-------------------------------------------------------------------
\item[``I think GHC is producing incorrect code'':]

Unlikely :-) A useful be-more-paranoid option to give to GHC is
\tr{-dcore-lint}\index{-dcore-lint option}; this causes a ``lint'' pass to
check for errors (notably type errors) after each Core-to-Core
transformation pass.  We run with \tr{-dcore-lint} on all the time; it
costs about 5\% in compile time.  (Or maybe 25\%; who knows?)

%-------------------------------------------------------------------
%\item[``Can I use HBC-produced \tr{.hi} interface files?'']
%Yes, though you should keep compiling until you have a stable set of
%GHC-produced ones.

%-------------------------------------------------------------------
\item[``Why did I get a link error?'']

If the linker complains about not finding \tr{_<something>_fast}, then
your interface files haven't settled---keep on compiling!  (In
particular, this error means that arity information, which you can see
in any \tr{.hi} file, has changed.)

%If the linker complains about not finding \tr{SpA}, \tr{SuA}, and
%other such things, then you've tried to link ``unregisterised'' object
%code (produced with \tr{-O0}) with the normal registerised stuff.

%If you get undefined symbols that look anything like (for example)
%\tr{J3C_Interact$__writeln}, \tr{C_Prelude$__$2B$2B},
%\tr{VC_Prelude$__map}, etc., then you are trying to link HBC-produced
%object files with GHC.

%-------------------------------------------------------------------
\item[``What's a `consistency error'?'']
(These are reported just after linking your program.)

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.

If you run \tr{nm -o *.o | egrep 't (cc|hsc)\.'} (or, on
unregisterised files: \tr{what *.o}), you'll see all the consistency
tags/strings in your object files.  They must all be the same!
(ToDo: tell you what they mean...)

%-------------------------------------------------------------------
\item[``Is this line number right?'']
On this score, GHC usually does pretty well, especially
if you ``allow'' 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.

Please report line-number errors that you find particularly unhelpful.
\end{description}

%************************************************************************
%*                                                                      *
\subsection[wrong-compilee]{When your program ``does the wrong thing''}
\index{problems running your program}
%*                                                                      *
%************************************************************************

(For advice about overly slow or memory-hungry Haskell programs,
please see \sectionref{sooner-faster-quicker}).

\begin{description}
%-----------------------------------------------------------------------
\item[``Help! My program crashed!'']
(e.g., a `segmentation fault' or `core dumped')

If your program has no @_ccall_@s/@_casm_@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 with a stable
group of interface (\tr{.hi}) files.

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.
{\em This applies to pragmas inside interfaces too!}  If the pragma is
lying (e.g., about the ``arity'' of a value), then duff code may result.
Furthermore, arities may change even if types do not.

In short, if you compile a module and its interface changes, then all
the modules that import that interface {\em must} be re-compiled.

A useful option to alert you when interfaces change is
\tr{-hi-diffs}\index{-hi-diffs option}.  It will run \tr{diff} on the
changed interface file, before and after, when applicable.

If you are using \tr{make}, a useful tool to make sure that every
module {\em is} up-to-date with respect to its imported interfaces is
\tr{mkdependHS} (which comes with GHC).  Please see
\sectionref{mkdependHS}.

If you are down to your last-compile-before-a-bug-report, we
would recommend that you add a \tr{-dcore-lint} option (for
extra checking) to your compilation options.

So, before you report a bug because of a core dump, you should probably:
\begin{verbatim}
% 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...
\end{verbatim}

Of course, if you have @_ccall_@s/@_casm_@s in your program then all bets
are off, because you can trash the heap, the stack, or whatever.

If you are interested in hard-core debugging of a crashing
GHC-compiled program, please see \sectionref{hard-core-debug}.

% (If you have an ``unregisterised'' arity-checking
% (\tr{-O0 -darity-checks}) around [as we sometimes do at Glasgow], then you
% might recompile with \tr{-darity-checks}\index{-darity-checks option},
% which will definitely detect arity-compatibility errors.)

%-------------------------------------------------------------------
\item[``My program entered an `absent' argument.'']
This is definitely caused by a bug in GHC. Please report it.

%-----------------------------------------------------------------------
\item[``What's with this `arithmetic (or `floating') exception' ''?]

@Int@, @Float@, and @Double@ arithmetic is {\em unchecked}.  Overflows
and underflows are {\em silent}.  Divide-by-zero {\em may} cause an
untrapped exception (please report it if it does).  I suppose other
arithmetic uncheckiness might cause an exception, too...
\end{description}

%************************************************************************
%*                                                                      *
\subsection[bug-reports]{How to report a bug in the GHC system}
\index{bug reports}
%*                                                                      *
%************************************************************************

Glasgow Haskell is a changing system so there are sure to be bugs in
it.  Please report them to
\tr{glasgow-haskell-bugs@dcs.gla.ac.uk}!  (However, please check
the earlier part of this section to be sure it's not a known
not-really-a problem.)

The name of the bug-reporting game is: facts, facts, facts.
Don't omit them because ``Oh, they won't be interested...''
\begin{enumerate}
\item
What kind of machine are you running on, and exactly what version of the
operating system are you using? (\tr{uname -a} or \tr{cat /etc/motd} will show the desired
information.)

\item
What version of GCC are you using? \tr{gcc -v} will tell you.

\item
Run the sequence of compiles/runs that caused the offending behaviour,
capturing all the input/output in a ``script'' (a UNIX command) or in
an Emacs shell window.  We'd prefer to see the whole thing.

\item
Be sure any Haskell compilations are run with a \tr{-v} (verbose)
flag, so we can see exactly what was run, what versions of things you
have, etc.

\item
What is the program behaviour that is wrong, in your opinion?

\item
If practical, please send enough source files/interface files for us
to duplicate the problem.

\item
If you are a Hero and track down the problem in the compilation-system
sources, please send us {\em whole files} (by e-mail or FTP) that we
can compare against some base release.
\end{enumerate}

%************************************************************************
%*                                                                      *
\subsection[hard-core-debug]{Hard-core debugging of GHC-compiled programs}
\index{debugging, hard-core}
%*                                                                      *
%************************************************************************

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

This section suggests ways to Make Further Progress Anyway.

The first thing to establish is: Is it a garbage-collection (GC) bug?
Try your program with a very large heap and a \tr{-Sstderr} RTS
flag.
\begin{itemize}
\item
If it crashes {\em without} garbage-collecting, then it is
definitely {\em not} a GC bug.
\item
If you can make it crash with one heap size but not with another, then
it {\em probably is} a GC bug.
\item
If it crashes with the normal
collector, but not when you force two-space collection (\tr{-F2s}
runtime flag), then it {\em probably is} a GC bug.
\end{itemize}

If it {\em is} a GC bug, you may be able to avoid it by using a
particular heap size or by using a \tr{-F2s} runtime flag.  (But don't
forget to report the bug!!!)

ToDo: more here?