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