Un-ignore .bat files

[cabal.git] / doc / how-to-run-in-windows.rst

How to use Cabal in Windows\r
===========================\r
\r
This document describes how to use Cabal in a Windows system. See the\r
:ref:`Further reading` section for some other references that might provide some\r
more explanations. For a TL;DR, jump to the :ref:`Complete configuration`.\r
\r
Install the Haskell environment\r
-------------------------------\r
\r
Haskell development on Windows makes use of the `MSYS2 <https://www.msys2.org/>`_ \r
tools.\r
\r
The recommended way of setting up a Haskell environment in Windows is by using\r
`GHCup <https://www.haskell.org/ghcup/>`_. Follow the steps outlined in its\r
webpage to install at least GHC and Cabal. GHCup will install its own MSYS2\r
system in your computer unless told not to do so: refer to `its documentation\r
<https://www.haskell.org/ghcup/install/#windows_1>`_ for more information.\r
\r
.. NOTE::\r
   Stack is another tool you can use to set up a Haskell environment on Windows. Stack\r
   can be installed on its own or via GHCup. See \r
   `Stack's webpage <https://docs.haskellstack.org/en/stable/>`_ and/or \r
   `GHCup's section on Stack integration <https://www.haskell.org/ghcup/guide/#stack-integration>`_,\r
   in particular the `Windows related subsection <https://www.haskell.org/ghcup/guide/#windows>`_.\r
\r
Ensure that Cabal can call the tools it needs\r
---------------------------------------------\r
\r
Cabal sometimes needs to call tools that do not come with Windows (such as\r
``make`` or even ``git``). The MSYS2 project makes many of them available on\r
Windows. The directories where those are located need to be made visible in the\r
``PATH`` when executing ``cabal``. For that, Cabal provides the\r
``extra-prog-path`` configuration option. Your :ref:`global configuration\r
<config-file-discovery>` should include this option:\r
\r
::\r
\r
   extra-prog-path: <msys-dir>\<environment>\bin\r
                    <msys-dir>\usr\bin\r
\r
Where ``<msys-dir>`` points to the location of your MSYS2 installation. Refer to\r
GHCup's documentation on the default location of this directory.\r
``<environment>`` has to be one of the environments of MSYS2, which for GHCup is\r
``mingw64``. You can learn more about the different environments in the `MSYS2\r
documentation <https://www.msys2.org/docs/environments/>`_.\r
\r
.. note::\r
\r
   Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`\r
   by default.\r
\r
Ensure that Cabal can use system libraries\r
------------------------------------------\r
\r
Third-party libraries can be installed using the ``pacman`` package manager on\r
the MSYS2 installation. When installing a third party package its libraries and\r
header files will (usually) be placed in\r
``<msys-dir>\<environment>\{lib,include}`` respectively. These directories need\r
to be specified in the ``extra-lib-dirs`` and ``extra-include-dirs``\r
respectively. Your :ref:`global configuration <config-file-discovery>` should\r
include these options:\r
\r
::\r
\r
   extra-include-dirs: <msys-dir>\<environment>\include\r
   extra-lib-dirs: <msys-dir>\<environment>\lib\r
\r
\r
.. note::\r
\r
   Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-include-dirs` and `extra-lib-dirs`\r
   by default.\r
\r
.. warning::\r
\r
   Packages in the ``msys/`` repo are not native Windows libraries and will\r
   probably not work when one tries to link to them. Install the packages for\r
   your selected environment, which for GHCup is ``mingw64/``. Refer to `MSYS2's\r
   package management documentation\r
   <https://www.msys2.org/docs/package-management/>`_ for more information.\r
\r
Ensure that Cabal can call Haskell tools\r
----------------------------------------\r
\r
Haskell tools are located in two places:\r
\r
- ``<ghcup-dir>\bin`` for standard Haskell tools such as GHC, Cabal, Haddock, ``hsc2hs``...\r
\r
- The ``installdir`` that Cabal is configured with for user-installed Haskell tools.\r
\r
For Cabal to be able to invoke these tools, those directories need to be made\r
visible in the ``PATH``. Your :ref:`global configuration <config-file-discovery>` should\r
include these options:\r
\r
::\r
\r
   installdir: <installdir>\r
   extra-prog-path: ...\r
                    <ghcup-dir>\bin\r
                    <installdir>\r
\r
.. note::\r
\r
   Unless told otherwise, the GHCup bootstrap script already adds these directories to `extra-prog-path`\r
   by default.\r
\r
.. _Complete configuration:\r
\r
Complete configuration\r
----------------------\r
\r
The complete :ref:`global configuration <config-file-discovery>` should finally\r
look like this:\r
\r
::\r
\r
   installdir: <installdir>\r
   extra-include-dirs: <msys-dir>\<environment>\include\r
   extra-lib-dirs: <msys-dir>\<environment>\lib\r
   extra-prog-path: <ghcup-dir>\bin\r
                    <installdir>\r
                    <msys-dir>\<environment>\bin\r
                    <msys-dir>\usr\bin\r
\r
.. note::\r
\r
   Unless told otherwise, the GHCup bootstrap script already sets this configuration file to the right\r
   values by default.\r
\r
.. _Further reading:\r
\r
Further reading\r
---------------\r
\r
- MSYS2 homepage: https://www.msys2.org\r
- MinGW-W64 homepage: https://www.mingw-w64.org/\r
- Setting up Windows to build GHC:\r
  https://gitlab.haskell.org/ghc/ghc/-/wikis/building/preparation/windows\r
- Some definitions and useful tools:\r
  https://gitlab.haskell.org/ghc/ghc/-/wikis/surviving-windows\r
\r
Outdated links\r
~~~~~~~~~~~~~~\r
\r
These links are outdated but still useful to understand the overall picture:\r
\r
- GHC's wiki about the Windows platform (outdated, GHC now uses MSYS2):\r
  https://gitlab.haskell.org/ghc/ghc/-/wikis/building/platforms/windows\r
- The Windows toolchain (outdated, GHC now uses the ``CLANG64`` environment):\r
  https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/windows-toolchain\r
- Haskell Wiki on Windows (outdated, it talks about MSYS and old tools such as\r
  the Haskell platform): https://wiki.haskell.org/Windows\r