79bed2c16de7fedeca86bcd9e01aad0b9f1bd59c
[ghc.git] / docs / users_guide / 7.12.1-notes.rst
1 .. _release-7-12-1:
2
3 Release notes for version 7.12.1
4 ================================
5
6 The significant changes to the various parts of the compiler are listed
7 in the following sections. There have also been numerous bug fixes and
8 performance improvements over the 7.10 branch.
9
10 Highlights
11 ----------
12
13 The highlights, since the 7.10 branch, are:
14
15 - TODO FIXME
16
17 - nokinds
18
19 - Record pattern synonyms
20
21 - ``-XDeriveAnyClass``
22
23 - More reliable DWARF debugging information
24
25 - Injective type classes
26
27 - Applicative ``do`` notation
28
29 - Support for wildcards in data and type family instances
30
31 - ``Strict`` and ``StrictData`` extensions, allowing modules to be compiled with
32    strict-by-default bindings.
33
34 - ``DuplicateRecordFields``, allowing multiple datatypes to declare the same
35   record field names provided they are used unambiguously
36
37 - Support for implicit parameters providing light-weight callstacks and source locations
38
39 - User-defined error messages for type errors
40
41 - A rewritten (and greatly improved) pattern exhaustiveness checker
42
43 - The reworked users guide you are now reading
44
45
46 Full details
47 ------------
48
49 Language
50 ~~~~~~~~
51
52 -  TODO FIXME.
53
54 -  The parser now supports Haddock comments on GADT data constructors.
55    For example ::
56
57         data Expr a where
58             -- | Just a normal sum
59             Sum :: Int -> Int -> Expr Int
60
61 -  Implicit parameters of the new ``base`` type ``GHC.Stack.CallStack``
62    are treated specially in function calls, the solver automatically
63    appends the source location of the call to the ``CallStack`` in
64    the environment. For example ::
65
66         myerror :: (?callStack :: CallStack) => String -> a
67         myerror msg = error (msg ++ "\n" ++ prettyCallStack ?callStack)
68
69         ghci> myerror "die"
70         *** Exception: die
71         CallStack (from ImplicitParams):
72           myerror, called at <interactive>:2:1 in interactive:Ghci1
73
74    prints the call-site of ``myerror``. The name of the implicit
75    parameter does not matter, but within ``base`` we call it
76    ``?callStack``.
77
78    See :ref:`lib-base` for a description of the ``CallStack`` type.
79
80 -  To conform to the common case, the default role assigned to
81    parameters of datatypes declared in ``hs-boot`` files is
82    ``representational``. However, if the constructor(s) for the datatype
83    are given, it makes sense to do normal role inference. This is now
84    implemented, effectively making the default role for non-abstract
85    datatypes in ``hs-boot`` files to be ``phantom``, like it is in
86    regular Haskell code.
87
88 -  Wildcards can be used in the type arguments of type/data family
89    instance declarations to indicate that the name of a type variable
90    doesn't matter. They will be replaced with new unique type variables.
91    See :ref:`data-instance-declarations` for more details.
92
93 -  GHC now allows to declare type families as injective. Injectivity
94    information can then be used by the typechecker. See
95    :ref:`injective-ty-fams` for details.
96
97 -  Due to a :ghc-ticket:`security issue <10826>`, Safe Haskell now forbids
98    annotations in programs marked as ``-XSafe``.
99
100 -  Generic instances can be derived for data types whose constructors have
101    arguments with certain unlifted types. See :ref:`generic-programming` for
102    more details.
103
104 -  The ``-XDeriveAnyClass`` extension now fills in associated type family
105    default instances when deriving a class that contains them.
106
107 -  Users can now define record pattern synonyms. This allows pattern synonyms
108    to behave more like normal data constructors. For example, ::
109
110       pattern P :: a -> b -> (a, b)
111       pattern P{x,y} = (x,y)
112
113    will allow ``P`` to be used like a record data constructor and also defines
114    selector functions ``x :: (a, b) -> a`` and ``y :: (a, b) -> b``.
115
116 -  Pattern synonyms can now be bundled with type constructors. For a pattern
117    synonym ``P`` and a type constructor ``T``, ``P`` can be bundled with ``T``
118    so that when ``T`` is imported ``P`` is also imported. With this change
119    a library author can provide either real data constructors or pattern
120    synonyms in an opaque manner. See :ref:`pattern-synonyms` for details. ::
121
122       -- Foo.hs
123       module Foo ( T(P) ) where
124
125       data T = T
126
127       pattern P = T
128
129       -- Baz.hs
130       module Baz where
131
132       -- P is imported
133       import Foo (T(..))
134
135 -  Whenever a data instance is exported, the corresponding data family
136    is exported, too. This allows one to write ::
137
138      -- Foo.hs
139      module Foo where
140
141      data family T a
142
143      -- Bar.hs
144      module Bar where
145
146      import Foo
147
148      data instance T Int = MkT
149
150      -- Baz.hs
151      module Baz where
152
153      import Bar (T(MkT))
154
155    In previous versions of GHC, this required a workaround via an
156    explicit export list in ``Bar``.
157
158
159
160 Compiler
161 ~~~~~~~~
162
163 -  Added the option ``-dth-dec-file``. This dumps out a .th.hs file of
164    all Template Haskell declarations in a corresponding .hs file. The
165    idea is that application developers can check this into their
166    repository so that they can grep for identifiers used elsewhere that
167    were defined in Template Haskell. This is similar to using
168    ``-ddump-to-file`` with ``-ddump-splices`` but it always generates a
169    file instead of being coupled to ``-ddump-to-file`` and only outputs
170    code that does not exist in the .hs file and a comment for the splice
171    location in the original file.
172
173 -  Added the option ``-fprint-expanded-types``. When enabled, GHC also
174    prints type-synonym-expanded types in type errors.
175
176 -  Added the option ``-fcpr-anal``. When enabled, the demand analyser
177    performs CPR analysis. It is implied by ``-O``. Consequently,
178    ``-fcpr-off`` is now removed, run with ``-fno-cpr-anal`` to get the
179    old ``-fcpr-off`` behaviour.
180
181 -  Added the option ``-fworker-wrapper``. When enabled, the worker-wrapper
182    transformation is performed after a strictness analysis pass. It is implied
183    by ``-O`` and by ``-fstrictness``. It is disabled by ``-fno-strictness``.
184    Enabling ``-fworker-wrapper`` while strictness analysis is disabled (by
185    ``-fno-strictness``) has no effect.
186
187 -  Added the options ``-fwarn-missed-specialisations`` and
188    ``-fwarn-all-missed-specialisations``. When enabled, the simplifier will
189    produce a warning when a overloaded imported function cannot be
190    specialised (typically due to a missing ``INLINEABLE`` pragma). This
191    is intended to alert users to cases where they apply ``INLINEABLE`` but
192    may not get the speed-up they expect.
193
194 -  Added the option ``-fwarn-noncanonical-monad-instances`` which helps
195    detect noncanonical ``Applicative``/``Monad`` instance definitions.
196    See flag description in :ref:`options-sanity` for more details.
197
198 -  When printing an out-of-scope error message, GHC will give helpful advice if
199    the error might be caused by too restrictive imports.
200
201 -  Added the ``-Wcompat`` warning group, along with its opposite
202    ``-Wno-compat``. Turns on warnings that will be enabled by default in the
203    future, but remain off in normal compilations for the time being. This
204    allows library authors eager to make their code future compatible to adapt
205    to new features before they even generate warnings.
206
207 -  Added the ``-fwarn-missing-monadfail-instance`` flag. When enabled, this
208    will issue a warning if a failable pattern is used in a context that does
209    not have a ``MonadFail`` constraint. This flag represents phase 1 of the
210    `MonadFail Proposal (MFP)
211    <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
212
213 -  Added the ``-fwarn-semigroup`` flag. When enabled, this
214    will issue a warning if a type is an instance of ``Monoid`` but not
215    ``Semigroup``, and when a custom definition ``(<>)`` is made. Fixing these
216    warnings makes sure the definition of ``Semigroup`` as a superclass of
217    ``Monoid`` does not break any code.
218
219 -  Added the ``-fwarn-missing-pat-syn-sigs`` flag. When enabled, this will issue
220    a warning when a pattern synonym definition doesn't have a type signature.
221    It is turned off by default but enabled by ``-Wall``.
222
223 GHCi
224 ~~~~
225
226 -  ``Main`` with an explicit module header but without ``main`` is now
227    an error (#7765).
228
229 -  The ``:back`` and ``:forward`` commands now take an optional count
230    allowing the user to move forward or backward in history several
231    steps at a time.
232
233 -  Added commands ``:load!`` and ``:reload!``, effectively setting
234    "-fdefer-type-errors" before loading a module and unsetting it after
235    loading if it has not been set before (#8353).
236
237 -  ``ghci -e`` now behaves like ``ghc -e`` (#9360).
238
239 -  Added support for top-level function declarations (#7253).
240
241 Template Haskell
242 ~~~~~~~~~~~~~~~~
243
244 -  The new ``-XTemplateHaskellQuotes`` flag allows to use the
245    quotes (not quasi-quotes) subset of ``TemplateHaskell``.  This is
246    particularly useful for use with a stage 1 compiler (i.e. GHC
247    without interpreter support). Also, ``-XTemplateHaskellQuotes`` is
248    considered safe under Safe Haskell.
249
250 -  Partial type signatures can now be used in splices, see
251    :ref:`pts-where`.
252
253 -  ``Template Haskell`` now fully supports typed holes and quoting unbound
254    variables.  This means it is now possible to use pattern splices nested
255    inside quotation brackets.
256
257 -  ``Template Haskell`` now supports the use of ``UInfixT`` in types to
258    resolve infix operator fixities, in the same vein as ``UInfixP`` and
259    ``UInfixE`` in patterns and expressions. ``ParensT`` and ``InfixT``
260    have also been introduced, serving the same functions as their
261    pattern and expression counterparts.
262
263 -  Primitive chars (e.g., ``[| 'a'# |]``) and primitive strings (e.g.,
264    ``[| "abc"# |]``) can now be quoted with Template Haskell. The
265    ``Lit`` data type also has a new constructor, ``CharPrimL``, for
266    primitive char literals.
267
268 -  ``addTopDecls`` now accepts annotation pragmas.
269
270 -  Internally, the implementation of quasi-quotes has been unified with
271    that of normal Template Haskell splices. Under the previous
272    implementation, top-level declaration quasi-quotes did not cause a
273    break in the declaration groups, unlike splices of the form
274    ``$(...)``. This behavior has been preserved under the new
275    implementation, and is now recognized and documented in
276    :ref:`th-syntax`.
277
278 -  The ``Lift`` class is now derivable via the ``-XDeriveLift`` extension. See
279    :ref:`deriving-lift` for more information.
280
281 -  The ``FamilyD`` data constructor and ``FamFlavour`` data type have
282    been removed. Data families are now represented by ``DataFamilyD`` and
283    open type families are now represented by ``OpenTypeFamilyD`` instead
284    of ``FamilyD``. Common elements of ``OpenTypeFamilyD`` and
285    ``ClosedTypeFamilyD`` have been moved to ``TypeFamilyHead``.
286
287 -  The representation of ``data``, ``newtype``, ``data instance``, and
288    ``newtype instance`` declarations has been changed to allow for
289    multi-parameter type classes in the ``deriving`` clause. In particular,
290    ``dataD`` and ``newtypeD`` now take a ``CxtQ`` instead of a ``[Name]``
291    for the list of derived classes.
292
293 Runtime system
294 ~~~~~~~~~~~~~~
295
296 -  Support for performance monitoring with PAPI has been dropped.
297
298 Build system
299 ~~~~~~~~~~~~
300
301 -  TODO FIXME.
302
303 Package system
304 ~~~~~~~~~~~~~~
305
306 -  TODO FIXME.
307
308 Libraries
309 ---------
310
311 array
312 ~~~~~
313
314 -  Version number XXXXX (was 0.5.0.0)
315
316
317 .. _lib-base:
318
319 base
320 ~~~~
321
322 -  Version number 4.9.0.0 (was 4.7.0.0)
323
324 -  ``GHC.Stack`` exports two new types ``SrcLoc`` and ``CallStack``. A
325    ``SrcLoc`` contains package, module, and file names, as well as start
326    and end positions. A ``CallStack`` is a ``[(String, SrcLoc)]``,
327    sorted by most-recent call.
328
329 -  ``error`` and ``undefined`` will now report a partial stack-trace
330    using the new ``CallStack`` feature (and the ``-prof`` stack if available).
331
332 -  A new function, ``interruptible``, was added to ``GHC.IO`` allowing
333    an ``IO`` action to be run such that it can be interrupted by an
334    asynchronous exception, even if exceptions are masked (except if
335    masked with ``interruptibleMask``).
336
337    This was introduced to fix the behavior of ``allowInterrupt``, which
338    would previously incorrectly allow exceptions in uninterruptible
339    regions (see :ghc-ticket:`9516`).
340
341 -  Per-thread allocation counters (``setAllocationCounter`` and
342    ``getAllocationCounter``) and limits (``enableAllocationLimit``,
343    ``disableAllocationLimit`` are now available from ``System.Mem``. Previously
344    this functionality was only available from ``GHC.Conc``.
345
346 - ``forever``, ``filterM``, ``mapAndUnzipM``, ``zipWithM``, ``zipWithM_``,
347   ``replicateM``, and ``replicateM`` were generalized from ``Monad`` to
348   ``Applicative``. If this causes performance regressions, try to make the
349   implementation of ``(*>)`` match that of ``(>>)``.
350
351 - Add ``GHC.TypeLits.TypeError`` and ``ErrorMessage`` to allow users
352   to define custom compile-time error messages.
353
354 binary
355 ~~~~~~
356
357 -  Version number XXXXX (was 0.7.1.0)
358
359 bytestring
360 ~~~~~~~~~~
361
362 -  Version number XXXXX (was 0.10.4.0)
363
364 Cabal
365 ~~~~~
366
367 -  Version number XXXXX (was 1.18.1.3)
368
369 containers
370 ~~~~~~~~~~
371
372 -  Version number XXXXX (was 0.5.4.0)
373
374 deepseq
375 ~~~~~~~
376
377 -  Version number XXXXX (was 1.3.0.2)
378
379 directory
380 ~~~~~~~~~
381
382 -  Version number XXXXX (was 1.2.0.2)
383
384 filepath
385 ~~~~~~~~
386
387 -  Version number XXXXX (was 1.3.0.2)
388
389 ghc
390 ~~~
391
392 -  TODO FIXME.
393
394 -  The ``HsBang`` type has been removed in favour of ``HsSrcBang`` and
395    ``HsImplBang``. Data constructors now always carry around their
396    strictness annotations as the user wrote them, whether from an
397    imported module or not.
398
399 -  Moved ``startsVarSym``, ``startsVarId``, ``startsConSym``, ``startsConId``,
400    ``startsVarSymASCII``, and ``isVarSymChar`` from ``Lexeme`` to the
401    ``GHC.Lemexe`` module of the ``ghc-boot`` library.
402
403 -  Add ``isImport``, ``isDecl``, and ``isStmt`` functions.
404
405 ghc-boot
406 ~~~~~~~~
407
408 -  This is an internal package. Use with caution.
409
410 -  This package was renamed from ``bin-package-db`` to reflect its new purpose
411    of containing intra-GHC functionality that needs to be shared across
412    multiple GHC boot libraries.
413
414 -  Added ``GHC.Lexeme``, which contains functions for determining if a
415    character can be the first letter of a variable or data constructor in
416    Haskell, as defined by GHC. (These functions were moved from ``Lexeme``
417    in ``ghc``.)
418
419 ghc-prim
420 ~~~~~~~~
421
422 -  Version number XXXXX (was 0.3.1.0)
423
424 haskell98
425 ~~~~~~~~~
426
427 -  Version number XXXXX (was 2.0.0.3)
428
429 haskell2010
430 ~~~~~~~~~~~
431
432 -  Version number XXXXX (was 1.1.1.1)
433
434 hoopl
435 ~~~~~
436
437 -  Version number XXXXX (was 3.10.0.0)
438
439 hpc
440 ~~~
441
442 -  Version number XXXXX (was 0.6.0.1)
443
444 integer-gmp
445 ~~~~~~~~~~~
446
447 -  Version number XXXXX (was 0.5.1.0)
448
449 old-locale
450 ~~~~~~~~~~
451
452 -  Version number XXXXX (was 1.0.0.6)
453
454 old-time
455 ~~~~~~~~
456
457 -  Version number XXXXX (was 1.1.0.2)
458
459 process
460 ~~~~~~~
461
462 -  Version number XXXXX (was 1.2.0.0)
463
464 template-haskell
465 ~~~~~~~~~~~~~~~~
466
467 -  Version number XXXXX (was 2.9.0.0)
468
469 -  The ``Lift`` type class for lifting values into Template Haskell
470    splices now has a default signature ``lift :: Data a => a -> Q Exp``,
471    which means that you do not have to provide an explicit
472    implementation of ``lift`` for types which have a ``Data`` instance.
473    To manually use this default implementation, you can use the
474    ``liftData`` function which is now exported from
475    ``Language.Haskell.TH.Syntax``.
476
477 -  ``Info``'s constructors no longer have ``Fixity`` fields. A
478    ``qReifyFixity`` function was added to the ``Quasi`` type class (as
479    well as the ``reifyFixity`` function, specialized for ``Q``) to allow
480    lookup of fixity information for any given ``Name``.
481
482 time
483 ~~~~
484
485 -  Version number XXXXX (was 1.4.1)
486
487 unix
488 ~~~~
489
490 -  Version number XXXXX (was 2.7.0.0)
491
492 Win32
493 ~~~~~
494
495 -  Version number XXXXX (was 2.3.0.1)
496
497 Known bugs
498 ----------
499
500 -  TODO FIXME