From b608bed8b00bcd7e0f3151bdd71b97ff2f2e2dbd Mon Sep 17 00:00:00 2001
From: sheaf <sam.derbyshire@gmail.com>
Date: Tue, 8 Sep 2020 00:29:14 +0200
Subject: [PATCH] add installation instructions

---
 installation_notes.md | 144 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 144 insertions(+)
 create mode 100644 installation_notes.md

diff --git a/installation_notes.md b/installation_notes.md
new file mode 100644
index 0000000..6639a39
--- /dev/null
+++ b/installation_notes.md
@@ -0,0 +1,144 @@
+
+# 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.