2 <Title>What to do when something goes wrong
6 <IndexTerm><Primary>problems</Primary></IndexTerm>
10 If you still have a problem after consulting this section, then you
11 may have found a <Emphasis>bug</Emphasis>—please report it! See <XRef LinkEnd="bug-reports"> for a
12 list of things we'd like to know about your bug. If in doubt, send a
13 report—we love mail from irate users :-!
17 (<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
18 Haskell's shortcomings vs. the Haskell language definition, may also
22 <Sect1 id="wrong-compiler">
23 <Title>When the compiler ``does the wrong thing''
27 <IndexTerm><Primary>compiler problems</Primary></IndexTerm>
28 <IndexTerm><Primary>problems with the compiler</Primary></IndexTerm>
35 <Term>``Help! The compiler crashed (or `panic'd)!''</Term>
38 These events are <Emphasis>always</Emphasis> bugs in the GHC system—please report them.
43 <Term>``The compiler ran out of heap (or stack) when compiling itself!''</Term>
46 It happens. We try to supply reasonable <Option>-H<n></Option> flags for
47 <Filename>ghc/compiler/</Filename> and <Filename>ghc/lib/</Filename>, but GHC's memory consumption
48 can vary by platform (e.g., on a 64-bit machine).
52 Just say <Command>make all EXTRA_HC_OPTS=-H<a reasonable number></Command> and see
57 Note that this is less likely to happen if you are compiling with GHC
58 4.00 or later, since the introduction of the dynamically expanding
64 <Term>``The compiler died with a pattern-matching error.''</Term>
67 This is a bug just as surely as a ``panic.'' Please report it.
72 <Term>``This is a terrible error message.''</Term>
75 If you think that GHC could have produced a better error message,
76 please report it as a bug.
81 <Term>``What about these `trace' messages from GHC?''</Term>
84 Almost surely not a problem. About some specific cases…
88 <Term>Simplifier still going after N iterations:</Term>
91 Sad, but harmless. You can change the number with a
92 <Option>-fmax-simplifier-iterations<N></Option><IndexTerm><Primary>-fmax-simplifier-iterations<N> option</Primary></IndexTerm> option (no space);
93 and you can see what actions took place in each iteration by
94 turning on the <Option>-fshow-simplifier-progress</Option>
95 <IndexTerm><Primary>-fshow-simplifier-progress option</Primary></IndexTerm> option.
99 If the simplifier definitely seems to be ``looping,'' please report
109 <Term>``What about this warning from the C compiler?''</Term>
112 For example: ``…warning: `Foo' declared `static' but never defined.''
113 Unsightly, but shouldn't be a problem.
118 <Term>Sensitivity to <Filename>.hi</Filename> interface files:</Term>
121 GHC is very sensitive about interface files. For example, if it picks
122 up a non-standard <Filename>Prelude.hi</Filename> file, pretty terrible things will
123 happen. If you turn on
124 <Option>-fno-implicit-prelude</Option><IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>, the
125 compiler will almost surely die, unless you know what you are doing.
129 Furthermore, as sketched below, you may have big problems
130 running programs compiled using unstable interfaces.
135 <Term>``I think GHC is producing incorrect code'':</Term>
138 Unlikely :-) A useful be-more-paranoid option to give to GHC is
139 <Option>-dcore-lint</Option><IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>; this causes a ``lint''
140 pass to check for errors (notably type errors) after each Core-to-Core
141 transformation pass. We run with <Option>-dcore-lint</Option> on all the time; it
142 costs about 5% in compile time.
147 <Term>``Why did I get a link error?''</Term>
150 If the linker complains about not finding <Literal>_<something>_fast</Literal>, then
151 something is inconsistent: you probably didn't compile modules in the
152 proper dependency order.
157 <Term>``What's a `consistency error'?''</Term>
160 (These are reported just after linking your program.)
164 You tried to link incompatible object files, e.g., normal ones
165 (registerised, Appel garbage-collector) with profiling ones (two-space
166 collector). Or those compiled by a previous version of GHC
167 with an incompatible newer version.
171 If you run <Command>nm -o *.o | egrep 't (cc|hsc)\.'</Command> (or, on
172 unregisterised files: <Command>what *.o</Command>), you'll see all the consistency
173 tags/strings in your object files. They must all be the same!
174 (ToDo: tell you what they mean…)
179 <Term>``Is this line number right?''</Term>
182 On this score, GHC usually does pretty well, especially
183 if you ``allow'' it to be off by one or two. In the case of an
184 instance or class declaration, the line number
185 may only point you to the declaration, not to a specific method.
189 Please report line-number errors that you find particularly unhelpful.
198 <Sect1 id="wrong-compilee">
199 <Title>When your program ``does the wrong thing''
203 <IndexTerm><Primary>problems running your program</Primary></IndexTerm>
207 (For advice about overly slow or memory-hungry Haskell programs,
208 please see <XRef LinkEnd="sooner-faster-quicker">).
215 <Term>``Help! My program crashed!''</Term>
218 (e.g., a `segmentation fault' or `core dumped')
219 <IndexTerm><Primary>segmentation fault</Primary></IndexTerm>
223 If your program has no <Function>_ccall_</Function>s/<Function>_casm_</Function>s in it, then a crash is
224 always a BUG in the GHC system, except in one case: If your program is
225 made of several modules, each module must have been compiled after any
226 modules on which it depends (unless you use <Filename>.hi-boot</Filename> files, in which
227 case these <Emphasis>must</Emphasis> be correct with respect to the module source).
231 For example, if an interface is lying about the type of an imported
232 value then GHC may well generate duff code for the importing module.
233 <Emphasis>This applies to pragmas inside interfaces too!</Emphasis> If the pragma is
234 lying (e.g., about the ``arity'' of a value), then duff code may result.
235 Furthermore, arities may change even if types do not.
239 In short, if you compile a module and its interface changes, then all
240 the modules that import that interface <Emphasis>must</Emphasis> be re-compiled.
244 A useful option to alert you when interfaces change is
245 <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>. It will run <Command>diff</Command> on the
246 changed interface file, before and after, when applicable.
250 If you are using <Command>make</Command>, a useful tool to make sure that every module
251 <Emphasis>is</Emphasis> up-to-date with respect to its imported interfaces is
252 <Command>mkdependHS</Command> (which comes with GHC). Please see <XRef LinkEnd="mkdependHS">.
256 If you are down to your last-compile-before-a-bug-report, we would
257 recommend that you add a <Option>-dcore-lint</Option> option (for extra checking) to your compilation options.
261 So, before you report a bug because of a core dump, you should probably:
264 % rm *.o # scrub your object files
265 % make my_prog # re-make your program; use -hi-diffs to highlight changes;
266 # as mentioned above, use -dcore-lint to be more paranoid
267 % ./my_prog ... # retry...
273 Of course, if you have <Function>_ccall_</Function>s/<Function>_casm_</Function>s in your program then all
274 bets are off, because you can trash the heap, the stack, or whatever.
278 If you are interested in hard-core debugging of a crashing
279 GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
284 <Term>``My program entered an `absent' argument.''</Term>
287 This is definitely caused by a bug in GHC. Please report it.
292 <Term>``What's with this `arithmetic (or `floating') exception' ''?</Term>
295 <Literal>Int</Literal>, <Literal>Float</Literal>, and <Literal>Double</Literal> arithmetic is <Emphasis>unchecked</Emphasis>.
296 Overflows, underflows and loss of precision are either silent or
297 reported as an exception by the operating system (depending on the
298 architecture). Divide-by-zero <Emphasis>may</Emphasis> cause an untrapped
299 exception (please report it if it does).
308 <Sect1 id="bug-reports">
309 <Title>How to report a bug in the GHC system
313 <IndexTerm><Primary>bug reports</Primary></IndexTerm>
317 Glasgow Haskell is a changing system so there are sure to be bugs in
318 it. Please report them to <Email>glasgow-haskell-bugs@haskell.org</Email>! (However, please
319 check the earlier part of this section to be sure it's not a known
320 not-really-a problem.)
324 The name of the bug-reporting game is: facts, facts, facts.
325 Don't omit them because ``Oh, they won't be interested…''
334 What kind of machine are you running on, and exactly what
335 version of the operating system are you using? (<Command>uname -a</Command> or <Command>cat
336 /etc/motd</Command> will show the desired information.)
343 What version of GCC are you using? <Command>gcc -v</Command> will tell you.
350 Run the sequence of compiles/runs that caused the offending
351 behaviour, capturing all the input/output in a ``script'' (a UNIX
352 command) or in an Emacs shell window. We'd prefer to see the whole
360 Be sure any Haskell compilations are run with a <Option>-v</Option> (verbose)
361 flag, so we can see exactly what was run, what versions of things you
369 What is the program behaviour that is wrong, in your opinion?
376 If practical, please send enough source files/interface files
377 for us to duplicate the problem.
384 If you are a Hero and track down the problem in the
385 compilation-system sources, please send us patches relative to a known
386 released version of GHC, or whole files if you prefer.
397 <Sect1 id="hard-core-debug">
398 <Title>Hard-core debugging of GHC-compiled programs
402 <IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
406 If your program is crashing, you should almost surely file a bug
407 report, as outlined in previous sections.
411 This section suggests ways to Make Further Progress Anyway.
415 The first thing to establish is: Is it a garbage-collection (GC) bug?
416 Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
423 If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
424 definitely <Emphasis>not</Emphasis> a GC bug.
430 If you can make it crash with one heap size but not with another, then
431 it <Emphasis>probably is</Emphasis> a GC bug.
437 If it crashes with the normal
438 collector, but not when you force two-space collection (<Option>-F2s</Option>
439 runtime flag), then it <Emphasis>probably is</Emphasis> a GC bug.
448 If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by using a
449 particular heap size or by using a <Option>-F2s</Option> runtime flag. (But don't
450 forget to report the bug!!!)