--- /dev/null
+<?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: ***
+ -->
projects / ghc-hetmet.git / blobdiff