.. _release-9-14-1:

Version 9.14.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.14>`_ on the GHC Wiki
for specific guidance on migrating programs to this release.

Language
~~~~~~~~

* `GHC proposal 493: allow expressions in SPECIALISE pragmas <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0493-specialise-expressions.rst>`_
  has been implemented. SPECIALISE pragmas now allow arbitrary expressions such as: ::

    {-# SPECIALISE f @Int False :: Int -> Char #-}

  The ability to specify multiple specialisations in a single SPECIALISE pragma,
  with syntax of the form (note the comma between the type signatures): ::

    {-# SPECIALISE g : Int -> Int, Float -> Float #-}

  has been deprecated, and is scheduled to be removed in GHC 9.18.
  This deprecation is controlled by the newly introduced ``-Wdeprecated-pragmas``
  flag in ``-Wdefault``.

* Visible ``GADT`` syntax can now be used in GADT data constructors (:ghc-ticket:`25127`) ::

      data KindVal a where
          K :: forall k.
            forall (a::k) ->   -- now allowed!
            k ->
            KindVal a

* ``-Wincomplete-record-selectors`` is now part of `-Wall`, as specified
  by `GHC Proposal 516: add warning for incomplete record selectors <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0516-incomplete-record-selectors.rst>`_.
  Hence, if a library is compiled with ``-Werror``, compilation may now fail. Solution: fix the library.
  Workaround: add ``-Werror=no-incomplete-record-selectors``.

  Note that this warning is at least
  as serious as a warning about missing patterns from a function definition, perhaps even
  more so, since it is invisible in the source program.

* The combination of :extension:`ScopedTypeVariables` and :extension:`TypeApplications`
  no longer enables type applications in patterns, which now always requires
  :extension:`TypeAbstractions`. The warning flag``deprecated-type-abstractions``
  has also been removed from the compiler.

* :extension:`OverloadedRecordUpdate` now passes the arguments to a ``setField`` function
  in the flipped order, as specified by `GHC Proposal 583: HasField redesign <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0583-hasfield-redesign.rst>`_.

  Previously GHC expected ``setField`` to have this type: ::

    setField :: forall (fld :: Symbol) a r. r -> a -> r

  And that's what GHC expects now: ::

    setField :: forall (fld :: Symbol) a r. a -> r -> r

  That will break the combination of :extension:`OverloadedRecordUpdate` with :extension:`RebindableSyntax`.

* Multiline strings are now accepted in ``foreign import``\ s. (#25157)

* GHC now does a better job at inferring types in calls to ``coerce``: instead of
  complaining about ambiguous type variables, GHC will consider that such type
  variables are determined by the ``Coercible`` constraints they appear in.

* With :extension:`LinearTypes` record fields can now be non-linear. This means that
  the following record declaration is now valid:

  ::

      data Record = Rec { x %'Many :: Int, y :: Char }

  This causes the constructor to have type ``Rec :: Int %'Many -> Char %1 -> Record``.

* The :extension:`ExplicitNamespaces` extension now allows the ``data``
  namespace specifier in import and export lists.

* The ``-Wdata-kinds-tc`` warning has been deprecated, and the use of promoted
  data types in kinds is now an error (rather than a warning) unless the
  :extension:`DataKinds` extension is enabled. For example, the following code
  will be rejected unless :extension:`DataKinds` is on: ::

    import Data.Kind (Type)
    import GHC.TypeNats (Nat)

    -- Nat shouldn't be allowed here without DataKinds
    data Vec :: Nat -> Type -> Type

  (The ``-Wdata-kinds-tc`` warning was introduced in GHC 9.10 as part of a fix
  for an accidental oversight in which programs like the one above were
  mistakenly accepted without the use of :extension:`DataKinds`.)

* The :extension:`MonadComprehensions` extension now implies :extension:`ParallelListComp` as was originally intended (see `Monad Comprehensions <https://ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/monad_comprehensions.html>`_).

* In accordance with `GHC Proposal #281 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0281-visible-forall.rst>`_,
  section 4.7 "Data constructors", the :extension:`RequiredTypeArguments`
  extension now allows visible forall in types of data constructors
  (:ghc-ticket:`25127`). The following declaration is now accepted by GHC:

  ::

    data T a where
      Typed :: forall a -> a -> T a

  See :ref:`visible-forall-in-gadts` for details.

- Explicit level import support, allowing ``import`` declarations to explicitly
  state which compilation stages they are are visible to.

Compiler
~~~~~~~~

- An improved error message is introduced to refer users to the heap-controlling flags of the RTS when there is a heap overflow during compilation. (:ghc-ticket:`25198`)

