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
12 <XRef LinkEnd="bug-reporting"> for details on how to report a bug and
13 a list of things we'd like to know about your bug. If in doubt, send
14 a report—we love mail from irate users :-!
18 (<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
19 Haskell's shortcomings vs. the Haskell language definition, may also
23 <Sect1 id="wrong-compiler">
24 <Title>When the compiler “does the wrong thing”
28 <IndexTerm><Primary>compiler problems</Primary></IndexTerm>
29 <IndexTerm><Primary>problems with the compiler</Primary></IndexTerm>
36 <Term>“Help! The compiler crashed (or `panic'd)!”</Term>
39 These events are <Emphasis>always</Emphasis> bugs in the GHC system—please report them.
44 <Term>“The compiler ran out of heap (or stack) when compiling itself!”</Term>
47 It happens. We try to supply reasonable <Option>-H<n></Option> flags for
48 <Filename>ghc/compiler/</Filename> and <Filename>ghc/lib/</Filename>, but GHC's memory consumption
49 can vary by platform (e.g., on a 64-bit machine).
53 Just say <Command>make all EXTRA_HC_OPTS=-H<a reasonable number></Command> and see
58 Note that this is less likely to happen if you are compiling with GHC
59 4.00 or later, since the introduction of the dynamically expanding
65 <Term>“The compiler died with a pattern-matching error.”</Term>
68 This is a bug just as surely as a “panic.” Please report it.
73 <Term>“This is a terrible error message.”</Term>
76 If you think that GHC could have produced a better error message,
77 please report it as a bug.
82 <Term>“What about these `trace' messages from GHC?”</Term>
85 Almost surely not a problem. About some specific cases…
89 <Term>Simplifier still going after N iterations:</Term>
92 Sad, but harmless. You can change the number with a
93 <Option>-fmax-simplifier-iterations<N></Option><IndexTerm><Primary>-fmax-simplifier-iterations<N> option</Primary></IndexTerm> option (no space);
94 and you can see what actions took place in each iteration by
95 turning on the <Option>-fshow-simplifier-progress</Option>
96 <IndexTerm><Primary>-fshow-simplifier-progress option</Primary></IndexTerm> option.
100 If the simplifier definitely seems to be “looping,” please report
110 <Term>“What about this warning from the C compiler?”</Term>
113 For example: “…warning: `Foo' declared `static' but never defined.”
114 Unsightly, but shouldn't be a problem.
119 <Term>Sensitivity to <Filename>.hi</Filename> interface files:</Term>
122 GHC is very sensitive about interface files. For example, if it picks
123 up a non-standard <Filename>Prelude.hi</Filename> file, pretty terrible things will
124 happen. If you turn on
125 <Option>-fno-implicit-prelude</Option><IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>, the
126 compiler will almost surely die, unless you know what you are doing.
130 Furthermore, as sketched below, you may have big problems
131 running programs compiled using unstable interfaces.
136 <Term>“I think GHC is producing incorrect code”:</Term>
139 Unlikely :-) A useful be-more-paranoid option to give to GHC is
140 <Option>-dcore-lint</Option><IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>; this causes a “lint”
141 pass to check for errors (notably type errors) after each Core-to-Core
142 transformation pass. We run with <Option>-dcore-lint</Option> on all the time; it
143 costs about 5% in compile time.
148 <Term>“Why did I get a link error?”</Term>
151 If the linker complains about not finding <Literal>_<something>_fast</Literal>, then
152 something is inconsistent: you probably didn't compile modules in the
153 proper dependency order.
159 <Term>“Is this line number right?”</Term>
162 On this score, GHC usually does pretty well, especially
163 if you “allow” it to be off by one or two. In the case of an
164 instance or class declaration, the line number
165 may only point you to the declaration, not to a specific method.
169 Please report line-number errors that you find particularly unhelpful.
178 <Sect1 id="wrong-compilee">
179 <Title>When your program “does the wrong thing”
183 <IndexTerm><Primary>problems running your program</Primary></IndexTerm>
187 (For advice about overly slow or memory-hungry Haskell programs,
188 please see <XRef LinkEnd="sooner-faster-quicker">).
195 <Term>“Help! My program crashed!”</Term>
198 (e.g., a `segmentation fault' or `core dumped')
199 <IndexTerm><Primary>segmentation fault</Primary></IndexTerm>
203 If your program has no foreign calls in it, then a crash is always a BUG in
204 the GHC system, except in one case: If your program is made of several
205 modules, each module must have been compiled after any modules on which it
206 depends (unless you use <Filename>.hi-boot</Filename> files, in which case
207 these <Emphasis>must</Emphasis> be correct with respect to the module
212 For example, if an interface is lying about the type of an imported
213 value then GHC may well generate duff code for the importing module.
214 <Emphasis>This applies to pragmas inside interfaces too!</Emphasis> If the pragma is
215 lying (e.g., about the “arity” of a value), then duff code may result.
216 Furthermore, arities may change even if types do not.
220 In short, if you compile a module and its interface changes, then all
221 the modules that import that interface <Emphasis>must</Emphasis> be re-compiled.
225 A useful option to alert you when interfaces change is
226 <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>. It will run <Command>diff</Command> on the
227 changed interface file, before and after, when applicable.
231 If you are using <Command>make</Command>, GHC can automatically
232 generate the dependencies required in order to make sure that every
233 module <Emphasis>is</Emphasis> up-to-date with respect to its imported
234 interfaces. Please see <XRef LinkEnd="sec-makefile-dependencies">.
238 If you are down to your last-compile-before-a-bug-report, we would
239 recommend that you add a <Option>-dcore-lint</Option> option (for extra checking) to your compilation options.
243 So, before you report a bug because of a core dump, you should probably:
246 % rm *.o # scrub your object files
247 % make my_prog # re-make your program; use -hi-diffs to highlight changes;
248 # as mentioned above, use -dcore-lint to be more paranoid
249 % ./my_prog ... # retry...
255 Of course, if you have foreign calls in your program then all
256 bets are off, because you can trash the heap, the stack, or whatever.
260 If you are interested in hard-core debugging of a crashing
261 GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
266 <Term>“My program entered an `absent' argument.”</Term>
269 This is definitely caused by a bug in GHC. Please report it (see <xref
270 linkend="bug-reporting">).
275 <Term>“What's with this `arithmetic (or `floating') exception' ”?</Term>
278 <Literal>Int</Literal>, <Literal>Float</Literal>, and <Literal>Double</Literal> arithmetic is <Emphasis>unchecked</Emphasis>.
279 Overflows, underflows and loss of precision are either silent or
280 reported as an exception by the operating system (depending on the
281 architecture). Divide-by-zero <Emphasis>may</Emphasis> cause an untrapped
282 exception (please report it if it does).
291 <Sect1 id="hard-core-debug">
292 <Title>Hard-core debugging of GHC-compiled programs
296 <IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
300 If your program is crashing, you should almost surely file a bug
301 report, as outlined in <xref linkend="bug-reporting">.
305 This section suggests ways to Make Further Progress Anyway.
309 The first thing to establish is: Is it a garbage-collection (GC) bug?
310 Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
317 If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
318 definitely <Emphasis>not</Emphasis> a GC bug.
324 If you can make it crash with one heap size but not with another, then
325 it <Emphasis>probably is</Emphasis> a GC bug.
331 If it crashes with the normal collector, but not when you force
332 two-space collection (<Option>-G1</Option> runtime flag), then it
333 <Emphasis>probably is</Emphasis> a GC bug.
342 If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by
343 using a particular heap size or by using a <Option>-G1</Option>
344 runtime flag. (But don't forget to report the bug!!!)
356 ;;; Local Variables: ***
358 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***