diff options
Diffstat (limited to 'docs/users_guide/gone_wrong.xml')
| -rw-r--r-- | docs/users_guide/gone_wrong.xml | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/docs/users_guide/gone_wrong.xml b/docs/users_guide/gone_wrong.xml new file mode 100644 index 0000000000..d31087c164 --- /dev/null +++ b/docs/users_guide/gone_wrong.xml @@ -0,0 +1,213 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<chapter id="wrong"> + <title>What to do when something goes wrong</title> + + <indexterm><primary>problems</primary></indexterm> + + <para>If you still have a problem after consulting this section, + then you may have found a <emphasis>bug</emphasis>—please + report it! See <xref linkend="bug-reporting"/> 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 + :-!</para> + + <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow + Haskell's shortcomings vs. the Haskell language definition, may + also be of interest.)</para> + + <sect1 id="wrong-compiler"> + <title>When the compiler “does the wrong thing”</title> + + <indexterm><primary>compiler problems</primary></indexterm> + <indexterm><primary>problems with the compiler</primary></indexterm> + + <variablelist> + <varlistentry> + <term>“Help! The compiler crashed (or `panic'd)!”</term> + <listitem> + <para>These events are <emphasis>always</emphasis> bugs in + the GHC system—please report them.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“This is a terrible error message.”</term> + <listitem> + <para>If you think that GHC could have produced a better + error message, please report it as a bug.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“What about this warning from the C + compiler?”</term> + <listitem> + <para>For example: “…warning: `Foo' declared + `static' but never defined.” Unsightly, but shouldn't + be a problem.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Sensitivity to <filename>.hi</filename> interface files:</term> + <listitem> + <para>GHC is very sensitive about interface files. For + example, if it picks up a non-standard + <filename>Prelude.hi</filename> file, pretty terrible things + will happen. If you turn on + <option>-fno-implicit-prelude</option><indexterm><primary>-fno-implicit-prelude + option</primary></indexterm>, the compiler will almost + surely die, unless you know what you are doing.</para> + + <para>Furthermore, as sketched below, you may have big + problems running programs compiled using unstable + interfaces.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“I think GHC is producing incorrect code”:</term> + <listitem> + <para>Unlikely :-) A useful be-more-paranoid option to give + to GHC is + <option>-dcore-lint</option><indexterm><primary>-dcore-lint + option</primary></indexterm>; this causes a + “lint” pass to check for errors (notably type + errors) after each Core-to-Core transformation pass. We run + with <option>-dcore-lint</option> on all the time; it costs + about 5% in compile time.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“Why did I get a link error?”</term> + <listitem> + <para>If the linker complains about not finding + <literal>_<something>_fast</literal>, + then something is inconsistent: you probably didn't compile + modules in the proper dependency order.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“Is this line number right?”</term> + <listitem> + <para>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.</para> + + <para>Please report line-number errors that you find + particularly unhelpful.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="wrong-compilee"> + <title>When your program “does the wrong thing”</title> + + <indexterm><primary>problems running your program</primary></indexterm> + + <para>(For advice about overly slow or memory-hungry Haskell + programs, please see <xref + linkend="sooner-faster-quicker"/>).</para> + + <variablelist> + + <varlistentry> + <term>“Help! My program crashed!”</term> + <listitem> + <para>(e.g., a `segmentation fault' or `core dumped') + <indexterm><primary>segmentation + fault</primary></indexterm></para> + + <para>If your program has no foreign calls in it, and no + calls to known-unsafe functions (such as + <literal>unsafePerformIO</literal>) 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 <filename>.hi-boot</filename> files, in which case these + <emphasis>must</emphasis> be correct with respect to the + module source).</para> + + <para>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. <emphasis>This applies to pragmas + inside interfaces too!</emphasis> 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.</para> + + <para>In short, if you compile a module and its interface + changes, then all the modules that import that interface + <emphasis>must</emphasis> be re-compiled.</para> + + <para>A useful option to alert you when interfaces change is + <option>-hi-diffs</option><indexterm><primary>-hi-diffs + option</primary></indexterm>. It will run + <command>diff</command> on the changed interface file, + before and after, when applicable.</para> + + <para>If you are using <command>make</command>, GHC can + automatically generate the dependencies required in order to + make sure that every module <emphasis>is</emphasis> + up-to-date with respect to its imported interfaces. Please + see <xref linkend="sec-makefile-dependencies"/>.</para> + + <para>If you are down to your + last-compile-before-a-bug-report, we would recommend that + you add a <option>-dcore-lint</option> option (for extra + checking) to your compilation options.</para> + + <para>So, before you report a bug because of a core dump, + you should probably:</para> + +<screen> +% 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... +</screen> + + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“My program entered an `absent' argument.”</term> + <listitem> + <para>This is definitely caused by a bug in GHC. Please + report it (see <xref linkend="bug-reporting"/>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>“What's with this `arithmetic (or `floating') + exception' ”?</term> + <listitem> + <para><literal>Int</literal>, <literal>Float</literal>, and + <literal>Double</literal> arithmetic is + <emphasis>unchecked</emphasis>. 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 <emphasis>may</emphasis> cause an + untrapped exception (please report it if it does).</para> + </listitem> + </varlistentry> + + </variablelist> + </sect1> + +</chapter> + +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** + ;;; End: *** + --> |