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