Sections with undefined operators have non-standard behavior
[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-recursive-groups:
130
131 Typechecking of recursive binding groups
132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
133
134 The Haskell Report specifies that a group of bindings (at top level, or
135 in a ``let`` or ``where``) should be sorted into strongly-connected
136 components, and then type-checked in dependency order
137 (`Haskell Report, Section
138 4.5.1 <http://www.haskell.org/onlinereport/decls.html#sect4.5.1>`__). As
139 each group is type-checked, any binders of the group that have an
140 explicit type signature are put in the type environment with the
141 specified polymorphic type, and all others are monomorphic until the
142 group is generalised (`Haskell Report, Section
143 4.5.2 <http://www.haskell.org/onlinereport/decls.html#sect4.5.2>`__).
144
145 Following a suggestion of Mark Jones, in his paper `Typing Haskell in
146 Haskell <http://citeseer.ist.psu.edu/424440.html>`__, GHC implements a
147 more general scheme. In GHC *the dependency analysis ignores references to
148 variables that have an explicit type signature*. As a result of this refined
149 dependency analysis, the dependency groups are smaller, and more bindings will
150 typecheck. For example, consider: ::
151
152       f :: Eq a => a -> Bool
153       f x = (x == x) || g True || g "Yes"
154
155       g y = (y <= y) || f True
156
157 This is rejected by Haskell 98, but under Jones's scheme the definition
158 for ``g`` is typechecked first, separately from that for ``f``, because
159 the reference to ``f`` in ``g``\'s right hand side is ignored by the
160 dependency analysis. Then ``g``\'s type is generalised, to get ::
161
162       g :: Ord a => a -> Bool
163
164 Now, the definition for ``f`` is typechecked, with this type for ``g``
165 in the type environment.
166
167 The same refined dependency analysis also allows the type signatures of
168 mutually-recursive functions to have different contexts, something that is
169 illegal in Haskell 98 (Section 4.5.2, last sentence). GHC only insists that the
170 type signatures of a *refined* group have identical type signatures; in practice
171 this means that only variables bound by the same pattern binding must have the
172 same context. For example, this is fine: ::
173
174       f :: Eq a => a -> Bool
175       f x = (x == x) || g True
176
177       g :: Ord a => a -> Bool
178       g y = (y <= y) || f True
179
180 .. _infelicities-Modules:
181
182 Module system and interface files
183 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
184
185 GHC requires the use of ``hs-boot`` files to cut the recursive loops
186 among mutually recursive modules as described in
187 :ref:`mutual-recursion`. This more of an infelicity than a bug: the
188 Haskell Report says (`Section
189 5.7 <http://haskell.org/onlinereport/modules.html#sect5.7>`__)
190
191     "Depending on the Haskell implementation used, separate compilation of
192     mutually recursive modules may require that imported modules contain
193     additional information so that they may be referenced before they are
194     compiled. Explicit type signatures for all exported values may be
195     necessary to deal with mutual recursion. The precise details of separate
196     compilation are not defined by this Report."
197
198 .. _infelicities-numbers:
199
200 Numbers, basic types, and built-in classes
201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
202
203 ``Num`` superclasses
204     The ``Num`` class does not have ``Show`` or ``Eq`` superclasses.
205
206
207     You can make code that works with both Haskell98/Haskell2010 and GHC
208     by:
209
210     -  Whenever you make a ``Num`` instance of a type, also make
211         ``Show`` and ``Eq`` instances, and
212
213     -  Whenever you give a function, instance or class a ``Num t``
214         constraint, also give it ``Show t`` and ``Eq t`` constraints.
215
216 ``Bits`` superclass
217     The ``Bits`` class does not have a ``Num`` superclass. It
218     therefore does not have default methods for the ``bit``, ``testBit``
219     and ``popCount`` methods.
220
221     You can make code that works with both Haskell 2010 and GHC by:
222
223     -  Whenever you make a ``Bits`` instance of a type, also make a
224         ``Num`` instance, and
225
226     -  Whenever you give a function, instance or class a ``Bits t``
227         constraint, also give it a ``Num t`` constraint, and
228
229     -  Always define the ``bit``, ``testBit`` and ``popCount`` methods
230         in ``Bits`` instances.
231
232 ``Read`` class methods
233     The ``Read`` class has two extra methods, ``readPrec`` and
234     ``readListPrec``, that are not found in the Haskell 2010 since they rely
235     on the ``ReadPrec`` data type, which requires the :ghc-flag:`-XRankNTypes`
236     extension. GHC also derives ``Read`` instances by implementing ``readPrec``
237     instead of ``readsPrec``, and relies on a default implementation of
238     ``readsPrec`` that is defined in terms of ``readPrec``. GHC adds these two
239     extra methods simply because ``ReadPrec`` is more efficient than ``ReadS``
240     (the type on which ``readsPrec`` is based).
241
242 ``Monad`` superclass
243     The ``Monad`` class has an ``Applicative`` superclass. You cannot write
244     ``Monad`` instances that work for GHC and also for a Haskell 2010
245     implementation that does not define ``Applicative``.
246
247 Extra instances
248     The following extra instances are defined: ::
249
250         instance Functor ((->) r)
251         instance Monad ((->) r)
252         instance Functor ((,) a)
253         instance Functor (Either a)
254         instance Monad (Either e)
255
256 Multiply-defined array elements not checked
257     This code fragment should elicit a fatal error, but it does not: ::
258
259         main = print (array (1,1) [(1,2), (1,3)])
260
261     GHC's implementation of ``array`` takes the value of an array slot
262     from the last (index,value) pair in the list, and does no checking
263     for duplicates. The reason for this is efficiency, pure and simple.
264
265 .. _infelicities-Prelude:
266
267 In ``Prelude`` support
268 ^^^^^^^^^^^^^^^^^^^^^^
269
270 Arbitrary-sized tuples
271     Tuples are currently limited to size 100. However, standard
272     instances for tuples (``Eq``, ``Ord``, ``Bounded``, ``Ix``, ``Read``,
273     and ``Show``) are available *only* up to 16-tuples.
274
275     This limitation is easily subvertible, so please ask if you get
276     stuck on it.
277
278 ``splitAt`` semantics
279     ``Data.List.splitAt`` is more strict than specified in the Report.
280     Specifically, the Report specifies that ::
281
282        splitAt n xs = (take n xs, drop n xs)
283
284     which implies that ::
285
286        splitAt undefined undefined = (undefined, undefined)
287
288     but GHC's implementation is strict in its first argument, so ::
289
290        splitAt undefined [] = undefined
291
292 ``Show``\ ing records
293     The Haskell 2010 definition of ``Show`` stipulates that the rendered
294     string should only include parentheses which are necessary to unambiguously
295     parse the result. For historical reasons, ``Show`` instances derived by GHC
296     include parentheses around records despite the fact that record syntax
297     binds more tightly than function application; e.g., ::
298
299         data Hello = Hello { aField :: Int } deriving (Show)
300
301         -- GHC produces...
302         show (Just (Hello {aField=42})) == "Just (Hello {aField=42})"
303
304         -- whereas Haskell 2010 calls for...
305         show (Just (Hello {aField=42})) == "Just Hello {aField=42}"
306
307 ``Read``\ ing integers
308     GHC's implementation of the ``Read`` class for integral types
309     accepts hexadecimal and octal literals (the code in the Haskell 98
310     report doesn't). So, for example, ::
311
312         read "0xf00" :: Int
313
314     works in GHC.
315
316     A possible reason for this is that ``readLitChar`` accepts hex and
317     octal escapes, so it seems inconsistent not to do so for integers
318     too.
319
320 ``isAlpha``
321     The Haskell 98 definition of ``isAlpha`` is: ::
322
323         isAlpha c = isUpper c || isLower c
324
325     GHC's implementation diverges from the Haskell 98 definition in the
326     sense that Unicode alphabetic characters which are neither upper nor
327     lower case will still be identified as alphabetic by ``isAlpha``.
328
329 ``hGetContents``
330     Lazy I/O throws an exception if an error is encountered, in contrast
331     to the Haskell 98 spec which requires that errors are discarded (see
332     Section 21.2.2 of the Haskell 98 report). The exception thrown is
333     the usual IO exception that would be thrown if the failing IO
334     operation was performed in the IO monad, and can be caught by
335     ``System.IO.Error.catch`` or ``Control.Exception.catch``.
336
337 .. _infelicities-ffi:
338
339 The Foreign Function Interface
340 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
341
342 ``hs_init()``, ``hs_exit()``
343     The FFI spec requires the implementation to support re-initialising
344     itself after being shut down with ``hs_exit()``, but GHC does not
345     currently support that. See :ghc-ticket:`13693`.
346
347     .. index::
348         single: hs_init
349         single: hs_exit
350
351 .. _infelicities-operator-sections:
352
353 Operator sections
354 ^^^^^^^^^^^^^^^^^
355
356 The Haskell Report demands that, for infix operators ``%``, the following
357 identities hold:
358
359 ::
360     (% expr) = \x -> x % expr
361     (expr %) = \x -> expr % x
362
363 However, the second law is violated in the presence of undefined operators,
364
365 ::
366     (%) = error "urk"
367     (() %)         `seq` () -- urk
368     (\x -> () % x) `seq` () -- OK, result ()
369
370 The operator section is treated like function application of an undefined
371 function, while the lambda form is in WHNF that contains an application of an
372 undefined function.
373
374 .. _haskell-98-2010-undefined:
375
376 GHC's interpretation of undefined behaviour in Haskell 98 and Haskell 2010
377 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
378
379 This section documents GHC's take on various issues that are left
380 undefined or implementation specific in Haskell 98.
381
382 ``Char``
383     .. index::
384        single: Char; size of
385
386     Following the ISO-10646 standard, ``maxBound :: Char`` in GHC is
387     ``0x10FFFF``.
388
389 ``Int``
390     .. index::
391        single: Int; size of
392        single: fromInteger function
393        single: fromIntegral function
394
395     In GHC the ``Int`` type follows the size of an address on the host
396     architecture; in other words it holds 32 bits on a 32-bit machine,
397     and 64-bits on a 64-bit machine.
398
399     Arithmetic on ``Int`` is unchecked for overflowoverflow\ ``Int``, so
400     all operations on ``Int`` happen modulo 2\ :sup:`⟨n⟩` where ⟨n⟩ is
401     the size in bits of the ``Int`` type.
402
403     The ``fromInteger`` (and hence also ``fromIntegral``) is a special case when
404     converting to ``Int``. The value of ``fromIntegral x :: Int`` is
405     given by taking the lower ⟨n⟩ bits of ``(abs x)``, multiplied by the
406     sign of ``x`` (in 2's complement ⟨n⟩-bit arithmetic). This behaviour
407     was chosen so that for example writing ``0xffffffff :: Int``
408     preserves the bit-pattern in the resulting ``Int``.
409
410     Negative literals, such as ``-3``, are specified by (a careful
411     reading of) the Haskell Report as meaning
412     ``Prelude.negate (Prelude.fromInteger 3)``. So ``-2147483648`` means
413     ``negate (fromInteger 2147483648)``. Since ``fromInteger`` takes the
414     lower 32 bits of the representation,
415     ``fromInteger (2147483648::Integer)``, computed at type ``Int`` is
416     ``-2147483648::Int``. The ``negate`` operation then overflows, but
417     it is unchecked, so ``negate (-2147483648::Int)`` is just
418     ``-2147483648``. In short, one can write ``minBound::Int`` as a
419     literal with the expected meaning (but that is not in general
420     guaranteed).
421
422     The ``fromIntegral`` function also preserves bit-patterns when
423     converting between the sized integral types (``Int8``, ``Int16``,
424     ``Int32``, ``Int64`` and the unsigned ``Word`` variants), see the
425     modules ``Data.Int`` and ``Data.Word`` in the library documentation.
426
427 Unchecked floating-point arithmetic
428     Operations on ``Float`` and ``Double`` numbers are *unchecked* for
429     overflow, underflow, and other sad occurrences. (note, however, that
430     some architectures trap floating-point overflow and
431     loss-of-precision and report a floating-point exception, probably
432     terminating the program)
433
434     .. index::
435         single: floating-point exceptions.
436
437 .. _bugs:
438
439 Known bugs or infelicities
440 --------------------------
441
442 The bug tracker lists bugs that have been reported in GHC but not yet
443 fixed: see the `GHC Trac <http://ghc.haskell.org/trac/ghc/>`__. In
444 addition to those, GHC also has the following known bugs or
445 infelicities. These bugs are more permanent; it is unlikely that any of
446 them will be fixed in the short term.
447
448 .. _bugs-ghc:
449
450 Bugs in GHC
451 ~~~~~~~~~~~
452
453 -  GHC's runtime system implements cooperative multitasking, with
454    context switching potentially occurring only when a program
455    allocates. This means that programs that do not allocate may never
456    context switch. This is especially true of programs using STM, which
457    may deadlock after observing inconsistent state. See :ghc-ticket:`367`
458    for further discussion.
459
460    If you are hit by this, you may want to compile the affected module
461    with :ghc-flag:`-fno-omit-yields <-fomit-yields>` (see :ref:`options-f`).
462    This flag ensures that yield points are inserted at every function entrypoint
463    (at the expense of a bit of performance).
464
465 -  GHC does not allow you to have a data type with a context that
466    mentions type variables that are not data type parameters. For
467    example:
468
469    ::
470
471          data C a b => T a = MkT a
472
473    so that ``MkT``\'s type is
474
475    ::
476
477          MkT :: forall a b. C a b => a -> T a
478
479    In principle, with a suitable class declaration with a functional
480    dependency, it's possible that this type is not ambiguous; but GHC
481    nevertheless rejects it. The type variables mentioned in the context
482    of the data type declaration must be among the type parameters of the
483    data type.
484
485 -  GHC's inliner can be persuaded into non-termination using the
486    standard way to encode recursion via a data type:
487
488    ::
489
490          data U = MkU (U -> Bool)
491
492          russel :: U -> Bool
493          russel u@(MkU p) = not $ p u
494
495          x :: Bool
496          x = russel (MkU russel)
497
498    The non-termination is reported like this:
499
500    .. code-block:: none
501
502        ghc: panic! (the 'impossible' happened)
503          (GHC version 8.2.1 for x86_64-unknown-linux):
504            Simplifier ticks exhausted
505          When trying UnfoldingDone x_alB
506          To increase the limit, use -fsimpl-tick-factor=N (default 100)
507
508    with the panic being reported no matter how high a
509    :ghc-flag:`-fsimpl-tick-factor` you supply.
510
511    We have never found another class of programs, other than this
512    contrived one, that makes GHC diverge, and fixing the problem would
513    impose an extra overhead on every compilation. So the bug remains
514    un-fixed. There is more background in `Secrets of the GHC
515    inliner <http://research.microsoft.com/~simonpj/Papers/inlining/>`__.
516
517 -  On 32-bit x86 platforms when using the native code generator, the
518    :ghc-flag:`-fexcess-precision` option is always on.
519    This means that floating-point calculations are non-deterministic,
520    because depending on how the program is compiled (optimisation
521    settings, for example), certain calculations might be done at 80-bit
522    precision instead of the intended 32-bit or 64-bit precision.
523    Floating-point results may differ when optimisation is turned on. In
524    the worst case, referential transparency is violated, because for
525    example ``let x = E1 in E2`` can evaluate to a different value than
526    ``E2[E1/x]``.
527
528    .. index::
529       single: -msse2 option
530
531    One workaround is to use the :ghc-flag:`-msse2` option (see
532    :ref:`options-platform`), which generates code to use the SSE2
533    instruction set instead of the x87 instruction set. SSE2 code uses
534    the correct precision for all floating-point operations, and so gives
535    deterministic results. However, note that this only works with
536    processors that support SSE2 (Intel Pentium 4 or AMD Athlon 64 and
537    later), which is why the option is not enabled by default. The
538    libraries that come with GHC are probably built without this option,
539    unless you built GHC yourself.
540
541 -  The :ghc-flag:`state hack <-fstate-hack>` optimization can result in
542    non-obvious changes in evaluation ordering which may hide exceptions, even
543    with :ghc-flag:`-fpedantic-bottoms` (see, e.g., :ghc-ticket:`7411`). For
544    instance, ::
545
546      import Control.Exception
547      import Control.DeepSeq
548      main = do
549          evaluate (('a' : undefined) `deepseq` return () :: IO ())
550          putStrLn "Hello"
551
552    Compiling this program with ``-O`` results in ``Hello`` to be printed,
553    despite the fact that ``evaluate`` should have bottomed. Compiling
554    with ``-O -fno-state-hack`` results in the exception one would expect.
555
556 -  Programs compiled with :ghc-flag:`-fdefer-type-errors` may fail a bit
557    more eagerly than one might expect. For instance, ::
558
559      {-# OPTIONS_GHC -fdefer-type-errors #-}
560      main = do
561        putStrLn "Hi there."
562        putStrLn True
563
564    Will emit no output, despite the fact that the ill-typed term appears
565    after the well-typed ``putStrLn "Hi there."``. See :ghc-ticket:`11197`.
566
567 -  Despite appearances ``*`` and ``Constraint`` aren't really distinct kinds
568    in the compiler's internal representation and can be unified producing
569    unexpected results. See :ghc-ticket:`11715` for one example.
570
571 -  Because of a toolchain limitation we are unable to support full Unicode paths
572    on Windows. On Windows we support up to Latin-1. See :ghc-ticket:`12971` for more.
573
574 .. _bugs-ghci:
575
576 Bugs in GHCi (the interactive GHC)
577 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578
579 -  GHCi does not respect the ``default`` declaration in the module whose
580    scope you are in. Instead, for expressions typed at the command line,
581    you always get the default default-type behaviour; that is,
582    ``default(Int,Double)``.
583
584    It would be better for GHCi to record what the default settings in
585    each module are, and use those of the 'current' module (whatever that
586    is).
587
588 -  On Windows, there's a GNU ld/BFD bug whereby it emits bogus PE object
589    files that have more than 0xffff relocations. When GHCi tries to load
590    a package affected by this bug, you get an error message of the form
591
592    .. code-block:: none
593
594        Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
595
596    The last time we looked, this bug still wasn't fixed in the BFD
597    codebase, and there wasn't any noticeable interest in fixing it when
598    we reported the bug back in 2001 or so.
599
600    The workaround is to split up the .o files that make up your package
601    into two or more .o's, along the lines of how the ``base`` package does
602    it.