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`),
as well as the `hmatrix` library.


With an `MSYS2` installation, the following environment variables will need to be set (with `MSYS2` installed at `C:\msys64`):

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


Then we install some necessary packages using the following command:

```bash
pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-pkg-config mingw64/mingw-w64-x86_64-gobject-introspection mingw64/mingw-w64-x86_64-gtksourceview3 mingw64/mingw-w64-x86_64-openblas
```

## Possible errors

### pkg-config could not be found

The error

```bash
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

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

to install it.


### gobject could not be found

An error such as 
```bash
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

```bash
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`.

### ...is a relative path which makes no sense

Any error of the form:
```bash
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.
At the time of writing, the only dependency which presents this problem is `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}
```

The package `fontconfig` also presented this issue; this was resolved in [this patch](https://github.com/msys2/MINGW-packages/issues/872). 

### Missing C library `openblas`

The error message

```
Missing dependencies on foreign libraries:
* Missing (or bad) C library: openblas
```

indicates that `cabal` could not find a C library that `hmatrix` depends on.

Make sure that `openblas` is installed:

```
pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-openblas
```

then ensure that `cabal` can find it, for instance:

```
package hmatrix
  extra-lib-dirs: "C:/msys64/mingw64/bin"
  extra-include-dirs: "C:/msys64/mingw64/include"
```

enables `cabal` to find `C:/msys64/mingw64/bin/libopenblas.dll`.

### The code execution cannot proceed because libgfortran_64-3.dll was not found

An error such as

```
The code execution cannot proceed because libgfortran_64-3.dll was not found
```

or

```
The code execution cannot proceed because libgcc_s_seh_64-1.dll was not found
```

indicates that a dependency of `BLAS` could not be loaded. These should have been installed as dependencies of `openblas` (see previous error), but otherwise you can try:

```
pacman -S -q --noconfirm mingw64/mingw-w64-x86_64-gcc-fortran mingw64/mingw-w64-x86_64-gcc
```

### addDLL: library not loaded

The error message

```
addDLL: libopenblas or dependencies not loaded. (Win32 error 126)
```

means that `GHC` was not able to find the `BLAS` library, or a dependency thereof.

Follow the previous two steps to ensure both the library and its dependencies can be found.


### Unknown symbol dgesvd_

An error of the form

```
ghc.exe:  | MetaBrush\dist-newstyle\build\x86_64-windows\ghc-8.8.4\hmatrix-0.20.0.0\build\libHShmatrix-0.20.0.0-inplace.a: unknown symbol `dgesvd_'
```

indicates that `GHC` was not able to load symbols for the `hmatrix` dependency. This should be solved in the same way as the previous error.