ghc/docs/users_guide/gone_wrong.sgml

   1 <Chapter id="wrong">
   2 <Title>What to do when something goes wrong
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>problems</Primary></IndexTerm>
   7 </Para>
   8
   9 <Para>
  10 If you still have a problem after consulting this section, then you
  11 may have found a <Emphasis>bug</Emphasis>&mdash;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&mdash;we love mail from irate users :-!
  15 </Para>
  16
  17 <Para>
  18 (<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
  19 Haskell's shortcomings vs.&nbsp;the Haskell language definition, may also
  20 be of interest.)
  21 </Para>
  22
  23 <Sect1 id="wrong-compiler">
  24 <Title>When the compiler &ldquo;does the wrong thing&rdquo;
  25 </Title>
  26
  27 <Para>
  28 <IndexTerm><Primary>compiler problems</Primary></IndexTerm>
  29 <IndexTerm><Primary>problems with the compiler</Primary></IndexTerm>
  30 </Para>
  31
  32 <Para>
  33 <VariableList>
  34
  35 <VarListEntry>
  36 <Term>&ldquo;Help! The compiler crashed (or `panic'd)!&rdquo;</Term>
  37 <ListItem>
  38 <Para>
  39 These events are <Emphasis>always</Emphasis> bugs in the GHC system&mdash;please report them.
  40 </Para>
  41 </ListItem>
  42 </VarListEntry>
  43 <VarListEntry>
  44 <Term>&ldquo;The compiler ran out of heap (or stack) when compiling itself!&rdquo;</Term>
  45 <ListItem>
  46 <Para>
  47 It happens.  We try to supply reasonable <Option>-H&lt;n&gt;</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).
  50 </Para>
  51
  52 <Para>
  53 Just say <Command>make all EXTRA&lowbar;HC&lowbar;OPTS=-H&lt;a reasonable number&gt;</Command> and see
  54 how you get along.
  55 </Para>
  56
  57 <Para>
  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
  60 heap.
  61 </Para>
  62 </ListItem>
  63 </VarListEntry>
  64 <VarListEntry>
  65 <Term>&ldquo;The compiler died with a pattern-matching error.&rdquo;</Term>
  66 <ListItem>
  67 <Para>
  68 This is a bug just as surely as a &ldquo;panic.&rdquo; Please report it.
  69 </Para>
  70 </ListItem>
  71 </VarListEntry>
  72 <VarListEntry>
  73 <Term>&ldquo;This is a terrible error message.&rdquo;</Term>
  74 <ListItem>
  75 <Para>
  76 If you think that GHC could have produced a better error message,
  77 please report it as a bug.
  78 </Para>
  79 </ListItem>
  80 </VarListEntry>
  81 <VarListEntry>
  82 <Term>&ldquo;What about these `trace' messages from GHC?&rdquo;</Term>
  83 <ListItem>
  84 <Para>
  85 Almost surely not a problem.  About some specific cases&hellip;
  86 <VariableList>
  87
  88 <VarListEntry>
  89 <Term>Simplifier still going after N iterations:</Term>
  90 <ListItem>
  91 <Para>
  92 Sad, but harmless.  You can change the number with a
  93 <Option>-fmax-simplifier-iterations&lt;N&gt;</Option><IndexTerm><Primary>-fmax-simplifier-iterations&lt;N&gt; 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.
  97 </Para>
  98
  99 <Para>
 100 If the simplifier definitely seems to be &ldquo;looping,&rdquo; please report
 101 it.
 102 </Para>
 103 </ListItem>
 104 </VarListEntry>
 105 </VariableList>
 106 </Para>
 107 </ListItem>
 108 </VarListEntry>
 109 <VarListEntry>
 110 <Term>&ldquo;What about this warning from the C compiler?&rdquo;</Term>
 111 <ListItem>
 112 <Para>
 113 For example: &ldquo;&hellip;warning: `Foo' declared `static' but never defined.&rdquo;
 114 Unsightly, but shouldn't be a problem.
 115 </Para>
 116 </ListItem>
 117 </VarListEntry>
 118 <VarListEntry>
 119 <Term>Sensitivity to <Filename>.hi</Filename> interface files:</Term>
 120 <ListItem>
 121 <Para>
 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.
 127 </Para>
 128
 129 <Para>
 130 Furthermore, as sketched below, you may have big problems
 131 running programs compiled using unstable interfaces.
 132 </Para>
 133 </ListItem>
 134 </VarListEntry>
 135 <VarListEntry>
 136 <Term>&ldquo;I think GHC is producing incorrect code&rdquo;:</Term>
 137 <ListItem>
 138 <Para>
 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 &ldquo;lint&rdquo;
 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&percnt; in compile time.
 144 </Para>
 145 </ListItem>
 146 </VarListEntry>
 147 <VarListEntry>
 148 <Term>&ldquo;Why did I get a link error?&rdquo;</Term>
 149 <ListItem>
 150 <Para>
 151 If the linker complains about not finding <Literal>&lowbar;&lt;something&gt;&lowbar;fast</Literal>, then
 152 something is inconsistent: you probably didn't compile modules in the
 153 proper dependency order.
 154 </Para>
 155 </ListItem>
 156 </VarListEntry>
 157
 158 <VarListEntry>
 159 <Term>&ldquo;Is this line number right?&rdquo;</Term>
 160 <ListItem>
 161 <Para>
 162 On this score, GHC usually does pretty well, especially
 163 if you &ldquo;allow&rdquo; 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.
 166 </Para>
 167
 168 <Para>
 169 Please report line-number errors that you find particularly unhelpful.
 170 </Para>
 171 </ListItem>
 172 </VarListEntry>
 173 </VariableList>
 174 </Para>
 175
 176 </Sect1>
 177
 178 <Sect1 id="wrong-compilee">
 179 <Title>When your program &ldquo;does the wrong thing&rdquo;
 180 </Title>
 181
 182 <Para>
 183 <IndexTerm><Primary>problems running your program</Primary></IndexTerm>
 184 </Para>
 185
 186 <Para>
 187 (For advice about overly slow or memory-hungry Haskell programs,
 188 please see <XRef LinkEnd="sooner-faster-quicker">).
 189 </Para>
 190
 191 <Para>
 192 <VariableList>
 193
 194 <VarListEntry>
 195 <Term>&ldquo;Help! My program crashed!&rdquo;</Term>
 196 <ListItem>
 197 <Para>
 198 (e.g., a `segmentation fault' or `core dumped')
 199 <IndexTerm><Primary>segmentation fault</Primary></IndexTerm>
 200 </Para>
 201
 202 <Para>
 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
 208 source).
 209 </Para>
 210
 211 <Para>
 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 &ldquo;arity&rdquo; of a value), then duff code may result.
 216 Furthermore, arities may change even if types do not.
 217 </Para>
 218
 219 <Para>
 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.
 222 </Para>
 223
 224 <Para>
 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.
 228 </Para>
 229
 230 <Para>
 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">.
 235 </Para>
 236
 237 <Para>
 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.
 240 </Para>
 241
 242 <Para>
 243 So, before you report a bug because of a core dump, you should probably:
 244
 245 <Screen>
 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...
 250 </Screen>
 251
 252 </Para>
 253
 254 <Para>
 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.
 257 </Para>
 258
 259 <Para>
 260 If you are interested in hard-core debugging of a crashing
 261 GHC-compiled program, please see <XRef LinkEnd="hard-core-debug">.
 262 </Para>
 263 </ListItem>
 264 </VarListEntry>
 265 <VarListEntry>
 266 <Term>&ldquo;My program entered an `absent' argument.&rdquo;</Term>
 267 <ListItem>
 268 <Para>
 269 This is definitely caused by a bug in GHC. Please report it (see <xref
 270 linkend="bug-reporting">).
 271 </Para>
 272 </ListItem>
 273 </VarListEntry>
 274 <VarListEntry>
 275 <Term>&ldquo;What's with this `arithmetic (or `floating') exception' &rdquo;?</Term>
 276 <ListItem>
 277 <Para>
 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).
 283 </Para>
 284 </ListItem>
 285 </VarListEntry>
 286 </VariableList>
 287 </Para>
 288
 289 </Sect1>
 290
 291 <Sect1 id="hard-core-debug">
 292 <Title>Hard-core debugging of GHC-compiled programs
 293 </Title>
 294
 295 <Para>
 296 <IndexTerm><Primary>debugging, hard-core</Primary></IndexTerm>
 297 </Para>
 298
 299 <Para>
 300 If your program is crashing, you should almost surely file a bug
 301 report, as outlined in <xref linkend="bug-reporting">.
 302 </Para>
 303
 304 <Para>
 305 This section suggests ways to Make Further Progress Anyway.
 306 </Para>
 307
 308 <Para>
 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
 311 flag.
 312
 313 <ItemizedList>
 314 <ListItem>
 315
 316 <Para>
 317 If it crashes <Emphasis>without</Emphasis> garbage-collecting, then it is
 318 definitely <Emphasis>not</Emphasis> a GC bug.
 319 </Para>
 320 </ListItem>
 321 <ListItem>
 322
 323 <Para>
 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.
 326 </Para>
 327 </ListItem>
 328 <ListItem>
 329
 330 <Para>
 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.
 334 </Para>
 335 </ListItem>
 336
 337 </ItemizedList>
 338
 339 </Para>
 340
 341 <Para>
 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!!!)
 345 </Para>
 346
 347 <Para>
 348 ToDo: more here?
 349 </Para>
 350
 351 </Sect1>
 352
 353 </Chapter>
 354
 355 <!-- Emacs stuff:
 356      ;;; Local Variables: ***
 357      ;;; mode: sgml ***
 358      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 359      ;;; End: ***
 360  -->