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).
+
+
+
+
+
+
+
+
+