From 8e9258c5fcfbf76a1ee6c6ee34b07aa09076fcda Mon Sep 17 00:00:00 2001 From: Samuel Pilz Date: Thu, 31 Jan 2019 13:39:35 +0100 Subject: [PATCH 1/3] First draft of `Build.md` build documentation --- docs/Build.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/Build.md diff --git a/docs/Build.md b/docs/Build.md new file mode 100644 index 000000000..5a1be35a5 --- /dev/null +++ b/docs/Build.md @@ -0,0 +1,31 @@ +## Build system + +`haskell-ide-engine` is built using the library `shake`. The build descriptions are defined in the file `install.hs`. + +### Design decisions + +The design of the build system follows 2 main goals: + +* works same on every platform +* has minimal run-time dependencies: `stack` and `git` +* is completely functional right after simple `git clone` +* one-stop-shop for all building + +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. + +### Tradeoffs + +#### `shake.yaml` + +A `shake.yaml` is required for executing the `install.hs` file. + +* It contains the required version of `shake`. +* In contrast to the other `*.yaml` it does not contain the submodules, which is necessary for `stack` to work even before the submodules have been initialized. + +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. + +This may lead to an extra `GHC` to be installed by `stack` if not all versions of `haskell-ide-engine` are installed. From b34dd3c0f0d3045de282dd70c6176de154d1b09b Mon Sep 17 00:00:00 2001 From: Samuel Pilz Date: Sat, 2 Feb 2019 13:28:26 +0100 Subject: [PATCH 2/3] Document design decision of build script `install.hs` --- docs/Build.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/Build.md b/docs/Build.md index 5a1be35a5..26dd6a01b 100644 --- a/docs/Build.md +++ b/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. From e0e1cbdd032061884a12e8b50d5ce7410c005860 Mon Sep 17 00:00:00 2001 From: Samuel Pilz Date: Sat, 2 Feb 2019 13:41:46 +0100 Subject: [PATCH 3/3] fix grammar in build system documentation --- docs/Build.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Build.md b/docs/Build.md index 26dd6a01b..2bdf9341a 100644 --- a/docs/Build.md +++ b/docs/Build.md @@ -13,7 +13,7 @@ The design of the build system has the following main goals: - a working installation of `stack` - `git` * is completely functional right after simple `git clone` -* one-stop-shop for building everything +* one-stop-shop for building all executables required for using `hie` in IDEs. See the project's `README` for detailed information about installing `hie`. @@ -26,11 +26,11 @@ A `shake.yaml` is required for executing the `install.hs` file. * It contains the required version of `shake`. * In contrast to the other `*.yaml` it does not contain the submodules, which is necessary for `stack` to work even before the submodules have been initialized. -It is necessary to update the `resolver` field of the `shake.yaml` if the . +It is necessary to update the `resolver` field of the `shake.yaml` if the script should run with a different `GHC`. #### `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 completely 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 necessary if `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.