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