Update documentation about build system

README.md

@@ -214,7 +214,7 @@ cabal v2-run ./install.hs --project-file install/shake.project <target>
 
 Running the script with cabal on windows requires a cabal version greater or equal to `3.0.0.0`.
 
-Unfortunately, it is still required to have `stack` installed so that the install-script can locate the `local-bin` directory (on Linux `~/.local/bin`) and copy the `hie` binaries to `hie-x.y.z`, which is required for the `hie-wrapper` to function as expected.
+Unfortunately, it is still required to have `stack` installed so that the install-script can locate the `local-bin` directory (on Linux `~/.local/bin`) and copy the `hie` binaries to `hie-x.y.z`, which is required for the `hie-wrapper` to function as expected. There are plans to remove this requirement and let users build hie only with one build tool or another.
 
 For brevity, only the `stack`-based commands are presented in the following sections.
 
@@ -246,7 +246,6 @@ stack ./install.hs build-data
 
 The Haskell IDE Engine can also be built with `cabal new-build` instead of `stack build`.
 This has the advantage that you can decide how the GHC versions have been installed.
-However, this approach does currently not work for windows due to a missing feature upstream.
 To see what GHC versions are available, the command `stack install.hs cabal-ghcs` can be used.
 It will list all GHC versions that are on the path and their respective installation directory.
 If you think, this list is incomplete, you can try to modify the PATH variable, such that the executables can be found.

docs/Build.md

@@ -28,8 +28,10 @@ See the project's `README` for detailed information about installing `hie`.
 The build script `install.hs` defines several targets using the `shake` build system. The targets are roughly:
 
 * `hie-*`: builds and installs the `hie` binaries. Also renames the binaries to contain the correct version-number.
-* `build`: builds and installs `hie` binaries for all supported `ghc` versions.
+* `build-lastest`: builds ad installs `hie` for the last available and supported `ghc` version.
+* `build-all`: builds and installs `hie` binaries for all supported `ghc` versions. This option may take a long time and computer resources so use it with caution.
 * `build-data`: builds the hoogle-db required by `hie`
+* `build`:  builds ad installs `hie` for the last supported `ghc` version (like `build-lastest`) and the hoogle-db (like `build-data`)
 * `cabal-*`: execute the same task as the original target, but with `cabal` instead of `stack`
 
 Each `stack-*.yaml` contains references to packages in the submodules. Calling `stack` with one of those causes the build to fail if the submodules have not been initialized already. The file `shake.yaml` solves this issue invoking the `git` binary itself to update the submodules. Moreover, it specifies the correct version of `shake` and is used for installing all run-time dependencies such as `cabal` and `hoogle` if necessary.
@@ -38,7 +40,7 @@ Each `stack-*.yaml` contains references to packages in the submodules. Calling `
 
 `hie` depends on a correct environment in order to function properly:
 
-* `cabal-install`: If no `cabal` executable can be found or has an outdated version, `cabal-install` is installed via `stack`.
+* `cabal-install`: This dependency is required by `hie` to handle correctly projects that are not `stack` based (without `stack.yaml`). You can install an appropiate version using `stack` with the `stack-install-cabal` target.
 * The `hoogle` database: `hoogle generate` needs to be called with the most-recent `hoogle` version.
 
 ### Steps to build `hie`
@@ -47,10 +49,9 @@ Installing `hie` is a multi-step process:
 
 1. `git submodule sync && git submodule update --init`
 2. `hoogle generate` (`hoogle>=5.0.17` to be safe)
-3. ensure that `cabal-install` is installed in the correct version
-4. `stack --stack-yaml=stack-<X>.yaml install` or `cabal new-install -w ghc-<X>`
-5. rename `hie` binary to `hie-<X>` in `$HOME/.local/bin`, where `<X>` is the GHC version used
-6. repeat step 4 and 5 for all desired GHC versions
+3. `stack --stack-yaml=stack-<X>.yaml install` or `cabal new-install -w ghc-<X>`
+4. rename `hie` binary to `hie-<X>` in `$HOME/.local/bin`, where `<X>` is the GHC version used
+5. repeat step 4 and 5 for all desired GHC versions
 
 This ensures that a complete install is always possible after each `git pull` or a `git clone`.
 
@@ -90,19 +91,17 @@ The final step is to configure the `hie` client to use a custom `hie-wrapper` sc
 The `install.hs` script performs some checks to ensure that a correct installation is possible and provide meaningful error messages for known issues.
 
 * `stack` needs to be up-to-date. Version `1.9.3` is required
+* `cabal` needs to be up-to-date. Version `3.0.0.0` is required for windows systems and `2.4.1.0` for other ones.
 * `ghc-8.6.3` is broken on windows. Trying to install `hie-8.6.3` on windows is not possible.
-* `cabal new-build` does not work on windows at the moment. All `cabal-*` targets exit with an error message about that.
 * When the build fails, an error message, that suggests to remove `.stack-work` directory, is displayed.
 
 ### Tradeoffs
 
 #### `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`.
+Currently, `stack` is needed even if you run the script with `cabal` to get the path where install the binaries but there are plans to remove that dependency (see #1380).
 
-We are open to suggestions of other build systems that honor the requirements above, but are executable without `stack`.
-
-#### `install.hs` installs a GHC before running
+#### run `install.hs` with `stack` installs a GHC before running
 
 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.