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

## 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 using a Unix-style path.
This was the case with `fontconfig`, which was resolved in [this patch](https://github.com/msys2/MINGW-packages/issues/872). 

At the time of writing, another dependency suffers from the same issue: `graphite2`. To fix this, change its `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}
```

### Missing C library `blas` or `lapack`

The error message

```
Missing dependencies on foreign libraries:
* Missing (or bad) C libraries: blas, lapack
```

indicates that `cabal` could not find the C libraries that `hmatrix` depends on.

These can be downloaded [here](https://icl.cs.utk.edu/lapack-for-windows/lapack/). You will need:

  * `BLAS` x64 dll,
  * `LAPACK` x64 dll,

Put these in some folder, say "C:/GSL", then:

  * add the folder to the PATH environment variable,
  * add the following to your `cabal.project` file:

```
package hmatrix
  extra-lib-dirs: "C:/GSL"
  extra-include-dirs: "C:/GSL"
```

### 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`/`LAPACK` could not be loaded. Download these DLLs and add them to the `PATH`.

### addDLL: library not loaded

The error message

```
addDLL: C:\GSL\libblas 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.