X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fgone_wrong.sgml;h=d4fc7f9ae8b9c563a609555a415d026723a3f9f5;hb=2dfd507259664e6f28df4a9467a8de34d01d70a0;hp=b5910c9960e08646ed9c8b3a2f1f6da3d9157e3e;hpb=7db602a0d8f840362c455650cbddc1ecc04ec43d;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index b5910c9..d4fc7f9 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -1,459 +1,212 @@ - -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 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. - - - - -“What's a `consistency error'?” - - -(These are reported just after linking your program.) - - - -You tried to link incompatible object files, e.g., normal ones -(registerised, Appel garbage-collector) with profiling ones (two-space -collector). Or those compiled by a previous version of GHC -with an incompatible newer version. - - - -If you run nm -o *.o | egrep 't (cc|hsc)\.' (or, on -unregisterised files: what *.o), you'll see all the consistency -tags/strings in your object files. They must all be the same! -(ToDo: tell you what they mean…) - - - - -“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 _ccall_s/_casm_s 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, a useful tool to make sure that every module -is up-to-date with respect to its imported interfaces is -mkdependHS (which comes with GHC). 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 % make my_prog # re-make your program; use -hi-diffs to highlight changes; # as mentioned above, use -dcore-lint to be more paranoid % ./my_prog ... # retry... - - - - - -Of course, if you have _ccall_s/_casm_s 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. - - - - -“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). - - - - - - - - - -How to report a bug in the GHC system - - - -bug reports - - - -Glasgow Haskell is a changing system so there are sure to be bugs in -it. Please report them to glasgow-haskell-bugs@haskell.org! (However, please -check the earlier part of this section to be sure it's not a known -not-really-a problem.) - - - -The name of the bug-reporting game is: facts, facts, facts. -Don't omit them because “Oh, they won't be interested…” - - - - - - - - - What kind of machine are you running on, and exactly what -version of the operating system are you using? (uname -a or cat -/etc/motd will show the desired information.) - - - - - - - What version of GCC are you using? gcc -v will tell you. - - - - - - - Run the sequence of compiles/runs that caused the offending -behaviour, capturing all the input/output in a “script” (a UNIX -command) or in an Emacs shell window. We'd prefer to see the whole -thing. - - - - - - - Be sure any Haskell compilations are run with a (verbose) -flag, so we can see exactly what was run, what versions of things you -have, etc. - - - - - - - What is the program behaviour that is wrong, in your opinion? - - - - - - - If practical, please send enough source files/interface files -for us to duplicate the problem. - - - - - - - If you are a Hero and track down the problem in the -compilation-system sources, please send us patches relative to a known -released version of GHC, or whole files if you prefer. - - - - - - - - - - - -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 previous sections. - - - -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. + + + + + “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). + + + + + + + + +