Skip to content
Snippets Groups Projects
Select Git revision
  • wip/7502
  • master default protected
  • to-spec-origin
  • wip/10726
  • wip/10797
  • TeofilC-patch-1
  • wip/10775
  • 3.14
  • wip/v2-gen-bounds
  • wip/pkgname_datadir_3_14
  • wip/8419
  • main-is-fix
  • wip/t10717
  • wip/t10759
  • wip/duplicate-env-vars
  • fix10819
  • fix10773
  • fix10821
  • re10819
  • wip/investigate-recomp
  • cabal-head
  • 3.14.1.1+1
  • cabal-install-v3.14.1.1
  • Cabal-hooks-3.14.1.1
  • Cabal-v3.14.1.1
  • 3.14.1.1
  • 3.14.1.1+0
  • cabal-install-solver-v3.14.1.0
  • cabal-install-v3.14.1.0
  • Cabal-syntax-v3.14.1.0
  • Cabal-v3.14.1.0
  • Cabal-3.14.0.0
  • Cabal-syntax-3.14.0.0
  • 3.12.1+0
  • cabal-install-solver-v3.12.1.0
  • cabal-install-v3.12.1.0
  • Cabal-syntax-v3.12.1.0
  • Cabal-v3.12.1.0
  • 3.12.0+0
  • cabal-install-v3.12.0.0-prerelease
40 results
Blame Permalink
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
how-to-run-in-windows.rst 7.72 KiB

How to use Cabal in Windows
===========================

This document describes how to use Cabal in a Windows system. See the
:ref:`Further reading` section for some other references that might provide some
more explanations. For a TL;DR, jump to the :ref:`Complete configuration`.

Install the Haskell environment
-------------------------------

Haskell development on Windows makes use of the `MSYS2 `_
tools.

The recommended way of setting up a Haskell environment in Windows is by using
`GHCup `_. Follow the steps outlined in its
webpage to install at least GHC and Cabal. GHCup will install its own MSYS2
system in your computer unless told not to do so: refer to `its documentation
`_ for more information.

.. NOTE::
Stack is another tool you can use to set up a Haskell environment on Windows. Stack
can be installed on its own or via GHCup. See
`Stack's webpage `_ and/or
`GHCup's section on Stack integration `_,
in particular the `Windows related subsection `_.

MSYS2 environments and packages
-------------------------------

A particular environment has to be chosen when using MSYS2. By default GHCup will
use ``MINGW64``. You can learn more about the different environments in the `MSYS2
documentation `_.

GHCs before 9.4.1 are shipped with a minimal set of packages based on the
``MINGW64`` environment, and GHC 9.4.1 and newer are shipped with a minimal set
of packages based on the ``CLANG64`` environment. It is in general advisable to
work inside the same environment as your GHC uses, but (with some exceptions)
it shouldn't matter whether environments are mixed. Stay warned that it can
sometimes lead to undecipherable errors.

We will refer to the chosen environment as ```` through this
documentation.

Third-party libraries and tools can be installed using the ``pacman`` package
manager on the MSYS2 installation
(`see `_). If MSYS2 was
installed via GHCup, check GHCup's documentation on how to call ``pacman``. Note
that installing a package ``mingw-w64--x86_64-`` will install
it in the ``\`` tree of directories, and might not be
visible if working on a different environment than ````. In
general, it is advisable to install only packages for the environment that was
chosen above.

Apart from these environments, there is the ``msys`` environment which is based
on Cygwin. Some tools only exist for this environment. Tools from this environment
are callable when working in any other environment. It is in general not possible
to link to libraries installed in the ``msys`` environment.

Ensure that Cabal can call the tools it needs
---------------------------------------------

Cabal sometimes needs to call tools that do not come with Windows (such as
``make`` or even ``git``). The MSYS2 project makes many of them available on
Windows. The directories where those are located need to be made visible in the
``PATH`` when executing ``cabal``. For that, Cabal provides the
``extra-prog-path`` configuration option. Your :ref:`global configuration
` should include this option:

::

extra-prog-path: \\bin
\usr\bin

Where ```` points to the location of your MSYS2 installation. If MSYS2
was installed via GHCup, refer to GHCup's documentation on the default location
of this directory. If MSYS2 was installed system-wide this is usually
``C:\msys64``.

.. note::

Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`
by default.

Ensure that Cabal can use system libraries
------------------------------------------

When installing a third party package its libraries and
header files will (usually) be placed in
``\\{lib,include}`` respectively. These directories need
to be specified in the ``extra-lib-dirs`` and ``extra-include-dirs``
respectively. Your :ref:`global configuration ` should
include these options:

::

extra-include-dirs: \\include
extra-lib-dirs: \\lib

.. note::

Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-include-dirs` and `extra-lib-dirs`
by default.

.. warning::

GHCs older than 9.4.1 will crash if a recent
``mingw-w64--x86_64-crt-git`` is installed for whichever ```` and
these directories are set globally .

Effectively this means that if you have installed ``mingw-w64--x86_64-crt-git``
(which you probably have if you are using ``clang`` in the ``CLANG64``
environment or ``gcc`` in the ``UCRT64`` or ``MINGW64`` environments outside of
Haskell, as this package is part of the ``mingw-w64--x86_64-toolchain``
meta-packages) and are using a GHC older than 9.4.1, you cannot simply depend on system
libraries by adding these paths to the global config, and instead you will
have to go through some other method to depend on those libraries like
:pkg-field:`pkgconfig-depends`.

Ensure that Cabal can call Haskell tools
----------------------------------------

Haskell tools are located in two places:

- ``\bin`` for standard Haskell tools such as GHC, Cabal, Haddock, ``hsc2hs``...

- The ``installdir`` that Cabal is configured with for user-installed Haskell tools.

For Cabal to be able to invoke these tools, those directories need to be made
visible in the ``PATH``. Your :ref:`global configuration ` should
include these options:

::

installdir:
extra-prog-path: ...
\bin

.. note::

Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`
by default.

.. _Complete configuration:

Complete configuration
----------------------

The complete :ref:`global configuration ` should finally
look like this:

::

installdir:
extra-include-dirs: \\include
extra-lib-dirs: \\lib
extra-prog-path: \bin

\\bin
\usr\bin

.. note::

Unless told otherwise, the GHCup bootstrap script already sets this configuration file to the right
values by default.

.. _Further reading:

Further reading
---------------

- MSYS2 homepage: https://www.msys2.org
- MinGW-W64 homepage: https://www.mingw-w64.org/
- Setting up Windows to build GHC:
https://gitlab.haskell.org/ghc/ghc/-/wikis/building/preparation/windows
- Some definitions and useful tools:
https://gitlab.haskell.org/ghc/ghc/-/wikis/surviving-windows

Outdated links
~~~~~~~~~~~~~~

These links are outdated but still useful to understand the overall picture:

- GHC's wiki about the Windows platform (outdated, GHC now uses MSYS2):
https://gitlab.haskell.org/ghc/ghc/-/wikis/building/platforms/windows
- The Windows toolchain (outdated, GHC now uses the ``CLANG64`` environment):
https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/windows-toolchain
- Haskell Wiki on Windows (outdated, it talks about MSYS and old tools such as
the Haskell platform): https://wiki.haskell.org/Windows