- The kind checker now does a better job of finding type family instances for
  use in the kinds of other declarations in the same module. This fixes a number
  of tickets:
  :ghc-ticket:`12088`, :ghc-ticket:`12239`, :ghc-ticket:`14668`, :ghc-ticket:`15561`,
  :ghc-ticket:`16410`, :ghc-ticket:`16448`, :ghc-ticket:`16693`, :ghc-ticket:`19611`,
  :ghc-ticket:`20875`, :ghc-ticket:`21172`, :ghc-ticket:`22257`, :ghc-ticket:`25238`,
  :ghc-ticket:`25834`.

- The compiler no longer accepts invalid ``type`` namespace specifiers in
  subordinate import lists (:ghc-ticket:`22581`).

- A new flag, :ghc-flag:`-Wuseless-specialisations`, controls warnings emitted when GHC
  determines that a ``SPECIALISE`` pragma would have no effect.

- A new flag, :ghc-flag:`-Wrule-lhs-equalities`, controls warnings emitted for ``RULES``
  whose left-hand side attempts to quantify over equality constraints that
  previous GHC versions accepted quantifying over. GHC will now drop such RULES,
  emitting a warning message controlled by this flag.

  This warning is intended to give visibility to the fact that the ``RULES`` that
  previous GHC versions generated in such circumstances could never fire.

