From 3ccb534cfe1f26e6c344c3dd80b42e9bc32eb1c9 Mon Sep 17 00:00:00 2001 From: Javier Sagredo Date: Mon, 15 Jul 2024 17:33:37 +0200 Subject: [PATCH] Docs: Clarify MSYS2 complications --- doc/how-to-run-in-windows.rst | 67 +++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 15 deletions(-) diff --git a/doc/how-to-run-in-windows.rst b/doc/how-to-run-in-windows.rst index 5c06f62bbb3..53aeb33b849 100644 --- a/doc/how-to-run-in-windows.rst +++ b/doc/how-to-run-in-windows.rst @@ -8,7 +8,7 @@ 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 `_ +Haskell development on Windows makes use of the `MSYS2 `_ tools. The recommended way of setting up a Haskell environment in Windows is by using @@ -19,11 +19,43 @@ system in your computer unless told not to do so: refer to `its documentation .. 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 + 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 `_. +MSYS2 environments and packages +------------------------------- + +A particular environment has to be chosen when using MSYS2. By default GHCup will +use ``MINGW64``. You can learn more about the different environments in the `MSYS2 +documentation `_. + +GHCs before 9.4.1 are shipped with a minimal set of packages based on the +``MINGW64`` environment, and GHC 9.4.1 and newer are shipped with a minimal set +of packages based on the ``CLANG64`` environment. It is in general advisable to +work inside the same environment as your GHC uses, but (with some exceptions) +it shouldn't matter whether environments are mixed. Stay warned that it can +sometimes lead to undecipherable errors. + +We will refer to the chosen environment as ```` through this +documentation. + +Third-party libraries and tools can be installed using the ``pacman`` package +manager on the MSYS2 installation +(`see `_). If MSYS2 was +installed via GHCup, check GHCup's documentation on how to call ``pacman``. Note +that installing a package ``mingw-w64--x86_64-`` will install +it in the ``\`` tree of directories, and might not be +visible if working on a different environment than ````. In +general, it is advisable to install only packages for the environment that was +chosen above. + +Apart from these environments, there is the ``msys`` environment which is based +on Cygwin. Some tools only exist for this environment. Tools from this environment +are callable when working in any other environment. It is in general not possible +to link to libraries installed in the ``msys`` environment. + Ensure that Cabal can call the tools it needs --------------------------------------------- @@ -39,11 +71,10 @@ Windows. The directories where those are located need to be made visible in the 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 `_. +Where ```` points to the location of your MSYS2 installation. If MSYS2 +was installed via GHCup, refer to GHCup's documentation on the default location +of this directory. If MSYS2 was installed system-wide this is usually +``C:\msys64``. .. note:: @@ -53,8 +84,7 @@ documentation `_. 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 +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`` @@ -74,11 +104,18 @@ include these options: .. 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. + GHCs older than 9.4.1 will crash if a recent + ``mingw-w64--x86_64-crt-git`` is installed for whichever ```` and + these directories are set globally . + + Effectively this means that if you have installed ``mingw-w64--x86_64-crt-git`` + (which you probably have if you are using ``clang`` in the ``CLANG64`` + environment or ``gcc`` in the ``UCRT64`` or ``MINGW64`` environments outside of + Haskell, as this package is part of the ``mingw-w64--x86_64-toolchain`` + meta-packages) and are using a GHC older than 9.4.1, you cannot simply depend on system + libraries by adding these paths to the global config, and instead you will + have to go through some other method to depend on those libraries like + :pkg-field:`pkgconfig-depends`. Ensure that Cabal can call Haskell tools ----------------------------------------