Implement the EmptyDataDeriving proposal
[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 Compiler
104 ~~~~~~~~
105
106 - The ``configure`` script now no longer accepts ``--with-TOOL`` flags (e.g.
107   ``--with-nm``, ``--with-ld``, etc.). Instead, these are taken from environment
108   variables, as is typical in ``autoconf`` scripts. For instance,
109   ``./configure --with-nm=/usr/local/bin/nm`` turns into
110   ``./configure NM=/usr/local/bin/nm``.
111
112 - Derived ``Functor``, ``Foldable``, and ``Traversable`` instances are now
113   optimized when their last type parameters have phantom roles.
114   Specifically, ::
115
116     fmap _ = coerce
117     traverse _ x = pure (coerce x)
118     foldMap _ _ = mempty
119
120   These definitions of ``foldMap`` and ``traverse`` are lazier than the ones we
121   would otherwise derive, as they may produce results without inspecting their
122   arguments at all.
123
124   See also :ref:`deriving-functor`, :ref:`deriving-foldable`, and
125   :ref:`deriving-traversable`.
126
127 - Derived instances for empty data types are now substantially different
128   than before. Here is an overview of what has changed. These examples will
129   use a running example of ``data Empty a`` to describe what happens when an
130   instance is derived for ``Empty``:
131
132   - Derived ``Eq`` and ``Ord`` instances would previously emit code that used
133     ``error``: ::
134
135       instance Eq (Empty a) where
136         (==) = error "Void =="
137
138       instance Ord (Empty a) where
139         compare = error "Void compare"
140
141     Now, they emit code that uses maximally defined, lazier semantics: ::
142
143       instance Eq (Empty a) where
144         _ == _ = True
145
146       instance Ord (Empty a) where
147         compare _ _ = EQ
148
149   - Derived ``Read`` instances would previous emit code that used
150     ``parens``: ::
151
152       instance Read (Empty a) where
153         readPrec = parens pfail
154
155     But ``parens`` forces parts of the parsed string that it doesn't need to.
156     Now, the derived instance will not use ``parens`` (that it, parsing
157     ``Empty`` will always fail, without reading *any* input): ::
158
159       instance Read (Empty a) where
160         readPrec = pfail
161
162   - Derived ``Show`` instances would previously emit code that used
163     ``error``: ::
164
165       instance Show (Empty a) where
166         showsPrec = "Void showsPrec"
167
168     Now, they emit code that inspects the argument. That is, if the argument
169     diverges, then showing it will also diverge: ::
170
171       instance Show (Empty a) where
172         showsPrec _ x = case x of {}
173
174   - Derived ``Functor``, ``Foldable``, ``Traversable``, ``Generic``,
175     ``Generic1``, ``Lift``, and ``Data`` instances previously emitted code that
176     used ``error``: ::
177
178       instance Functor Empty where
179         fmap = error "Void fmap"
180
181       instance Foldable Empty where
182         foldMap = error "Void foldMap"
183
184       instance Traversable Empty where
185         traverse = error "Void traverse"
186
187       instance Generic (Empty a) where
188         from = M1 (error "No generic representation for empty datatype Empty")
189         to (M1 _) = error "No values for empty datatype Empty"
190       -- Similarly for Generic1
191
192       instance Lift (Empty a) where
193         lift _ = error "Can't lift value of empty datatype Empty"
194
195       instance Data a => Data (Empty a) where
196         gfoldl _ _ _ = error "Void gfoldl"
197         toConstr _ = error "Void toConstr"
198         ...
199
200     Now, derived ``Functor``, ``Traversable, ``Generic``, ``Generic1``,
201     ``Lift``, and ``Data`` instances emit code which inspects their
202     arguments: ::
203
204       instance Functor Empty where
205         fmap _ x = case x of {}
206
207       instance Traversable Empty where
208         traverse _ x = pure (case x of {})
209
210       instance Generic (Empty a) where
211         from x = M1 (case x of {})
212         to (M1 x) = case x of {}
213
214       -- Similarly for Generic1
215
216       instance Lift (Empty a) where
217         lift x = pure (case x of {})
218
219       instance Data a => Data (Empty a) where
220         gfoldl _ x = case x of {}
221         toConstr x = case x of {}
222         ...
223
224     Derived ``Foldable`` instances now are maximally lazy: ::
225
226       instance Foldable Empty where
227         foldMap _ _ = mempty
228
229 - Derived ``Foldable`` instances now derive custom definitions for ``null``
230   instead of using the default one. This leads to asymptotically better
231   performance for recursive types not shaped like cons-lists, and allows ``null``
232   to terminate for more (but not all) infinitely large structures.
233
234 - `-fsplit-sections` is now supported on x86_64 Windows and is on by default.
235   See :ghc-ticket:`12913`.
236
237 - Configure on Windows now supports ``--enable-distro-toolchain`` which can be
238   used to build a GHC using compilers on your ``PATH`` instead of using the
239   bundled bindist. See :ghc-ticket:`13792`
240
241 - The optional ``instance`` keyword is now usable in type family instance
242   declarations. See :ghc-ticket:`13747`
243
244 - 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>`_
245   for a complete list.
246
247 Runtime system
248 ~~~~~~~~~~~~~~
249
250 - Function ``hs_add_root()`` was removed. It was a no-op since GHC-7.2.1
251   where module initialisation stopped requiring a call to ``hs_add_root()``.
252
253 - Proper import library support added to GHC which can handle all of the libraries produced
254   by ``dlltool``. The limitation of them needing to be named with the suffix .dll.a is also removed.
255   See :ghc-ticket:`13606`, :ghc-ticket:`12499`, :ghc-ticket:`12498`
256
257 - The GHCi runtime linker on Windows now supports the ``big-obj`` file format.
258
259 - The runtime system's :ref:`native stack backtrace <backtrace-signal>` support
260   on POSIX platforms is now triggered by ``SIGQUIT`` instead of ``SIGUSR2`` as
261   it was in previous releases. This change is to bring GHC's behavior into
262   compliance with the model set by the most Java virtual machine
263   implementations.
264
265 - The GHC runtime on Windows now uses Continue handlers instead of Vectorized
266   handlers to trap exceptions. This change gives other exception handlers a chance
267   to handle the exception before the runtime does. Furthermore The RTS flag
268   :rts-flag:`--install-seh-handlers=<yes|no>` Can be used on Wndows to
269   completely disable the runtime's handling of exceptions. See
270   :ghc-ticket:`13911`, :ghc-ticket:`12110`.
271
272 - The GHC runtime on Windows can now generate crash dumps on unhandled exceptions
273   using the RTS flag :rts-flag:`--generate-crash-dumps`.
274
275 - The GHCi runtime linker now avoid calling GCC to find libraries as much as possible by caching
276   the list of search directories of GCC and querying the file system directly. This results in
277   much better performance, especially on Windows.
278
279 - The GHC runtime on Windows can now generate stack traces on unhandled exceptions.
280   When running in GHCi more information is displayed about the symbols if available.
281   This behavior can be controlled with the RTS flag `--generate-stack-traces=<yes|no>`.
282
283 Template Haskell
284 ~~~~~~~~~~~~~~~~
285
286 - Template Haskell now reifies data types with GADT syntax accurately.
287   Previously, TH used heuristics to determine whether a data type
288   should be reified using GADT syntax, which could lead to incorrect results,
289   such as ``data T1 a = (a ~ Int) => MkT1`` being reified as a GADT and
290   ``data T2 a where MkT2 :: Show a => T2 a`` *not* being reified as a GADT.
291
292   In addition, reified GADT constructors now more accurately track the order in
293   which users write type variables. Before, if you reified ``MkT`` as below: ::
294
295       data T a where
296         MkT :: forall b a. b -> T a
297
298   Then the reified type signature of ``MkT`` would have been headed by
299   ``ForallC [PlainTV a, PlainTV b]``. Now, reifying ``MkT`` will give a type
300   headed by ``ForallC [PlainTV b, PlainTV a]``, as one would expect.
301
302 ``ghc`` library
303 ~~~~~~~~~~~~~~~
304
305 - 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>`_
306
307   The main change for users of the GHC API is that the AST is no longer indexed
308   by the type used as the identifier, but by a specific index type, ::
309
310       type GhcPs   = GhcPass 'Parsed      -- Old 'RdrName' type param
311       type GhcRn   = GhcPass 'Renamed     -- Old 'Name' type param
312       type GhcTc   = GhcPass 'Typechecked -- Old 'Id' type para,
313       type GhcTcId = GhcTc                -- Old 'TcId' type param
314
315   The simplest way to support the current GHC as well as earlier ones is to define ::
316
317       #if MIN_VERSION_ghc(8,3,0)
318       type ParseI     = GhcPs
319       type RenameI    = GhcRn
320       type TypecheckI = GhcTc
321       #else
322       type ParseI     = RdrName
323       type RenameI    = Name
324       type TypecheckI = Var
325       #endif
326
327   and then replace all hardcoded index types accordingly. For polymorphic types,
328   the constraint ::
329
330       #if MIN_VERSION_ghc(8,3,0)
331       -- |bundle up the constraints required for a trees that grow pass
332       type IsPass pass = (DataId pass, OutputableBndrId pass, SourceTextX pass)
333       else
334       type IsPass pass = (DataId pass, OutputableBndrId pass)
335       #endif
336
337   can be used.
338
339 ``base`` library
340 ~~~~~~~~~~~~~~~~
341
342 - Blank strings can now be used as values for environment variables using the
343   System.Environment.Blank module. See :ghc-ticket:`12494`
344
345 - ``Data.Type.Equality.==`` is now a closed type family. It works for all kinds
346   out of the box. Any modules that previously declared instances of this family
347   will need to remove them. Whereas the previous definition was somewhat ad
348   hoc, the behavior is now completely uniform. As a result, some applications
349   that used to reduce no longer do, and conversely. Most notably, ``(==)`` no
350   longer treats the ``*``, ``j -> k``, or ``()`` kinds specially; equality is
351   tested structurally in all cases.
352
353 Build system
354 ~~~~~~~~~~~~
355
356 - ``dll-split`` has been removed and replaced with an automatic partitioning utility ``gen-dll``.
357   This utility can transparently split and compile any DLLs that require this. Note that the ``rts`` and
358   ``base`` can not be split at this point because of the mutual recursion between ``base`` and ``rts``.
359   There is currently no explicit dependency between the two in the build system and such there is no way
360   to notify ``base`` that the ``rts`` has been split, or vice versa.
361   (see :ghc-ticket:`5987`).