Add `-W(no-)xxx` aliases for `-f(no-)warn-xxx` flags
[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 -  Warnings can now be controlled with ``-W(no-)...`` flags in addition to
164    the old ``-f(no-)warn...`` ones. This was done as the first part of a
165    rewrite of the warning system to provide better control over warnings,
166    better warning messages, and more common syntax compared to other
167    compilers. The old ``-f``-based warning flags will remain functional for
168    the forseeable future.
169
170 -  Added the option ``-dth-dec-file``. This dumps out a .th.hs file of
171    all Template Haskell declarations in a corresponding .hs file. The
172    idea is that application developers can check this into their
173    repository so that they can grep for identifiers used elsewhere that
174    were defined in Template Haskell. This is similar to using
175    ``-ddump-to-file`` with ``-ddump-splices`` but it always generates a
176    file instead of being coupled to ``-ddump-to-file`` and only outputs
177    code that does not exist in the .hs file and a comment for the splice
178    location in the original file.
179
180 -  Added the option ``-fprint-expanded-types``. When enabled, GHC also
181    prints type-synonym-expanded types in type errors.
182
183 -  Added the option ``-fcpr-anal``. When enabled, the demand analyser
184    performs CPR analysis. It is implied by ``-O``. Consequently,
185    ``-fcpr-off`` is now removed, run with ``-fno-cpr-anal`` to get the
186    old ``-fcpr-off`` behaviour.
187
188 -  Added the option ``-fworker-wrapper``. When enabled, the worker-wrapper
189    transformation is performed after a strictness analysis pass. It is implied
190    by ``-O`` and by ``-fstrictness``. It is disabled by ``-fno-strictness``.
191    Enabling ``-fworker-wrapper`` while strictness analysis is disabled (by
192    ``-fno-strictness``) has no effect.
193
194 -  Added the options ``-Wmissed-specialisations`` and
195    ``-Wall-missed-specialisations``. When enabled, the simplifier will
196    produce a warning when a overloaded imported function cannot be
197    specialised (typically due to a missing ``INLINEABLE`` pragma). This
198    is intended to alert users to cases where they apply ``INLINEABLE`` but
199    may not get the speed-up they expect.
200
201 -  Added the option ``-Wnoncanonical-monad-instances`` which helps
202    detect noncanonical ``Applicative``/``Monad`` instance definitions.
203    See flag description in :ref:`options-sanity` for more details.
204
205 -  When printing an out-of-scope error message, GHC will give helpful advice if
206    the error might be caused by too restrictive imports.
207
208 -  Added the ``-Wcompat`` warning group, along with its opposite
209    ``-Wno-compat``. Turns on warnings that will be enabled by default in the
210    future, but remain off in normal compilations for the time being. This
211    allows library authors eager to make their code future compatible to adapt
212    to new features before they even generate warnings.
213
214 -  Added the ``-Wmissing-monadfail-instance`` flag. When enabled, this
215    will issue a warning if a failable pattern is used in a context that does
216    not have a ``MonadFail`` constraint. This flag represents phase 1 of the
217    `MonadFail Proposal (MFP)
218    <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
219
220 -  Added the ``-Wsemigroup`` flag. When enabled, this
221    will issue a warning if a type is an instance of ``Monoid`` but not
222    ``Semigroup``, and when a custom definition ``(<>)`` is made. Fixing these
223    warnings makes sure the definition of ``Semigroup`` as a superclass of
224    ``Monoid`` does not break any code.
225
226 -  Added the ``-Wmissing-pat-syn-sigs`` flag. When enabled, this will issue
227    a warning when a pattern synonym definition doesn't have a type signature.
228    It is turned off by default but enabled by ``-Wall``.
229
230 GHCi
231 ~~~~
232
233 -  ``Main`` with an explicit module header but without ``main`` is now
234    an error (#7765).
235
236 -  The ``:back`` and ``:forward`` commands now take an optional count
237    allowing the user to move forward or backward in history several
238    steps at a time.
239
240 -  Added commands ``:load!`` and ``:reload!``, effectively setting
241    "-fdefer-type-errors" before loading a module and unsetting it after
242    loading if it has not been set before (#8353).
243
244 -  ``ghci -e`` now behaves like ``ghc -e`` (#9360).
245
246 -  Added support for top-level function declarations (#7253).
247
248 Template Haskell
249 ~~~~~~~~~~~~~~~~
250
251 -  The new ``-XTemplateHaskellQuotes`` flag allows to use the
252    quotes (not quasi-quotes) subset of ``TemplateHaskell``.  This is
253    particularly useful for use with a stage 1 compiler (i.e. GHC
254    without interpreter support). Also, ``-XTemplateHaskellQuotes`` is
255    considered safe under Safe Haskell.
256
257 -  Partial type signatures can now be used in splices, see
258    :ref:`pts-where`.
259
260 -  ``Template Haskell`` now fully supports typed holes and quoting unbound
261    variables.  This means it is now possible to use pattern splices nested
262    inside quotation brackets.
263
264 -  ``Template Haskell`` now supports the use of ``UInfixT`` in types to
265    resolve infix operator fixities, in the same vein as ``UInfixP`` and
266    ``UInfixE`` in patterns and expressions. ``ParensT`` and ``InfixT``
267    have also been introduced, serving the same functions as their
268    pattern and expression counterparts.
269
270 -  Primitive chars (e.g., ``[| 'a'# |]``) and primitive strings (e.g.,
271    ``[| "abc"# |]``) can now be quoted with Template Haskell. The
272    ``Lit`` data type also has a new constructor, ``CharPrimL``, for
273    primitive char literals.
274
275 -  ``addTopDecls`` now accepts annotation pragmas.
276
277 -  Internally, the implementation of quasi-quotes has been unified with
278    that of normal Template Haskell splices. Under the previous
279    implementation, top-level declaration quasi-quotes did not cause a
280    break in the declaration groups, unlike splices of the form
281    ``$(...)``. This behavior has been preserved under the new
282    implementation, and is now recognized and documented in
283    :ref:`th-syntax`.
284
285 -  The ``Lift`` class is now derivable via the ``-XDeriveLift`` extension. See
286    :ref:`deriving-lift` for more information.
287
288 -  The ``FamilyD`` data constructor and ``FamFlavour`` data type have
289    been removed. Data families are now represented by ``DataFamilyD`` and
290    open type families are now represented by ``OpenTypeFamilyD`` instead
291    of ``FamilyD``. Common elements of ``OpenTypeFamilyD`` and
292    ``ClosedTypeFamilyD`` have been moved to ``TypeFamilyHead``.
293
294 -  The representation of ``data``, ``newtype``, ``data instance``, and
295    ``newtype instance`` declarations has been changed to allow for
296    multi-parameter type classes in the ``deriving`` clause. In particular,
297    ``dataD`` and ``newtypeD`` now take a ``CxtQ`` instead of a ``[Name]``
298    for the list of derived classes.
299
300 -  ``isExtEnabled`` can now be used to determine whether a language extension
301    is enabled in the ``Q`` monad. Similarly, ``extsEnabled`` can be used to list
302    all enabled language extensions.
303
304
305 Runtime system
306 ~~~~~~~~~~~~~~
307
308 -  Support for performance monitoring with PAPI has been dropped.
309
310 Build system
311 ~~~~~~~~~~~~
312
313 -  TODO FIXME.
314
315 Package system
316 ~~~~~~~~~~~~~~
317
318 -  TODO FIXME.
319
320 Libraries
321 ---------
322
323 array
324 ~~~~~
325
326 -  Version number XXXXX (was 0.5.0.0)
327
328
329 .. _lib-base:
330
331 base
332 ~~~~
333
334 -  Version number 4.9.0.0 (was 4.7.0.0)
335
336 -  ``GHC.Stack`` exports two new types ``SrcLoc`` and ``CallStack``. A
337    ``SrcLoc`` contains package, module, and file names, as well as start
338    and end positions. A ``CallStack`` is a ``[(String, SrcLoc)]``,
339    sorted by most-recent call.
340
341 -  ``error`` and ``undefined`` will now report a partial stack-trace
342    using the new ``CallStack`` feature (and the ``-prof`` stack if available).
343
344 -  A new function, ``interruptible``, was added to ``GHC.IO`` allowing
345    an ``IO`` action to be run such that it can be interrupted by an
346    asynchronous exception, even if exceptions are masked (except if
347    masked with ``interruptibleMask``).
348
349    This was introduced to fix the behavior of ``allowInterrupt``, which
350    would previously incorrectly allow exceptions in uninterruptible
351    regions (see :ghc-ticket:`9516`).
352
353 -  Per-thread allocation counters (``setAllocationCounter`` and
354    ``getAllocationCounter``) and limits (``enableAllocationLimit``,
355    ``disableAllocationLimit`` are now available from ``System.Mem``. Previously
356    this functionality was only available from ``GHC.Conc``.
357
358 - ``forever``, ``filterM``, ``mapAndUnzipM``, ``zipWithM``, ``zipWithM_``,
359   ``replicateM``, and ``replicateM`` were generalized from ``Monad`` to
360   ``Applicative``. If this causes performance regressions, try to make the
361   implementation of ``(*>)`` match that of ``(>>)``.
362
363 - Add ``GHC.TypeLits.TypeError`` and ``ErrorMessage`` to allow users
364   to define custom compile-time error messages.
365
366 binary
367 ~~~~~~
368
369 -  Version number XXXXX (was 0.7.1.0)
370
371 bytestring
372 ~~~~~~~~~~
373
374 -  Version number XXXXX (was 0.10.4.0)
375
376 Cabal
377 ~~~~~
378
379 -  Version number XXXXX (was 1.18.1.3)
380
381 containers
382 ~~~~~~~~~~
383
384 -  Version number XXXXX (was 0.5.4.0)
385
386 deepseq
387 ~~~~~~~
388
389 -  Version number XXXXX (was 1.3.0.2)
390
391 directory
392 ~~~~~~~~~
393
394 -  Version number XXXXX (was 1.2.0.2)
395
396 filepath
397 ~~~~~~~~
398
399 -  Version number XXXXX (was 1.3.0.2)
400
401 ghc
402 ~~~
403
404 -  TODO FIXME.
405
406 -  The ``HsBang`` type has been removed in favour of ``HsSrcBang`` and
407    ``HsImplBang``. Data constructors now always carry around their
408    strictness annotations as the user wrote them, whether from an
409    imported module or not.
410
411 -  Moved ``startsVarSym``, ``startsVarId``, ``startsConSym``, ``startsConId``,
412    ``startsVarSymASCII``, and ``isVarSymChar`` from ``Lexeme`` to the
413    ``GHC.Lemexe`` module of the ``ghc-boot`` library.
414
415 -  Add ``isImport``, ``isDecl``, and ``isStmt`` functions.
416
417 ghc-boot
418 ~~~~~~~~
419
420 -  This is an internal package. Use with caution.
421
422 -  This package was renamed from ``bin-package-db`` to reflect its new purpose
423    of containing intra-GHC functionality that needs to be shared across
424    multiple GHC boot libraries.
425
426 -  Added ``GHC.Lexeme``, which contains functions for determining if a
427    character can be the first letter of a variable or data constructor in
428    Haskell, as defined by GHC. (These functions were moved from ``Lexeme``
429    in ``ghc``.)
430
431 -  Added ``GHC.LanguageExtensions`` which contains a type listing all
432    supported language extensions.
433
434 ghc-prim
435 ~~~~~~~~
436
437 -  Version number XXXXX (was 0.3.1.0)
438
439 haskell98
440 ~~~~~~~~~
441
442 -  Version number XXXXX (was 2.0.0.3)
443
444 haskell2010
445 ~~~~~~~~~~~
446
447 -  Version number XXXXX (was 1.1.1.1)
448
449 hoopl
450 ~~~~~
451
452 -  Version number XXXXX (was 3.10.0.0)
453
454 hpc
455 ~~~
456
457 -  Version number XXXXX (was 0.6.0.1)
458
459 integer-gmp
460 ~~~~~~~~~~~
461
462 -  Version number XXXXX (was 0.5.1.0)
463
464 old-locale
465 ~~~~~~~~~~
466
467 -  Version number XXXXX (was 1.0.0.6)
468
469 old-time
470 ~~~~~~~~
471
472 -  Version number XXXXX (was 1.1.0.2)
473
474 process
475 ~~~~~~~
476
477 -  Version number XXXXX (was 1.2.0.0)
478
479 template-haskell
480 ~~~~~~~~~~~~~~~~
481
482 -  Version number XXXXX (was 2.9.0.0)
483
484 -  The ``Lift`` type class for lifting values into Template Haskell
485    splices now has a default signature ``lift :: Data a => a -> Q Exp``,
486    which means that you do not have to provide an explicit
487    implementation of ``lift`` for types which have a ``Data`` instance.
488    To manually use this default implementation, you can use the
489    ``liftData`` function which is now exported from
490    ``Language.Haskell.TH.Syntax``.
491
492 -  ``Info``'s constructors no longer have ``Fixity`` fields. A
493    ``qReifyFixity`` function was added to the ``Quasi`` type class (as
494    well as the ``reifyFixity`` function, specialized for ``Q``) to allow
495    lookup of fixity information for any given ``Name``.
496
497 time
498 ~~~~
499
500 -  Version number XXXXX (was 1.4.1)
501
502 unix
503 ~~~~
504
505 -  Version number XXXXX (was 2.7.0.0)
506
507 Win32
508 ~~~~~
509
510 -  Version number XXXXX (was 2.3.0.1)
511
512 Known bugs
513 ----------
514
515 -  TODO FIXME