Document design decision of build script install.hs

Author: samuelpilz

docs/Build.md

@@ -2,16 +2,20 @@
 
 `haskell-ide-engine` is built using the library `shake`. The build descriptions are defined in the file `install.hs`.
 
-### Design decisions
+Previously, `haskell-ide-engine` was built using a `Makefile` on Unix systems and a `PowerShell` script on Windows. By replacing both scripts by a Haskell-based solution, the build process is unified.
 
-The design of the build system follows 2 main goals:
+### Design goals
 
-* works same on every platform
-* has minimal run-time dependencies: `stack` and `git`
+The design of the build system has the following main goals:
+
+* works identically on every platform
+* has minimal run-time dependencies:
+    - a working installation of `stack`
+    - `git`
 * is completely functional right after simple `git clone`
-* one-stop-shop for all building
+* one-stop-shop for building everything
 
-Previously, `haskell-ide-engine` was built using a `Makefile` on Unix systems and a `PowerShell` script on Windows. By replacing both scripts by a Haskell-based solution, the scripts can be can be replaced by a single script.
+See the project's `README` for detailed information about installing `hie`.
 
 ### Tradeoffs
 
@@ -26,6 +30,21 @@ It is necessary to update the `resolver` field of the `shake.yaml` if the .
 
 #### `install.hs` installs a GHC
 
-Before the code in `install.hs` can be executed, `stack` installs a `GHC`, depending on the `resolver` field in `shake.yaml`. This is a necessary if the `install.hs` should be totally functional right after a fresh `git clone` without further configuration.
+Before the code in `install.hs` can be executed, `stack` installs a `GHC`, depending on the `resolver` field in `shake.yaml`. This is a necessary if the `install.hs` should be completely functional right after a fresh `git clone` without further configuration.
 
 This may lead to an extra `GHC` to be installed by `stack` if not all versions of `haskell-ide-engine` are installed.
+
+#### `stack` is a build dependency
+
+Currently, it is not possible to build all `hie-*` executables automatically without `stack`, since the `install.hs` script is executed by `stack`.
+
+Other parts of the script also depend on `stack`:
+
+* finding the local install-dir `stack path --local-bin`
+* finding and installing different `ghc` versions
+
+#### `install.hs` executes `cabal install Cabal`
+
+`ghc-mod` installs `cabal-helper` at runtime depending on the `ghc` used by the project, which can take a long time upon startup of `hie`. The `install.hs` script speeds up this process by calling `cabal install Cabal` upon build.
+
+Hopefully, this behaviour can be removed in the future.