Fix more documentation wibbles
[ghc.git] / docs / users_guide / 8.2.1-notes.rst
1 .. _release-8-2-1:
2
3 Release notes for version 8.2.1
4 ===============================
5
6 The significant changes to the various parts of the compiler are listed
7 in the following sections. There have also been numerous bug fixes and
8 performance improvements over the 8.0 branch.
9
10 Highlights
11 ----------
12
13 The highlights since the 8.0 release include:
14
15 - A new, more expressive ``Typeable`` mechanism, ``Type.Reflection``
16
17 - Colorful error messages with caret diagnostics
18
19 - SCC annotations can now be used for declarations.
20
21 - Heap overflow throws an exception in certain circumstances.
22
23 - Improved code generation of join points
24
25 - Deriving strategies
26
27 - Compact regions support, allowing efficient garbage collection of large heaps
28
29 - More reliable DWARF debug information
30
31 Full details
32 ------------
33
34 Package system
35 ~~~~~~~~~~~~~~
36
37 - The long awaited Backpack module system is now fully usable. See
38   :ghc-wiki:`the GHC Wiki <Backpack>` for details.
39
40 Language
41 ~~~~~~~~
42
43 - Pattern synonym signatures can now be applied to multiple patterns, just like
44   value-level binding signatures. See :ref:`patsyn-typing` for details.
45
46 - It is now possible to explicitly pick a strategy to use when deriving a
47   class instance using the :ghc-flag:`-XDerivingStrategies` language extension
48   (see :ref:`deriving-strategies`).
49
50 - The new :ghc-flag:`-XUnboxedSums` extension allows more efficient representation
51   of sum data. Some future GHC release will have support for worker/wrapper
52   transformation of sum arguments and constructor unpacking.
53
54 - Support for overloaded record fields via a new ``HasField`` class and
55   associated compiler logic (see :ref:`record-field-selector-polymorphism`)
56
57 Compiler
58 ~~~~~~~~
59
60 - GHC will now use ``ld.gold`` or ``ld.lld`` instead of the system's default
61   ``ld``, if available. Linker availability will be evaluated at ``configure``
62   time. The user can manually override which linker to use by passing the ``LD``
63   variable to ``configure``. You can revert to the old behavior of using the
64   system's default ``ld`` by passing the ``--disable-ld-override`` flag to
65   ``configure``.
66
67 - GHC now uses section splitting (i.e. :ghc-flag:`-split-sections`) instead of
68   object splitting (i.e. :ghc-flag:`-split-objs`) as the default mechanism for
69   linker-based dead code removal. While the effect is the same, split sections
70   tends to produce significantly smaller objects than split objects and more
71   closely mirrors the approach used by other compilers. Split objects will
72   be deprecated and eventually removed in a future GHC release.
73
74   Note that some versions of the ubiquitous BFD linker exhibit performance
75   trouble with large libraries with section splitting enabled (see
76   :ghc-ticket:`13739`). It is recommended that you use either the ``gold`` or
77   ``lld`` linker if you observe this. This will require that you install one of
78   these compilers, rerun ``configure``, and reinstall GHC.
79
80   Split sections is enabled by default in the official binary distributions for
81   platforms that support it.
82
83 - Old profiling flags ``-auto-all``, ``-auto``, and ``-caf-all`` are deprecated
84   and their usage provokes a compile-time warning.
85
86 - Support for adding cost centres to declarations is added. The same ``SCC``
87   syntax can be used, in addition to a new form for specifying the cost centre
88   name. See :ref:`scc-pragma` for examples.
89
90 - GHC is now much more particular about :ghc-flag:`-XDefaultSignatures`. The
91   type signature for a default method of a type class must now be the same as
92   the corresponding main method's type signature modulo differences in the
93   signatures' contexts. Otherwise, the typechecker will reject that class's
94   definition. See :ref:`class-default-signatures` for further details.
95
96 - :ghc-flag:`-XDeriveAnyClass` is no longer limited to type classes whose
97   argument is of kind ``*`` or ``* -> *``.
98
99 - The means by which :ghc-flag:`-XDeriveAnyClass` infers instance contexts has
100   been completely overhauled. The instance context is now inferred using the
101   type signatures (and default type signatures) of the derived class's methods
102   instead of using the datatype's definition, which often led to
103   over-constrained instances or instances that didn't typecheck (or worse,
104   triggered GHC panics). See the section on
105   :ref:`DeriveAnyClass <derive-any-class>` for more details.
106
107 - GHC now allows standalone deriving using :ghc-flag:`-XDeriveAnyClass` on
108   any data type, even if its data constructors are not in scope. This is
109   consistent with the fact that this code (in the presence of
110   :ghc-flag:`-XDeriveAnyClass`): ::
111
112       deriving instance C T
113
114   is exactly equivalent to: ::
115
116       instance C T
117
118   and the latter code has no restrictions about whether the data constructors
119   of ``T`` are in scope.
120
121 - :ghc-flag:`-XGeneralizedNewtypeDeriving` now supports deriving type classes
122   with associated type families. See the section on
123   :ref:`GeneralizedNewtypeDeriving and associated type families
124   <gnd-and-associated-types>`.
125
126 - :ghc-flag:`-XGeneralizedNewtypeDeriving` will no longer infer constraints
127   when deriving a class with no methods. That is, this code: ::
128
129       class Throws e
130       newtype Id a = MkId a
131         deriving Throws
132
133   will now generate this instance: ::
134
135       instance Throws (Id a)
136
137   instead of this instance: ::
138
139       instance Throws a => Throws (Id a)
140
141   This change was motivated by the fact that the latter code has a strictly
142   redundant ``Throws a`` constraint, so it would emit a warning when compiled
143   with :ghc-flag:`-Wredundant-constraints`. The latter instance could still
144   be derived if so desired using :ghc-flag:`-XStandaloneDeriving`: ::
145
146       deriving instance Throws a => Throws (Id a)
147
148 - Add warning flag :ghc-flag:`-Wcpp-undef` which passes ``-Wundef`` to the C
149   pre-processor causing the pre-processor to warn on uses of the ``#if``
150   directive on undefined identifiers.
151
152 - GHC will no longer automatically infer the kind of higher-rank type synonyms;
153   you must explicitly explicitly annotate the synonym with a kind signature.
154   For example, given::
155
156     data T :: (forall k. k -> Type) -> Type
157
158   to define a synonym of ``T``, you must write::
159
160     type TSyn = (T :: (forall k. k -> Type) -> Type)
161
162 - The Mingw-w64 toolchain for the Windows version of GHC has been updated. GHC now uses
163   `GCC 6.2.0` and `binutils 2.27`.
164
165 - Previously, :ghc-flag:`-Wmissing-methods` would not warn whenever a type
166   class method beginning with an underscore was not implemented in an instance.
167   For instance, this code would compile without any warnings: ::
168
169      class Foo a where
170        _Bar :: a -> Int
171
172      instance Foo Int
173
174   :ghc-flag:`-Wmissing-methods` will now warn that ``_Bar`` is not implemented
175   in the ``Foo Int`` instance.
176
177 - A new flag :ghc-flag:`-ddump-json` has been added. This flag dumps compiler
178   output as JSON documents. It is experimental and will be refined depending
179   on feedback from tooling authors for the next release.
180
181 - GHC is now able to better optimize polymorphic expressions by using known
182   superclass dictionaries where possible. Some examples: ::
183
184     -- uses of `Monad IO` or `Applicative IO` here are improved
185     foo :: MonadBaseControl IO m => ...
186
187     -- uses of `Monoid MyMonoid` here are improved
188     bar :: MonadWriter MyMonoid m => ...
189
190 - GHC now derives the definition of ``<$`` when using :ghc-flag:`-XDeriveFunctor`
191   rather than using the default definition. This prevents unnecessary
192   allocation and a potential space leak when deriving ``Functor`` for
193   a recursive type.
194
195 - The :ghc-flag:`-XExtendedDefaultRules` extension now defaults multi-parameter
196   typeclasses. See :ghc-ticket:`12923`.
197
198 - GHC now ignores ``RULES`` for data constructors (:ghc-ticket:`13290`).
199   Previously, it accepted::
200
201     {-# RULES "NotAllowed" forall x. Just x = e #-}
202
203   That rule will no longer take effect, and a warning will be issued. ``RULES``
204   may still mention data constructors, but not in the outermost position::
205
206     {-# RULES "StillWorks" forall x. f (Just x) = e #-}
207
208 - Type synonyms can no longer appear in the class position of an instance.
209   This means something like this is no longer allowed: ::
210
211     type ReadShow a = (Read a, Show a)
212     instance Read Foo
213     instance Show Foo
214     instance ReadShow Foo -- illegal
215
216   See :ghc-ticket:`13267`.
217
218 - Validity checking for associated type family instances has tightened
219   somewhat. Before, this would be accepted: ::
220
221     class Foo a where
222       type Bar a
223
224     instance Foo (Either a b) where
225       type Bar (Either c d) = d -> c
226
227   This is now disallowed, as the type variables used in the `Bar` instance do
228   not match those in the instance head. This instance can be fixed by changing
229   it to: ::
230
231     instance Foo (Either a b) where
232       type Bar (Either a b) = b -> a
233
234   See the section on :ref:`associated type family instances <assoc-data-inst>`
235   for more information.
236
237 - A bug involving the interaction between :ghc-flag:`-XMonoLocalBinds` and
238   :ghc-flag:`-XPolyKinds` has been fixed. This can cause some programs to fail
239   to typecheck in case explicit kind signatures are not provided. See
240   :ref:`kind-generalisation` for an example.
241
242 GHCi
243 ~~~~
244
245 - Added :ghc-flag:`-flocal-ghci-history` which uses current directory for `.ghci-history`.
246
247 - Added support for :ghc-flag:`-XStaticPointers` in interpreted modules. Note, however,
248   that ``static`` expressions are still not allowed in expressions evaluated in the REPL.
249
250 Template Haskell
251 ~~~~~~~~~~~~~~~~
252
253 -  Reifying types that contain unboxed tuples now works correctly. (Previously,
254    Template Haskell reified unboxed tuples as boxed tuples with twice their
255    appropriate arity.)
256
257 -  Splicing singleton unboxed tuple types (e.g., ``(# Int #)``) now works
258    correctly. Previously, Template Haskell would implicitly remove the
259    parentheses when splicing, which would turn ``(# Int #)`` into ``Int``.
260
261 -  Add support for type signatures in patterns. (:ghc-ticket:`12164`)
262
263 -  Make quoting and reification return the same types.  (:ghc-ticket:`11629`)
264
265 -  More kind annotations appear in the left-hand sides of reified closed
266    type family equations, in order to disambiguate types that would otherwise
267    be ambiguous in the presence of :ghc-flag:`-XPolyKinds`.
268    (:ghc-ticket:`12646`)
269
270 -  Quoted type signatures are more accurate with respect to implicitly
271    quantified type variables. Before, if you quoted this: ::
272
273      [d| id :: a -> a
274          id x = x
275        |]
276
277    then the code that Template Haskell would give back to you would actually be
278    this instead: ::
279
280      id :: forall a. a -> a
281      id x = x
282
283    That is, quoting would explicitly quantify all type variables, even ones
284    that were implicitly quantified in the source. This could be especially
285    harmful if a kind variable was implicitly quantified. For example, if
286    you took this quoted declaration: ::
287
288      [d| idProxy :: forall proxy (b :: k). proxy b -> proxy b
289          idProxy x = x
290        |]
291
292    and tried to splice it back in, you'd get this instead: ::
293
294      idProxy :: forall k proxy (b :: k). proxy b -> proxy b
295      idProxy x = x
296
297    Now ``k`` is explicitly quantified, and that requires turning on
298    :ghc-flag:`-XTypeInType`, whereas the original declaration did not!
299
300    Template Haskell quoting now respects implicit quantification in type
301    signatures, so the quoted declarations above now correctly leave the
302    type variables ``a`` and ``k`` as implicitly quantified.
303    (:ghc-ticket:`13018` and :ghc-ticket:`13123`)
304
305 - Looking up type constructors with symbol names (e.g., ``+``) now works
306   as expected (:ghc-ticket:`11046`)
307
308
309 Runtime system
310 ~~~~~~~~~~~~~~
311
312 - Heap overflow throws a catchable exception, provided that it was detected
313   by the RTS during a GC cycle due to the program exceeding a limit set by
314   ``+RTS -M`` (see :rts-flag:`-M ⟨size⟩`), and not due to an allocation being refused
315   by the operating system. This exception is thrown to the same thread that
316   receives ``UserInterrupt`` exceptions, and may be caught by user programs.
317
318 - Added support for *Compact Regions*, which offer a way to manually
319   move long-lived data outside of the heap so that the garbage
320   collector does not have to trace it repeatedly.  Compacted data can
321   also be serialized, stored, and deserialized again later by the same
322   program.  For more details see the :ghc-compact-ref:`GHC.Compact
323   <GHC-Compact.html>` module. Moreover, see the ``compact`` library on `Hackage
324   <https://hackage.haskell.org/package/compact>`_ for a high-level interface.
325
326 - There is new support for improving performance on machines with a
327   Non-Uniform Memory Architecture (NUMA).  See :rts-flag:`--numa`.
328   This is supported on Linux and Windows systems.
329
330 - The garbage collector can be told to use fewer threads than the
331   global number of capabilities set by :rts-flag:`-N ⟨x⟩`. By default, the garbage
332   collector will use a number of threads equal to the lesser of the global number
333   of capabilities or the number of physical cores. See :rts-flag:`-qn ⟨x⟩`, and a
334   `blog post <http://simonmar.github.io/posts/2016-12-08-Haskell-in-the-datacentre.html>`_
335   that describes this.
336
337 - The :ref:`heap profiler <prof-heap>` can now emit heap census data to the GHC
338   event log, allowing heap profiles to be correlated with other tracing events
339   (see :ghc-ticket:`11094`).
340
341 - Some bugs have been fixed in the stack-trace implementation in the
342   profiler that sometimes resulted in incorrect stack traces and
343   costs attributed to the wrong cost centre stack (see :ghc-ticket:`5654`).
344
345 - Added processor group support for Windows. This allows the runtime to allocate
346   threads to all cores in systems which have multiple processor groups.
347   (e.g. > 64 cores, see :ghc-ticket:`11054`)
348
349 - Output of :ref:`Event log <rts-eventlog>` data can now be configured,
350   enabling external tools to collect and analyze the event log data while the
351   application is still running.
352
353 - ``advapi32``, ``shell32`` and ``user32`` are now automatically loaded in GHCi.
354   ``libGCC`` is also loaded when a dependency requires it. See
355   :ghc-ticket:`13189`.
356
357 hsc2hs
358 ~~~~~~
359
360 -  Version number 0.68.2
361
362 Libraries
363 ---------
364
365 array
366 ~~~~~
367
368 -  Version number 0.5.2.0 (was 0.5.0.0)
369
370 .. _lib-base:
371
372 base
373 ~~~~
374
375 See ``changelog.md`` in the ``base`` package for full release notes.
376
377 -  Version number 4.10.0.0 (was 4.9.0.0)
378
379 - ``Data.Either`` now provides ``fromLeft`` and ``fromRight``
380
381 - ``Data.Type.Coercion`` now provides ``gcoerceWith``, which is analogous to
382   ``gcastWith`` from ``Data.Type.Equality``.
383
384 - The ``Read1`` and ``Read2`` classes in ``Data.Functor.Classes`` have new
385   methods, ``liftReadList(2)`` and ``liftReadListPrec(2)``, that are defined in
386   terms of ``ReadPrec`` instead of ``ReadS``. This matches the interface
387   provided in GHC's version of the ``Read`` class, and allows users to write
388   more efficient ``Read1`` and ``Read2`` instances.
389
390 - Add ``type family AppendSymbol (m :: Symbol) (n :: Symbol) :: Symbol`` to
391   ``GHC.TypeLits``
392
393 - Add ``GHC.TypeNats`` module with ``Natural``-based ``KnownNat``. The ``Nat``
394   operations in ``GHC.TypeLits`` are a thin compatibility layer on top.
395   Note: the ``KnownNat`` evidence is changed from an ``Integer`` to a ``Natural``.
396
397 - ``liftA2`` is now a method of the ``Applicative`` class. ``Traversable``
398   deriving has been modified to use ``liftA2`` for the first two elements
399   traversed in each constructor. ``liftA2`` is not yet in the ``Prelude``,
400   and must currently be imported from ``Control.Applicative``. It is likely
401   to be added to the ``Prelude`` in the future.
402
403 binary
404 ~~~~~~
405
406 -  Version number 0.8.5.1 (was 0.7.1.0)
407
408 bytestring
409 ~~~~~~~~~~
410
411 -  Version number 0.10.8.2 (was 0.10.4.0)
412
413 Cabal
414 ~~~~~
415
416 -  Version number 2.0.0.0 (was 1.24.2.0)
417
418 containers
419 ~~~~~~~~~~
420
421 -  Version number 0.5.10.2 (was 0.5.4.0)
422
423 deepseq
424 ~~~~~~~
425
426 -  Version number 1.4.3.0 (was 1.3.0.2)
427
428 directory
429 ~~~~~~~~~
430
431 -  Version number 1.3.0.2 (was 1.2.0.2)
432
433 filepath
434 ~~~~~~~~
435
436 -  Version number 1.4.1.2 (was 1.3.0.2)
437
438 ghc
439 ~~~
440
441 -  Version number 8.2.1
442
443 ghc-boot
444 ~~~~~~~~
445
446 -  This is an internal package. Use with caution.
447
448 ghc-compact
449 ~~~~~~~~~~~
450
451 The ``ghc-compact`` library provides an experimental API for placing immutable
452 data structures into a contiguous memory region. Data in these regions is not
453 traced during garbage collection and can be serialized to disk or over the
454 network.
455
456 - Version number 0.1.0.0 (newly added)
457
458 ghc-prim
459 ~~~~~~~~
460
461 -  Version number 0.5.1.0 (was 0.3.1.0)
462
463 -  Added new ``isByteArrayPinned#`` and ``isMutableByteArrayPinned#`` operation.
464
465 -  New function ``noinline`` in ``GHC.Magic`` lets you mark that a function
466    should not be inlined.  It is optimized away after the simplifier runs.
467
468 hoopl
469 ~~~~~
470
471 -  Version number 3.10.2.2 (was 3.10.2.1)
472
473 hpc
474 ~~~
475
476 -  Version number 0.6.0.3 (was 0.6.0.2)
477
478 integer-gmp
479 ~~~~~~~~~~~
480
481 -  Version number 1.0.0.1 (was 1.0.0.1)
482
483 process
484 ~~~~~~~
485
486 -  Version number 1.6.1.0 (was 1.4.3.0)
487
488 template-haskell
489 ~~~~~~~~~~~~~~~~
490
491 -  Version 2.12.0.0 (was 2.11.1.0)
492
493 -  Added support for unboxed sums :ghc-ticket:`12478`.
494
495 -  Added support for visible type applications :ghc-ticket:`12530`.
496
497 time
498 ~~~~
499
500 -  Version number 1.8.0.1 (was 1.6.0.1)
501
502 unix
503 ~~~~
504
505 -  Version number 2.7.2.2 (was 2.7.2.1)
506
507 Win32
508 ~~~~~
509
510 -  Version number 2.5.4.1 (was 2.3.1.1)
511
512 Known bugs
513 ----------
514
515 - At least one known program regresses in compile time significantly over 8.0.
516   See :ghc-ticket:`13535`.
517
518 - Some uses of type applications may cause GHC to panic. See :ghc-ticket:`13819`.
519
520 - The compiler may loop during typechecking on some modules using
521   :ghc-flag:`-XUndecidableInstances`. See :ghc-ticket:`13943`.