.. _release-9-8-1:

Version 9.8.1
=============

The significant changes to the various parts of the compiler are listed in the
following sections. See the `migration guide
<https://gitlab.haskell.org/ghc/ghc/-/wikis/migration/9.8>`_ on the GHC Wiki
for specific guidance on migrating programs to this release.

The :ghc-flag:`LLVM backend <-fllvm>` of this release is to be used with LLVM
11, 12, 13, 14 or 15.

Breaking changes
~~~~~~~~~~~~~~~~

- In accordance with GHC proposal `#425
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0425-decl-invis-binders.rst>`_
  GHC no longer implicitly quantifies over type variables that appear only in the RHS of type and
  data family instances. This code will no longer work: ::

    type family F1 a :: k
    type instance F1 Int = Any :: j -> j

  Instead you should write::

    type instance F1 @(j -> j) Int = Any :: j -> j

  Or::

    type instance forall j . F1 Int = Any :: j -> j

- GHC proposal `#475 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0475-tuple-syntax.rst>`_
  has been partially implemented. Namely, tuple data types, which were previously represented using a brackets-with-commas
  syntax form ((), (,), (,,), and so on) have been renamed to common names of the form ``Unit``, ``Tuple2``, ``Tuple3``,
  and so on, where the number after ``Tuple`` indicates its arity: ::

    data Unit = ()

    data Tuple2 a b = (a,b)
    data Tuple3 a b c = (a, b, c)
    -- and so on, up to Tuple64

  For consistency, we also introduce type aliases: ::

    type Tuple0 = Unit
    type Tuple1 = Solo

  The renamed tuple data types and the new type aliases can be found in the ``GHC.Tuple`` module. This renaming
  does not break existing code that directly uses tuple data types, but it does affect tools and libraries
  that have access to the data type names, such as ``Generic`` and Template Haskell.

- Data types with ``deriving`` clauses now reject inferred instance contexts
  that mention ``TypeError`` constraints (see :ref:`custom-errors`), such as
  this one: ::

      newtype Foo = Foo Int

      class Bar a where
        bar :: a

      instance (TypeError (Text "Boo")) => Bar Foo where
        bar = undefined

      newtype Baz = Baz Foo
        deriving Bar

  Here, the derived ``Bar`` instance for ``Baz`` would look like this: ::

      instance TypeError (Text "Boo") => Bar Baz

  While GHC would accept this before, GHC 9.8 now rejects it, emitting "``Boo``"
  in the resulting error message. If you really want to derive this instance and
  defer the error to sites where the instance is used, you must do so manually
  with :extension:`StandaloneDeriving`, e.g. ::

      deriving instance TypeError (Text "Boo") => Bar Baz


Language
~~~~~~~~

