1 %************************************************************************
3 <sect>What to do when something goes wrong
8 %************************************************************************
10 If you still have a problem after consulting this section, then you
11 may have found a <em>bug</em>---please report it! See Section <ref
12 name="How to report a bug in the GHC system" id="bug-reports"> for a
13 list of things we'd like to know about your bug. If in doubt, send a
14 report---we love mail from irate users :-!
16 (Section <ref name="Haskell 98 vs. Glasgow Haskell: language
17 non-compliance" id="vs-Haskell-defn">, which describes Glasgow
18 Haskell's shortcomings vs.~the Haskell language definition, may also
21 %************************************************************************
23 <sect1>When the compiler ``does the wrong thing''
24 <label id="wrong-compiler">
26 <nidx>compiler problems</nidx>
27 <nidx>problems with the compiler</nidx>
29 %************************************************************************
32 %-------------------------------------------------------------------
33 <tag>``Help! The compiler crashed (or `panic'd)!''</tag>
34 These events are <em>always</em> bugs in the GHC system---please report
37 %-------------------------------------------------------------------
38 <tag>``The compiler ran out of heap (or stack) when compiling itself!''</tag>
39 It happens. We try to supply reasonable @-H<n>@ flags for
40 @ghc/compiler/@ and @ghc/lib/@, but GHC's memory consumption
41 can vary by platform (e.g., on a 64-bit machine).
43 Just say @make all EXTRA_HC_OPTS=-H<a reasonable number>@ and see
46 Note that this is less likely to happen if you are compiling with GHC
47 4.00 or later, since the introduction of the dynamically expanding
50 %-------------------------------------------------------------------
51 <tag>``The compiler died with a pattern-matching error.''</tag>
52 This is a bug just as surely as a ``panic.'' Please report it.
54 %-------------------------------------------------------------------
55 <tag>``This is a terrible error message.''</tag>
56 If you think that GHC could have produced a better error message,
57 please report it as a bug.
59 %-------------------------------------------------------------------
60 <tag>``What about these `trace' messages from GHC?''</tag>
61 Almost surely not a problem. About some specific cases...
63 <tag>Simplifier still going after N iterations:</tag>
64 Sad, but harmless. You can change the number with a
65 @-fmax-simplifier-iterations<N>@<nidx>-fmax-simplifier-iterations<N> option</nidx> option (no space);
66 and you can see what actions took place in each iteration by
67 turning on the @-fshow-simplifier-progress@
68 <nidx>-fshow-simplifier-progress option</nidx> option.
70 If the simplifier definitely seems to be ``looping,'' please report
74 %-------------------------------------------------------------------
75 <tag>``What about this warning from the C compiler?''</tag>
77 For example: ``...warning: `Foo' declared `static' but never defined.''
78 Unsightly, but shouldn't be a problem.
80 %-------------------------------------------------------------------
81 <tag>Sensitivity to @.hi@ interface files:</tag>
83 GHC is very sensitive about interface files. For example, if it picks
84 up a non-standard @Prelude.hi@ file, pretty terrible things will
85 happen. If you turn on
86 @-fno-implicit-prelude@<nidx>-fno-implicit-prelude option</nidx>, the
87 compiler will almost surely die, unless you know what you are doing.
89 Furthermore, as sketched below, you may have big problems
90 running programs compiled using unstable interfaces.
92 %-------------------------------------------------------------------
93 <tag>``I think GHC is producing incorrect code'':</tag>
95 Unlikely :-) A useful be-more-paranoid option to give to GHC is
96 @-dcore-lint@<nidx>-dcore-lint option</nidx>; this causes a ``lint''
97 pass to check for errors (notably type errors) after each Core-to-Core
98 transformation pass. We run with @-dcore-lint@ on all the time; it
99 costs about 5\% in compile time.
101 %-------------------------------------------------------------------
102 <tag>``Why did I get a link error?''</tag>
104 If the linker complains about not finding @_<something>_fast@, then
105 something is inconsistent: you probably didn't compile modules in the
106 proper dependency order.
108 %-------------------------------------------------------------------
109 <tag>``What's a `consistency error'?''</tag>
110 (These are reported just after linking your program.)
112 You tried to link incompatible object files, e.g., normal ones
113 (registerised, Appel garbage-collector) with profiling ones (two-space
114 collector). Or those compiled by a previous version of GHC
115 with an incompatible newer version.
117 If you run @nm -o *.o | egrep 't (cc|hsc)\.'@ (or, on
118 unregisterised files: @what *.o@), you'll see all the consistency
119 tags/strings in your object files. They must all be the same!
120 (ToDo: tell you what they mean...)
122 %-------------------------------------------------------------------
123 <tag>``Is this line number right?''</tag>
124 On this score, GHC usually does pretty well, especially
125 if you ``allow'' it to be off by one or two. In the case of an
126 instance or class declaration, the line number
127 may only point you to the declaration, not to a specific method.
129 Please report line-number errors that you find particularly unhelpful.
132 %************************************************************************
134 <sect1>When your program ``does the wrong thing''
135 <label id="wrong-compilee">
137 <nidx>problems running your program</nidx>
139 %************************************************************************
141 (For advice about overly slow or memory-hungry Haskell programs,
142 please see Section <ref name="Advice on: sooner, faster, smaller,
143 stingier" id="sooner-faster-quicker">).
146 %-----------------------------------------------------------------------
147 <tag>``Help! My program crashed!''</tag>
148 (e.g., a `segmentation fault' or `core dumped')
149 <nidx>segmentation fault</nidx>
151 If your program has no @_ccall_@s/@_casm_@s in it, then a crash is
152 always a BUG in the GHC system, except in one case: If your program is
153 made of several modules, each module must have been compiled after any
154 modules on which it depends (unless you use @.hi-boot@ files, in which
155 case these <em/must/ be correct with respect to the module source).
157 For example, if an interface is lying about the type of an imported
158 value then GHC may well generate duff code for the importing module.
159 <em>This applies to pragmas inside interfaces too!</em> If the pragma is
160 lying (e.g., about the ``arity'' of a value), then duff code may result.
161 Furthermore, arities may change even if types do not.
163 In short, if you compile a module and its interface changes, then all
164 the modules that import that interface <em>must</em> be re-compiled.
166 A useful option to alert you when interfaces change is
167 @-hi-diffs@<nidx>-hi-diffs option</nidx>. It will run @diff@ on the
168 changed interface file, before and after, when applicable.
170 If you are using @make@, a useful tool to make sure that every module
171 <em>is</em> up-to-date with respect to its imported interfaces is
172 @mkdependHS@ (which comes with GHC). Please see Section <ref
173 name="Makefile dependencies in Haskell: using mkdependHS"
176 If you are down to your last-compile-before-a-bug-report, we would
177 recommend that you add a @-dcore-lint@ option (for extra checking) to
178 your compilation options.
180 So, before you report a bug because of a core dump, you should probably:
182 % rm *.o # scrub your object files
183 % make my_prog # re-make your program; use -hi-diffs to highlight changes;
184 # as mentioned above, use -dcore-lint to be more paranoid
185 % ./my_prog ... # retry...
188 Of course, if you have @_ccall_@s/@_casm_@s in your program then all
189 bets are off, because you can trash the heap, the stack, or whatever.
191 If you are interested in hard-core debugging of a crashing
192 GHC-compiled program, please see Section <ref name="Hard-core
193 debugging of GHC-compiled programs" id="hard-core-debug">.
195 %-------------------------------------------------------------------
196 <tag>``My program entered an `absent' argument.''</tag>
197 This is definitely caused by a bug in GHC. Please report it.
199 %-----------------------------------------------------------------------
200 <tag>``What's with this `arithmetic (or `floating') exception' ''?</tag>
202 @Int@, @Float@, and @Double@ arithmetic is <em>unchecked</em>.
203 Overflows, underflows and loss of precision are either silent or
204 reported as an exception by the operating system (depending on the
205 architecture). Divide-by-zero <em>may</em> cause an untrapped
206 exception (please report it if it does).
210 %************************************************************************
212 <sect1>How to report a bug in the GHC system
213 <label id="bug-reports">
215 <nidx>bug reports</nidx>
217 %************************************************************************
219 Glasgow Haskell is a changing system so there are sure to be bugs in
220 it. Please report them to <htmlurl
221 name="glasgow-haskell-bugs@@dcs.gla.ac.uk"
222 url="mailto:glasgow-haskell-bugs@@dcs.gla.ac.uk">! (However, please
223 check the earlier part of this section to be sure it's not a known
224 not-really-a problem.)
226 The name of the bug-reporting game is: facts, facts, facts.
227 Don't omit them because ``Oh, they won't be interested...''
231 <item> What kind of machine are you running on, and exactly what
232 version of the operating system are you using? (@uname -a@ or @cat
233 /etc/motd@ will show the desired information.)
235 <item> What version of GCC are you using? @gcc -v@ will tell you.
237 <item> Run the sequence of compiles/runs that caused the offending
238 behaviour, capturing all the input/output in a ``script'' (a UNIX
239 command) or in an Emacs shell window. We'd prefer to see the whole
242 <item> Be sure any Haskell compilations are run with a @-v@ (verbose)
243 flag, so we can see exactly what was run, what versions of things you
246 <item> What is the program behaviour that is wrong, in your opinion?
248 <item> If practical, please send enough source files/interface files
249 for us to duplicate the problem.
251 <item> If you are a Hero and track down the problem in the
252 compilation-system sources, please send us patches relative to a known
253 released version of GHC, or whole files if you prefer.
257 %************************************************************************
259 <sect1>Hard-core debugging of GHC-compiled programs
260 <label id="hard-core-debug">
262 <nidx>debugging, hard-core</nidx>
264 %************************************************************************
266 If your program is crashing, you should almost surely file a bug
267 report, as outlined in previous sections.
269 This section suggests ways to Make Further Progress Anyway.
271 The first thing to establish is: Is it a garbage-collection (GC) bug?
272 Try your program with a very large heap and a @-Sstderr@ RTS
276 If it crashes <em>without</em> garbage-collecting, then it is
277 definitely <em>not</em> a GC bug.
279 If you can make it crash with one heap size but not with another, then
280 it <em>probably is</em> a GC bug.
282 If it crashes with the normal
283 collector, but not when you force two-space collection (@-F2s@
284 runtime flag), then it <em>probably is</em> a GC bug.
287 If it <em>is</em> a GC bug, you may be able to avoid it by using a
288 particular heap size or by using a @-F2s@ runtime flag. (But don't
289 forget to report the bug!!!)