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 foreign calls in it, then a crash is always a BUG in
224 the GHC system, except in one case: If your program is made of several
225 modules, each module must have been compiled after any modules on which it
226 depends (unless you use <Filename>.hi-boot</Filename> files, in which case
227 these <Emphasis>must</Emphasis> be correct with respect to the module
232 For example, if an interface is lying about the type of an imported
233 value then GHC may well generate duff code for the importing module.
234 <Emphasis>This applies to pragmas inside interfaces too!</Emphasis> If the pragma is
235 lying (e.g., about the “arity” of a value), then duff code may result.
236 Furthermore, arities may change even if types do not.
240 In short, if you compile a module and its interface changes, then all
241 the modules that import that interface <Emphasis>must</Emphasis> be re-compiled.
245 A useful option to alert you when interfaces change is
246 <Option>-hi-diffs</Option><IndexTerm><Primary>-hi-diffs option</Primary></IndexTerm>. It will run <Command>diff</Command> on the
247 changed interface file, before and after, when applicable.
251 If you are using <Command>make</Command>, GHC can automatically
252 generate the dependencies required in order to make sure that every
253 module <Emphasis>is</Emphasis> up-to-date with respect to its imported
254 interfaces. Please see <XRef LinkEnd="sec-makefile-dependencies">.
258 If you are down to your last-compile-before-a-bug-report, we would
259 recommend that you add a <Option>-dcore-lint</Option> option (for extra checking) to your compilation options.
263 So, before you report a bug because of a core dump, you should probably:
266 % rm *.o # scrub your object files
267 % make my_prog # re-make your program; use -hi-diffs to highlight changes;
268 # as mentioned above, use -dcore-lint to be more paranoid
269 % ./my_prog ... # retry...
275 Of course, if you have foreign calls in your program then all
276 bets are off, because you can trash the heap, the stack, or whatever.
280 If you are interested in hard-core debugging of a crashing
281 GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
286 <Term>“My program entered an `absent' argument.”</Term>
289 This is definitely caused by a bug in GHC. Please report it.
294 <Term>“What's with this `arithmetic (or `floating') exception' ”?</Term>
297 <Literal>Int</Literal>, <Literal>Float</Literal>, and <Literal>Double</Literal> arithmetic is <Emphasis>unchecked</Emphasis>.
298 Overflows, underflows and loss of precision are either silent or
299 reported as an exception by the operating system (depending on the
300 architecture). Divide-by-zero <Emphasis>may</Emphasis> cause an untrapped
301 exception (please report it if it does).
310 <Sect1 id="bug-reports">
311 <Title>How to report a bug in the GHC system
315 <IndexTerm><Primary>bug reports</Primary></IndexTerm>
319 Glasgow Haskell is a changing system so there are sure to be bugs in
320 it. Please report them to
321 <Email>glasgow-haskell-bugs@haskell.org</Email>! (However, please
322 check the earlier part of this section to be sure it's not a known
323 not-really-a problem.)
327 The name of the bug-reporting game is: facts, facts, facts.
328 Don't omit them because “Oh, they won't be interested…”
337 What kind of machine are you running on, and exactly what version of
338 the operating system are you using? (<Command>uname -a</Command> or
339 <Command>cat /etc/motd</Command> will show the desired information.)
346 What version of GCC are you using? <Command>gcc -v</Command> will tell you.
353 Run the sequence of compiles/runs that caused the offending
354 behaviour, capturing all the input/output in a “script” (a UNIX
355 command) or in an Emacs shell window. We'd prefer to see the whole
363 Be sure any Haskell compilations are run with a <Option>-v</Option> (verbose)
364 flag, so we can see exactly what was run, what versions of things you
372 What is the program behaviour that is wrong, in your opinion?
379 If practical, please send enough source files for us to duplicate the
387 If you are a Hero and track down the problem in the
388 compilation-system sources, please send us patches relative to a known
389 released version of GHC, or whole files if you prefer.
400 <Sect1 id="hard-core-debug">
401 <Title>Hard-core debugging of GHC-compiled programs
405 <IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
409 If your program is crashing, you should almost surely file a bug
410 report, as outlined in previous sections.
414 This section suggests ways to Make Further Progress Anyway.
418 The first thing to establish is: Is it a garbage-collection (GC) bug?
419 Try your program with a very large heap and a <Option>-Sstderr</Option> RTS
426 If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
427 definitely <Emphasis>not</Emphasis> a GC bug.
433 If you can make it crash with one heap size but not with another, then
434 it <Emphasis>probably is</Emphasis> a GC bug.
440 If it crashes with the normal collector, but not when you force
441 two-space collection (<Option>-G1</Option> runtime flag), then it
442 <Emphasis>probably is</Emphasis> a GC bug.
451 If it <Emphasis>is</Emphasis> a GC bug, you may be able to avoid it by
452 using a particular heap size or by using a <Option>-G1</Option>
453 runtime flag. (But don't forget to report the bug!!!)
465 ;;; Local Variables: ***
467 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***