diff --git a/doc/how-to-run-in-windows.rst b/doc/how-to-run-in-windows.rst new file mode 100644 index 00000000000..5c06f62bbb3 --- /dev/null +++ b/doc/how-to-run-in-windows.rst @@ -0,0 +1,153 @@ +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 `_. + +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. Refer to +GHCup's documentation on the default location of this directory. +```` has to be one of the environments of MSYS2, which for GHCup is +``mingw64``. You can learn more about the different environments in the `MSYS2 +documentation `_. + +.. 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 +------------------------------------------ + +Third-party libraries can be installed using the ``pacman`` package manager on +the MSYS2 installation. 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:: + + Packages in the ``msys/`` repo are not native Windows libraries and will + probably not work when one tries to link to them. Install the packages for + your selected environment, which for GHCup is ``mingw64/``. Refer to `MSYS2's + package management documentation + `_ for more information. + +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 diff --git a/doc/index.rst b/doc/index.rst index 69109a67685..e0007bc291f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,6 +15,7 @@ Welcome to the Cabal User Guide how-to-package-haskell-code how-to-build-like-nix + how-to-run-in-windows how-to-use-backpack how-to-report-bugs