From: simonmar Date: Tue, 30 Apr 2002 16:23:47 +0000 (+0000) Subject: [project @ 2002-04-30 16:23:47 by simonmar] X-Git-Tag: Approx_11550_changesets_converted~2079 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=359591c5fbf8003fe9d499a974ff0f7c01e053b7 [project @ 2002-04-30 16:23:47 by simonmar] Remove some out of date stuff and tidy up the markup. --- diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index e36d13c..93585da 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -1,246 +1,168 @@ - -What to do when something goes wrong - - - -problems - - - -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 :-! - - - -(, which describes Glasgow -Haskell's shortcomings vs. the Haskell language definition, may also -be of interest.) - - - -When the compiler “does the wrong thing” - - - -compiler problems -problems with the compiler - - - - - - -“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). - - - -Just say make all EXTRA_HC_OPTS=-H<a reasonable number> and see -how you get along. - - - -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… - - - -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. - - - -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. - - - -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. - - - - - -“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. - - - -Please report line-number errors that you find particularly unhelpful. - - - - - - - - - -When your program “does the wrong thing” - - - -problems running your program - - - -(For advice about overly slow or memory-hungry Haskell programs, -please see ). - - - - - - -“Help! My program crashed!” - - -(e.g., a `segmentation fault' or `core dumped') -segmentation fault - - - -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. - - - -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. - - - -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. - - - -So, before you report a bug because of a core dump, you should probably: + + What to do when something goes wrong + + problems + + 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 + :-! + + (, which describes Glasgow + Haskell's shortcomings vs. the Haskell language definition, may + also be of interest.) + + + When the compiler “does the wrong thing” + + compiler problems + problems with the compiler + + + + “Help! The compiler crashed (or `panic'd)!” + + These events are always bugs in + the GHC system—please report them. + + + + + “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 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. + + 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. + + + + + “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. + + Please report line-number errors that you find + particularly unhelpful. + + + + + + + When your program “does the wrong thing” + + problems running your program + + (For advice about overly slow or memory-hungry Haskell + programs, please see ). + + + + + “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). + + 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. + + 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 . + + 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: % rm *.o # scrub your object files @@ -249,108 +171,42 @@ So, before you report a bug because of a core dump, you should probably: % ./my_prog ... # retry... - - - -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. - - - - - - - - -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!!!) - - - -ToDo: more here? - - - - - + 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 + platform). Divide-by-zero may cause an + untrapped exception (please report it if it does). + + + + + + +