.. _release-9-10-1:

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

Language
~~~~~~~~

- The :extension:`GHC2024` language edition is now supported. It builds on top of
  :extension:`GHC2021`, adding the following extensions:

  * :extension:`DataKinds`
  * :extension:`DerivingStrategies`
  * :extension:`DisambiguateRecordFields`
  * :extension:`ExplicitNamespaces`
  * :extension:`GADTs`
  * :extension:`MonoLocalBinds`
  * :extension:`LambdaCase`
  * :extension:`RoleAnnotations`

  At the moment, :extension:`GHC2021` remains the default langauge edition that
  is used when no other language edition is explicitly loaded (e.g. when running
  ``ghc`` directly). Because language editions are not necessarily backwards
  compatible, and future releases of GHC may change the default, it is highly
  recommended to specify the language edition explicitly.

- GHC Proposal `#575 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0575-deprecated-instances.rst>`_
  has been implemented, allowing ``DEPRECATED`` and ``WARNING``
  pragmas to be applied to class ``instance`` declarations.
  Doing so will cause warnings to be emitted whenever such instances are used
  to solve a constraint.  For details, see :ref:`warning-deprecated-pragma`.

- GHC Proposal `#281 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0281-visible-forall.rst>`_
  "Visible forall in types of terms" has been partially implemented.
  The following code is now accepted by GHC::

    {-# LANGUAGE RequiredTypeArguments #-}

    vshow :: forall a -> Show a => a -> String
    vshow t x = show (x :: t)

    s1 = vshow Int    42      -- "42"
    s2 = vshow Double 42      -- "42.0"

  The use of ``forall a ->`` instead of ``forall a.`` indicates a *required* type
  argument. A required type argument is visually indistinguishable from a value
  argument but does not exist at runtime.

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

- The :extension:`ExplicitNamespaces` extension can now be used in conjunction
  with :extension:`RequiredTypeArguments` to select the type namespace in a
  required type argument::

    data T = T               -- the name `T` is ambiguous
    f :: forall a -> ...     -- `f` expects a required type argument

    x1 = f T         -- refers to the /data/ constructor `T`
    x2 = f (type T)  -- refers to the /type/ constructor `T`

- With :extension:`LinearTypes`, ``let`` and ``where`` bindings can
  now be linear. So the following now typechecks::

    f :: A %1 -> B
    g :: B %1 -> C

    h :: A %1 -> C
    h x = g y
      where
        y = f x

- Due to an oversight, previous GHC releases (starting from 9.4) allowed the use
  of promoted data types in kinds, even when :extension:`DataKinds` was not
  enabled. That is, GHC would erroneously accept the following code: ::

    {-# LANGUAGE NoDataKinds #-}

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

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

  This oversight has now been fixed. If you wrote code that took advantage of
  this oversight, you may need to enable :extension:`DataKinds` in your code to
  allow it to compile with GHC 9.10.

  For more information on what types are allowed in kinds, see the
  :ref:`promotion` section.

- Using ``forall`` as an identifier is now a parse error, as forewarned
  by :ghc-flag:`-Wforall-identifier`::

    forall :: (Variable a, MonadQSAT s m) => m a
    -- parse error on input ‘forall’

  Library authors are advised to use a different name for their functions,
  such as ``forAll``, ``for_all``, or ``forall_``.

- GHC Proposal `#65 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0065-type-infix.rst>`_
  "Require namespacing fixity declarations for type names and WARNING/DEPRECATED pragmas" has been partially implemented.
  Now, with :extension:`ExplicitNamespaces` enabled, you can specify the
  namespace of a name in fixity signatures, ``DEPRECATED`` and ``WARNING`` pragmas: ::

    type f $ a = f a
    f $ a = f a

    infixl 9 type $ -- type-level $ is left-associative with priority 9
    infixr 0 data $ -- term-level $ is right-associative with priority 0

    {-# DEPRECATED type D "Use `()` instead" #-} -- this will deprecate type D, but will not touch pattern synonym
    data D = MkD

    {-# DEPRECATED data D "Use `MkD` instead" #-} -- this will deprecate pattern synonym only
    pattern D = MkD

    pattern Head x <- (head -> x)
    {-# WARNING in "x-partial" data Head [ "This is a partial synonym,"
                                         , "it throws an error on empty lists."] #-}

- GHC Proposal `#475 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0475-tuple-syntax.rst>`_
  "Non-punning list and tuple syntax" has been partially implemented.
  When the newly introduced extension :extension:`ListTuplePuns` is disabled,
  bracket syntax for lists, tuples and sums only denotes their data
  constructors, while their type constructors have been changed to use regular
  prefix syntax::

    data List a = [] | a : List a
    data Tuple2 a b = (a, b)

  The extension is enabled by default, establishing the usual behavior.

- In accordance with GHC Proposal `#448 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0448-type-variable-scoping.rst>`_,
  the :extension:`TypeAbstractions` extension has been extended to support
  ``@``-binders in lambdas and function equations::

    id :: forall a. a -> a
    id @t x = x :: t
    -- ^^ @-binder in a function equation

    e = higherRank (\ @t -> ... )
    --                ^^ @-binder in a lambda

  This feature is an experimental alternative to :extension:`ScopedTypeVariables`,
  see the :ref:`type-abstractions-in-functions` section.

Compiler
~~~~~~~~

- GHC Proposal `#516
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0516-incomplete-record-selectors.rst>`_
  has been implemented. It introduces a warning :ghc-flag:`-Wincomplete-record-selectors` which warns about when
  an invocation of a record selector may fail due to being applied to a constructor for which it is not defined.

  For example ::

    data T = T1 | T2 { x :: Int }
    f :: T -> Int
    f a = x a + 1 -- emit a warning here, since `f T1` will fail

  Unlike :ghc-flag:`-Wpartial-fields` this produces a warning about incomplete selectors at use sites instead of
  definition sites, so it is useful in cases when the library does intend for incomplete record selectors to be
  used but only in specific circumstances (e.g. when other cases are handled by previous pattern matches).

- The :ghc-flag:`-finfo-table-map-with-stack` and
  :ghc-flag:`-finfo-table-map-with-fallback` flags have been introduced. These
  flags include ``STACK`` info tables and info tables with default source
  location information in the info table map, respectively. They are implied by
  the :ghc-flag:`-finfo-table-map` flag. The corresponding negative flags
  (:ghc-flag:`-fno-info-table-map-with-stack`,
  :ghc-flag:`-fno-info-table-map-with-fallback`) are useful for omitting these
  info tables from the info table map and reducing the size of executables
  containing info table profiling information. In a test on the `Agda codebase
  <https://github.com/agda/agda>`_, the size of the build results was reduced by
  about 10% when these info tables were omitted.

- Fixed a bug where compiling with both :ghc-flag:`-ddump-timings` and :ghc-flag:`-ddump-to-file` did not
  suppress printing timings to the console. See :ghc-ticket:`20316`.

- Defaulting plugins can now propose solutions to entangled sets of type variables. This allows defaulting
  of multi-parameter type classes. See :ghc-ticket:`23832`.

- The flag `-funbox-small-strict-fields` will now properly recognize unboxed tuples
  containing multiple elements as large. Constructors like `Foo (# Int64, Int64# )`
  will no longer be considered small and therefore not unboxed by default under `-O`
  even when used as strict field. :ghc-ticket:`22309`.

- The flag `-funbox-small-strict-fields` will now always unpack things as if compiling
  for a 64bit platform. Even when generating code for a 32bit platform.
  This makes core optimizations more consistent between 32bit and 64bit platforms
  at the cost of slightly worse 32bit performance in edge cases.

- Type abstractions in constructor patterns that were previously admitted without enabling the :extension:`TypeAbstractions`
  extension now trigger a warning, :ghc-flag:`-Wdeprecated-type-abstractions`.
  This new warning is part of the :ghc-flag:`-Wcompat` warning group and will become an error in a future GHC release.

- The :ghc-flag:`-Wforall-identifier` flag is now deprecated and removed from :ghc-flag:`-Wdefault`,
  as ``forall`` is no longer parsed as an identifier.

- Late plugins have been added. These are plugins which can access and/or modify
  the core of a module after optimization and after interface creation. See :ghc-ticket:`24254`.

- If you use :ghc-flag:`-fllvm` we now use an assembler from the LLVM toolchain rather than
  the preconfigured assembler. This is typically ``clang``. The ``LLVMAS`` environment
  variable can be specified at configure time to instruct GHC which ``clang`` to use.
  This means that if you are using ``-fllvm`` you now need ``llc``, ``opt`` and ``clang``
  available.

- The :ghc-flag:`-fprof-late-overloaded` flag has been introduced. It causes
  cost centres to be added to *overloaded* top level bindings, unlike
  :ghc-flag:`-fprof-late` which adds cost centres to all top level bindings.

- The :ghc-flag:`-fprof-late-overloaded-calls` flag has been introduced. It
  causes cost centres to be inserted at call sites including instance dictionary
  arguments. This may be preferred over :ghc-flag:`-fprof-late-overloaded` since
  it may reveal whether imported functions are called overloaded.

JavaScript backend
~~~~~~~~~~~~~~~~~~

- The JavaScript backend now supports linking with C sources. It uses Emscripten
  to compile them to WebAssembly. The resulting JS file embeds and loads these
  WebAssembly files. Important note: JavaScript wrappers are required to call
  into C functions and pragmas have been added to indicate which C functions are
  exported (see the users guide).

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

- The wasm backend now implements JavaScript FFI, allowing JavaScript
  to be called from Haskell and vice versa when targetting JavaScript
  environments like browsers and node.js. See :ref:`JavaScript FFI in
  the wasm backend <wasm-jsffi>` for details.

GHCi
~~~~

- GHCi now differentiates between adding, unadding, loading, unloading and reloading
  in its responses to using the respective commands. The output with `-fshow-loaded-modules`
  is not changed to keep backwards compatibility for tooling.

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

- Internal fragmentation incurred by the non-moving GC's allocator has been reduced for small objects.
  In one real-world application, this has reduced resident set size by about 20% and modestly improved run-time.
  See :ghc-ticket:`23340`.
  :rts-flag:`--nonmoving-dense-allocator-count=⟨count⟩` has been added to fine-tune this behaviour.
- Add support for heap profiling with the non-moving GC.
  See :ghc-ticket:`22221`.

- Add a :rts-flag:`--no-automatic-time-samples` flag which stops time profiling samples being automatically started on
  startup. Time profiling can be controlled manually using functions in ``GHC.Profiling``.

- Add a :rts-flag:`-xr ⟨size⟩` which controls the size of virtual
  memory address space reserved by the two step allocator on a 64-bit
  platform. The default size is now 1T on aarch64 as well. See
  :ghc-ticket:`24498`.

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

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

- The functions :base-ref:`GHC.Exts.dataToTag#` and
  :base-ref:`GHC.Base.getTag` have had their types changed to the
  following:

  ::

    dataToTag#, getTag
      :: forall {lev :: Levity} (a :: TYPE (BoxedRep lev))
      .  DataToTag a => a -> Int#

  In particular, they are now applicable only at some (not all)
  lifted types.  However, if ``t`` is an algebraic data type (i.e. ``t``
  matches a ``data`` or ``data instance`` declaration) with all of its
  constructors in scope and the levity of ``t`` is statically known,
  then the constraint ``DataToTag t`` can always be solved.

- Exceptions can now carry arbitrary user-defined annotations via the new
  :base-ref:`GHC.Exception.Type.ExceptionContext` implicit parameter of
  ``SomeException``. These annotations are intended to be used to carry
  context describing the provenance of an exception.

- GHC now collects backtraces for synchronous exceptions. These are carried by
  the exception via the ``ExceptionContext`` mechanism described above.
  GHC supports several mechanisms by which backtraces can be collected which
  can be individually enabled and disabled via
  :base-ref:`GHC.Exception.Backtrace.setEnabledBacktraceMechanisms`.

- Deprecation of ``GHC.Pack`` has reached Phase 2. A warning is now thrown when importing the module.
  See `ghc/ghc#21461 <https://gitlab.haskell.org/ghc/ghc/-/issues/21461>`_.

- `CLC proposal #258 <https://github.com/haskell/core-libraries-committee/issues/258>`_:
  ``Data.List.NonEmpty.unzip`` raises a specific warning about its future monomorphisation.
  Do consider switching to ``Data.Functor.unzip`` if you need to keep it polymorphic.


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

- ``dataToTag#`` has been moved from ``GHC.Prim``.  It remains
  exported by ``GHC.Exts``, but with a different type, as described in
  the notes for ``base`` above.

- New primops for unaligned ``Addr#`` access.
  These primops will be emulated on platforms that don't support unaligned access.
  These primops take the form

  .. code-block:: haskell

     indexWord8OffAddrAs<ty> :: Addr# -> Int# -> <ty>#
     readWord8OffAddrAs<ty> :: Addr# -> Int# -> State# s -> (# State# s, <ty># #)
     writeWord8OffAddrAs<ty> :: Addr# -> Int# -> <ty># -> State# s -> State# s

  where ``<ty>`` is one of:

  - ``Word``
  - ``Word{16,32,64}``
  - ``Int``
  - ``Int{16,32,64,}``
  - ``Char``
  - ``WideChar``
  - ``Addr``
  - ``Float``
  - ``Double``
  - ``StablePtr``

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

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

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

- ``ghc-experimental`` is a new library for functions and data types with
  weaker stability guarantees. Introduced per the HF Technical Proposal `#51
  <https://github.com/haskellfoundation/tech-proposals/blob/main/proposals/accepted/051-ghc-base-libraries.rst>`_.

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

- Extend ``Pat`` with ``TypeP`` and ``Exp`` with ``TypeE``,
  introduce functions ``typeP`` and ``typeE`` (Template Haskell support for GHC Proposal `#281
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0281-visible-forall.rst>`_).

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/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