users-guide: Mention changes necessary due to #13391
[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 Compiler
81 ~~~~~~~~
82
83 - The ``configure`` script now no longer accepts ``--with-TOOL`` flags (e.g.
84   ``--with-nm``, ``--with-ld``, etc.). Instead, these are taken from environment
85   variables, as is typical in ``autoconf`` scripts. For instance,
86   ``./configure --with-nm=/usr/local/bin/nm`` turns into
87   ``./configure NM=/usr/local/bin/nm``.
88
89 - Derived ``Functor``, ``Foldable``, and ``Traversable`` instances are now
90   optimized when their last type parameters have phantom roles.
91   Specifically, ::
92
93     fmap _ = coerce
94     traverse _ x = pure (coerce x)
95     foldMap _ _ = mempty
96
97   These definitions of ``foldMap`` and ``traverse`` are lazier than the ones we
98   would otherwise derive, as they may produce results without inspecting their
99   arguments at all.
100
101   See also :ref:`deriving-functor`, :ref:`deriving-foldable`, and
102   :ref:`deriving-traversable`.
103
104 - Derived ``Functor``, ``Foldable``, ``Traversable``, ``Generic``, and
105   ``Generic1`` instances now have better, and generally better-documented,
106   behaviors for types with no constructors. In particular, ::
107
108       fmap _ x = case x of
109       foldMap _ _ = mempty
110       traverse _ x = pure (case x of)
111       to x = case x of
112       to1 x = case x of
113       from x = case x of
114       from1 x = case x of
115
116   The new behavior generally leads to more useful error messages than the
117   old did, and lazier semantics for ``foldMap`` and ``traverse``.
118
119 - Derived ``Foldable`` instances now derive custom definitions for ``null``
120   instead of using the default one. This leads to asymptotically better
121   performance for recursive types not shaped like cons-lists, and allows ``null``
122   to terminate for more (but not all) infinitely large structures.
123
124 - Derived instances for types with no constructors now have appropriate
125   arities: they take all their arguments before producing errors. This may not
126   be terribly important in practice, but it seems like the right thing to do.
127   Previously, we generated ::
128
129       (==) = error ...
130
131 Now we generate ::
132
133       _ == _ = error ...
134
135 - `-fsplit-sections` is now supported on x86_64 Windows and is on by default.
136   See :ghc-ticket:`12913`.
137
138 - Configure on Windows now supports ``--enable-distro-toolchain`` which can be
139   used to build a GHC using compilers on your ``PATH`` instead of using the
140   bundled bindist. See :ghc-ticket:`13792`
141
142 - The optional ``instance`` keyword is now usable in type family instance
143   declarations. See :ghc-ticket:`13747`
144
145 - 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>`_
146   for a complete list.
147
148 Runtime system
149 ~~~~~~~~~~~~~~
150
151 - Function ``hs_add_root()`` was removed. It was a no-op since GHC-7.2.1
152   where module initialisation stopped requiring a call to ``hs_add_root()``.
153
154 - Proper import library support added to GHC which can handle all of the libraries produced
155   by dlltool. The limitation of them needing to be named with the suffix .dll.a is also removed.
156   See :ghc-ticket:`13606`, :ghc-ticket:`12499`, :ghc-ticket:`12498`
157
158 - The GHCi runtime linker on Windows now supports the `big-obj` file format.
159
160 Template Haskell
161 ~~~~~~~~~~~~~~~~
162
163 - Template Haskell now reifies data types with GADT syntax accurately.
164   Previously, TH used heuristics to determine whether a data type
165   should be reified using GADT syntax, which could lead to incorrect results,
166   such as ``data T1 a = (a ~ Int) => MkT1`` being reified as a GADT and
167   ``data T2 a where MkT2 :: Show a => T2 a`` *not* being reified as a GADT.
168
169 ``ghc`` library
170 ~~~~~~~~~~~~~~~
171
172 - 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>`_
173
174   The main change for users of the GHC API is that the AST is no longer indexed
175   by the type used as the identifier, but by a specific index type, ::
176
177       type GhcPs   = GhcPass 'Parsed      -- Old 'RdrName' type param
178       type GhcRn   = GhcPass 'Renamed     -- Old 'Name' type param
179       type GhcTc   = GhcPass 'Typechecked -- Old 'Id' type para,
180       type GhcTcId = GhcTc                -- Old 'TcId' type param
181
182   The simplest way to support the current GHC as well as earlier ones is to define ::
183
184       #if MIN_VERSION_ghc(8,3,0)
185       type ParseI     = GhcPs
186       type RenameI    = GhcRn
187       type TypecheckI = GhcTc
188       #else
189       type ParseI     = RdrName
190       type RenameI    = Name
191       type TypecheckI = Var
192       #endif
193
194   and then replace all hardcoded index types accordingly. For polymorphic types,
195   the constraint ::
196
197       #if MIN_VERSION_ghc(8,3,0)
198       -- |bundle up the constraints required for a trees that grow pass
199       type IsPass pass = (DataId pass, OutputableBndrId pass, SourceTextX pass)
200       else
201       type IsPass pass = (DataId pass, OutputableBndrId pass)
202       #endif
203
204   can be used.
205
206 ``base`` library
207 ~~~~~~~~~~~~~~~~
208
209 - Blank strings can now be used as values for environment variables using the
210   System.Environment.Blank module. See :ghc-ticket:`12494`
211
212 - ``Data.Type.Equality.==`` is now a closed type family. It works for all kinds
213   out of the box. Any modules that previously declared instances of this family
214   will need to remove them. Whereas the previous definition was somewhat ad
215   hoc, the behavior is now completely uniform. As a result, some applications
216   that used to reduce no longer do, and conversely. Most notably, ``(==)`` no
217   longer treats the ``*``, ``j -> k``, or ``()`` kinds specially; equality is
218   tested structurally in all cases.
219
220 Build system
221 ~~~~~~~~~~~~
222
223 - ``dll-split`` has been removed and replaced with an automatic partitioning utility ``gen-dll``.
224   This utility can transparently split and compile any DLLs that require this. Note that the ``rts`` and
225   ``base`` can not be split at this point because of the mutual recursion between ``base`` and ``rts``.
226   There is currently no explicit dependency between the two in the build system and such there is no way
227   to notify ``base`` that the ``rts`` has been split, or vice versa.
228   (see :ghc-ticket:`5987`).