.. _release-9-12-1:

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

Language
~~~~~~~~

- New language extension: :extension:`OrPatterns` implements `GHC proposal #522
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0522-or-patterns.rst>`_.
- GHC proposal `#569 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0569-multiline-strings.rst>`_
  "Multiline string literals" has been implemented.
  The following code is now accepted by GHC::

    {-# LANGUAGE MultilineStrings #-}

    x :: String
    x =
      """
      This is a
      multiline

          string

      literal
      """

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

- The ordering of variables used for visible type application has been changed in two cases.
  It is supposed to be left-to-right, but due to an oversight, it was wrong:

  - in an infix application ``f :: a `op` b``, it is now ``forall a op b.`` rather than
    ``forall op a b.``
  - in a linear type ``f :: a %m -> b``, it is now ``forall a m b.`` rather than
    ``forall a b m.``.

  This change is backwards-incompatible, although in practice we don't expect it
  to cause significant disruption.

- The built-in ``HasField`` class, used by :extension:`OverloadedRecordDot`, now
  supports representation polymorphism (implementing part of `GHC proposal #583
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0583-hasfield-redesign.rst>`_).
  This means that code using :extension:`UnliftedDatatypes` or
  :extension:`UnliftedNewtypes` can now use :extension:`OverloadedRecordDot`.

- Unboxed ``Float#``/``Double#`` literals now support the :extension:`HexFloatLiterals` extension
  (:ghc-ticket:`22155`).

- :extension:`UnliftedFFITypes`: GHC will now accept FFI types like: ``(# #) -> T`` where ``(# #)``
  is used as the one and only function argument.

- The venerable ``default`` declarations have been generalized. They can now name a class
  other than ``Num`` and the class defaults can be exported. The functionality is guarded
  by the new ``NamedDefaults`` language extension. See `GHC proposal #409
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0409-exportable-named-default.rst>`__
  for details.

- GHC now takes ``COMPLETE`` pragmas into consideration when deciding whether
  pattern matches in do notation are fallible.

- As part of `GHC proposal #281 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0281-visible-forall.rst>`_
  GHC now accepts type syntax in expressions, namely function type arrow ``a -> b``,
  constraint arrow ``a => b``, and ``forall`` telescopes: ::

    g = f (forall a. Show a => a -> String)
      where f :: forall a -> ...

- In accordance with `GHC proposal #425 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0425-decl-invis-binders.rst>`_,
  GHC now permits wildcard binders in type declarations: ::

    type Const a b = a   -- before: the `b` had to be named even if unused on the RHS
    type Const a _ = a   -- now: the compiler accepts a wildcard binder `_`

Compiler
~~~~~~~~

- GHC now has experimental support for native RISC-V code generation (:ghc-ticket:`16783`).

- Constructor ``PluginProv`` of type ``UnivCoProvenance``, relevant
  for typing plugins, gets an extra ``DCoVarSet`` argument.
  The argument is intended to contain the in-scope coercion variables
  that the the proof represented by the coercion makes use of.
  See ``Note [The importance of tracking UnivCo dependencies]``
  in ``GHC.Core.TyCo.Rep``, :ref:`constraint-solving-with-plugins`
  and the migration guide.

- The flag :ghc-flag:`-fprof-late` will no longer prevent top level constructors from being statically allocated.

  It used to be the case that we would add a cost centre for bindings like ``foo = Just bar``.
  This turned the binding into a CAF that would allocate the constructor on first evaluation.

  However without the cost centre ``foo`` can be allocated at compile time. This reduces code-bloat and
  reduces overhead for short-running applications.

  The tradeoff is that calling ``whoCreated`` on top level value definitions like ``foo`` will be less informative.

- A new flag :ghc-flag:`-fexpose-overloaded-unfoldings` has been added providing a lightweight alternative to :ghc-flag:`-fexpose-all-unfoldings`.

- :ghc-flag:`-Wderiving-typeable` has been added to :ghc-flag:`-Wall`.

- SIMD support has been added to the X86 native code generator.
  For the time being, only 128 bit wide vectors are supported, with most
  floating-point operations implemented, together with a few integer vector
  operations. Other operations still require the LLVM backend. Contributors
  welcome!

- i386 Windows support is now completely removed amid massive cleanup
  of legacy code to pave way for ARM64 Windows support (:ghc-ticket:`24883`). Rest
  assured, this does not impact existing support for x86_64 Windows or
  i386 Linux. For end users, the ``stdcall`` C calling convention is
  now fully deprecated and GHC will unconditionally produce a warning
  and treat it as ``ccall``. All C import/export declarations on
  Windows should now use ``ccall``.

- 32-bit macOS/iOS support has also been completely removed (:ghc-ticket:`24921`). This does
  not affect existing support of Apple systems on x86_64/aarch64.

- The flag :ghc-flag:`-fignore-asserts` will now also enable the
  :extension:`CPP` macro ``__GLASGOW_HASKELL_ASSERTS_IGNORED__`` (`#24967
  <https://gitlab.haskell.org/ghc/ghc/-/issues/24967>`_).
  This enables people to write their own custom assertion functions.
  See :ref:`assertions`.

- The flag :ghc-flag:`-fkeep-auto-rules` that forces GHC to keep auto generated
  specialization rules was added. It was actually added ghc-9.10.1 already but
  mistakenly not mentioned in the 9.10.1 changelog.

- A new flag :ghc-flag:`-fmax-forced-spec-args=⟨n⟩` has been added. When a function
  with a SPEC argument is specialized GHC now checks the number of arguments the
  resulting function takes.
  If the specialized version takes less than `max-forced-spec-args` arguments it is
  specialized. Otherwise GHC will not specialize the function and emit a warning.

  This avoids edge cases where a SPEC keyword could result in functions being
  specialized to large static data resulting in functions with thousands of arguments.

- Fixed a bug that caused GHC to panic when using the aarch64 NCG and :ghc-flag:`-fregs-graph`
  on certain programs (:ghc-ticket:`22255`).

- A new warning :ghc-flag:`-Wview-pattern-signatures` is introduced to notify users about
  future changes in parsing of view patterns in combination with pattern signatures.

- GHC now includes a new experimental flag, :ghc-flag:`-fobject-determinism`,
  which enables deterministic object code generation, with a minor trade-off in
  compilation speed (typically a 1-2% regression). Note, however, that this
  flag doesn't yet ensure determinism across all compilation configurations; we
  anticipate these cases will be addressed in future updates (:ghc-ticket:`12935`).

- GHC now includes a new flag, :ghc-flag:`-fwrite-if-compression=⟨n⟩`,
  which controls the level of compression used when writing interface files to disk.
  While we think the majority of users will be well served by the default setting,
  the flag allows users to pick their own tradeoff between memory footprint and
  compilation time when needed.

GHCi
~~~~

- Fix a bug where GHCi would not start alongside a local file called ``Prelude.hs``
  or ``Prelude.lhs`` (:ghc-ticket:`10920`).


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

- Reduce fragmentation incurred by the nonmoving GC's segment allocator. In one application this reduced resident set size by 26%. See :ghc-ticket:`24150`.

- Memory return logic now uses live bytes rather than live blocks to measure the size of the heap.
  This primarily affects the non-moving GC, which should now be more willing to return memory to the OS.
  Users who have fine-tuned the :rts-flag:`-F ⟨factor⟩`, :rts-flag:`-Fd ⟨factor⟩`, or :rts-flag:`-O ⟨size⟩` flags,
  and use the non-moving GC, should see if adjustments are needed in light of this change.

- The new runtime flag :rts-flag:`--read-tix-file=\<yes|no\>` allows to modify whether a preexisting .tix file is read in at the beginning of a program run.
  The default is currently ``--read-tix-file=yes`` but will change to ``--read-tix-file=no`` in a future version of GHC.
  For this reason, a warning is emitted if a .tix file is read in implicitly. You can silence this warning by explicitly passing ``--read-tix-file=yes``.
  Details can be found in `GHC proposal #612 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0612-fhpc-accumulation.md>`__.

Cmm
~~~

- The ``bits128``, ``bits256`` and ``bits512`` types have been removed, in
  favour of ``vec128``, ``vec256`` and ``vec512``.

- The ``[*]`` jump annotation ("all registers live") has been removed, in favour
  of more specific annotations ``GP_ARG_REGS`` (all general-purpose registers
  live), ``SCALAR_ARG_REGS`` (all scalar registers live), and ``V16_ARG_REGS``,
  ``V32_ARG_REGS`` and ``V64_ARG_REGS`` (meaning: all scalar registers plus
  all vector registers up to the given vector width in bytes).

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

- Improve display of exception stack traces and display more metadata about
  exceptions in the default top-level uncaught exception handler
  (``GHC.Conc.Sync.uncaughtExceptionHandler``). See CLC proposals
  `#231 <https://github.com/haskell/core-libraries-committee/issues/231>`_,
  `#261 <https://github.com/haskell/core-libraries-committee/issues/261>`_ and
  `#285 <https://github.com/haskell/core-libraries-committee/issues/285>`_.

- Propagate HasCallStack from ``errorCallWithCallStackException`` to exception backtraces, fixing a bug in the implementation of `CLC proposal #164 <https://github.com/haskell/core-libraries-committee/issues/164>`_.

- Annotate re-thrown exceptions with backtraces as per `CLC proposal #202 <https://github.com/haskell/core-libraries-committee/issues/202>`_.

- Introduced ``catchNoPropagate``, ``rethrowIO`` and ``tryWithContext`` as part of
  `CLC proposal #202 <https://github.com/haskell/core-libraries-committee/issues/202>`_ to
  facilitate rethrowing exceptions without adding a ``WhileHandling``
  context -- if rethrowing ``e``, you don't want to add ``WhileHandling e`` to
  the context since it will be redundant. These functions are mostly useful
  for libraries that define exception-handling combinators like ``catch`` and
  ``onException``, such as ``base``, or the ``exceptions`` package.

- The `deprecation process of GHC.Pack <https://gitlab.haskell.org/ghc/ghc/-/issues/21461>`_ has come its term. The module has now been removed from ``base``.

- ``GHC.Desugar`` has been deprecated and should be removed in GHC 9.14. (`CLC proposal #216 <https://github.com/haskell/core-libraries-committee/issues/216>`_)
- Add a ``readTixFile`` field to the ``HpcFlags`` record in ``GHC.RTS.Flags`` (`CLC proposal #276 <https://github.com/haskell/core-libraries-committee/issues/276>`_)
- Add ``compareLength`` to ``Data.List`` and ``Data.List.NonEmpty`` (`CLC proposal #257 <https://github.com/haskell/core-libraries-committee/issues/257>`_)
- Add ``INLINE[1]`` to ``compareInt`` / ``compareWord`` (`CLC proposal #179 <https://github.com/haskell/core-libraries-committee/issues/179>`_)
- Refactor ``GHC.RTS.Flags`` in preparation for new I/O managers: introduce ``data IoManagerFlag`` and use it in ``MiscFlags``, remove ``getIoManagerFlag``, deprecate re-export of ``IoSubSystem`` (`CLC proposal #263 <https://github.com/haskell/core-libraries-committee/issues/263>`_)
- Add the ``MonadFix`` instance for ``(,) a``, similar to the one for ``Writer a`` (`CLC proposal #238 <https://github.com/haskell/core-libraries-committee/issues/238>`_)
- Improve ``toInteger :: Word32 -> Integer`` on 64-bit platforms (`CLC proposal #259 <https://github.com/haskell/core-libraries-committee/issues/259>`_)
- Make ``flip`` representation polymorphic (`CLC proposal #245 <https://github.com/haskell/core-libraries-committee/issues/245>`_)
- The ``HasField`` class now supports representation polymorphism (`CLC proposal #194 <https://github.com/haskell/core-libraries-committee/issues/194>`_)
- Make ``read`` accept binary integer notation (`CLC proposal #177 <https://github.com/haskell/core-libraries-committee/issues/177>`_)
- Improve the performance of ``Data.List.sort`` using an improved merging strategy. Instead of ``compare``, ``sort`` now uses ``(>)`` which may brea-malform- ``Ord`` instances (`CLC proposal #236 <https://github.com/haskell/core-libraries-committee/issues/236>`_)
- Add ``inits1`` and ``tails1`` to ``Data.List``, factored from the corresponding functions in ``Data.List.NonEmpty`` (`CLC proposal #252 <https://github.com/haskell/core-libraries-committee/issues/252>`_)
- Add ``firstA`` and ``secondA`` to ``Data.Bitraversable``. (`CLC proposal #172 <https://github.com/haskell/core-libraries-committee/issues/172>`_)
- Deprecate ``GHC.TypeNats.Internal``, ``GHC.TypeLits.Internal``, ``GHC.ExecutionStack.Internal`` (`CLC proposal #217 <https://github.com/haskell/core-libraries-committee/issues/217>`_)
- ``System.IO.Error.ioError`` and ``Control.Exception.ioError`` now both carry ``HasCallStack`` constraints (`CLC proposal #275 <https://github.com/haskell/core-libraries-committee/issues/275>`_)
- Define ``Eq1``, ``Ord1``, ``Show1`` and ``Read1`` instances for basic ``Generic`` representation types. (`CLC proposal #273 <https://github.com/haskell/core-libraries-committee/issues/273>`_)
- ``setNonBlockingMode`` will no longer throw an exception when called on a FD associated with a unknown device type. (`CLC proposal #282 <https://github.com/haskell/core-libraries-committee/issues/282>`_)



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

- Usage of deprecated primops is now correctly reported (`#19629 <https://gitlab.haskell.org/ghc/ghc/-/issues/19629>`_).
- New primops ``isMutableByteArrayWeaklyPinned#`` and ``isByteArrayWeaklyPinned#``
  to allow users to avoid copying large arrays when dealing with FFI.
  See :ref:`pinned-byte-arrays` for more details on the different kinds of
  pinned arrays in 9.12.

  This need for this distinction originally surfaced in `#22255 <https://gitlab.haskell.org/ghc/ghc/-/issues/22255>`_.

- New fused multiply-add instructions for vectors of floating-point values,
  such as ``fmaddFloatX4# :: FloatX4# -> FloatX4# -> FloatX4# -> FloatX4#`` and
  ``fnmsubDoubleX2# :: DoubleX2# -> DoubleX2# -> DoubleX2# -> DoubleX2#``.
  These follow the same semantics as ``fmadd``/``fmsub``/``fnmadd``/``fnmsub``,
  operating in parallel on vectors of floating-point values.

- New vector shuffle instructions, such as ``shuffleFloatX4# :: FloatX4# -> FloatX4# -> (# Int#, Int#, Int#, Int# #) -> FloatX4#``.
  These instructions take two input vectors and a collection of indices (which must
  be compile-time literal integers), and constructs a result vector by extracting
  out the values at those indices. For instance, ``shuffleFloatX4#`` on input vectors with
  components ``(# 0.1#, 11.1#, 22.1#, 33.1# #)`` and ``(# 44.1#, 55.1#, 66.1#, 77.1# #)``,
  and indices ``(# 4#, 3#, 6#, 1# #)``, will return a vector with components
  ``(# 44.1#, 33.1#, 66.1#, 11.1# #)``.

- New instructions for minimum/maximum, such as ``minDouble#`` and
  ``minFloatX4#``. These instructions compute the minimum/maximum of their inputs,
  working component-wise for SIMD vectors. Supported argument types are vector
  integer values (e.g. ``Word16X8#``, ``Int32X4#`` etc) and both scalar and vector
  floating point values (e.g. ``Float#``, ``DoubleX2#``, ``FloatX8#`` etc).

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

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

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

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

- Extend ``Exp`` with ``ForallE``, ``ForallVisE``, ``ConstraintedE``, introduce
  functions ``forallE``, ``forallVisE``, ``constraintedE`` `GHC proposal #281
  <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0281-visible-forall.rst>`_.
- ``template-haskell`` is no longer wired-in. All wired-in identifiers have been moved to ``ghc-internal``.
- ``Lift`` instances were added for the ``template-haskell`` AST.

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

    compiler/ghc.cabal:                                  The compiler itself
    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/file-io/file-io.cabal:                     Dependency of ``directory`` library
    libraries/filepath/filepath.cabal:                   Dependency of ``ghc`` 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:                   GHC heap-walking library
    libraries/ghci/ghci.cabal:                           The REPL interface
    libraries/ghc-internal/ghc-internal.cabal:           Core library
    libraries/ghc-platform/ghc-platform.cabal:           Internal 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/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/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
    utils/haddock/haddock-api/haddock-api.cabal:         Dependency of ``haddock`` executable
    utils/haddock/haddock-library/haddock-library.cabal: Dependency of ``haddock`` executable
