Skip to content

Commit c732a3d

Browse files
jasagredojasagredo
committed
How to use Cabal in Windows
1 parent 3d3622f commit c732a3d

File tree

2 files changed

+143
-0
lines changed

2 files changed

+143
-0
lines changed

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

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