metabrush/installation_notes.md

Installation notes

On Windows, we need to install an up-to-date MinGW/MSYS2 toolchain, together with the packages required by the haskell-gi libraries (for GTK).

With an MSYS2 installation at C:\Haskell\ghcup\msys64, the following environment variables will need to be set :

PATH: C:\Haskell\ghcup\msys64\mingw64\bin;C:\Haskell\ghcup\msys64\usr\bin
PKG_CONFIG_PATH: C:\Haskell\ghcup\msys64\mingw64\lib\pkgconfig
XDG_DATA_DIRS: C:\Haskell\ghcup\msys64\mingw64\share;C:\Haskell\ghcup\msys64\usr\share

Then we need pkg-config and the suite of GTK libraries.
After updating the package database if necessary with pacman -Sy msys2-keyring, we can do:

pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-pkg-config mingw64/mingw-w64-x86_64-gobject-introspection mingw64/mingw-w64-x86_64-atk mingw64/mingw-w64-x86_64-gtksourceview5

NB: at the time of writing, the relevant gtksource version is 5; this might need to be updated if you run into issues, as the API of the auto-generated Haskell gi libraries might be different dependent on the version numbers of the gi foreign libraries.

Note that GHC 9.2 and below are affected by some bugs on Windows, e.g. #21109 and #21111. So you should use GHC 9.4 (or above), and make sure that you are using cabal-install > 3.8 (due to #21990).

Possible errors

pkg-config could not be found

The error

The program 'pkg-config' is required but it could not be found.

means that pkg-config couldn't be found on the path. Run the command

pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-pkg-config

to install it.

gobject could not be found

An error such as

The pkg-config package 'gobject' is required but it could not be found.

indicates missing dependencies for the haskell-gi suite of packages. Ensure these are installed by running the aforementioned pacman command. Also check that the packages are registered with pkg-config using the command

pkg-config --list-all

If packages such as cairo, gtk etc do not appear, this means PKG_CONFIG_PATH is not set correctly. Search for *.pc files in your MSYS2 installation, and ensure their paths are included in PKG_CONFIG_PATH.

You might also have multiple different pkg-config executables in your PATH; if so, ensure that cabal is using the correct one, e.g. by modifying the extra-prog-path field in your cabal.config file; see e.g. ghcup issue #371.

Missing (or bad) C libraries

An error of the form:

Missing dependencies on foreign libraries:
* Missing (or bad) C libraries: gobject-2.0

indicates that cabal is not able to find an external C dependency. If the C dependency is indeed installed, then perhaps cabal is calling the wrong pkg-config executable. This could be due to an incorrect extra-prog-path in your cabal.config file; see e.g. ghcup issue #371.

To fix this, you need to ensure the pkg-config executable is correct, e.g. by re-ordering the paths in the extra-prog-path stanza so that the path containing the correct pkg-config appears first.

Failed to load shared library

An error of the form

Failed to load shared library 'libcairo-gobject-2.dll' referenced by the typelib: 'libcairo-gobject-2.dll': The specified procedure could not be found.
gi-cairo> Could not resolve symbol "cairo_gobject_context_get_type" in namespace "cairo"

indicates an issue finding exported functions in the DLLs that we depend upon. I'm not yet sure how to fix this issue; see haskell-gi issue #391.

Error compiling C standard libraries

An error of the form

C:\Haskell\ghcup\ghc\9.4.3\lib\..\mingw\include\c++\v1\cmath:642:26: error:
     error: no template named 'numeric_limits'

signals that GHC is getting confused about which Unix toolchain to use. This might be due to having

extra-include-dirs: C:\Haskell\ghcup\msys64\mingw64\include

in your global cabal.config file, or in your cabal.project.local file.
You should not specify extra-include-dirs on a per-package basis in your cabal.project.local file either: these should be handled by pkg-config.

Remove any extra-include-dirs and extra-lib-dirs, both in your global cabal.config and in local cabal.project/cabal.project.local files to proceed.

...is a relative path which makes no sense

Any error of the form:

include-dirs: /mingw64/bin is a relative path which makes no sense

indicates that one of the packages is incorrectly configured with a Unix-style path.

The version of pkg-config packaged with MSYS2 should automatically convert into the correct full filepaths. So you might need to uninstall the currently installed pkg-config, and install the MSYS2 one:

pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-pkg-config

This should fix the issue. Another solution is to pass the --force flag to ghc-pkg for the problematic packages.
One dependency which used to present this problem was graphite2, which is a dependency of cairo. This causes a problem with the gi-cairo-render library, so in the cabal.project file we can specify:

package gi-cairo-render
  ghc-pkg-options: "--force"

We can otherwise manually fix this issue by changing the pkg-config package file graphite2.pc as follows:

>>> before:
Libs: -L/mingw64/lib -lgraphite2
Cflags: -I/mingw64/include

>>> after:
Libs: -L${libdir} -lgraphite2
Cflags: -I${includedir}

See this patch. The package fontconfig also presented this issue; this was resolved in this patch.