Fix more documentation wibbles
[ghc.git] / docs / users_guide / 8.0.2-notes.rst
1 .. _release-8-0-2:
2
3 Release notes for version 8.0.2
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.0.1 release.
9
10 .. warning::
11
12     Only Cabal versions 1.24 and newer will function properly with this release.
13     (see :ghc-ticket:`11558`). Consequently it will likely be necessary to
14     recompile ``cabal-install`` before installing new packages.
15
16     The reason for this is a change in how packages are identified in GHC
17     8.0. While previous versions of Cabal identified packages to GHC with a
18     package key (with GHC's :ghc-flag:`-this-package-key` argument), GHC 8.0 and
19     later uses installed package IDs in place of package keys.
20
21 .. note::
22
23     Users compiling GHC on Mac OS X with XCode 7.3 will need to tell the build
24     system to use the ``nm-classic`` command instead of Apple's new ``nm``
25     implementation as the latter breaks POSIX compliance (see
26     :ghc-ticket:`11744`). This can be done by passing something like
27     ``--with-nm=$(xcrun --find nm-classic)`` to ``configure``.
28
29 Highlights
30 ----------
31
32 The highlights, since the 8.0.1 release, are:
33
34 -  Compatibility fixes with macOS Sierra and recent Linux distributions.
35
36 -  Many, many bug fixes.
37
38 -  A bug has been fixed that caused standalone derived ``Ix`` instances to fail
39    for GADTs with exactly one constructor (:ghc-ticket:`12583`).
40
41 -  Interface files produced by GHC should now be deterministic.
42
43 Full details
44 ------------
45
46 Language
47 ~~~~~~~~
48
49 -  A bug has been fixed that caused derived ``Show`` instances to fail in the
50    presence of :ghc-flag:`-XRebindableSyntax` and
51    :ghc-flag:`-XOverloadedStrings` (:ghc-ticket:`12688`).
52
53 -  GHC is now a bit more strict in typechecking code generated by
54    :ghc-flag:`-XGeneralizedNewtypeDeriving`. For example, GHC will now reject
55    this program: ::
56
57       class C m where
58         foo :: C m => m ()
59
60       newtype N m a = N (m a)
61         deriving C -- This is now an error
62
63    This is in contrast to GHC 8.0.1 and earlier, which would accept this code.
64    To fix this code, simply remove the ``C m`` constraint from ``foo``, as it
65    is wholly unnecessary: ::
66
67       class C m where
68         foo :: m ()
69
70 -  Some programs using :ghc-flag:`-XDefaultSignatures` that incorrectly
71    type-checked in GHC 8.0.1 are now rejected by GHC 8.0.2. Here is a
72    characteristic example: ::
73
74       class Monad m => MonadSupply m where
75         fresh :: m Integer
76         default fresh :: (MonadTrans t, MonadSupply m) => t m Integer
77         fresh = lift fresh
78
79       instance MonadSupply m => MonadSupply (IdentityT m)
80
81    Note that the ``m`` in the default type signature is being used in
82    a completely different way than the ``m`` in the non-default signature!
83    We can fix this (in a backwards-compatible way) like so: ::
84
85       class Monad m => MonadSupply m where
86         fresh :: m Integer
87         default fresh :: (MonadTrans t, MonadSupply m', m ~ t m') => m Integer
88                          -- Same 'm Integer' after the '=>'
89         fresh = lift fresh
90
91 -  Some programs which combine default type class method implementations and
92    overlapping instances may now fail to type-check. Here is an example: ::
93
94       class Foo a where
95         foo :: a -> [a]
96         foo _ = []
97
98       instance Foo a
99       instance Foo Int
100
101    The problem is that the overlapping ``Foo Int`` instance is not explicitly
102    marked as overlapping. To fix this, simply add an ``OVERLAPPING`` pragma: ::
103
104       instance {-# OVERLAPPING #-} Foo Int
105
106 -  GHC now adheres more closely to the Haskell 2010 Report with respect to
107    defaulting rules. As a result, GHC will now reject some defaulting rules
108    which GHC 8.0.1 and earlier would accept. For example, this is now
109    rejected ::
110
111       module Foo where
112       default (Bool)
113
114    because when the :ghc-flag:`-XExtendedDefaultRules` extension is not
115    enabled, defaulting rules only work for the ``Num`` class, of which ``Bool``
116    is not an instance. To make GHC accept the above program, simply enable the
117    :ghc-flag:`-XExtendedDefaultRules` extension.
118
119 Compiler
120 ~~~~~~~~
121
122 -  A compiler bug present in 8.0.1 resulting in undefined reference errors while
123    compiling some packages has been fixed. (see :ghc-ticket:`12076`).
124
125 -  A code generator bug which resulted in segmentation faults in compiled
126    programs has been fixed (see :ghc-ticket:`12757`).
127
128 -  GHC now supports systems whose C compiler produces position-independent
129    executables by default. (see :ghc-ticket:`12579`).
130
131 -  GHC can now be built on systems which use the ``gold`` linker by default
132    (see :ghc-ticket:`12816`).
133
134 -  GHC now reliably runs on macOS Sierra systems. Sierra introduced a linker
135    limitation which GHC occasionally surpassed when compiling programs with
136    many package dependencies. (see :ghc-ticket:`12479`).
137
138 -  The :ghc-flag:`-Wredundant-constraints` flag has been removed from the
139    :ghc-flag:`-Wall` flag set (see :ghc-ticket:`10635`).
140
141 -  Added :ghc-flag:`-fdefer-out-of-scope-variables`, which converts
142    out-of-scope variable errors into warnings.
143
144 -  The RTS :ghc-flag:`-xb` now reads the base heap address in any base,
145    defaulting to decimal, hexadecimal if the address starts with ``0x``, and
146    octal if the address starts with ``0``.
147
148 -  Due to an oversight in GHC 8.0.1, the value of the preprocessor macro
149    ``__GLASGOW_HASKELL_LLVM__``, which exposes the LLVM version used by GHC, was
150    no longer an integer. This value is now turned into an integer again, but the
151    formatting is changed to be in line with ``__GLASGOW_HASKELL__``
152    (:ghc-ticket:`12628`).
153
154 -  Parallel programs should be significantly more reliable on platforms with weak
155    memory consistency guarantees (:ghc-ticket:`12469`)
156
157 -  Interface files should now be bit-wise identical for a given build.
158    (:ghc-ticket:`4012`)
159
160 - Nearly two-hundred more bugs. See `Trac
161    <https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`__
162    for a complete list.
163
164 Runtime system
165 ~~~~~~~~~~~~~~
166
167 - The Runtime linker on Windows is once again recognizing POSIX functions under their
168   "deprecated" name. e.g. "strdup" will now be recognized and internally forwarded to "_strdup".
169   If you have existing code already using the correct names (e.g. _strdup) then this will just continue
170   to work and no change is needed. For more information about how the forwarding is done please see
171   `MSDN <https://msdn.microsoft.com/en-us/library/ms235384.aspx>`_ . This should now introduce the same
172   behavior both compiled and interpreted. (see :ghc-ticket:`12497`).
173
174 - Profiles from the cost-centre profiler now provide source span information.
175   (see :ghc-ticket:`11543`).
176
177 - The number of threads used for garbage collection is now configurable
178   independently from the number of capabilities with the new :ghc-flag:`-qn`
179   flag.
180
181 - The runtime system should now wake-up less often with large capability counts
182
183 - The runtime system is now a more efficient in handling programs with many
184   bound threads. (:ghc-ticket:`12419`)
185
186 - A number of runtime system bugs which could result in crashes (see
187   :ghc-ticket:`12728`, :ghc-ticket:`10860`, :ghc-ticket:`12019`,
188   :ghc-ticket:`11978`,  :ghc-ticket:`12038`, :ghc-ticket:`12208`)
189
190 Template Haskell
191 ~~~~~~~~~~~~~~~~
192
193 - ``addModFinalizer`` now exposes the local typing environment at the splice
194   point. This allows ``reify`` to see local and top-level definitions in the
195   current declaration group when used as in
196
197   .. code-block:: none
198
199       f x = $(addModFinalizer (reify 'x >>= runIO . print) >> [| x |])
200
201 ``ghc`` library
202 ~~~~~~~~~~~~~~~
203
204 - Accessors are now exposed for ``ErrUtils.ErrMsg`` and ``ErrUtils.ErrDoc``.
205
206 - There is now a ``createIservProcessHook`` to allow API users to redirect the
207   ``stdout`` and ``stderr`` handles.