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