fix doc bugs
[ghc.git] / docs / users_guide / bugs.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <chapter id="bugs-and-infelicities">
3 <title>Known bugs and infelicities</title>
4
5 <sect1 id="vs-Haskell-defn">
6 <title>Haskell&nbsp;standards vs.&nbsp;Glasgow Haskell: language non-compliance
7 </title>
8
9 <indexterm><primary>GHC vs the Haskell standards</primary></indexterm>
10 <indexterm><primary>Haskell standards vs GHC</primary></indexterm>
11
12 <para>
13 This section lists Glasgow Haskell infelicities in its
14 implementation of Haskell&nbsp;98 and Haskell&nbsp;2010.
15 See also the &ldquo;when things go wrong&rdquo; section
16 (<xref linkend="wrong"/>) for information about crashes,
17 space leaks, and other undesirable phenomena.
18 </para>
19
20 <para>
21 The limitations here are listed in Haskell Report order
22 (roughly).
23 </para>
24
25 <sect2 id="haskell-standards-divergence">
26 <title>Divergence from Haskell&nbsp;98 and Haskell&nbsp;2010</title>
27
28 <para>
29 By default, GHC mainly aims to behave (mostly) like a Haskell&nbsp;2010
30 compiler, although you can tell it to try to behave like a
31 particular version of the langauge with the
32 <literal>-XHaskell98</literal> and
33 <literal>-XHaskell2010</literal> flags. The known deviations
34 from the standards are described below. Unless otherwise stated,
35 the deviation applies in Haskell&nbsp;98, Haskell&nbsp;2010 and
36 the default modes.
37 </para>
38
39 <sect3 id="infelicities-lexical">
40 <title>Lexical syntax</title>
41
42 <itemizedlist>
43 <listitem>
44 <para>Certain lexical rules regarding qualified identifiers
45 are slightly different in GHC compared to the Haskell
46 report. When you have
47 <replaceable>module</replaceable><literal>.</literal><replaceable>reservedop</replaceable>,
48 such as <literal>M.\</literal>, GHC will interpret it as a
49 single qualified operator rather than the two lexemes
50 <literal>M</literal> and <literal>.\</literal>.</para>
51 </listitem>
52 </itemizedlist>
53 </sect3>
54
55 <sect3 id="infelicities-syntax">
56 <title>Context-free syntax</title>
57
58 <itemizedlist>
59 <listitem>
60 <para>In Haskell&nbsp;98 mode and by default (but not in
61 Haskell&nbsp;2010 mode), GHC is a little less strict about the
62 layout rule when used
63 in <literal>do</literal> expressions. Specifically, the
64 restriction that "a nested context must be indented further to
65 the right than the enclosing context" is relaxed to allow the
66 nested context to be at the same level as the enclosing context,
67 if the enclosing context is a <literal>do</literal>
68 expression.</para>
69
70 <para>For example, the following code is accepted by GHC:
71
72 <programlisting>
73 main = do args &lt;- getArgs
74 if null args then return [] else do
75 ps &lt;- mapM process args
76 mapM print ps</programlisting>
77
78 This behaviour is controlled by the
79 <literal>NondecreasingIndentation</literal> extension.
80 </para>
81 </listitem>
82
83 <listitem>
84 <para>GHC doesn't do the fixity resolution in expressions during
85 parsing as required by Haskell&nbsp;98 (but not by Haskell&nbsp;2010).
86 For example, according to the Haskell&nbsp;98 report, the
87 following expression is legal:
88 <programlisting>
89 let x = 42 in x == 42 == True</programlisting>
90 and parses as:
91 <programlisting>
92 (let x = 42 in x == 42) == True</programlisting>
93
94 because according to the report, the <literal>let</literal>
95 expression <quote>extends as far to the right as
96 possible</quote>. Since it can't extend past the second
97 equals sign without causing a parse error
98 (<literal>==</literal> is non-fix), the
99 <literal>let</literal>-expression must terminate there. GHC
100 simply gobbles up the whole expression, parsing like this:
101 <programlisting>
102 (let x = 42 in x == 42 == True)</programlisting></para>
103 </listitem>
104 </itemizedlist>
105 </sect3>
106
107 <sect3 id="infelicities-exprs-pats">
108 <title>Expressions and patterns</title>
109
110 <para>None known.</para>
111 </sect3>
112
113 <sect3 id="infelicities-decls">
114 <title>Declarations and bindings</title>
115
116 <para>GHC's typechecker makes all pattern bindings monomorphic
117 by default; this behaviour can be disabled with
118 <option>-XNoMonoPatBinds</option>. See <xref
119 linkend="options-language" />.</para>
120
121 <para>In its default mode, GHC does not accept datatype contexts,
122 as it has been decided to remove them from the next version of the
123 language standard. This behaviour can be controlled with the
124 <option>DatatypeContexts</option> extension.
125 See <xref linkend="datatype-contexts" />.</para>
126 </sect3>
127
128 <sect3 id="infelicities-Modules">
129 <title>Module system and interface files</title>
130
131 <para>GHC requires the use of <literal>hs-boot</literal>
132 files to cut the recursive loops among mutually recursive modules
133 as described in <xref linkend="mutual-recursion"/>. This more of an infelicity
134 than a bug: the Haskell Report says
135 (<ulink url="http://haskell.org/onlinereport/modules.html#sect5.7">Section 5.7</ulink>) "Depending on the Haskell
136 implementation used, separate compilation of mutually
137 recursive modules may require that imported modules contain
138 additional information so that they may be referenced before
139 they are compiled. Explicit type signatures for all exported
140 values may be necessary to deal with mutual recursion. The
141 precise details of separate compilation are not defined by
142 this Report."
143
144 </para>
145
146 </sect3>
147
148 <sect3 id="infelicities-numbers">
149 <title>Numbers, basic types, and built-in classes</title>
150
151 <variablelist>
152 <varlistentry>
153 <term>Multiply-defined array elements&mdash;not checked:</term>
154 <listitem>
155 <para>This code fragment should
156 elicit a fatal error, but it does not:
157
158 <programlisting>
159 main = print (array (1,1) [(1,2), (1,3)])</programlisting>
160 GHC's implementation of <literal>array</literal> takes the value of an
161 array slot from the last (index,value) pair in the list, and does no
162 checking for duplicates. The reason for this is efficiency, pure and simple.
163 </para>
164 </listitem>
165 </varlistentry>
166 </variablelist>
167
168 </sect3>
169
170 <sect3 id="infelicities-Prelude">
171 <title>In <literal>Prelude</literal> support</title>
172
173 <variablelist>
174 <varlistentry>
175 <term>Arbitrary-sized tuples</term>
176 <listitem>
177 <para>Tuples are currently limited to size 100. HOWEVER:
178 standard instances for tuples (<literal>Eq</literal>,
179 <literal>Ord</literal>, <literal>Bounded</literal>,
180 <literal>Ix</literal> <literal>Read</literal>, and
181 <literal>Show</literal>) are available
182 <emphasis>only</emphasis> up to 16-tuples.</para>
183
184 <para>This limitation is easily subvertible, so please ask
185 if you get stuck on it.</para>
186 </listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term><literal>Read</literal>ing integers</term>
191 <listitem>
192 <para>GHC's implementation of the
193 <literal>Read</literal> class for integral types accepts
194 hexadecimal and octal literals (the code in the Haskell
195 98 report doesn't). So, for example,
196 <programlisting>read "0xf00" :: Int</programlisting>
197 works in GHC.</para>
198 <para>A possible reason for this is that <literal>readLitChar</literal> accepts hex and
199 octal escapes, so it seems inconsistent not to do so for integers too.</para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><literal>isAlpha</literal></term>
205 <listitem>
206 <para>The Haskell 98 definition of <literal>isAlpha</literal>
207 is:</para>
208
209 <programlisting>isAlpha c = isUpper c || isLower c</programlisting>
210
211 <para>GHC's implementation diverges from the Haskell 98
212 definition in the sense that Unicode alphabetic characters which
213 are neither upper nor lower case will still be identified as
214 alphabetic by <literal>isAlpha</literal>.</para>
215 </listitem>
216 </varlistentry>
217
218 <varlistentry>
219 <term><literal>hGetContents</literal></term>
220 <listitem>
221 <para>
222 Lazy I/O throws an exception if an error is
223 encountered, in contrast to the Haskell 98 spec which
224 requires that errors are discarded (see Section 21.2.2
225 of the Haskell 98 report). The exception thrown is
226 the usual IO exception that would be thrown if the
227 failing IO operation was performed in the IO monad, and can
228 be caught by <literal>System.IO.Error.catch</literal>
229 or <literal>Control.Exception.catch</literal>.
230 </para>
231 </listitem>
232 </varlistentry>
233 </variablelist>
234 </sect3>
235
236 <sect3 id="infelicities-ffi">
237 <title>The Foreign Function Interface</title>
238 <variablelist>
239 <varlistentry>
240 <term><literal>hs_init()</literal> not allowed
241 after <literal>hs_exit()</literal></term>
242 <listitem>
243 <para>The FFI spec requires the implementation to support
244 re-initialising itself after being shut down
245 with <literal>hs_exit()</literal>, but GHC does not
246 currently support that.</para>
247 </listitem>
248 </varlistentry>
249 </variablelist>
250 </sect3>
251
252 </sect2>
253
254 <sect2 id="haskell-98-2010-undefined">
255 <title>GHC's interpretation of undefined behaviour in
256 Haskell&nbsp;98 and Haskell&nbsp;2010</title>
257
258 <para>This section documents GHC's take on various issues that are
259 left undefined or implementation specific in Haskell 98.</para>
260
261 <variablelist>
262 <varlistentry>
263 <term>
264 The <literal>Char</literal> type
265 <indexterm><primary><literal>Char</literal></primary><secondary>size of</secondary></indexterm>
266 </term>
267 <listitem>
268 <para>Following the ISO-10646 standard,
269 <literal>maxBound :: Char</literal> in GHC is
270 <literal>0x10FFFF</literal>.</para>
271 </listitem>
272 </varlistentry>
273
274 <varlistentry>
275 <term>
276 Sized integral types
277 <indexterm><primary><literal>Int</literal></primary><secondary>size of</secondary></indexterm>
278 </term>
279 <listitem>
280 <para>In GHC the <literal>Int</literal> type follows the
281 size of an address on the host architecture; in other words
282 it holds 32 bits on a 32-bit machine, and 64-bits on a
283 64-bit machine.</para>
284
285 <para>Arithmetic on <literal>Int</literal> is unchecked for
286 overflow<indexterm><primary>overflow</primary><secondary><literal>Int</literal></secondary>
287 </indexterm>, so all operations on <literal>Int</literal> happen
288 modulo
289 2<superscript><replaceable>n</replaceable></superscript>
290 where <replaceable>n</replaceable> is the size in bits of
291 the <literal>Int</literal> type.</para>
292
293 <para>The <literal>fromInteger</literal><indexterm><primary><literal>fromInteger</literal></primary>
294 </indexterm> function (and hence
295 also <literal>fromIntegral</literal><indexterm><primary><literal>fromIntegral</literal></primary>
296 </indexterm>) is a special case when
297 converting to <literal>Int</literal>. The value of
298 <literal>fromIntegral x :: Int</literal> is given by taking
299 the lower <replaceable>n</replaceable> bits of <literal>(abs
300 x)</literal>, multiplied by the sign of <literal>x</literal>
301 (in 2's complement <replaceable>n</replaceable>-bit
302 arithmetic). This behaviour was chosen so that for example
303 writing <literal>0xffffffff :: Int</literal> preserves the
304 bit-pattern in the resulting <literal>Int</literal>.</para>
305
306
307 <para>Negative literals, such as <literal>-3</literal>, are
308 specified by (a careful reading of) the Haskell Report as
309 meaning <literal>Prelude.negate (Prelude.fromInteger 3)</literal>.
310 So <literal>-2147483648</literal> means <literal>negate (fromInteger 2147483648)</literal>.
311 Since <literal>fromInteger</literal> takes the lower 32 bits of the representation,
312 <literal>fromInteger (2147483648::Integer)</literal>, computed at type <literal>Int</literal> is
313 <literal>-2147483648::Int</literal>. The <literal>negate</literal> operation then
314 overflows, but it is unchecked, so <literal>negate (-2147483648::Int)</literal> is just
315 <literal>-2147483648</literal>. In short, one can write <literal>minBound::Int</literal> as
316 a literal with the expected meaning (but that is not in general guaranteed).
317 </para>
318
319 <para>The <literal>fromIntegral</literal> function also
320 preserves bit-patterns when converting between the sized
321 integral types (<literal>Int8</literal>,
322 <literal>Int16</literal>, <literal>Int32</literal>,
323 <literal>Int64</literal> and the unsigned
324 <literal>Word</literal> variants), see the modules
325 <literal>Data.Int</literal> and <literal>Data.Word</literal>
326 in the library documentation.</para>
327 </listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term>Unchecked float arithmetic</term>
332 <listitem>
333 <para>Operations on <literal>Float</literal> and
334 <literal>Double</literal> numbers are
335 <emphasis>unchecked</emphasis> for overflow, underflow, and
336 other sad occurrences. (note, however, that some
337 architectures trap floating-point overflow and
338 loss-of-precision and report a floating-point exception,
339 probably terminating the
340 program)<indexterm><primary>floating-point
341 exceptions</primary></indexterm>.</para>
342 </listitem>
343 </varlistentry>
344 </variablelist>
345 </sect2>
346
347 </sect1>
348
349
350 <sect1 id="bugs">
351 <title>Known bugs or infelicities</title>
352
353 <para>The bug tracker lists bugs that have been reported in GHC but not
354 yet fixed: see the <ulink url="http://hackage.haskell.org/trac/ghc/">GHC Trac</ulink>. In addition to those, GHC also has the following known bugs
355 or infelicities. These bugs are more permanent; it is unlikely that
356 any of them will be fixed in the short term.</para>
357
358 <sect2 id="bugs-ghc">
359 <title>Bugs in GHC</title>
360
361 <itemizedlist>
362 <listitem>
363 <para> GHC can warn about non-exhaustive or overlapping
364 patterns (see <xref linkend="options-sanity"/>), and usually
365 does so correctly. But not always. It gets confused by
366 string patterns, and by guards, and can then emit bogus
367 warnings. The entire overlap-check code needs an overhaul
368 really.</para>
369 </listitem>
370
371 <listitem>
372 <para>GHC does not allow you to have a data type with a context
373 that mentions type variables that are not data type parameters.
374 For example:
375 <programlisting>
376 data C a b => T a = MkT a
377 </programlisting>
378 so that <literal>MkT</literal>'s type is
379 <programlisting>
380 MkT :: forall a b. C a b => a -> T a
381 </programlisting>
382 In principle, with a suitable class declaration with a functional dependency,
383 it's possible that this type is not ambiguous; but GHC nevertheless rejects
384 it. The type variables mentioned in the context of the data type declaration must
385 be among the type parameters of the data type.</para>
386 </listitem>
387
388 <listitem>
389 <para>GHC's inliner can be persuaded into non-termination
390 using the standard way to encode recursion via a data type:</para>
391 <programlisting>
392 data U = MkU (U -> Bool)
393
394 russel :: U -> Bool
395 russel u@(MkU p) = not $ p u
396
397 x :: Bool
398 x = russel (MkU russel)
399 </programlisting>
400
401 <para>We have never found another class of programs, other
402 than this contrived one, that makes GHC diverge, and fixing
403 the problem would impose an extra overhead on every
404 compilation. So the bug remains un-fixed. There is more
405 background in <ulink
406 url="http://research.microsoft.com/~simonpj/Papers/inlining/">
407 Secrets of the GHC inliner</ulink>.</para>
408 </listitem>
409
410 <listitem>
411 <para>GHC does not keep careful track of
412 what instance declarations are 'in scope' if they come from other packages.
413 Instead, all instance declarations that GHC has seen in other
414 packages are all in scope everywhere, whether or not the
415 module from that package is used by the command-line
416 expression. This bug affects only the <option>--make</option> mode and
417 GHCi.</para>
418 </listitem>
419
420 </itemizedlist>
421 </sect2>
422
423 <sect2 id="bugs-ghci">
424 <title>Bugs in GHCi (the interactive GHC)</title>
425 <itemizedlist>
426 <listitem>
427 <para>GHCi does not respect the <literal>default</literal>
428 declaration in the module whose scope you are in. Instead,
429 for expressions typed at the command line, you always get the
430 default default-type behaviour; that is,
431 <literal>default(Int,Double)</literal>.</para>
432
433 <para>It would be better for GHCi to record what the default
434 settings in each module are, and use those of the 'current'
435 module (whatever that is).</para>
436 </listitem>
437
438 <listitem>
439 <para>On Windows, there's a GNU ld/BFD bug
440 whereby it emits bogus PE object files that have more than
441 0xffff relocations. When GHCi tries to load a package affected by this
442 bug, you get an error message of the form
443 <screen>
444 Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
445 </screen>
446 The last time we looked, this bug still
447 wasn't fixed in the BFD codebase, and there wasn't any
448 noticeable interest in fixing it when we reported the bug
449 back in 2001 or so.
450 </para>
451 <para>The workaround is to split up the .o files that make up
452 your package into two or more .o's, along the lines of
453 how the "base" package does it.</para>
454 </listitem>
455 </itemizedlist>
456 </sect2>
457 </sect1>
458
459 </chapter>
460
461 <!-- Emacs stuff:
462 ;;; Local Variables: ***
463 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
464 ;;; End: ***
465 -->