<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>&mdash;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&mdash;we love mail from irate users
  :-!</para>

  <para>(<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
  Haskell's shortcomings vs.&nbsp;the Haskell language definition, may
  also be of interest.)</para>

  <sect1 id="wrong-compiler">
    <title>When the compiler &ldquo;does the wrong thing&rdquo;</title>

    <Indexterm><Primary>compiler problems</Primary></Indexterm>
    <Indexterm><Primary>problems with the compiler</Primary></Indexterm>

    <variablelist>
      <varlistentry>
	<term>&ldquo;Help! The compiler crashed (or `panic'd)!&rdquo;</term>
	<listitem>
	  <para>These events are <Emphasis>always</Emphasis> bugs in
	  the GHC system&mdash;please report them.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>&ldquo;This is a terrible error message.&rdquo;</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>&ldquo;What about this warning from the C
	compiler?&rdquo;</term>
	<listitem>
	  <para>For example: &ldquo;&hellip;warning: `Foo' declared
          `static' but never defined.&rdquo; 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>&ldquo;I think GHC is producing incorrect code&rdquo;:</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
          &ldquo;lint&rdquo; 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&percnt; in compile time.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>&ldquo;Why did I get a link error?&rdquo;</term>
	<listitem>
	  <para>If the linker complains about not finding
          <literal>&lowbar;&lt;something&gt;&lowbar;fast</literal>,
          then something is inconsistent: you probably didn't compile
          modules in the proper dependency order.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>&ldquo;Is this line number right?&rdquo;</term>
	<listitem>
	  <para>On this score, GHC usually does pretty well,
          especially if you &ldquo;allow&rdquo; 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 &ldquo;does the wrong thing&rdquo;</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>&ldquo;Help! My program crashed!&rdquo;</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 &ldquo;arity&rdquo; 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>&ldquo;My program entered an `absent' argument.&rdquo;</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>&ldquo;What's with this `arithmetic (or `floating')
	exception' &rdquo;?</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: sgml ***
     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
     ;;; End: ***
 -->
