Trac #11554 fix loopy GADTs
[ghc.git] / docs / users_guide / bugs.rst
1 .. _bugs-and-infelicities:
2
3 Known bugs and infelicities
4 ===========================
5
6 .. _vs-Haskell-defn:
7
8 Haskell standards vs. Glasgow Haskell: language non-compliance
9 --------------------------------------------------------------
10
11 .. index::
12    single: GHC vs the Haskell standards
13    single: Haskell standards vs GHC
14
15 This section lists Glasgow Haskell infelicities in its implementation of
16 Haskell 98 and Haskell 2010. See also the “when things go wrong” section
17 (:ref:`wrong`) for information about crashes, space leaks, and other
18 undesirable phenomena.
19
20 The limitations here are listed in Haskell Report order (roughly).
21
22 .. _haskell-standards-divergence:
23
24 Divergence from Haskell 98 and Haskell 2010
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26
27 By default, GHC mainly aims to behave (mostly) like a Haskell 2010
28 compiler, although you can tell it to try to behave like a particular
29 version of the language with the :ghc-flag:`-XHaskell98` and
30 :ghc-flag:`-XHaskell2010` flags. The known deviations from the standards are
31 described below. Unless otherwise stated, the deviation applies in Haskell 98,
32 Haskell 2010 and the default modes.
33
34 .. _infelicities-lexical:
35
36 Lexical syntax
37 ^^^^^^^^^^^^^^
38
39 -  Certain lexical rules regarding qualified identifiers are slightly
40    different in GHC compared to the Haskell report. When you have
41    ⟨module⟩\ ``.``\ ⟨reservedop⟩, such as ``M.\``, GHC will interpret it
42    as a single qualified operator rather than the two lexemes ``M`` and
43    ``.\``.
44
45 .. _infelicities-syntax:
46
47 Context-free syntax
48 ^^^^^^^^^^^^^^^^^^^
49
50 -  In Haskell 98 mode and by default (but not in Haskell 2010 mode), GHC
51    is a little less strict about the layout rule when used in ``do``
52    expressions. Specifically, the restriction that "a nested context
53    must be indented further to the right than the enclosing context" is
54    relaxed to allow the nested context to be at the same level as the
55    enclosing context, if the enclosing context is a ``do`` expression.
56
57    For example, the following code is accepted by GHC: ::
58
59        main = do args <- getArgs
60                  if null args then return [] else do
61                  ps <- mapM process args
62                  mapM print ps
63
64    This behaviour is controlled by the ``NondecreasingIndentation``
65    extension.
66
67 -  GHC doesn't do the fixity resolution in expressions during parsing as
68    required by Haskell 98 (but not by Haskell 2010). For example,
69    according to the Haskell 98 report, the following expression is
70    legal: ::
71
72            let x = 42 in x == 42 == True
73
74    and parses as: ::
75
76            (let x = 42 in x == 42) == True
77
78    because according to the report, the ``let`` expression “extends as
79    far to the right as possible”. Since it can't extend past the second
80    equals sign without causing a parse error (``==`` is non-fix), the
81    ``let``\-expression must terminate there. GHC simply gobbles up the
82    whole expression, parsing like this: ::
83
84            (let x = 42 in x == 42 == True)
85
86 -  The Haskell Report allows you to put a unary ``-`` preceding certain
87    expressions headed by keywords, allowing constructs like ``- case x of ...``
88    or ``- do { ... }``. GHC does not allow this. Instead, unary ``-`` is allowed
89    before only expressions that could potentially be applied as a function.
90
91
92 .. _infelicities-exprs-pats:
93
94 Expressions and patterns
95 ^^^^^^^^^^^^^^^^^^^^^^^^
96
97 In its default mode, GHC makes some programs slightly more defined than
98 they should be. For example, consider ::
99
100     f :: [a] -> b -> b
101     f [] = error "urk"
102     f (x:xs) = \v -> v
103
104     main = print (f [] `seq` True)
105
106 This should call ``error`` but actually prints ``True``. Reason: GHC
107 eta-expands ``f`` to
108
109 ::
110
111     f :: [a] -> b -> b
112     f []     v = error "urk"
113     f (x:xs) v = v
114
115 This improves efficiency slightly but significantly for most programs,
116 and is bad for only a few. To suppress this bogus "optimisation" use
117 ``-fpedantic-bottoms``.
118
119 .. _infelicities-decls:
120
121 Declarations and bindings
122 ^^^^^^^^^^^^^^^^^^^^^^^^^
123
124 In its default mode, GHC does not accept datatype contexts, as it has
125 been decided to remove them from the next version of the language
126 standard. This behaviour can be controlled with the ``DatatypeContexts``
127 extension. See :ref:`datatype-contexts`.
128
129 .. _infelicities-Modules:
130
131 Module system and interface files
132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
133
134 GHC requires the use of ``hs-boot`` files to cut the recursive loops
135 among mutually recursive modules as described in
136 :ref:`mutual-recursion`. This more of an infelicity than a bug: the
137 Haskell Report says (`Section
138 5.7 <http://haskell.org/onlinereport/modules.html#sect5.7>`__)
139
140     "Depending on the Haskell implementation used, separate compilation of
141     mutually recursive modules may require that imported modules contain
142     additional information so that they may be referenced before they are
143     compiled. Explicit type signatures for all exported values may be
144     necessary to deal with mutual recursion. The precise details of separate
145     compilation are not defined by this Report."
146
147 .. _infelicities-numbers:
148
149 Numbers, basic types, and built-in classes
150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151
152 ``Num`` superclasses
153     The ``Num`` class does not have ``Show`` or ``Eq`` superclasses.
154
155     
156     You can make code that works with both Haskell98/Haskell2010 and GHC
157     by:
158
159     -  Whenever you make a ``Num`` instance of a type, also make
160         ``Show`` and ``Eq`` instances, and
161
162     -  Whenever you give a function, instance or class a ``Num t``
163         constraint, also give it ``Show t`` and ``Eq t`` constraints.
164
165 ``Bits`` superclasses
166     The ``Bits`` class does not have a ``Num`` superclasses. It
167     therefore does not have default methods for the ``bit``, ``testBit``
168     and ``popCount`` methods.
169
170     You can make code that works with both Haskell 2010 and GHC by:
171
172     -  Whenever you make a ``Bits`` instance of a type, also make a
173         ``Num`` instance, and
174
175     -  Whenever you give a function, instance or class a ``Bits t``
176         constraint, also give it a ``Num t`` constraint, and
177
178     -  Always define the ``bit``, ``testBit`` and ``popCount`` methods
179         in ``Bits`` instances.
180
181 Extra instances
182     The following extra instances are defined: ::
183
184         instance Functor ((->) r)
185         instance Monad ((->) r)
186         instance Functor ((,) a)
187         instance Functor (Either a)
188         instance Monad (Either e)
189
190 Multiply-defined array elements not checked
191     This code fragment should elicit a fatal error, but it does not: ::
192
193         main = print (array (1,1) [(1,2), (1,3)])
194
195     GHC's implementation of ``array`` takes the value of an array slot
196     from the last (index,value) pair in the list, and does no checking
197     for duplicates. The reason for this is efficiency, pure and simple.
198
199 .. _infelicities-Prelude:
200
201 In ``Prelude`` support
202 ^^^^^^^^^^^^^^^^^^^^^^
203
204 Arbitrary-sized tuples
205     Tuples are currently limited to size 100. However, standard
206     instances for tuples (``Eq``, ``Ord``, ``Bounded``, ``Ix``, ``Read``,
207     and ``Show``) are available *only* up to 16-tuples.
208
209     This limitation is easily subvertible, so please ask if you get
210     stuck on it.
211
212 ``splitAt`` semantics
213     ``Data.List.splitAt`` is more strict than specified in the Report.
214     Specifically, the Report specifies that ::
215
216        splitAt n xs = (take n xs, drop n xs)
217
218     which implies that ::
219
220        splitAt undefined undefined = (undefined, undefined)
221
222     but GHC's implementation is strict in its first argument, so ::
223
224        splitAt undefined [] = undefined
225
226 ``Show``\ ing records
227     The Haskell 2010 definition of ``Show`` stipulates that the rendered
228     string should only include parentheses which are necessary to unambiguously
229     parse the result. For historical reasons, ``Show`` instances derived by GHC
230     include parentheses around records despite the fact that record syntax
231     binds more tightly than function application; e.g., ::
232
233         data Hello = Hello { aField :: Int } deriving (Show)
234
235         -- GHC produces...
236         show (Just (Hello {aField=42})) == "Just (Hello {aField=42})"
237
238         -- whereas Haskell 2010 calls for...
239         show (Just (Hello {aField=42})) == "Just Hello {aField=42}"
240
241 ``Read``\ ing integers
242     GHC's implementation of the ``Read`` class for integral types
243     accepts hexadecimal and octal literals (the code in the Haskell 98
244     report doesn't). So, for example, ::
245
246         read "0xf00" :: Int
247
248     works in GHC.
249
250     A possible reason for this is that ``readLitChar`` accepts hex and
251     octal escapes, so it seems inconsistent not to do so for integers
252     too.
253
254 ``isAlpha``
255     The Haskell 98 definition of ``isAlpha`` is: ::
256
257         isAlpha c = isUpper c || isLower c
258
259     GHC's implementation diverges from the Haskell 98 definition in the
260     sense that Unicode alphabetic characters which are neither upper nor
261     lower case will still be identified as alphabetic by ``isAlpha``.
262
263 ``hGetContents``
264     Lazy I/O throws an exception if an error is encountered, in contrast
265     to the Haskell 98 spec which requires that errors are discarded (see
266     Section 21.2.2 of the Haskell 98 report). The exception thrown is
267     the usual IO exception that would be thrown if the failing IO
268     operation was performed in the IO monad, and can be caught by
269     ``System.IO.Error.catch`` or ``Control.Exception.catch``.
270
271 .. _infelicities-ffi:
272
273 The Foreign Function Interface
274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275
276 ``hs_init()``, ``hs_exit()``
277     The FFI spec requires the implementation to support re-initialising
278     itself after being shut down with ``hs_exit()``, but GHC does not
279     currently support that.
280
281     .. index::
282         single: hs_init
283         single: hs_exit
284
285 .. _haskell-98-2010-undefined:
286
287 GHC's interpretation of undefined behaviour in Haskell 98 and Haskell 2010
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289
290 This section documents GHC's take on various issues that are left
291 undefined or implementation specific in Haskell 98.
292
293 ``Char``
294     .. index::
295        single: Char; size of
296
297     Following the ISO-10646 standard, ``maxBound :: Char`` in GHC is
298     ``0x10FFFF``.
299
300 ``Int``
301     .. index::
302        single: Int; size of
303        single: fromInteger function
304        single: fromIntegral function
305
306     In GHC the ``Int`` type follows the size of an address on the host
307     architecture; in other words it holds 32 bits on a 32-bit machine,
308     and 64-bits on a 64-bit machine.
309
310     Arithmetic on ``Int`` is unchecked for overflowoverflow\ ``Int``, so
311     all operations on ``Int`` happen modulo 2\ :sup:`⟨n⟩` where ⟨n⟩ is
312     the size in bits of the ``Int`` type.
313
314     The ``fromInteger`` (and hence also ``fromIntegral``) is a special case when
315     converting to ``Int``. The value of ``fromIntegral x :: Int`` is
316     given by taking the lower ⟨n⟩ bits of ``(abs x)``, multiplied by the
317     sign of ``x`` (in 2's complement ⟨n⟩-bit arithmetic). This behaviour
318     was chosen so that for example writing ``0xffffffff :: Int``
319     preserves the bit-pattern in the resulting ``Int``.
320
321     Negative literals, such as ``-3``, are specified by (a careful
322     reading of) the Haskell Report as meaning
323     ``Prelude.negate (Prelude.fromInteger 3)``. So ``-2147483648`` means
324     ``negate (fromInteger 2147483648)``. Since ``fromInteger`` takes the
325     lower 32 bits of the representation,
326     ``fromInteger (2147483648::Integer)``, computed at type ``Int`` is
327     ``-2147483648::Int``. The ``negate`` operation then overflows, but
328     it is unchecked, so ``negate (-2147483648::Int)`` is just
329     ``-2147483648``. In short, one can write ``minBound::Int`` as a
330     literal with the expected meaning (but that is not in general
331     guaranteed).
332
333     The ``fromIntegral`` function also preserves bit-patterns when
334     converting between the sized integral types (``Int8``, ``Int16``,
335     ``Int32``, ``Int64`` and the unsigned ``Word`` variants), see the
336     modules ``Data.Int`` and ``Data.Word`` in the library documentation.
337
338 Unchecked floating-point arithmetic
339     Operations on ``Float`` and ``Double`` numbers are *unchecked* for
340     overflow, underflow, and other sad occurrences. (note, however, that
341     some architectures trap floating-point overflow and
342     loss-of-precision and report a floating-point exception, probably
343     terminating the program)
344
345     .. index::
346         single: floating-point exceptions.
347
348 .. _bugs:
349
350 Known bugs or infelicities
351 --------------------------
352
353 The bug tracker lists bugs that have been reported in GHC but not yet
354 fixed: see the `GHC Trac <http://ghc.haskell.org/trac/ghc/>`__. In
355 addition to those, GHC also has the following known bugs or
356 infelicities. These bugs are more permanent; it is unlikely that any of
357 them will be fixed in the short term.
358
359 .. _bugs-ghc:
360
361 Bugs in GHC
362 ~~~~~~~~~~~
363
364 -  GHC's runtime system implements cooperative multitasking, with
365    context switching potentially occurring only when a program
366    allocates. This means that programs that do not allocate may never
367    context switch. This is especially true of programs using STM, which
368    may deadlock after observing inconsistent state. See :ghc-ticket:`367`
369    for further discussion.
370
371    If you are hit by this, you may want to compile the affected module
372    with :ghc-flag:`-fno-omit-yields <-fomit-yields>` (see :ref:`options-f`).
373    This flag ensures that yield points are inserted at every function entrypoint
374    (at the expense of a bit of performance).
375
376 -  GHC does not allow you to have a data type with a context that
377    mentions type variables that are not data type parameters. For
378    example:
379
380    ::
381
382          data C a b => T a = MkT a
383
384    so that ``MkT``\'s type is
385
386    ::
387
388          MkT :: forall a b. C a b => a -> T a
389
390    In principle, with a suitable class declaration with a functional
391    dependency, it's possible that this type is not ambiguous; but GHC
392    nevertheless rejects it. The type variables mentioned in the context
393    of the data type declaration must be among the type parameters of the
394    data type.
395
396 -  GHC's inliner can be persuaded into non-termination using the
397    standard way to encode recursion via a data type:
398
399    ::
400
401          data U = MkU (U -> Bool)
402
403          russel :: U -> Bool
404          russel u@(MkU p) = not $ p u
405
406          x :: Bool
407          x = russel (MkU russel)
408
409    The non-termination is reported like this:
410
411    .. code-block:: none
412
413        ghc: panic! (the 'impossible' happened)
414          (GHC version 7.10.1 for x86_64-unknown-linux):
415            Simplifier ticks exhausted
416          When trying UnfoldingDone x_alB
417          To increase the limit, use -fsimpl-tick-factor=N (default 100)
418
419    with the panic being reported no matter how high a
420    :ghc-flag:`-fsimpl-tick-factor` you supply.
421
422    We have never found another class of programs, other than this
423    contrived one, that makes GHC diverge, and fixing the problem would
424    impose an extra overhead on every compilation. So the bug remains
425    un-fixed. There is more background in `Secrets of the GHC
426    inliner <http://research.microsoft.com/~simonpj/Papers/inlining/>`__.
427
428 -  On 32-bit x86 platforms when using the native code generator, the
429    :ghc-flag:`-fexcess-precision` option is always on.
430    This means that floating-point calculations are non-deterministic,
431    because depending on how the program is compiled (optimisation
432    settings, for example), certain calculations might be done at 80-bit
433    precision instead of the intended 32-bit or 64-bit precision.
434    Floating-point results may differ when optimisation is turned on. In
435    the worst case, referential transparency is violated, because for
436    example ``let x = E1 in E2`` can evaluate to a different value than
437    ``E2[E1/x]``.
438
439    .. index::
440       single: -msse2 option
441
442    One workaround is to use the :ghc-flag:`-msse2` option (see
443    :ref:`options-platform`), which generates code to use the SSE2
444    instruction set instead of the x87 instruction set. SSE2 code uses
445    the correct precision for all floating-point operations, and so gives
446    deterministic results. However, note that this only works with
447    processors that support SSE2 (Intel Pentium 4 or AMD Athlon 64 and
448    later), which is why the option is not enabled by default. The
449    libraries that come with GHC are probably built without this option,
450    unless you built GHC yourself.
451
452 -  The :ghc-flag:`state hack <-fstate-hack>` optimization can result in
453    non-obvious changes in evaluation ordering which may hide exceptions, even
454    with :ghc-flag:`-fpedantic-bottoms` (see, e.g., :ghc-ticket:`7411`). For
455    instance, ::
456
457      import Control.Exception
458      import Control.DeepSeq
459      main = do
460          evaluate (('a' : undefined) `deepseq` return () :: IO ())
461          putStrLn "Hello"
462
463    Compiling this program with ``-O`` results in ``Hello`` to be printed,
464    despite the fact that ``evaluate`` should have bottomed. Compiling
465    with ``-O -fno-state-hack`` results in the exception one would expect.
466
467 -  Programs compiled with :ghc-flag:`-fdefer-type-errors` may fail a bit
468    more eagerly than one might expect. For instance, ::
469
470      {-# OPTIONS_GHC -fdefer-type-errors #-}
471      main = do
472        putStrLn "Hi there."
473        putStrLn True
474
475    Will emit no output, despite the fact that the ill-typed term appears
476    after the well-typed ``putStrLn "Hi there."``. See :ghc-ticket:`11197`.
477
478 -  Despite appearances ``*`` and ``Constraint`` aren't really distinct kinds
479    in the compiler's internal representation and can be unified producing
480    unexpected results. See :ghc-ticket:`11715` for one example.
481
482 .. _bugs-ghci:
483
484 Bugs in GHCi (the interactive GHC)
485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486
487 -  GHCi does not respect the ``default`` declaration in the module whose
488    scope you are in. Instead, for expressions typed at the command line,
489    you always get the default default-type behaviour; that is,
490    ``default(Int,Double)``.
491
492    It would be better for GHCi to record what the default settings in
493    each module are, and use those of the 'current' module (whatever that
494    is).
495
496 -  On Windows, there's a GNU ld/BFD bug whereby it emits bogus PE object
497    files that have more than 0xffff relocations. When GHCi tries to load
498    a package affected by this bug, you get an error message of the form
499
500    .. code-block:: none
501
502        Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
503
504    The last time we looked, this bug still wasn't fixed in the BFD
505    codebase, and there wasn't any noticeable interest in fixing it when
506    we reported the bug back in 2001 or so.
507
508    The workaround is to split up the .o files that make up your package
509    into two or more .o's, along the lines of how the ``base`` package does
510    it.