Improve documentation of INLINE pragmas
[ghc.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 -->