From 2be97e86889fae03a4f62b35b56a9790ac5523b0 Mon Sep 17 00:00:00 2001 From: jneira Date: Sat, 16 May 2020 02:18:30 +0200 Subject: [PATCH 1/4] Port partially hie README --- README.md | 274 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 271 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e738f9dd00..e85fddb121 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,279 @@ background](https://neilmitchell.blogspot.com/2020/01/one-haskell-ide-to-rule-th This is *very* early stage software. -To play along at home, do a recursive `git clone`. +- [Haskell Language Server (HLS)](#haskell-language-server) + - [Installation](#installation) + - [Installation from source](#installation-from-source) + - [Common pre-requirements](#common-pre-requirements) + - [Linux-specific pre-requirements](#linux-specific-pre-requirements) + - [Windows-specific pre-requirements](#windows-specific-pre-requirements) + - [Download the source code](#download-the-source-code) + - [Building](#building) + - [Install via cabal](#install-via-cabal) + - [Install specific GHC Version](#install-specific-ghc-version) + - [Project Configuration](#project-configuration) + - [Contributing](#contributing) + - [It's time to join the project!](#its-time-to-join-the-project) -Initial effort is to understand how plugins can be supported in a modular way. +## Installation -Builds with stack and cabal, using GHC 8.6.5 +For now only installation from source is supported. + +### Installation from source + +#### Common pre-requirements + +- `stack` or `cabal` must be in your PATH + - You need stack version >= 2.1.1 or cabal >= 2.4.0.0 +- `git` must be in your PATH +- The directory where `stack`or `cabal` put the binaries must be in you PATH: + - For stack you can get it with `stack path --local-bin` + - For cabal it is by default `$HOME/.cabal/bin` in linux and `%APPDATA%\cabal\bin` in windows. + +Tip: you can quickly check if some command is in your path by running the command. +If you receive some meaningful output instead of "command not found"-like message +then it means you have the command in PATH. + +#### Linux-specific pre-requirements + +On Linux you will need install a couple of extra libraries (for Unicode ([ICU](http://site.icu-project.org/)) and [NCURSES](https://www.gnu.org/software/ncurses/)): + +**Debian 9/Ubuntu 18.04 or earlier**: + +```bash +sudo apt install libicu-dev libtinfo-dev libgmp-dev +``` + +**Debian 10/Ubuntu 18.10 or later**: + +```bash +sudo apt install libicu-dev libncurses-dev libgmp-dev +``` + +**Fedora**: + +```bash +sudo dnf install libicu-devel ncurses-devel # also zlib-devel if not already installed +``` + +#### Windows-specific pre-requirements + +In order to avoid problems with long paths on Windows you can do either one of the following: + +1. Clone the `haskell-language-server` to a short path, for example the root of your logical drive (e.g. to + `C:\hls`). Even if you choose `C:\haskell-language-server` you could hit the problem. If this doesn't work or you want to use a longer path, try the second option. + +2. If the `Local Group Policy Editor` is available on your system, go to: `Local Computer Policy -> Computer Configuration -> Administrative Templates -> System -> Filesystem` set `Enable Win32 long paths` to `Enabled`. If you don't have the policy editor you can use regedit by using the following instructions [here](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#enable-long-paths-in-windows-10-version-1607-and-later). You also need to configure git to allow longer paths by using unicode paths. To set this for all your git repositories use `git config --system core.longpaths true` (you probably need an administrative shell for this) or for just this one repository use `git config core.longpaths true`. + +In addition make sure `haskell-language-server.exe` is not running by closing your editor, otherwise in case of an upgrade the executable can not be installed. + +#### Download the source code + +```bash +git clone https://github.com/haskell/haskell-language-server --recurse-submodules +cd haskell-language-server +``` + +#### Building + +Note, on first invocation of the build script with stack, a GHC is being installed for execution. +The GHC used for the `install.hs` can be adjusted in `./install/shake.yaml` by using a different resolver. + +Available commands can be seen with: + +```bash +stack ./install.hs help +``` + +Remember, this will take time to download a Stackage-LTS and an appropriate GHC for build +haskell-language-server the first time. + +##### Install via cabal + +The install-script can be invoked via `cabal` instead of `stack` with the command + +```bash +cabal v2-run ./install.hs --project-file install/shake.project +``` + +or using the existing alias script + +```bash +./cabal-hls-install +``` + +Running the script with cabal on windows requires a cabal version greater or equal to `3.0.0.0`. + +For brevity, only the `stack`-based commands are presented in the following sections. + +##### Install specific GHC Version + +Install haskell-language-server for the latest available and supported GHC version (and hoogle docs): + +```bash +stack ./install.hs hls +``` + +Install haskell-language-server for a specific GHC version (and hoogle docs): + +```bash +stack ./install.hs hls-8.8.3 +stack ./install.hs data +``` + +The Haskell Language Server can also be built with `cabal v2-build` instead of `stack build`. +This has the advantage that you can decide how the GHC versions have been installed. +To see what GHC versions are available, the command `cabal-hls-install ghcs` can be used. +It will list all *supported* GHC versions that are on the path for build with 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. +Note, that the targets `hls` and `data` depend on the found GHC versions. + +An example output is: + +```bash +> cabal-hls-install ghcs +****************************************************************** +Found the following GHC paths: +ghc-8.6.5: /opt/bin/ghc-8.6.5 +ghc-8.8.3: /opt/bin/ghc-8.8.3 + +****************************************************************** +``` + +If your desired ghc has been found, you use it to install haskell-language-server. + +```bash +cabal-hls-install hls-8.6.5 +cabal-hls-install data +``` + +## Project Configuration + +**For a full explanation of possible configurations, refer to [hie-bios/README](https://github.com/mpickering/hie-bios/blob/master/README.md).** + +haskell-language-server has some limited support via hie-bios to detect automatically +your project configuration and set up the environment for GHC. +The plan is to improve it to handle most use cases. + +However, for now, the more reliable way is using a `hie.yaml` file in the root +of the workspace to **explicitly** describe how to setup the environment. +For that you need to know what *components* have your project and the path +associated with each one. So you will need some knowledge about +[stack](https://docs.haskellstack.org/en/stable/build_command/#components) or [cabal](https://cabal.readthedocs.io/en/latest/cabal-commands.html?#cabal-v2-build) components. + +For example, to state that you want to use `stack` then the configuration file +would look like: + +```yaml +cradle: + stack: + component: "haskell-language-server:lib" +``` + +If you use `cabal` then you probably need to specify which component you want +to use. + +```yaml +cradle: + cabal: + component: "lib:haskell-language-server" +``` + +If you have a project with multiple components, you can use a cabal-multi +cradle: + +```yaml +cradle: + cabal: + - path: "./test/functional/" + component: "haskell-language-server:func-test" + - path: "./test/utils/" + component: "haskell-language-server:hls-test-utils" + - path: "./exe/Main.hs" + component: "haskell-language-server:exe:haskell-language-server" + - path: "./exe/Wrapper.hs" + component: "haskell-language-server:exe:haskell-language-server-wrapper" + - path: "./src" + component: "lib:haskell-language-server" + - path: "./ghcide/src" + component: "ghcide:lib:ghcide" + - path: "./ghcide/exe" + component: "ghcide:exe:ghcide" +``` + +Equivalently, you can use stack: + +```yaml +cradle: + stack: + - path: "./test/functional/" + component: "haskell-language-server:func-test" + - path: "./exe/Main.hs" + component: "haskell-language-server:exe:haskell-language-server" + - path: "./exe/Wrapper.hs" + component: "haskell-language-server:exe:haskell-language-server-wrapper" + - path: "./src" + component: "haskell-language-server:lib" + - path: "./ghcide/src" + component: "ghcide:lib:ghcide" + - path: "./ghcide/exe" + component: "ghcide:exe:ghcide" +``` + +You can get some help to extract what components have your project running + +```bash +stack ide targets +``` + +Or you can explicitly state the program which should be used to collect +the options by supplying the path to the program. It is interpreted +relative to the current working directory if it is not an absolute path. + +```yaml +cradle: + bios: + program: ".hie-bios" +``` + +The complete configuration is a subset of + +```yaml +cradle: + cabal: + component: "optional component name" + stack: + component: "optional component name" + bios: + program: "program to run" + dependency-program: "optional program to run" + direct: + arguments: ["list","of","ghc","arguments"] + default: + none: + +dependencies: + - someDep +``` + +## Contributing + +### It's time to join the project! + +:heart: Haskell tooling dream is near, we need your help! :heart: + +- Join [our IRC channel](https://webchat.freenode.net/?channels=haskell-ide-engine) at `#haskell-ide-engine` on `freenode`. +- Fork this repo and hack as much as you can. +- Ask @alanz or @hvr to join the project. + +### Hacking on haskell-language-server + +Haskell-language-server can be used on its own project. We have supplied +preset samples of `hie.yaml` files for stack and cabal, simply copy +the appropriate template to `hie.yaml` and it should work. + +- `hie.yaml.cbl` for cabal +- `hie.yaml.stack` for stack Two sample `hie.yaml` files are provided, `hie.yaml.stack` for stack usage, `hie.yaml.cbl` for cabal. Simply copy the relevant one to be From 7eca41ae5fecfec86b87d463b4fea4e63ff45849 Mon Sep 17 00:00:00 2001 From: jneira Date: Sat, 16 May 2020 16:54:08 +0200 Subject: [PATCH 2/4] Mention implicit-hie --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e85fddb121..814a7f5fb1 100644 --- a/README.md +++ b/README.md @@ -174,6 +174,10 @@ For that you need to know what *components* have your project and the path associated with each one. So you will need some knowledge about [stack](https://docs.haskellstack.org/en/stable/build_command/#components) or [cabal](https://cabal.readthedocs.io/en/latest/cabal-commands.html?#cabal-v2-build) components. +You also can use [this utility](https://github.com/Avi-D-coder/implicit-hie +) to generate automatically `hie.yaml` files for +the most common stack and cabal configurations + For example, to state that you want to use `stack` then the configuration file would look like: @@ -233,12 +237,6 @@ cradle: component: "ghcide:exe:ghcide" ``` -You can get some help to extract what components have your project running - -```bash -stack ide targets -``` - Or you can explicitly state the program which should be used to collect the options by supplying the path to the program. It is interpreted relative to the current working directory if it is not an absolute path. From 392a496e6412c0f460199021a338ea186becca8d Mon Sep 17 00:00:00 2001 From: jneira Date: Sat, 16 May 2020 22:49:14 +0200 Subject: [PATCH 3/4] Disable hoogle data files generation --- install/src/HlsInstall.hs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/install/src/HlsInstall.hs b/install/src/HlsInstall.hs index 3e25a39fc7..889a8fdff8 100644 --- a/install/src/HlsInstall.hs +++ b/install/src/HlsInstall.hs @@ -53,7 +53,8 @@ defaultMain = do need ["show-options"] need ["submodules"] need ["check"] - if isRunFromStack then stackBuildData args else cabalBuildData args + liftIO $ putStrLn "Generation of hoogle data files is disabled for now." + -- if isRunFromStack then stackBuildData args else cabalBuildData args forM_ versions From 1eba1b02f615089472653b1cc323f6ac5c1bf82a Mon Sep 17 00:00:00 2001 From: jneira Date: Sat, 16 May 2020 22:49:47 +0200 Subject: [PATCH 4/4] Add current dir to cabal-hls-install calls --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 814a7f5fb1..79726ef334 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ Note, that the targets `hls` and `data` depend on the found GHC versions. An example output is: ```bash -> cabal-hls-install ghcs +> ./cabal-hls-install ghcs ****************************************************************** Found the following GHC paths: ghc-8.6.5: /opt/bin/ghc-8.6.5 @@ -156,8 +156,8 @@ ghc-8.8.3: /opt/bin/ghc-8.8.3 If your desired ghc has been found, you use it to install haskell-language-server. ```bash -cabal-hls-install hls-8.6.5 -cabal-hls-install data +./cabal-hls-install hls-8.6.5 +./cabal-hls-install data ``` ## Project Configuration