diff options
Diffstat (limited to 'ghc/docs/users_guide/gone_wrong.lit')
| -rw-r--r-- | ghc/docs/users_guide/gone_wrong.lit | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/ghc/docs/users_guide/gone_wrong.lit b/ghc/docs/users_guide/gone_wrong.lit new file mode 100644 index 0000000000..4403d203f9 --- /dev/null +++ b/ghc/docs/users_guide/gone_wrong.lit @@ -0,0 +1,332 @@ +%************************************************************************ +%* * +\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 is 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 +% ./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.glasgow.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{cat /etc/motd} often shows 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? |