add installation instructions

This commit is contained in:
sheaf 2020-09-08 00:29:14 +02:00
parent a459467ed0
commit b608bed8b0

144
installation_notes.md Normal file
View file

@ -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.