- There is a new extension :extension:`ExtendedLiterals`, which enables
  sized primitive numeric literals, e.g. ``123#Int8`` is a literal of type ``Int8#``.
  See the GHC proposal `#451 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0451-sized-literals.rst>`_.
  Derived ``Show`` instances for datatypes containing sized literals (``Int8#``, ``Word8#``, ``Int16#`` etc.)
  now use the extended literal syntax, per GHC proposal `#596 <https://github.com/ghc-proposals/ghc-proposals/pull/596>`_.
  Furthermore, it is now possible to derive ``Show`` for datatypes containing
  fields of types ``Int64#`` and ``Word64#``.

- GHC Proposal `#425
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0425-decl-invis-binders.rst>`_
  has been partially implemented. Namely, the ``@k``-binders in type declarations are now permitted::

    type T :: forall k. k -> forall j. j -> Type
    data T @k (a :: k) @(j :: Type) (b :: j)

  This feature is guarded behind :extension:`TypeAbstractions`.

Compiler
~~~~~~~~

- Added a new warning :ghc-flag:`-Wterm-variable-capture` that helps to make code compatible with
  the future extension ``RequiredTypeArguments``.

- Rewrite rules now support a limited form of higher order matching when a
  pattern variable is applied to distinct locally bound variables, as proposed in
  `GHC Proposal #555 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0555-template-patterns.rst>`_.
  For example: ::

      forall f. foo (\x -> f x)

  Now matches: ::

      foo (\x -> x*2 + x)

- GHC Proposal `#496
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0496-empty-record-wildcards.rst>`_
  has been implemented, allowing ``{..}`` syntax for constructors without fields, for consistency.
  This is convenient for TH code generation, as you can now uniformly use record wildcards
  regardless of number of fields.

- Specialisation of incoherent instance applications can now be disabled with
  :ghc-flag:`-fno-specialise-incoherents`. This is necessary as the current
  specialisation implementation can result in in nondeterministic instance
  resolution in certain cases, breaking the specification described in the
  documentation of the :pragma:`INCOHERENT` pragma. See :ghc-ticket:`22448` for
  further details.

- Fix a bug in TemplateHaskell evaluation causing excessive calls to ``setNumCapabilities`` when :ghc-flag:`-j[⟨n⟩]` is greater than :rts-flag:`-N`.
  See :ghc-ticket:`23049`.

- The ``-Wno-⟨wflag⟩``, ``-Werror=⟨wflag⟩`` and ``-Wwarn=⟨wflag⟩`` options are
  now defined systematically for all warning groups (for example,
  ``-Wno-default``, ``-Werror=unused-binds`` and ``-Wwarn=all`` are now
  accepted). See :ref:`options-sanity`.

- ``WARNING`` pragmas may now be annotated with a category, following
  `GHC proposal #541 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0541-warning-pragmas-with-categories.rst>`_, in which case they are controlled with new
  ``-Wx-⟨category⟩`` flags rather than :ghc-flag:`-Wdeprecations`.
  A new warning group :ghc-flag:`-Wextended-warnings` includes all such warnings
  regardless of category.  See :ref:`warning-deprecated-pragma`.

- GHC is now better at disambiguating record updates in the presence of duplicate
  record fields. The following program is now accepted ::

     {-# LANGUAGE DuplicateRecordFields #-}

     data R = MkR1 { foo :: Int }
            | MkR2 { bar :: Int }

     data S = MkS { foo :: Int, bar :: Int }

     blah x = x { foo = 5, bar = 6 }

  The point is that only the type S has a constructor with both fields ``foo``
  and ``bar``, so this record update is unambiguous.

- GHC Proposal `#540 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0540-jsem.rst>`_ has been implemented.
  This adds the :ghc-flag:`-jsem` flag, which instructs GHC to act as a jobserver client.
  This enables multiple GHC processes running at once to share system resources
  with each other, communicating via the system semaphore specified by
  the flag argument.

  Complementary support for this feature in ``cabal-install`` will come soon.

- GHC Proposal `#433
  <https://github.com/ghc-proposals/ghc-proposals/blob/0c7667673fcb33ea8b38503e16f88de5b8b3d270/proposals/0433-unsatisfiable.rst>`_
  has been implemented. This adds the class ``Unsatisfiable :: ErrorMessage -> Constraint``
  to the :base-ref:`GHC.TypeError.` module. Constraints of the form ``Unsatisfiable msg``
  provide a mechanism for custom type errors that reports the errors in a more
  predictable behaviour than ``TypeError``, as these constraints are
  handled purely during constraint solving.

  For example: ::

      instance Unsatisfiable (Text "There is no Eq instance for functions") => Eq (a -> b) where
        (==) = unsatisfiable

  This allows errors to be reported when users use the instance, even when
  type errors are being deferred.

- GHC now deals with "insoluble Givens" in a consistent way. For example: ::

        k :: (Int ~ Bool) => Int -> Bool
        k x = x

  GHC used to accept the contradictory ``Int~Bool`` in the type signature, but
  reject the ``Int~Bool`` constraint that arises from typechecking the
  definition itself.  Now it accepts both.  More details in
  :ghc-ticket:`23413`, which gives examples of the previous inconsistency.  GHC
  now implements the "PermissivePlan" described in that ticket.

- The :ghc-flag:`-ddump-spec` flag has been split into :ghc-flag:`-ddump-spec` and
  :ghc-flag:`-ddump-spec-constr`, allowing only output from the typeclass specialiser or
  data-constructor specialiser to be dumped if desired.

- The compiler may now be configured to compress the debugging information
  included in :ghc-flag:`-finfo-table-map` enabled binaries. To do so, one must
  build GHC from source (see
  `here <https://gitlab.haskell.org/ghc/ghc/-/wikis/building>`_ for directions)
  and supply the ``--enable-ipe-data-compression`` flag to the ``configure``
  script. **Note**: This feature requires that the machine building GHC has
  `libzstd <https://github.com/facebook/zstd/>`_ version 1.4.0 or greater
  installed. The compression library `libzstd` may optionally be statically
  linked in the resulting compiler (on non-darwin machines) using the
  ``--enable-static-libzstd`` configure flag.

  In a test compiling GHC itself, the size of the :ghc-flag:`-finfo-table-map`
  enabled build results was reduced by over 20% when compression was enabled.

- GHC Proposal `#134
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0134-deprecating-exports-proposal.rst>`_
  has been implemented. This makes it possible to deprecate certain names exported from a module, without deprecating
  the name itself. You can check the full specification of the feature at :ref:`warning-deprecated-pragma`.

  For example ::

      module X
          ( {-# DEPRECATE D(D1) "D1 will not be exposed in a version 0.2 and later" #-}
            D(D1, D2)
          ) where
      data D = D1 | D2
      
  This allows for changing the structure of a library without immediately breaking user code,
  but instead being able to warn the user that a change in the library interface
  will occur in the future.

- Guard polymorphic specialisation behind the flag :ghc-flag:`-fpolymorphic-specialisation`.
  This optimisation has led to a number of incorrect runtime result bugs, so we are disabling it
  by default for now whilst we consider more carefully an appropiate fix.
  (See :ghc-ticket:`23469`, :ghc-ticket:`23109`, :ghc-ticket:`21229`, :ghc-ticket:`23445`)

- The warning about incompatible command line flags can now be controlled with the
  :ghc-flag:`-Winconsistent-flags`. In particular this allows you to silence a warning
  when using optimisation flags with :ghc-flag:`--interactive` mode.

GHCi
~~~~

- The deprecated ``:ctags`` and ``:etags`` GHCi commands have been removed. See
  this `wiki page
  <https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/GHCi/Tags>`_ if you
  want to add a macro to recover similar functionality.

Runtime system
~~~~~~~~~~~~~~

- On POSIX systems that support timerfd, RTS shutdown no longer has to wait for
  the next RTS 'tick' to occur before continuing the shutdown process. See :ghc-ticket:`22692`.

``base`` library
~~~~~~~~~~~~~~~~

Note that this is not an exhaustive list of changes in ``base``. See the
``base`` changelog for full details.

- Added ``{-# WARNING in "x-partial" #-}`` to ``Data.List.{head,tail}``.
- :base-ref:`Data.Tuple` now exports ``getSolo :: Solo a -> a``.
- Updated to `Unicode 15.1.0 <https://www.unicode.org/versions/Unicode15.1.0/>`_.
- Fixed exponent overflow/underflow bugs in the ``Read`` instances for ``Float`` and ``Double`` (`CLC proposal #192 <https://github.com/haskell/core-libraries-committee/issues/192>`_)

``ghc-prim`` library
~~~~~~~~~~~~~~~~~~~~

- Primitive pointer comparison functions are now levity-polymorphic, e.g. ::

      sameArray# :: forall {l} (a :: TYPE (BoxedRep l)). Array# a -> Array# a -> Int#

  This change affects the following functions:

    - ``sameArray#``, ``sameMutableArray#``,
    - ``sameSmallArray#``, ``sameSmallMutableArray#``,
    - ``sameMutVar#``, ``sameTVar#``, ``sameMVar#``
    - ``sameIOPort#``, ``eqStableName#``.

- New primops for fused multiply-add operations. These primops combine a
  multiplication and an addition, compiling to a single instruction when
  the :ghc-flag:`-mfma` flag is enabled and the architecture supports it.

  The new primops are ``fmaddFloat#, fmsubFloat#, fnmaddFloat#, fnmsubFloat# :: Float# -> Float# -> Float# -> Float#``
  and ``fmaddDouble#, fmsubDouble#, fnmaddDouble#, fnmsubDouble# :: Double# -> Double# -> Double# -> Double#``.

  These implement the following operations, while performing one single
  rounding at the end, leading to a more accurate result:

    - ``fmaddFloat# x y z``, ``fmaddDouble# x y z`` compute ``x * y + z``.
    - ``fmsubFloat# x y z``, ``fmsubDouble# x y z`` compute ``x * y - z``.
    - ``fnmaddFloat# x y z``, ``fnmaddDouble# x y z`` compute ``- x * y + z``.
    - ``fnmsubFloat# x y z``, ``fnmsubDouble# x y z`` compute ``- x * y - z``.

  Warning: on unsupported architectures, the software emulation provided by
  the fallback to the C standard library is not guaranteed to be IEEE-compliant.

``ghc`` library
~~~~~~~~~~~~~~~

- The ``RecordUpd`` constructor of ``HsExpr`` now takes an ``HsRecUpdFields``
  instead of ``Either [LHsRecUpdField p] [LHsRecUpdProj p]``.
  Instead of ``Left ..``, use the constructor ``RegularRecUpdFields``, and instead
  of ``Right ..``, use the constructor ``OverloadedRecUpdFields``.

- The ``loadWithCache`` function now takes an extra argument which allows API users
  to embed GHC diagnostics in their own diagnostic type before they are printed.
  This allows how messages are rendered and explained to users to be modified.
  We use this functionality in GHCi to modify how some messages are displayed.

- The extensions fields of constructors of ``IE`` now take ``Maybe (WarningTxt p)``
  in ``GhcPs`` and ``GhcRn`` variants of the Syntax Tree. 
  This represents the warning assigned to a certain export item, 
  which is used for :pragma:`deprecated exports <DEPRECATED>`.

``template-haskell`` library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Record fields now belong to separate ``NameSpace``\ s, keyed by the parent of
  the record field. This is the name of the first constructor of the parent type,
  even if this constructor does not have the field in question.
  This change enables :extension:`TemplateHaskell` support for :extension:`DuplicateRecordFields`.

``text`` library
~~~~~~~~~~~~~~~~

The version of the ``text`` library included changes ``Data.Text.Array.Array`` to be
a type synonym of ``Data.Array.Byte.ByteArray``. While its former  data
constructor, ``ByteArray``, has been replaced with a pattern synonym, it cannot
be imported as bundled with the type constructor.

Consequently, imports like: ::

    import Data.Text.Array (Array(..))

will need to avoid using a bundled import (e.g. by qualification): ::

    import Data.Text.Array as A


Included libraries
~~~~~~~~~~~~~~~~~~

The package database provided with this distribution also contains a number of
packages other than GHC itself. See the changelogs provided with these packages
for further change information.

.. ghc-package-list::

    libraries/array/array.cabal:             Dependency of ``ghc`` library
    libraries/base/base.cabal:               Core library
    libraries/binary/binary.cabal:           Dependency of ``ghc`` library
    libraries/bytestring/bytestring.cabal:   Dependency of ``ghc`` library
    libraries/Cabal/Cabal/Cabal.cabal:       Dependency of ``ghc-pkg`` utility
    libraries/Cabal/Cabal-syntax/Cabal-syntax.cabal:  Dependency of ``ghc-pkg`` utility
    libraries/containers/containers/containers.cabal: Dependency of ``ghc`` library
    libraries/deepseq/deepseq.cabal:         Dependency of ``ghc`` library
    libraries/directory/directory.cabal:     Dependency of ``ghc`` library
    libraries/exceptions/exceptions.cabal:   Dependency of ``ghc`` and ``haskeline`` library
    libraries/filepath/filepath.cabal:       Dependency of ``ghc`` library
    compiler/ghc.cabal:                      The compiler itself
    libraries/ghci/ghci.cabal:               The REPL interface
    libraries/ghc-boot/ghc-boot.cabal:       Internal compiler library
    libraries/ghc-boot-th/ghc-boot-th.cabal: Internal compiler library
    libraries/ghc-compact/ghc-compact.cabal: Core library
    libraries/ghc-heap/ghc-heap.cabal:       GHC heap-walking library
    libraries/ghc-prim/ghc-prim.cabal:       Core library
    libraries/haskeline/haskeline.cabal:     Dependency of ``ghci`` executable
    libraries/hpc/hpc.cabal:                 Dependency of ``hpc`` executable
    libraries/integer-gmp/integer-gmp.cabal: Core library
    libraries/mtl/mtl.cabal:                 Dependency of ``Cabal`` library
    libraries/parsec/parsec.cabal:           Dependency of ``Cabal`` library
    libraries/pretty/pretty.cabal:           Dependency of ``ghc`` library
    libraries/process/process.cabal:         Dependency of ``ghc`` library
    libraries/semaphore-compat/semaphore-compat.cabal: Dependency of ``ghc`` library
    libraries/stm/stm.cabal:                 Dependency of ``haskeline`` library
    libraries/template-haskell/template-haskell.cabal: Core library
    libraries/terminfo/terminfo.cabal:       Dependency of ``haskeline`` library
    libraries/text/text.cabal:               Dependency of ``Cabal`` library
    libraries/time/time.cabal:               Dependency of ``ghc`` library
    libraries/transformers/transformers.cabal: Dependency of ``ghc`` library
    libraries/unix/unix.cabal:               Dependency of ``ghc`` library
    libraries/Win32/Win32.cabal:             Dependency of ``ghc`` library
    libraries/xhtml/xhtml.cabal:             Dependency of ``haddock`` executable
