.. _release-9-6-1:

Version 9.6.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.6>`_ 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.


Language
--------

- GHC is now more conservative when solving constraints that arise from
  superclass expansion in terms of other constraints that also arise from
  superclass expansion.

  For example: ::

    class C a
    class C a => D a b
    instance D a a => D a b

  When typechecking the instance, we need to also solve the constraints arising
  from the superclasses of ``D``; in this case, we need ``C a``. We could obtain
  evidence for this constraint by expanding the superclasses of the context,
  as ``D a a`` also has a superclass context of ``C a``.
  However, is it unsound to do so in general, as we might be assuming precisely
  the predicate we want to prove! This can lead to programs that loop at runtime.

  When such potentially-loopy situations arise, GHC now emits a warning.
  In future releases, this behaviour will no longer be supported, and the
  typechecker will outright refuse to solve these constraints, emitting a
  ``Could not deduce`` error.

  In practice, you should be able to fix these issues by adding the necessary
  constraint to the context, e.g. for the above example: ::

    instance (C a, D a a) => D a b

- Record updates for GADTs and other existential datatypes are now
  fully supported.

  For example: ::

    data D b where
      MkD :: { fld1 :: a -> a, fld2 :: a -> (), fld3 :: b } -> D b

    foo :: D b -> D b
    foo d = d { fld1 = id, fld2 = const () }

  In this example, we have an existential variable ``a``, and we update
  all fields whose type involves ``a`` at once, so the update is valid.

  A side-effect of this change is that GHC now rejects some record updates
  involving fields whose types contain type families (these record updates
  were previously erroneously accepted).

  Example: ::

    type family F a where
      F Int   = Char
      F Float = Char

    data T b = MkT { x :: [Int], y :: [F b] }

    emptyT :: forall b. T b
    emptyT = MkT [] []

    bar :: T Int
    bar = emptyT { x = [3] }

  In this example, we can't infer the type of ``emptyT`` in ``bar``: it could be
  ``T Int``, but it could also be ``T Float`` because the type family ``F``
  is not injective and ``T Float ~ T Int``. Indeed, the following typechecks ::

    baz :: T Int
    baz = case ( emptyT :: T Float ) of { MkT _ y -> MkT [3] y }

  This means that the type of ``emptyT`` is ambiguous in the definition
  of ``bar`` above, and thus GHC rejects the record update: ::

    Couldn't match type `F b0' with `Char'
    Expected: [F Int]
      Actual: [F b0]
    NB: ‘F’ is a non-injective type family
    The type variable ‘b0’ is ambiguous

  To fix these issues, add a type signature to the expression that the
  record update is applied to (``emptyT`` in the example above), or
  add an injectivity annotation to the type family in the case that
  the type family is in fact injective.

- Error messages are now assigned unique error codes, of the form ``[GHC-12345]``.

- GHC Proposal `#106
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0106-type-data.rst>`_
  has been implemented, introducing a new language extension
  :extension:`TypeData`. This extension permits ``type data`` declarations
  as a more fine-grained alternative to :extension:`DataKinds`.

- GHC now does a better job of solving constraints in the presence of multiple
  matching quantified constraints. For example, if we want to solve
  ``C a b Int`` and we have matching quantified constraints: ::

    forall x y z. (Ord x, Enum y, Num z) => C x y z
    forall u v. (Enum v, Eq u) => C u v Int

  Then GHC will use the second quantified constraint to solve ``C a b Int``,
  as it has a strictly weaker precondition.

- GHC proposal `#170 Unrestricted OverloadedLabels
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0170-unrestricted-overloadedlabels.rst>`_
  has been implemented.
  This extends the variety syntax for constructing labels under :extension:`OverloadedLabels`.
  Examples of newly allowed syntax:
  - Leading capital letters: `#Foo` equivalant to `getLabel @"Foo"`
  - Numeric characters: `#1728` equivalent to `getLabel @"1728"`
  - Arbitrary strings: `#"Hello, World!"` equivalent to `getLabel @"Hello, World!"`

Compiler
--------

- The `WebAssembly backend
  <https://www.tweag.io/blog/2022-11-22-wasm-backend-merged-in-ghc>`_
  has been merged. This allows GHC to be built as a cross-compiler
  that targets ``wasm32-wasi`` and compiles Haskell code to
  self-contained WebAssembly modules that can be executed on a variety
  of different runtimes. There are a few caveats to be aware of:

  - To use the WebAssembly backend, one would need to follow the
    instructions on `ghc-wasm-meta
    <https://gitlab.haskell.org/ghc/ghc-wasm-meta>`_. The WebAssembly
    backend is not included in the GHC release bindists for the time
    being, nor is it supported by ``ghcup`` or ``stack`` yet.
  - The WebAssembly backend is still under active development. It's
    presented in this GHC version as a technology preview, bugs and
    missing features are expected.

