docs/users_guide/gone_wrong.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="wrong">
   3   <title>What to do when something goes wrong</title>
   4
   5   <indexterm><primary>problems</primary></indexterm>
   6
   7   <para>If you still have a problem after consulting this section,
   8   then you may have found a <emphasis>bug</emphasis>&mdash;please
   9   report it!  See <xref linkend="bug-reporting"/> for details on how to
  10   report a bug and a list of things we'd like to know about your bug.
  11   If in doubt, send a report&mdash;we love mail from irate users
  12   :-!</para>
  13
  14   <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow
  15   Haskell's shortcomings vs.&nbsp;the Haskell language definition, may
  16   also be of interest.)</para>
  17
  18   <sect1 id="wrong-compiler">
  19     <title>When the compiler &ldquo;does the wrong thing&rdquo;</title>
  20
  21     <indexterm><primary>compiler problems</primary></indexterm>
  22     <indexterm><primary>problems with the compiler</primary></indexterm>
  23
  24     <variablelist>
  25       <varlistentry>
  26         <term>&ldquo;Help! The compiler crashed (or `panic'd)!&rdquo;</term>
  27         <listitem>
  28           <para>These events are <emphasis>always</emphasis> bugs in
  29           the GHC system&mdash;please report them.</para>
  30         </listitem>
  31       </varlistentry>
  32
  33       <varlistentry>
  34         <term>&ldquo;This is a terrible error message.&rdquo;</term>
  35         <listitem>
  36           <para>If you think that GHC could have produced a better
  37           error message, please report it as a bug.</para>
  38         </listitem>
  39       </varlistentry>
  40
  41       <varlistentry>
  42         <term>&ldquo;What about this warning from the C
  43         compiler?&rdquo;</term>
  44         <listitem>
  45           <para>For example: &ldquo;&hellip;warning: `Foo' declared
  46           `static' but never defined.&rdquo; Unsightly, but shouldn't
  47           be a problem.</para>
  48         </listitem>
  49       </varlistentry>
  50
  51       <varlistentry>
  52         <term>Sensitivity to <filename>.hi</filename> interface files:</term>
  53         <listitem>
  54           <para>GHC is very sensitive about interface files.  For
  55           example, if it picks up a non-standard
  56           <filename>Prelude.hi</filename> file, pretty terrible things
  57           will happen.  If you turn on
  58           <option>-fno-implicit-prelude</option><indexterm><primary>-fno-implicit-prelude
  59           option</primary></indexterm>, the compiler will almost
  60           surely die, unless you know what you are doing.</para>
  61
  62           <para>Furthermore, as sketched below, you may have big
  63           problems running programs compiled using unstable
  64           interfaces.</para>
  65         </listitem>
  66       </varlistentry>
  67
  68       <varlistentry>
  69         <term>&ldquo;I think GHC is producing incorrect code&rdquo;:</term>
  70         <listitem>
  71           <para>Unlikely :-) A useful be-more-paranoid option to give
  72           to GHC is
  73           <option>-dcore-lint</option><indexterm><primary>-dcore-lint
  74           option</primary></indexterm>; this causes a
  75           &ldquo;lint&rdquo; pass to check for errors (notably type
  76           errors) after each Core-to-Core transformation pass.  We run
  77           with <option>-dcore-lint</option> on all the time; it costs
  78           about 5&percnt; in compile time.</para>
  79         </listitem>
  80       </varlistentry>
  81
  82       <varlistentry>
  83         <term>&ldquo;Why did I get a link error?&rdquo;</term>
  84         <listitem>
  85           <para>If the linker complains about not finding
  86           <literal>&lowbar;&lt;something&gt;&lowbar;fast</literal>,
  87           then something is inconsistent: you probably didn't compile
  88           modules in the proper dependency order.</para>
  89         </listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term>&ldquo;Is this line number right?&rdquo;</term>
  94         <listitem>
  95           <para>On this score, GHC usually does pretty well,
  96           especially if you &ldquo;allow&rdquo; it to be off by one or
  97           two.  In the case of an instance or class declaration, the
  98           line number may only point you to the declaration, not to a
  99           specific method.</para>
 100
 101           <para>Please report line-number errors that you find
 102           particularly unhelpful.</para>
 103         </listitem>
 104       </varlistentry>
 105     </variablelist>
 106   </sect1>
 107
 108   <sect1 id="wrong-compilee">
 109     <title>When your program &ldquo;does the wrong thing&rdquo;</title>
 110
 111     <indexterm><primary>problems running your program</primary></indexterm>
 112
 113     <para>(For advice about overly slow or memory-hungry Haskell
 114     programs, please see <xref
 115     linkend="sooner-faster-quicker"/>).</para>
 116
 117     <variablelist>
 118
 119       <varlistentry>
 120         <term>&ldquo;Help! My program crashed!&rdquo;</term>
 121         <listitem>
 122           <para>(e.g., a `segmentation fault' or `core dumped')
 123           <indexterm><primary>segmentation
 124           fault</primary></indexterm></para>
 125
 126           <para>If your program has no foreign calls in it, and no
 127           calls to known-unsafe functions (such as
 128           <literal>unsafePerformIO</literal>) then a crash is always a
 129           BUG in the GHC system, except in one case: If your program
 130           is made of several modules, each module must have been
 131           compiled after any modules on which it depends (unless you
 132           use <filename>.hi-boot</filename> files, in which case these
 133           <emphasis>must</emphasis> be correct with respect to the
 134           module source).</para>
 135
 136           <para>For example, if an interface is lying about the type
 137           of an imported value then GHC may well generate duff code
 138           for the importing module.  <emphasis>This applies to pragmas
 139           inside interfaces too!</emphasis> If the pragma is lying
 140           (e.g., about the &ldquo;arity&rdquo; of a value), then duff
 141           code may result.  Furthermore, arities may change even if
 142           types do not.</para>
 143
 144           <para>In short, if you compile a module and its interface
 145           changes, then all the modules that import that interface
 146           <emphasis>must</emphasis> be re-compiled.</para>
 147
 148           <para>A useful option to alert you when interfaces change is
 149           <option>-hi-diffs</option><indexterm><primary>-hi-diffs
 150           option</primary></indexterm>.  It will run
 151           <command>diff</command> on the changed interface file,
 152           before and after, when applicable.</para>
 153
 154           <para>If you are using <command>make</command>, GHC can
 155           automatically generate the dependencies required in order to
 156           make sure that every module <emphasis>is</emphasis>
 157           up-to-date with respect to its imported interfaces.  Please
 158           see <xref linkend="sec-makefile-dependencies"/>.</para>
 159
 160           <para>If you are down to your
 161           last-compile-before-a-bug-report, we would recommend that
 162           you add a <option>-dcore-lint</option> option (for extra
 163           checking) to your compilation options.</para>
 164
 165           <para>So, before you report a bug because of a core dump,
 166           you should probably:</para>
 167
 168 <screen>
 169 % rm *.o        # scrub your object files
 170 % make my_prog  # re-make your program; use -hi-diffs to highlight changes;
 171                 # as mentioned above, use -dcore-lint to be more paranoid
 172 % ./my_prog ... # retry...
 173 </screen>
 174
 175           <para>Of course, if you have foreign calls in your program
 176           then all bets are off, because you can trash the heap, the
 177           stack, or whatever.</para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term>&ldquo;My program entered an `absent' argument.&rdquo;</term>
 183         <listitem>
 184           <para>This is definitely caused by a bug in GHC. Please
 185           report it (see <xref linkend="bug-reporting"/>).</para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term>&ldquo;What's with this `arithmetic (or `floating')
 191         exception' &rdquo;?</term>
 192         <listitem>
 193           <para><literal>Int</literal>, <literal>Float</literal>, and
 194           <literal>Double</literal> arithmetic is
 195           <emphasis>unchecked</emphasis>.  Overflows, underflows and
 196           loss of precision are either silent or reported as an
 197           exception by the operating system (depending on the
 198           platform).  Divide-by-zero <emphasis>may</emphasis> cause an
 199           untrapped exception (please report it if it does).</para>
 200         </listitem>
 201       </varlistentry>
 202
 203     </variablelist>
 204   </sect1>
 205
 206 </chapter>
 207
 208 <!-- Emacs stuff:
 209      ;;; Local Variables: ***
 210      ;;; mode: xml ***
 211      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 212      ;;; End: ***
 213  -->