- A new flag, :ghc-flag:`-Wunusable-unpack-pragmas`, controls warnings emitted
  when GHC is unable to unpack a data constructor field annotated by the
  ``{-# UNPACK #-}`` pragma.

  Previous GHC versions issued this warning unconditionally. Now it is possible
  to disable it with ``-Wno-unusable-unpack-pragmas`` or turn it into an error
  with ``-Werror=unusable-unpack-pragmas``.

- Introduce a new warning :ghc-flag:`-Wpattern-namespace-specifier` to detect
  uses of the now deprecated ``pattern`` namespace specifier in import/export
  lists. See `GHC Proposal #581, section 2.3 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0581-namespace-specified-imports.rst#deprecate-use-of-pattern-in-import-export-lists>`_.

- Code coverage (:ghc-flag:`-fhpc`) now treats uses of record fields via
  :extension:`RecordWildCards` or :extension:`NamedFieldPuns` as if the fields
  were accessed using the generated record selector functions, marking the fields
  as covered in coverage reports (:ghc-ticket:`17834`).

- SIMD support in the x86 native code generator has been extended with 128-bit
  integer operations.  Also, ``shuffleFloatX4#`` and ``shuffleDoubleX2#`` no longer
  require ``-mavx``.

- Initial native code generator support for the LoongArch CPU architecture.


GHCi
~~~~

- Support for multiple home units in GHCi (:ghc-ticket:`20889`)

- :ghci-cmd:`:info` now outputs type declarations with ``@``-binders that are
  considered semantically significant. See the documentation for :ghci-cmd:`:info`
  itself for a more detailed explanation.

- GHCi errors and warnings now have their own numeric error codes that are
  displayed alongside the error.

- Many performance and correctness improvements in the bytecode interpreter.

- Numerous improvements in the GHCi debugger including:

  * Significantly improved performance of the :ghci-cmd:`:steplocal` command (:ghc-ticket:`25779`)
  * Every ``do`` statement is now a breakpoint, resulting in more predictable and intuitive :ghci-cmd:`:break` behavior
  * A :ghci-cmd:`:stepout` command is now available, allowing stepping out from
    functions and bindings when stopped at a breakpoint. Note that this feature
    is made available as a technology preview and we expect further refinement
    in future releases.
  * Improvements in the GHCi debugger API, setting the groundwork for
    integration with Debug Adapter Protocol (DAP) and other interactive
    debugging clients
  * Internal refactorings towards making the debugger multi-thread aware (:ghc-ticket:`26064`)

WebAssembly backend
~~~~~~~~~~~~~~~~~~~

The WebAssembly backend now supports evaluation via the interpreter, allowing
both interactive usage via GHCi and TemplateHaskell evaluation. This includes
usage of ``foreign import javascript``, allowing interactive
usage within the browser including interaction with the DOM (modulo various
constraints imposed by WebAsm implementations).

See the blog post on `Tweag's blog
<https://www.tweag.io/blog/2025-04-17-wasm-ghci-browser/>`_ for more
information.

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

- Add new runtime flag :rts-flag:`--optimistic-linking` which instructs the
  runtime linker to continue in the presence of unknown symbols. By default this
  flag is not passed, preserving previous behavior.


- Reorganise how certain symbols are linked to avoid a bootstrapping failure
  with the linker shipping newer macOS versions (:ghc-ticket:`26166`)

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

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

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

``ghc-prim`` is now a legacy interface providing access to primitive operations
and types which are now also exposed via the ``ghc-experimental`` package.

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

* The ``UnknownDiagnostic`` constructor now takes an additional type argument
  for the type of hints corresponding to the diagnostic, and an additional
  value-level argument used for existential wrapping of the hints of the inner
  diagnostic.

* Changes to the HPT and HUG interface:

  - ``addToHpt`` and ``addListToHPT`` were moved from ``GHC.Unit.Home.ModInfo`` to ``GHC.Unit.Home.PackageTable`` and deprecated in favour of ``addHomeModInfoToHpt`` and ``addHomeModInfosToHpt``.
  - ``UnitEnvGraph`` and operations ``unitEnv_lookup_maybe``, ``unitEnv_foldWithKey, ``unitEnv_singleton``, ``unitEnv_adjust``, ``unitEnv_insert``, ``unitEnv_new`` were moved from ``GHC.Unit.Env`` to ``GHC.Unit.Home.Graph``.
  - The HomePackageTable (HPT) is now exported from ``GHC.Unit.Home.PackageTable``,
    and is now backed by an IORef to avoid by construction very bad memory leaks.
    This means the API to the HPT now is for the most part in IO. For instance,
    ``emptyHomePackageTable`` and ``addHomeModInfoToHpt`` are now in IO.
  - ``mkHomeUnitEnv`` was moved to ``GHC.Unit.Home.PackageTable``, and now takes two
    extra explicit arguments. To restore previous behaviour, pass ``emptyUnitState``
    and ``Nothing`` as the first two arguments additionally.
  - ``hugElts`` was removed. Users should prefer ``allUnits`` to get the keys of the
    HUG (the typical use case), or ``traverse`` or ``unitEnv_foldWithKey`` in other
    cases.

* Changes to ``Language.Haskell.Syntax.Expr``

  - The ``ParStmtBlock`` list argument of the ``ParStmt`` constructor of ``StmtLR`` is now ``NonEmpty``.

* As part of the implementation of ``GHC proposal 493 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0493-specialise-expressions.rst>``_,
  the ``SpecSig`` constructor of ``Sig`` has been deprecated. It is replaced by
  the constructor ``SpecSigE`` which supports expressions at the head, rather than
  a lone variable.

``ghc-heap`` library
~~~~~~~~~~~~~~~~~~~~

* The functions ``getClosureInfoTbl_maybe``, ``getClosureInfoTbl``,
  ``getClosurePtrArgs`` and ``getClosurePtrArgs_maybe`` have been added to allow
  reading of the relevant Closure attributes without reliance on incomplete
  selectors.

``ghc-experimental`` library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- ``ghc-experimental`` now exposes ``GHC.RTS.Flags`` and ``GHC.Stats`` as
  ``GHC.RTS.Flags.Experimental`` and ``GHC.Stats.Experimental``. These are
  *also* exposed in ``base``, however the ``base`` versions will be deprecated as
  part of the split base project. See `CLC proposal 289
  <https://github.com/haskell/core-libraries-committee/issues/289>`__.
  Downstream consumers of these flags are encouraged to migrate to the
  ``ghc-experimental`` versions.


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

- As part of the implementation of `GHC proposal 493 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0493-specialise-expressions.rst>`_,
  the ``SpecialiseP`` constructor of the Template Haskell ``Pragma`` type, as
  well as the helpers ``pragSpecD`` and ``pragSpecInlD``, have been deprecated.

  They are replaced, respectively, by ``SpecialiseEP``, ``pragSpecED`` and
  ``pragSpecInlED``.

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-bignum/ghc-bignum.cabal:               Core library.
    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-experimental/ghc-experimental.cabal:   Core library.
    libraries/ghc-heap/ghc-heap.cabal:                   Core library.
    libraries/ghc-internal/ghc-internal.cabal:           Internal implementation.
    libraries/ghc-platform/ghc-platform.cabal:           Internal compiler library.
    libraries/ghc-prim/ghc-prim.cabal:                   Core library
    utils/ghc-toolchain/ghc-toolchain.cabal:             Internal compiler library.
    utils/haddock/haddock-api/haddock-api.cabal:         Dependency of ``haddock`` executable
    utils/haddock/haddock-library/haddock-library.cabal: Dependency of ``haddock`` executable
    libraries/haskeline/haskeline.cabal:                 Dependency of ``ghci`` executable
    libraries/hpc/hpc.cabal:                             Dependency of ``hpc`` executable
    libraries/file-io/file-io.cabal:                     Dependency of ``directory`` library
    libraries/integer-gmp/integer-gmp.cabal:             Core library
    libraries/mtl/mtl.cabal:                             Dependency of ``Cabal`` library
    libraries/os-string/os-string.cabal:                 Dependency of ``filepath`` 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/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/semaphore-compat/semaphore-compat.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