- The JavaScript backend has been merged. GHC is now able to be built as a
  cross-compiler targeting the JavaScript platform. The backend should be
  considered a technology preview. As such it is not ready for use in
  production, is not distributed in the GHC release bindists and requires the
  user to manually build GHC as a cross-compiler. See the JavaScript backend
  `wiki <https://gitlab.haskell.org/ghc/ghc/-/wikis/javascript-backend>`_ page
  on the GHC wiki for the current status, project roadmap, build instructions
  and demos.

- GHC now offers a new flag, :ghc-flag:`-fprefer-byte-code`, which instructs
  the compiler to to use byte-code when available when loading home package
  modules for execution (e.g. when evaluating TH splices). This avoids the
  considerable code generation and linking costs of native code, which is often
  unnecessary for one-off Template Haskell splices.
  See this `blog post <https://well-typed.com/blog/2023/02/interface-files-with-core/>`_
  for details.

- The :extension:`TypeInType` is now marked as deprecated. Its meaning has been included
  in :extension:`PolyKinds` and :extension:`DataKinds`.

- The :ghc-flag:`-Woperator-whitespace` warning no longer ignores constructor symbols
  (operators starting with ``:``).

- The :ghc-flag:`-Wstar-is-type` warning is now enabled by default, continuing
  the implementation of GHC proposal `#143
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0143-remove-star-kind.rst>`_.

GHCi
----

- GHCi will now accept any file-header pragmas it finds, such as
  ``{-# OPTIONS_GHC ... #-}`` and ``{-# LANGUAGE ... #-}`` (see :ref:`pragmas`).  For example,
  instead of using :ghci-cmd:`:set` to enable :ghc-flag:`-Wmissing-signatures`,
  you could instead write:

  .. code-block:: none

      ghci> {-# OPTIONS_GHC -Wmissing-signatures #-}

This can be convenient when pasting large multi-line blocks of code into GHCi.

Runtime system
--------------

- The `Delimited continuation primops <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0313-delimited-continuation-primops.rst>`_
  proposal has been implemented, adding native support for first-class,
  delimited continuations to the RTS. For the reasons given in the proposal,
  no safe API to access this functionality is provided anywhere in ``base``.
  Instead, the ``prompt#`` and ``control0#`` primops are intended to be consumed
  by library authors directly, who may wrap them a safe API that maintains the
  necessary invariants. See the documentation in ``GHC.Prim`` for more details.

- The behaviour of the ``-M`` flag has been made more strict. It will now trigger
  a heap overflow if the total amount of memory used by the Haskell heap exceeds the limit.
  Previously only live blocks were taken into account.
  This makes it more likely to trigger promptly when the heap is highly fragmented.

- Fixed a bug that sometimes caused live sparks to be GC'ed too early either during
  minor GC or major GC with workstealing disabled. See #22528.


``base`` library
----------------

Below is a list of major changes in ``base``. See the ``base`` changelog for a full list.

- Exceptions thrown by weak pointer finalizers can now be reported by setting
  a global exception handler, using ``GHC.Weak.Finalize.setFinalizerExceptionHandler``.
  The default behaviour is unchanged (exceptions are ignored and not reported).

- GHC now provides a set of operations for introspecting on the threads of a
  program, ``GHC.Conc.listThreads``, as well as operations for querying a thread's
  label (:base-ref:`GHC.Conc.Sync.threadLabel`) and status
  (:base-ref:`GHC.Conc.threadStatus`).

- Change default ``Ord`` implementation of ``(>=)``, ``(>)``, and ``(<)`` to use
  ``(<=)`` instead of ``compare`` per CLC proposal:
  https://github.com/haskell/core-libraries-committee/issues/24

- Updated to `Unicode 15.0.0 <https://www.unicode.org/versions/Unicode15.0.0/>`_.

- Add standard Unicode case predicates :base-ref:`Data.Char.isUpperCase` and
  :base-ref:`Data.Char.isLowerCase`. These predicates use the standard Unicode
  case properties and are more intuitive than :base-ref:`Data.Char.isUpper` and
  :base-ref:`Data.Char.isLower`.


``ghc`` library
---------------

- Add `Foreign.C.Types.ConstPtr` was added to encode ``const``-qualified pointer return
  types in foreign declarations when using ``CApiFFI`` extension.


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.
