Another s/autrijus/audreyt/ in comments.
[ghc-hetmet.git] / 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  -->