rel-notes: Fix up formatting in release notes
[ghc.git] / docs / users_guide / 8.4.1-notes.rst
1 .. _release-8-4-1:
2
3 Release notes for version 8.4.1
4 ===============================
5
6 The significant changes to the various parts of the compiler are listed in the
7 following sections. There have also been numerous bug fixes and performance
8 improvements over the 8.2.1 release.
9
10
11 Highlights
12 ----------
13
14 The highlights, since the 8.2.1 release, are:
15
16 -  Many, many bug fixes.
17
18 Full details
19 ------------
20
21 Language
22 ~~~~~~~~
23
24 - Data families have been generalised a bit: a data family declaration can now
25   end with a kind variable ``k`` instead of ``Type``. Additionally, data/newtype
26   instance no longer need to list all the patterns of the family if they don't
27   wish to; this is quite like how regular datatypes with a kind signature can omit
28   some type variables.
29
30 - There are now fewer restrictions regarding whether kind variables can appear
31   on the right-hand sides of type and data family instances. Before, there was
32   a strict requirements that all kind variables on the RHS had to be explicitly
33   bound by type patterns on the LHS. Now, kind variables can be *implicitly*
34   bound, which allows constructions like these: ::
35
36     data family Nat :: k -> k -> *
37     -- k is implicitly bound by an invisible kind pattern
38     newtype instance Nat :: (k -> *) -> (k -> *) -> * where
39       Nat :: (forall xx. f xx -> g xx) -> Nat f g
40
41     class Funct f where
42       type Codomain f :: *
43     instance Funct ('KProxy :: KProxy o) where
44       -- o is implicitly bound by the kind signature
45       -- of the LHS type pattern ('KProxy)
46       type Codomain 'KProxy = NatTr (Proxy :: o -> *)
47
48 - Implicitly bidirectional pattern synonyms no longer allow bang patterns
49   (``!``) or irrefutable patterns (``~``) on the right-hand side. Previously,
50   this was allowed, although the bang patterns and irrefutable patterns would
51   be silently ignored when used in an expression context. This is now a proper
52   error, and explicitly bidirectional pattern synonyms should be used in their
53   stead. That is, instead of using this (which is an error): ::
54
55       data StrictJust a = Just !a
56
57   Use this: ::
58
59       data StrictJust a <- Just !a where
60         StrictJust !a = Just a
61
62 - GADTs with kind-polymorphic type arguments now require :ghc-flag:`TypeInType`.
63   For instance, consider the following, ::
64
65       data G :: k -> * where
66         GInt   :: G Int
67         GMaybe :: G Maybe
68
69   In previous releases this would compile with :ghc-flag:`PolyKinds` alone due
70   to bug :ghc-ticket:`13391`. As of GHC 8.4, however, this requires
71   :ghc-flag:`TypeInType`. Note that since GADT kind signatures aren't generalized,
72   this will also require that you provide a :ref:`CUSK
73   <complete-kind-signatures>` by explicitly quantifying over the kind argument,
74   ``k``, ::
75
76       data G :: forall k. k -> * where
77         GInt   :: G Int
78         GMaybe :: G Maybe
79
80 - The order in which type variables are quantified in GADT constructor type
81   signatures has changed. Before, if you had ``MkT`` as below: ::
82
83       data T a where
84         MkT :: forall b a. b -> T a
85
86   Then the type of ``MkT`` would (counterintuitively) be
87   ``forall a b. b -> T a``! Now, GHC quantifies the type variables in the
88   order that the users writes them, so the type of ``MkT`` is now
89   ``forall b a. b -> T a`` (this matters for :ghc-flag:`-XTypeApplications`).
90
91 - The new :ghc-flag:`-XEmptyDataDeriving` extension allows deriving ``Eq``,
92   ``Ord``, ``Read``, and ``Show`` instances directly for empty data types, as
93   in ``data Empty deriving Eq``. (Previously, this would require the use of
94   :ghc-flag:`-XStandaloneDeriving` to accomplish.)
95
96   One can also now derive ``Data`` instances directly for empty data types (as
97   in ``data Empty deriving Data``) without needing to use
98   :ghc-flag:`-XStandaloneDeriving`. However, since already requires a GHC
99   extension (:ghc-flag:`-XDeriveDataTypeable`), one does not need to enable
100   :ghc-flag:`-XEmptyDataDeriving` to do so. This also goes for other classes
101   which require extensions to derive, such as :ghc-flag:`-XDeriveFunctor`.
102
103 - Hexadecimal floating point literals (e.g. ``0x0.1p4``), enabled with
104   :ghc-flag:`HexFloatLiterals`.  See
105   :ref:`Hexadecimal floating point literals <hex-float-literals>`
106   for the full details.
107
108 Compiler
109 ~~~~~~~~
110
111 - The ``configure`` script now no longer accepts ``--with-TOOL`` flags (e.g.
112   ``--with-nm``, ``--with-ld``, etc.). Instead, these are taken from environment
113   variables, as is typical in ``autoconf`` scripts. For instance,
114   ``./configure --with-nm=/usr/local/bin/nm`` turns into
115   ``./configure NM=/usr/local/bin/nm``.
116
117 - Derived ``Functor``, ``Foldable``, and ``Traversable`` instances are now
118   optimized when their last type parameters have phantom roles.
119   Specifically, ::
120
121     fmap _ = coerce
122     traverse _ x = pure (coerce x)
123     foldMap _ _ = mempty
124
125   These definitions of ``foldMap`` and ``traverse`` are lazier than the ones we
126   would otherwise derive, as they may produce results without inspecting their
127   arguments at all.
128
129   See also :ref:`deriving-functor`, :ref:`deriving-foldable`, and
130   :ref:`deriving-traversable`.
131
132 - Derived instances for empty data types are now substantially different
133   than before. Here is an overview of what has changed. These examples will
134   use a running example of ``data Empty a`` to describe what happens when an
135   instance is derived for ``Empty``:
136
137   - Derived ``Eq`` and ``Ord`` instances would previously emit code that used
138     ``error``: ::
139
140       instance Eq (Empty a) where
141         (==) = error "Void =="
142
143       instance Ord (Empty a) where
144         compare = error "Void compare"
145
146     Now, they emit code that uses maximally defined, lazier semantics: ::
147
148       instance Eq (Empty a) where
149         _ == _ = True
150
151       instance Ord (Empty a) where
152         compare _ _ = EQ
153
154   - Derived ``Read`` instances would previous emit code that used
155     ``parens``: ::
156
157       instance Read (Empty a) where
158         readPrec = parens pfail
159
160     But ``parens`` forces parts of the parsed string that it doesn't need to.
161     Now, the derived instance will not use ``parens`` (that it, parsing
162     ``Empty`` will always fail, without reading *any* input): ::
163
164       instance Read (Empty a) where
165         readPrec = pfail
166
167   - Derived ``Show`` instances would previously emit code that used
168     ``error``: ::
169
170       instance Show (Empty a) where
171         showsPrec = "Void showsPrec"
172
173     Now, they emit code that inspects the argument. That is, if the argument
174     diverges, then showing it will also diverge: ::
175
176       instance Show (Empty a) where
177         showsPrec _ x = case x of {}
178
179   - Derived ``Functor``, ``Foldable``, ``Traversable``, ``Generic``,
180     ``Generic1``, ``Lift``, and ``Data`` instances previously emitted code that
181     used ``error``: ::
182
183       instance Functor Empty where
184         fmap = error "Void fmap"
185
186       instance Foldable Empty where
187         foldMap = error "Void foldMap"
188
189       instance Traversable Empty where
190         traverse = error "Void traverse"
191
192       instance Generic (Empty a) where
193         from = M1 (error "No generic representation for empty datatype Empty")
194         to (M1 _) = error "No values for empty datatype Empty"
195       -- Similarly for Generic1
196
197       instance Lift (Empty a) where
198         lift _ = error "Can't lift value of empty datatype Empty"
199
200       instance Data a => Data (Empty a) where
201         gfoldl _ _ _ = error "Void gfoldl"
202         toConstr _ = error "Void toConstr"
203         ...
204
205     Now, derived ``Functor``, ``Traversable, ``Generic``, ``Generic1``,
206     ``Lift``, and ``Data`` instances emit code which inspects their
207     arguments: ::
208
209       instance Functor Empty where
210         fmap _ x = case x of {}
211
212       instance Traversable Empty where
213         traverse _ x = pure (case x of {})
214
215       instance Generic (Empty a) where
216         from x = M1 (case x of {})
217         to (M1 x) = case x of {}
218
219       -- Similarly for Generic1
220
221       instance Lift (Empty a) where
222         lift x = pure (case x of {})
223
224       instance Data a => Data (Empty a) where
225         gfoldl _ x = case x of {}
226         toConstr x = case x of {}
227         ...
228
229     Derived ``Foldable`` instances now are maximally lazy: ::
230
231       instance Foldable Empty where
232         foldMap _ _ = mempty
233
234 - Derived ``Foldable`` instances now derive custom definitions for ``null``
235   instead of using the default one. This leads to asymptotically better
236   performance for recursive types not shaped like cons-lists, and allows ``null``
237   to terminate for more (but not all) infinitely large structures.
238
239 - :ghc-flag:`-fsplit-sections` is now supported on x86_64 Windows and is on by default.
240   See :ghc-ticket:`12913`.
241
242 - Configure on Windows now supports the ``--enable-distro-toolchain``
243   ``configure`` flag, which can be used to build a GHC using compilers on your
244   ``PATH`` instead of using the bundled bindist. See :ghc-ticket:`13792`
245
246 - GHC now enables :ghc-flag:`-fllvm-pass-vectors-in-regs` by default. This means
247   that GHC will now use native vector registers to pass vector arguments across
248   function calls.
249
250 - The optional ``instance`` keyword is now usable in type family instance
251   declarations. See :ghc-ticket:`13747`
252
253 - Lots of other bugs. See `Trac <https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.4.1&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`_
254   for a complete list.
255
256 Runtime system
257 ~~~~~~~~~~~~~~
258
259 - Function ``hs_add_root()`` was removed. It was a no-op since GHC-7.2.1
260   where module initialisation stopped requiring a call to ``hs_add_root()``.
261
262 - Proper import library support added to GHC which can handle all of the libraries produced
263   by ``dlltool``. The limitation of them needing to be named with the suffix
264   ``.dll.a`` is also removed. See :ghc-ticket:`13606`, :ghc-ticket:`12499`,
265   :ghc-ticket:`12498`
266
267 - The GHCi runtime linker on Windows now supports the ``big-obj`` file format.
268
269 - The runtime system's :ref:`native stack backtrace <backtrace-signal>` support
270   on POSIX platforms is now triggered by ``SIGQUIT`` instead of ``SIGUSR2`` as
271   it was in previous releases. This change is to bring GHC's behavior into
272   compliance with the model set by the most Java virtual machine
273   implementations.
274
275 - The GHC runtime on Windows now uses Continue handlers instead of Vectorized
276   handlers to trap exceptions. This change gives other exception handlers a chance
277   to handle the exception before the runtime does. Furthermore The RTS flag
278   :rts-flag:`--install-seh-handlers=<yes|no>` Can be used on Wndows to
279   completely disable the runtime's handling of exceptions. See
280   :ghc-ticket:`13911`, :ghc-ticket:`12110`.
281
282 - The GHC runtime on Windows can now generate crash dumps on unhandled exceptions
283   using the RTS flag :rts-flag:`--generate-crash-dumps`.
284
285 - The GHCi runtime linker now avoid calling GCC to find libraries as much as possible by caching
286   the list of search directories of GCC and querying the file system directly. This results in
287   much better performance, especially on Windows.
288
289 - The GHC runtime on Windows can now generate stack traces on unhandled exceptions.
290   When running in GHCi more information is displayed about the symbols if available.
291   This behavior can be controlled with the RTS flag `--generate-stack-traces=<yes|no>`.
292
293 Template Haskell
294 ~~~~~~~~~~~~~~~~
295
296 - Template Haskell now reifies data types with GADT syntax accurately.
297   Previously, TH used heuristics to determine whether a data type
298   should be reified using GADT syntax, which could lead to incorrect results,
299   such as ``data T1 a = (a ~ Int) => MkT1`` being reified as a GADT and
300   ``data T2 a where MkT2 :: Show a => T2 a`` *not* being reified as a GADT.
301
302   In addition, reified GADT constructors now more accurately track the order in
303   which users write type variables. Before, if you reified ``MkT`` as below: ::
304
305       data T a where
306         MkT :: forall b a. b -> T a
307
308   Then the reified type signature of ``MkT`` would have been headed by
309   ``ForallC [PlainTV a, PlainTV b]``. Now, reifying ``MkT`` will give a type
310   headed by ``ForallC [PlainTV b, PlainTV a]``, as one would expect.
311
312 ``ghc`` library
313 ~~~~~~~~~~~~~~~
314
315 - hsSyn Abstract Syntax Tree (AST) is now extensible via the mechanism described in `Trees that Grow <http://www.jucs.org/jucs_23_1/trees_that_grow/jucs_23_01_0042_0062_najd.pdf>`_
316
317   The main change for users of the GHC API is that the AST is no longer indexed
318   by the type used as the identifier, but by a specific index type, ::
319
320       type GhcPs   = GhcPass 'Parsed      -- Old 'RdrName' type param
321       type GhcRn   = GhcPass 'Renamed     -- Old 'Name' type param
322       type GhcTc   = GhcPass 'Typechecked -- Old 'Id' type para,
323       type GhcTcId = GhcTc                -- Old 'TcId' type param
324
325   The simplest way to support the current GHC as well as earlier ones is to define ::
326
327       #if MIN_VERSION_ghc(8,3,0)
328       type ParseI     = GhcPs
329       type RenameI    = GhcRn
330       type TypecheckI = GhcTc
331       #else
332       type ParseI     = RdrName
333       type RenameI    = Name
334       type TypecheckI = Var
335       #endif
336
337   and then replace all hardcoded index types accordingly. For polymorphic types,
338   the constraint ::
339
340       #if MIN_VERSION_ghc(8,3,0)
341       -- |bundle up the constraints required for a trees that grow pass
342       type IsPass pass = (DataId pass, OutputableBndrId pass, SourceTextX pass)
343       else
344       type IsPass pass = (DataId pass, OutputableBndrId pass)
345       #endif
346
347   can be used.
348
349 ``base`` library
350 ~~~~~~~~~~~~~~~~
351
352 - Blank strings can now be used as values for environment variables using the
353   ``System.Environment.Blank`` module. See :ghc-ticket:`12494`
354
355 - ``Data.Type.Equality.==`` is now a closed type family. It works for all kinds
356   out of the box. Any modules that previously declared instances of this family
357   will need to remove them. Whereas the previous definition was somewhat ad
358   hoc, the behavior is now completely uniform. As a result, some applications
359   that used to reduce no longer do, and conversely. Most notably, ``(==)`` no
360   longer treats the ``*``, ``j -> k``, or ``()`` kinds specially; equality is
361   tested structurally in all cases.
362
363 Build system
364 ~~~~~~~~~~~~
365
366 - ``dll-split`` has been removed and replaced with an automatic partitioning utility ``gen-dll``.
367   This utility can transparently split and compile any DLLs that require this. Note that the ``rts`` and
368   ``base`` can not be split at this point because of the mutual recursion between ``base`` and ``rts``.
369   There is currently no explicit dependency between the two in the build system and such there is no way
370   to notify ``base`` that the ``rts`` has been split, or vice versa.
371   (see :ghc-ticket:`5987`).
372
373 Win32
374 ~~~~~
375
376 -  Version number 2.6.x.x (was 2.5.4.1)
377    NOTE: This release is a backwards incompatible release which corrects the type of certain APIs.
378    See issue https://github.com/haskell/win32/issues/24.