Skip to content

Commit 45dd397

Browse files
mergify[bot]mergify[bot]
authored
Merge pull request #9977 from haskell/mergify/bp/3.12/pr-9723
How to use Cabal in Windows (backport #9723)
2 parents aa968f8 + 3041b3c commit 45dd397

File tree

2 files changed

+154
-0
lines changed

2 files changed

+154
-0
lines changed

‎doc/how-to-run-in-windows.rst

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
How to use Cabal in Windows
2+
===========================
3+
4+
This document describes how to use Cabal in a Windows system. See the
5+
:ref:`Further reading` section for some other references that might provide some
6+
more explanations. For a TL;DR, jump to the :ref:`Complete configuration`.
7+
8+
Install the Haskell environment
9+
-------------------------------
10+
11+
Haskell development on Windows makes use of the `MSYS2 <https://www.msys2.org/>`_
12+
tools.
13+
14+
The recommended way of setting up a Haskell environment in Windows is by using
15+
`GHCup <https://www.haskell.org/ghcup/>`_. Follow the steps outlined in its
16+
webpage to install at least GHC and Cabal. GHCup will install its own MSYS2
17+
system in your computer unless told not to do so: refer to `its documentation
18+
<https://www.haskell.org/ghcup/install/#windows_1>`_ for more information.
19+
20+
.. NOTE::
21+
Stack is another tool you can use to set up a Haskell environment on Windows. Stack
22+
can be installed on its own or via GHCup. See
23+
`Stack's webpage <https://docs.haskellstack.org/en/stable/>`_ and/or
24+
`GHCup's section on Stack integration <https://www.haskell.org/ghcup/guide/#stack-integration>`_,
25+
in particular the `Windows related subsection <https://www.haskell.org/ghcup/guide/#windows>`_.
26+
27+
Ensure that Cabal can call the tools it needs
28+
---------------------------------------------
29+
30+
Cabal sometimes needs to call tools that do not come with Windows (such as
31+
``make`` or even ``git``). The MSYS2 project makes many of them available on
32+
Windows. The directories where those are located need to be made visible in the
33+
``PATH`` when executing ``cabal``. For that, Cabal provides the
34+
``extra-prog-path`` configuration option. Your :ref:`global configuration
35+
<config-file-discovery>` should include this option:
36+
37+
::
38+
39+
extra-prog-path: <msys-dir>\<environment>\bin
40+
<msys-dir>\usr\bin
41+
42+
Where ``<msys-dir>`` points to the location of your MSYS2 installation. Refer to
43+
GHCup's documentation on the default location of this directory.
44+
``<environment>`` has to be one of the environments of MSYS2, which for GHCup is
45+
``mingw64``. You can learn more about the different environments in the `MSYS2
46+
documentation <https://www.msys2.org/docs/environments/>`_.
47+
48+
.. note::
49+
50+
Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`
51+
by default.
52+
53+
Ensure that Cabal can use system libraries
54+
------------------------------------------
55+
56+
Third-party libraries can be installed using the ``pacman`` package manager on
57+
the MSYS2 installation. When installing a third party package its libraries and
58+
header files will (usually) be placed in
59+
``<msys-dir>\<environment>\{lib,include}`` respectively. These directories need
60+
to be specified in the ``extra-lib-dirs`` and ``extra-include-dirs``
61+
respectively. Your :ref:`global configuration <config-file-discovery>` should
62+
include these options:
63+
64+
::
65+
66+
extra-include-dirs: <msys-dir>\<environment>\include
67+
extra-lib-dirs: <msys-dir>\<environment>\lib
68+
69+
70+
.. note::
71+
72+
Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-include-dirs` and `extra-lib-dirs`
73+
by default.
74+
75+
.. warning::
76+
77+
Packages in the ``msys/`` repo are not native Windows libraries and will
78+
probably not work when one tries to link to them. Install the packages for
79+
your selected environment, which for GHCup is ``mingw64/``. Refer to `MSYS2's
80+
package management documentation
81+
<https://www.msys2.org/docs/package-management/>`_ for more information.
82+
83+
Ensure that Cabal can call Haskell tools
84+
----------------------------------------
85+
86+
Haskell tools are located in two places:
87+
88+
- ``<ghcup-dir>\bin`` for standard Haskell tools such as GHC, Cabal, Haddock, ``hsc2hs``...
89+
90+
- The ``installdir`` that Cabal is configured with for user-installed Haskell tools.
91+
92+
For Cabal to be able to invoke these tools, those directories need to be made
93+
visible in the ``PATH``. Your :ref:`global configuration <config-file-discovery>` should
94+
include these options:
95+
96+
::
97+
98+
installdir: <installdir>
99+
extra-prog-path: ...
100+
<ghcup-dir>\bin
101+
<installdir>
102+
103+
.. note::
104+
105+
Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`
106+
by default.
107+
108+
.. _Complete configuration:
109+
110+
Complete configuration
111+
----------------------
112+
113+
The complete :ref:`global configuration <config-file-discovery>` should finally
114+
look like this:
115+
116+
::
117+
118+
installdir: <installdir>
119+
extra-include-dirs: <msys-dir>\<environment>\include
120+
extra-lib-dirs: <msys-dir>\<environment>\lib
121+
extra-prog-path: <ghcup-dir>\bin
122+
<installdir>
123+
<msys-dir>\<environment>\bin
124+
<msys-dir>\usr\bin
125+
126+
.. note::
127+
128+
Unless told otherwise, the GHCup bootstrap script already sets this configuration file to the right
129+
values by default.
130+
131+
.. _Further reading:
132+
133+
Further reading
134+
---------------
135+
136+
- MSYS2 homepage: https://www.msys2.org
137+
- MinGW-W64 homepage: https://www.mingw-w64.org/
138+
- Setting up Windows to build GHC:
139+
https://gitlab.haskell.org/ghc/ghc/-/wikis/building/preparation/windows
140+
- Some definitions and useful tools:
141+
https://gitlab.haskell.org/ghc/ghc/-/wikis/surviving-windows
142+
143+
Outdated links
144+
~~~~~~~~~~~~~~
145+
146+
These links are outdated but still useful to understand the overall picture:
147+
148+
- GHC's wiki about the Windows platform (outdated, GHC now uses MSYS2):
149+
https://gitlab.haskell.org/ghc/ghc/-/wikis/building/platforms/windows
150+
- The Windows toolchain (outdated, GHC now uses the ``CLANG64`` environment):
151+
https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/windows-toolchain
152+
- Haskell Wiki on Windows (outdated, it talks about MSYS and old tools such as
153+
the Haskell platform): https://wiki.haskell.org/Windows

‎doc/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Welcome to the Cabal User Guide
1515

1616
how-to-package-haskell-code
1717
how-to-build-like-nix
18+
how-to-run-in-windows
1819
how-to-use-backpack
1920
how-to-report-bugs
2021

0 commit comments

Comments
 (0)