[[project @ 2002-04-30 16:23:47 by simonmar] simonmar**20020430162347 Remove some out of date stuff and tidy up the markup. ] { hunk ./ghc/docs/users_guide/gone_wrong.sgml 1 - -What to do when something goes wrong - + + What to do when something goes wrong hunk ./ghc/docs/users_guide/gone_wrong.sgml 4 - -problems - + problems hunk ./ghc/docs/users_guide/gone_wrong.sgml 6 - -If you still have a problem after consulting this section, then you -may have found a bug—please report it! See - for details on how to report a bug and -a list of things we'd like to know about your bug. If in doubt, send -a report—we love mail from irate users :-! - + If you still have a problem after consulting this section, + then you may have found a bug—please + report it! See for details on how to + report a bug and a list of things we'd like to know about your bug. + If in doubt, send a report—we love mail from irate users + :-! hunk ./ghc/docs/users_guide/gone_wrong.sgml 13 - -(, which describes Glasgow -Haskell's shortcomings vs. the Haskell language definition, may also -be of interest.) - + (, which describes Glasgow + Haskell's shortcomings vs. the Haskell language definition, may + also be of interest.) hunk ./ghc/docs/users_guide/gone_wrong.sgml 17 - -When the compiler “does the wrong thing” - + + When the compiler “does the wrong thing” hunk ./ghc/docs/users_guide/gone_wrong.sgml 20 - -compiler problems -problems with the compiler - + compiler problems + problems with the compiler hunk ./ghc/docs/users_guide/gone_wrong.sgml 23 - - + + + “Help! The compiler crashed (or `panic'd)!” + + These events are always bugs in + the GHC system—please report them. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 32 - -“Help! The compiler crashed (or `panic'd)!” - - -These events are always bugs in the GHC system—please report them. - - - - -“The compiler ran out of heap (or stack) when compiling itself!” - - -It happens. We try to supply reasonable flags for -ghc/compiler/ and ghc/lib/, but GHC's memory consumption -can vary by platform (e.g., on a 64-bit machine). - + + “This is a terrible error message.” + + If you think that GHC could have produced a better + error message, please report it as a bug. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 40 - -Just say make all EXTRA_HC_OPTS=-H<a reasonable number> and see -how you get along. - + + “What about this warning from the C + compiler?” + + For example: “…warning: `Foo' declared + `static' but never defined.” Unsightly, but shouldn't + be a problem. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 50 - -Note that this is less likely to happen if you are compiling with GHC -4.00 or later, since the introduction of the dynamically expanding -heap. - - - - -“The compiler died with a pattern-matching error.” - - -This is a bug just as surely as a “panic.” Please report it. - - - - -“This is a terrible error message.” - - -If you think that GHC could have produced a better error message, -please report it as a bug. - - - - -“What about these `trace' messages from GHC?” - - -Almost surely not a problem. About some specific cases… - + + Sensitivity to .hi interface files: + + GHC is very sensitive about interface files. For + example, if it picks up a non-standard + Prelude.hi file, pretty terrible things + will happen. If you turn on + -fno-implicit-prelude + option, the compiler will almost + surely die, unless you know what you are doing. hunk ./ghc/docs/users_guide/gone_wrong.sgml 61 - -Simplifier still going after N iterations: - - -Sad, but harmless. You can change the number with a --fmax-simplifier-iterations<N> option option (no space); -and you can see what actions took place in each iteration by -turning on the --fshow-simplifier-progress option option. - + Furthermore, as sketched below, you may have big + problems running programs compiled using unstable + interfaces. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 67 - -If the simplifier definitely seems to be “looping,” please report -it. - - - - - - - - -“What about this warning from the C compiler?” - - -For example: “…warning: `Foo' declared `static' but never defined.” -Unsightly, but shouldn't be a problem. - - - - -Sensitivity to .hi interface files: - - -GHC is very sensitive about interface files. For example, if it picks -up a non-standard Prelude.hi file, pretty terrible things will -happen. If you turn on --fno-implicit-prelude option, the -compiler will almost surely die, unless you know what you are doing. - + + “I think GHC is producing incorrect code”: + + Unlikely :-) A useful be-more-paranoid option to give + to GHC is + -dcore-lint + option; this causes a + “lint” pass to check for errors (notably type + errors) after each Core-to-Core transformation pass. We run + with on all the time; it costs + about 5% in compile time. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 81 - -Furthermore, as sketched below, you may have big problems -running programs compiled using unstable interfaces. - - - - -“I think GHC is producing incorrect code”: - - -Unlikely :-) A useful be-more-paranoid option to give to GHC is --dcore-lint option; this causes a “lint” -pass to check for errors (notably type errors) after each Core-to-Core -transformation pass. We run with on all the time; it -costs about 5% in compile time. - - - - -“Why did I get a link error?” - - -If the linker complains about not finding _<something>_fast, then -something is inconsistent: you probably didn't compile modules in the -proper dependency order. - - - + + “Why did I get a link error?” + + If the linker complains about not finding + _<something>_fast, + then something is inconsistent: you probably didn't compile + modules in the proper dependency order. + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 91 - -“Is this line number right?” - - -On this score, GHC usually does pretty well, especially -if you “allow” it to be off by one or two. In the case of an -instance or class declaration, the line number -may only point you to the declaration, not to a specific method. - + + “Is this line number right?” + + On this score, GHC usually does pretty well, + especially if you “allow” it to be off by one or + two. In the case of an instance or class declaration, the + line number may only point you to the declaration, not to a + specific method. hunk ./ghc/docs/users_guide/gone_wrong.sgml 100 - -Please report line-number errors that you find particularly unhelpful. - - - - - + Please report line-number errors that you find + particularly unhelpful. + + + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 107 - + + When your program “does the wrong thing” hunk ./ghc/docs/users_guide/gone_wrong.sgml 110 - -When your program “does the wrong thing” - + problems running your program hunk ./ghc/docs/users_guide/gone_wrong.sgml 112 - -problems running your program - + (For advice about overly slow or memory-hungry Haskell + programs, please see ). hunk ./ghc/docs/users_guide/gone_wrong.sgml 116 - -(For advice about overly slow or memory-hungry Haskell programs, -please see ). - + hunk ./ghc/docs/users_guide/gone_wrong.sgml 118 - - + + “Help! My program crashed!” + + (e.g., a `segmentation fault' or `core dumped') + segmentation + fault hunk ./ghc/docs/users_guide/gone_wrong.sgml 125 - -“Help! My program crashed!” - - -(e.g., a `segmentation fault' or `core dumped') -segmentation fault - + If your program has no foreign calls in it, and no + calls to known-unsafe functions (such as + unsafePerformIO) then a crash is always a + BUG in the GHC system, except in one case: If your program + is made of several modules, each module must have been + compiled after any modules on which it depends (unless you + use .hi-boot files, in which case these + must be correct with respect to the + module source). hunk ./ghc/docs/users_guide/gone_wrong.sgml 135 - -If your program has no foreign calls in it, then a crash is always a BUG in -the GHC system, except in one case: If your program is made of several -modules, each module must have been compiled after any modules on which it -depends (unless you use .hi-boot files, in which case -these must be correct with respect to the module -source). - + For example, if an interface is lying about the type + of an imported value then GHC may well generate duff code + for the importing module. This applies to pragmas + inside interfaces too! If the pragma is lying + (e.g., about the “arity” of a value), then duff + code may result. Furthermore, arities may change even if + types do not. hunk ./ghc/docs/users_guide/gone_wrong.sgml 143 - -For example, if an interface is lying about the type of an imported -value then GHC may well generate duff code for the importing module. -This applies to pragmas inside interfaces too! If the pragma is -lying (e.g., about the “arity” of a value), then duff code may result. -Furthermore, arities may change even if types do not. - + In short, if you compile a module and its interface + changes, then all the modules that import that interface + must be re-compiled. hunk ./ghc/docs/users_guide/gone_wrong.sgml 147 - -In short, if you compile a module and its interface changes, then all -the modules that import that interface must be re-compiled. - + A useful option to alert you when interfaces change is + -hi-diffs + option. It will run + diff on the changed interface file, + before and after, when applicable. hunk ./ghc/docs/users_guide/gone_wrong.sgml 153 - -A useful option to alert you when interfaces change is --hi-diffs option. It will run diff on the -changed interface file, before and after, when applicable. - + If you are using make, GHC can + automatically generate the dependencies required in order to + make sure that every module is + up-to-date with respect to its imported interfaces. Please + see . hunk ./ghc/docs/users_guide/gone_wrong.sgml 159 - -If you are using make, GHC can automatically -generate the dependencies required in order to make sure that every -module is up-to-date with respect to its imported -interfaces. Please see . - + If you are down to your + last-compile-before-a-bug-report, we would recommend that + you add a option (for extra + checking) to your compilation options. hunk ./ghc/docs/users_guide/gone_wrong.sgml 164 - -If you are down to your last-compile-before-a-bug-report, we would -recommend that you add a option (for extra checking) to your compilation options. - - - -So, before you report a bug because of a core dump, you should probably: + So, before you report a bug because of a core dump, + you should probably: hunk ./ghc/docs/users_guide/gone_wrong.sgml 174 - - - -Of course, if you have foreign calls in your program then all -bets are off, because you can trash the heap, the stack, or whatever. - - - -If you are interested in hard-core debugging of a crashing -GHC-compiled program, please see . - - - - -“My program entered an `absent' argument.” - - -This is definitely caused by a bug in GHC. Please report it (see ). - - - - -“What's with this `arithmetic (or `floating') exception' ”? - - -Int, Float, and Double arithmetic is unchecked. -Overflows, underflows and loss of precision are either silent or -reported as an exception by the operating system (depending on the -architecture). Divide-by-zero may cause an untrapped -exception (please report it if it does). - - - - - - - - - -Hard-core debugging of GHC-compiled programs - - - -debugging, hard-core - - - -If your program is crashing, you should almost surely file a bug -report, as outlined in . - - - -This section suggests ways to Make Further Progress Anyway. - - - -The first thing to establish is: Is it a garbage-collection (GC) bug? -Try your program with a very large heap and a RTS -flag. - - - - - -If it crashes without garbage-collecting, then it is -definitely not a GC bug. - - - - - -If you can make it crash with one heap size but not with another, then -it probably is a GC bug. - - - - - -If it crashes with the normal collector, but not when you force -two-space collection ( runtime flag), then it -probably is a GC bug. - - - - + Of course, if you have foreign calls in your program + then all bets are off, because you can trash the heap, the + stack, or whatever. hunk ./ghc/docs/users_guide/gone_wrong.sgml 178 - + If you are interested in hard-core debugging of a + crashing GHC-compiled program, please see . + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 184 - -If it is a GC bug, you may be able to avoid it by -using a particular heap size or by using a -runtime flag. (But don't forget to report the bug!!!) - + + “My program entered an `absent' argument.” + + This is definitely caused by a bug in GHC. Please + report it (see ). + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 192 - -ToDo: more here? - + + “What's with this `arithmetic (or `floating') + exception' ”? + + Int, Float, and + Double arithmetic is + unchecked. Overflows, underflows and + loss of precision are either silent or reported as an + exception by the operating system (depending on the + platform). Divide-by-zero may cause an + untrapped exception (please report it if it does). + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 206 - + + hunk ./ghc/docs/users_guide/gone_wrong.sgml 209 - + }