| blob | 53aeb33b849ac2f46265c49d5855e6a961a6f1dd |
1 How to use Cabal in Windows\r
2 ===========================\r
3 \r
4 This document describes how to use Cabal in a Windows system. See the\r
5 :ref:`Further reading` section for some other references that might provide some\r
6 more explanations. For a TL;DR, jump to the :ref:`Complete configuration`.\r
7 \r
8 Install the Haskell environment\r
9 -------------------------------\r
10 \r
11 Haskell development on Windows makes use of the `MSYS2 <https://www.msys2.org/>`_\r
12 tools.\r
13 \r
14 The recommended way of setting up a Haskell environment in Windows is by using\r
15 `GHCup <https://www.haskell.org/ghcup/>`_. Follow the steps outlined in its\r
16 webpage to install at least GHC and Cabal. GHCup will install its own MSYS2\r
17 system in your computer unless told not to do so: refer to `its documentation\r
18 <https://www.haskell.org/ghcup/install/#windows_1>`_ for more information.\r
19 \r
20 .. NOTE::\r
21 Stack is another tool you can use to set up a Haskell environment on Windows. Stack\r
22 can be installed on its own or via GHCup. See\r
23 `Stack's webpage <https://docs.haskellstack.org/en/stable/>`_ and/or\r
24 `GHCup's section on Stack integration <https://www.haskell.org/ghcup/guide/#stack-integration>`_,\r
25 in particular the `Windows related subsection <https://www.haskell.org/ghcup/guide/#windows>`_.\r
26 \r
27 MSYS2 environments and packages\r
28 -------------------------------\r
29 \r
30 A particular environment has to be chosen when using MSYS2. By default GHCup will\r
31 use ``MINGW64``. You can learn more about the different environments in the `MSYS2\r
32 documentation <https://www.msys2.org/docs/environments/>`_.\r
33 \r
34 GHCs before 9.4.1 are shipped with a minimal set of packages based on the\r
35 ``MINGW64`` environment, and GHC 9.4.1 and newer are shipped with a minimal set\r
36 of packages based on the ``CLANG64`` environment. It is in general advisable to\r
37 work inside the same environment as your GHC uses, but (with some exceptions)\r
38 it shouldn't matter whether environments are mixed. Stay warned that it can\r
39 sometimes lead to undecipherable errors.\r
40 \r
41 We will refer to the chosen environment as ``<environment>`` through this\r
42 documentation.\r
43 \r
44 Third-party libraries and tools can be installed using the ``pacman`` package\r
45 manager on the MSYS2 installation\r
46 (`see <https://www.msys2.org/docs/package-management/>`_). If MSYS2 was\r
47 installed via GHCup, check GHCup's documentation on how to call ``pacman``. Note\r
48 that installing a package ``mingw-w64-<environment>-x86_64-<pkg>`` will install\r
49 it in the ``<msys-dir>\<environment>`` tree of directories, and might not be\r
50 visible if working on a different environment than ``<environment>``. In\r
51 general, it is advisable to install only packages for the environment that was\r
52 chosen above.\r
53 \r
54 Apart from these environments, there is the ``msys`` environment which is based\r
55 on Cygwin. Some tools only exist for this environment. Tools from this environment\r
56 are callable when working in any other environment. It is in general not possible\r
57 to link to libraries installed in the ``msys`` environment.\r
58 \r
59 Ensure that Cabal can call the tools it needs\r
60 ---------------------------------------------\r
61 \r
62 Cabal sometimes needs to call tools that do not come with Windows (such as\r
63 ``make`` or even ``git``). The MSYS2 project makes many of them available on\r
64 Windows. The directories where those are located need to be made visible in the\r
65 ``PATH`` when executing ``cabal``. For that, Cabal provides the\r
66 ``extra-prog-path`` configuration option. Your :ref:`global configuration\r
67 <config-file-discovery>` should include this option:\r
68 \r
69 ::\r
70 \r
71 extra-prog-path: <msys-dir>\<environment>\bin\r
72 <msys-dir>\usr\bin\r
73 \r
74 Where ``<msys-dir>`` points to the location of your MSYS2 installation. If MSYS2\r
75 was installed via GHCup, refer to GHCup's documentation on the default location\r
76 of this directory. If MSYS2 was installed system-wide this is usually\r
77 ``C:\msys64``.\r
78 \r
79 .. note::\r
80 \r
81 Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`\r
82 by default.\r
83 \r
84 Ensure that Cabal can use system libraries\r
85 ------------------------------------------\r
86 \r
87 When installing a third party package its libraries and\r
88 header files will (usually) be placed in\r
89 ``<msys-dir>\<environment>\{lib,include}`` respectively. These directories need\r
90 to be specified in the ``extra-lib-dirs`` and ``extra-include-dirs``\r
91 respectively. Your :ref:`global configuration <config-file-discovery>` should\r
92 include these options:\r
93 \r
94 ::\r
95 \r
96 extra-include-dirs: <msys-dir>\<environment>\include\r
97 extra-lib-dirs: <msys-dir>\<environment>\lib\r
98 \r
99 \r
100 .. note::\r
101 \r
102 Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-include-dirs` and `extra-lib-dirs`\r
103 by default.\r
104 \r
105 .. warning::\r
106 \r
107 GHCs older than 9.4.1 will crash if a recent\r
108 ``mingw-w64-<environment>-x86_64-crt-git`` is installed for whichever ``<environment>`` and\r
109 these directories are set globally .\r
110 \r
111 Effectively this means that if you have installed ``mingw-w64-<environment>-x86_64-crt-git``\r
112 (which you probably have if you are using ``clang`` in the ``CLANG64``\r
113 environment or ``gcc`` in the ``UCRT64`` or ``MINGW64`` environments outside of\r
114 Haskell, as this package is part of the ``mingw-w64-<environment>-x86_64-toolchain``\r
115 meta-packages) and are using a GHC older than 9.4.1, you cannot simply depend on system\r
116 libraries by adding these paths to the global config, and instead you will\r
117 have to go through some other method to depend on those libraries like\r
118 :pkg-field:`pkgconfig-depends`.\r
119 \r
120 Ensure that Cabal can call Haskell tools\r
121 ----------------------------------------\r
122 \r
123 Haskell tools are located in two places:\r
124 \r
125 - ``<ghcup-dir>\bin`` for standard Haskell tools such as GHC, Cabal, Haddock, ``hsc2hs``...\r
126 \r
127 - The ``installdir`` that Cabal is configured with for user-installed Haskell tools.\r
128 \r
129 For Cabal to be able to invoke these tools, those directories need to be made\r
130 visible in the ``PATH``. Your :ref:`global configuration <config-file-discovery>` should\r
131 include these options:\r
132 \r
133 ::\r
134 \r
135 installdir: <installdir>\r
136 extra-prog-path: ...\r
137 <ghcup-dir>\bin\r
138 <installdir>\r
139 \r
140 .. note::\r
141 \r
142 Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`\r
143 by default.\r
144 \r
145 .. _Complete configuration:\r
146 \r
147 Complete configuration\r
148 ----------------------\r
149 \r
150 The complete :ref:`global configuration <config-file-discovery>` should finally\r
151 look like this:\r
152 \r
153 ::\r
154 \r
155 installdir: <installdir>\r
156 extra-include-dirs: <msys-dir>\<environment>\include\r
157 extra-lib-dirs: <msys-dir>\<environment>\lib\r
158 extra-prog-path: <ghcup-dir>\bin\r
159 <installdir>\r
160 <msys-dir>\<environment>\bin\r
161 <msys-dir>\usr\bin\r
162 \r
163 .. note::\r
164 \r
165 Unless told otherwise, the GHCup bootstrap script already sets this configuration file to the right\r
166 values by default.\r
167 \r
168 .. _Further reading:\r
169 \r
170 Further reading\r
171 ---------------\r
172 \r
173 - MSYS2 homepage: https://www.msys2.org\r
174 - MinGW-W64 homepage: https://www.mingw-w64.org/\r
175 - Setting up Windows to build GHC:\r
176 https://gitlab.haskell.org/ghc/ghc/-/wikis/building/preparation/windows\r
177 - Some definitions and useful tools:\r
178 https://gitlab.haskell.org/ghc/ghc/-/wikis/surviving-windows\r
179 \r
180 Outdated links\r
181 ~~~~~~~~~~~~~~\r
182 \r
183 These links are outdated but still useful to understand the overall picture:\r
184 \r
185 - GHC's wiki about the Windows platform (outdated, GHC now uses MSYS2):\r
186 https://gitlab.haskell.org/ghc/ghc/-/wikis/building/platforms/windows\r
187 - The Windows toolchain (outdated, GHC now uses the ``CLANG64`` environment):\r
188 https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/windows-toolchain\r
189 - Haskell Wiki on Windows (outdated, it talks about MSYS and old tools such as\r
190 the Haskell platform): https://wiki.haskell.org/Windows\r