ghc/docs/users_guide/gone_wrong.vsgml

   1 %************************************************************************
   2 %*                                                                      *
   3 <sect>What to do when something goes wrong
   4 <label id="wrong">
   5 <p>
   6 <nidx>problems</nidx>
   7 %*                                                                      *
   8 %************************************************************************
   9
  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 :-!
  15
  16 (Section <ref name="Haskell 1.4 vs. Glasgow Haskell 4.00: language
  17 non-compliance" id="vs-Haskell-defn">, which describes Glasgow
  18 Haskell's shortcomings vs.~the Haskell language definition, may also
  19 be of interest.)
  20
  21 %************************************************************************
  22 %*                                                                      *
  23 <sect1>When the compiler ``does the wrong thing''
  24 <label id="wrong-compiler">
  25 <p>
  26 <nidx>compiler problems</nidx>
  27 <nidx>problems with the compiler</nidx>
  28 %*                                                                      *
  29 %************************************************************************
  30
  31 <descrip>
  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
  35 them.
  36
  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).
  42
  43 Just say @make all EXTRA_HC_OPTS=-H<a reasonable number>@ and see
  44 how you get along.
  45
  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
  48 heap.
  49
  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.
  53
  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.
  58
  59 %-------------------------------------------------------------------
  60 <tag>``What about these `trace' messages from GHC?''</tag>
  61 Almost surely not a problem.  About some specific cases...
  62 <descrip>
  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&lt;N&gt; 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.
  69
  70 If the simplifier definitely seems to be ``looping,'' please report
  71 it.
  72 </descrip>
  73
  74 %-------------------------------------------------------------------
  75 <tag>``What about this warning from the C compiler?''</tag>
  76
  77 For example: ``...warning: `Foo' declared `static' but never defined.''
  78 Unsightly, but shouldn't be a problem.
  79
  80 %-------------------------------------------------------------------
  81 <tag>Sensitivity to @.hi@ interface files:</tag>
  82
  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.
  88
  89 Furthermore, as sketched below, you may have big problems
  90 running programs compiled using unstable interfaces.
  91
  92 %-------------------------------------------------------------------
  93 <tag>``I think GHC is producing incorrect code'':</tag>
  94
  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.
 100
 101 %-------------------------------------------------------------------
 102 <tag>``Why did I get a link error?''</tag>
 103
 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.
 107
 108 %-------------------------------------------------------------------
 109 <tag>``What's a `consistency error'?''</tag>
 110 (These are reported just after linking your program.)
 111
 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.
 116
 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...)
 121
 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.
 128
 129 Please report line-number errors that you find particularly unhelpful.
 130 </descrip>
 131
 132 %************************************************************************
 133 %*                                                                      *
 134 <sect1>When your program ``does the wrong thing''
 135 <label id="wrong-compilee">
 136 <p>
 137 <nidx>problems running your program</nidx>
 138 %*                                                                      *
 139 %************************************************************************
 140
 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">).
 144
 145 <descrip>
 146 %-----------------------------------------------------------------------
 147 <tag>``Help! My program crashed!''</tag>
 148 (e.g., a `segmentation fault' or `core dumped')
 149 <nidx>segmentation fault</nidx>
 150
 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).
 156
 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.
 162
 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.
 165
 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.
 169
 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"
 174 id="mkdependHS">.
 175
 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.
 179
 180 So, before you report a bug because of a core dump, you should probably:
 181 <tscreen><verb>
 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...
 186 </verb></tscreen>
 187
 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.
 190
 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">.
 194
 195 %-------------------------------------------------------------------
 196 <tag>``My program entered an `absent' argument.''</tag>
 197 This is definitely caused by a bug in GHC. Please report it.
 198
 199 %-----------------------------------------------------------------------
 200 <tag>``What's with this `arithmetic (or `floating') exception' ''?</tag>
 201
 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).
 207
 208 </descrip>
 209
 210 %************************************************************************
 211 %*                                                                      *
 212 <sect1>How to report a bug in the GHC system
 213 <label id="bug-reports">
 214 <p>
 215 <nidx>bug reports</nidx>
 216 %*                                                                      *
 217 %************************************************************************
 218
 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.)
 225
 226 The name of the bug-reporting game is: facts, facts, facts.
 227 Don't omit them because ``Oh, they won't be interested...''
 228
 229 <enum>
 230
 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.)
 234
 235 <item> What version of GCC are you using? @gcc -v@ will tell you.
 236
 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
 240 thing.
 241
 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
 244 have, etc.
 245
 246 <item> What is the program behaviour that is wrong, in your opinion?
 247
 248 <item> If practical, please send enough source files/interface files
 249 for us to duplicate the problem.
 250
 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.
 254
 255 </enum>
 256
 257 %************************************************************************
 258 %*                                                                      *
 259 <sect1>Hard-core debugging of GHC-compiled programs
 260 <label id="hard-core-debug">
 261 <p>
 262 <nidx>debugging, hard-core</nidx>
 263 %*                                                                      *
 264 %************************************************************************
 265
 266 If your program is crashing, you should almost surely file a bug
 267 report, as outlined in previous sections.
 268
 269 This section suggests ways to Make Further Progress Anyway.
 270
 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
 273 flag.
 274 <itemize>
 275 <item>
 276 If it crashes <em>without</em> garbage-collecting, then it is
 277 definitely <em>not</em> a GC bug.
 278 <item>
 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.
 281 <item>
 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.
 285 </itemize>
 286
 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!!!)
 290
 291 ToDo: more here?