ghc/docs/users_guide/gone_wrong.sgml

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