From b70f93d8c09beccaf006a7a213749804a5d15944 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Thu, 30 Jun 2022 10:15:58 +0100 Subject: [PATCH 1/6] Add material about using versions of GHC that aren't supported yet --- docs/installation.md | 18 ++++++-- docs/supported-versions.md | 84 +++++++++++++++++++++++++------------- docs/troubleshooting.md | 6 +-- 3 files changed, 73 insertions(+), 35 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 12abc3aa23..a512a8862a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -25,18 +25,30 @@ You can check if HLS is available for your platorm via ghcup here: = 9.0.1. +Please see the [supported versions page](./supported-versions.md) for more information, including what to do if you need binaries for a version that is not yet supported by a HLS release. ### Missing server or build tools From ed71897feba838fffec55131c074450db51a7ca7 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Thu, 30 Jun 2022 10:16:21 +0100 Subject: [PATCH 2/6] Add a note about clearing out the build cache --- docs/troubleshooting.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a71668c626..d92da65f3f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -117,6 +117,13 @@ One strategy for diagnosing this is simply disable all plugins, check if the iss There is a configuration JSON snippet which disables all plugins [here](https://github.com/haskell/haskell-language-server/issues/2151#issuecomment-911397030). +### Clearing HLS's build cache + +HLS builds the dependencies of your project in a separate directory to avoid clashing with your normal build tools. +Sometimes clearing this out can help if you have persistent build problems. +The cache directory is at `$HOME/.cache/hie-bios`. +You may be able to identify a specific subdirectory that relates to your project, but it should always be safe to delete the whole thing, at worst it will cause HLS to redo build work next time it opens a project. + ## Diagnosing problems with the client The most important thing to do is to consult the client's documentation. From 6ef2c6be978548a228e436c05fbe6b52e9f56bad Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Thu, 30 Jun 2022 10:19:14 +0100 Subject: [PATCH 3/6] Add note about cabal update to ghcup instructions --- docs/installation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index a512a8862a..b474c60b49 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -21,11 +21,13 @@ If you are using [`ghcup`](https://www.haskell.org/ghcup/) to manage your instal ghcup install hls ``` -You can check if HLS is available for your platorm via ghcup here: . +You can check if HLS is available for your platform via ghcup here: . You can also install HLS from source without checking out the code manually: ```bash +# `ghcup compile` uses cabal under the hood to build, so you may want to run `cabal update` beforehand +cabal update ghcup compile hls -v $HLS_VERSION --ghc $GHC_VERSION ``` @@ -132,7 +134,7 @@ If you are using [`chocolatey`](https://chocolatey.org/) to manage your installa ```bash choco install haskell-language-server -```` +``` ## Visual Studio Code From 952ec0c853b490a9b9c3c46a0c5c159c53416bb7 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Thu, 30 Jun 2022 11:23:26 +0100 Subject: [PATCH 4/6] Minor improvements to installing doc --- docs/installation.md | 52 ++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index b474c60b49..ec2a66c1bf 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,17 +1,10 @@ # Installation -A typical haskell-language-server installation consists of: - -- One binary file for each supported ghc version: `haskell-language-server-${ghcVersion}` -- Another binary named `haskell-language-version-wrapper` which analyzes the project or file in the current working dir - and calls the appropiate `haskell-language-server-${ghcVersion}` variant. - - It accepts all executable arguments from the plain `haskell-language-server` - ## Prerequisites -- For standalone `.hs`/`.lhs` files, [ghc](https://www.haskell.org/ghc/) must be installed and on the PATH. The easiest way to install it is with [ghcup](https://www.haskell.org/ghcup/) or [chocolatey](https://community.chocolatey.org/packages/ghc) on Windows. -- For Cabal based projects, both ghc and [cabal-install](https://www.haskell.org/cabal/) must be installed and on the PATH. It can also be installed with [ghcup](https://www.haskell.org/ghcup/) or [chocolatey](https://community.chocolatey.org/packages/cabal) on Windows. -- For Stack based projects, [stack](http://haskellstack.org) must be installed and on the PATH. +- For standalone `.hs`/`.lhs` files, [ghc](https://www.haskell.org/ghc/) must be installed and on the `PATH`. The easiest way to install it is with [ghcup](https://www.haskell.org/ghcup/) or [chocolatey](https://community.chocolatey.org/packages/ghc) on Windows. +- For Cabal based projects, both ghc and [cabal-install](https://www.haskell.org/cabal/) must be installed and on the `PATH`. It can also be installed with [ghcup](https://www.haskell.org/ghcup/) or [chocolatey](https://community.chocolatey.org/packages/cabal) on Windows. +- For Stack based projects, [stack](http://haskellstack.org) must be installed and on the `PATH`. ## ghcup @@ -21,7 +14,7 @@ If you are using [`ghcup`](https://www.haskell.org/ghcup/) to manage your instal ghcup install hls ``` -You can check if HLS is available for your platform via ghcup here: . +You can check if HLS is available for your platform via `ghcup` here: . You can also install HLS from source without checking out the code manually: @@ -57,23 +50,23 @@ Check `ghcup compile hls --help` for a full list of compilation options. ## Installation from source -Direct installation from Source, while possible via `cabal install haskell-language-server` +Direct installation from source, while possible via `cabal install haskell-language-server` and `stack install --stack-yaml stack-.yaml`, is not recommended for most people. -Said command builds the `haskell-language-server` binary and installs it in the default Cabal binaries folder, +Said command builds the `haskell-language-server` binary and installs it in the default `cabal` binaries folder, but the binary will only work with projects that use the same GHC version that built it. ### 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 +- `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. + - 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. +then it means you have the command in `PATH`. ### Linux-specific pre-requirements @@ -101,15 +94,6 @@ sudo apt install libicu-dev libncurses-dev libgmp-dev zlib1g-dev sudo dnf install libicu-devel ncurses-devel zlib-devel ``` -**Gentoo** - -Haskell Language Server is available via the Haskell overlay. Follow the instructions [here](https://github.com/gentoo-haskell/gentoo-haskell) to install the overlay, then run: - -```bash -emerge -av dev-util/haskell-language-server -``` -Depending on your system setup, you may need to enable the unstable flag for this package before install, and possible also for the dependencies. If you enabled the ~testing versions as explained in the gentoo-haskell overlay instructions, then this won't be necessary. - ### Windows-specific pre-requirements In order to avoid problems with long paths on Windows you can do either one of the following: @@ -145,7 +129,7 @@ If you need to find the binaries, please consult the [documentation](https://git ## Pre-built binaries There are pre-built binaries available from the [releases page](https://github.com/haskell/haskell-language-server/releases) for Linux, Windows and macOS. -To install, download the `haskell-language-server-wrapper` executable for your platform as well as any `haskell-language-server` executables for the GHC versions you plan on working with, and either put them on your PATH or point your client to them. +To install, download the `haskell-language-server-wrapper` executable for your platform as well as any `haskell-language-server` executables for the GHC versions you plan on working with, and either put them on your `PATH` or point your client to them. ## Arch Linux @@ -157,6 +141,7 @@ See [ArchWiki](https://wiki.archlinux.org/index.php/Haskell) for the details of ## Fedora + Binary packages for Fedora are available from [this Copr repo](https://copr.fedorainfracloud.org/coprs/petersen/haskell-language-server), built against the official Fedora ghc package. @@ -171,6 +156,15 @@ pkg install hs-haskell-language-server to install it. At the moment, HLS installed this way only supports the same GHC version as the ports one. +## Gentoo + +Haskell Language Server is available via the Haskell overlay. Follow the instructions [here](https://github.com/gentoo-haskell/gentoo-haskell) to install the overlay, then run: + +```bash +emerge -av dev-util/haskell-language-server +``` +Depending on your system setup, you may need to enable the unstable flag for this package before install, and possible also for the dependencies. If you enabled the ~testing versions as explained in the gentoo-haskell overlay instructions, then this won't be necessary. + ## Installation from Hackage Direct installation from Hackage, while possible via `cabal install haskell-language-server`, is not recommended for most people. From 7de2ca5cacbaabc198b381de87953342f5be5d10 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Thu, 30 Jun 2022 17:43:56 +0100 Subject: [PATCH 5/6] Tweak ghcup docs more --- docs/installation.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index ec2a66c1bf..246e1f7883 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -26,24 +26,16 @@ ghcup compile hls -v $HLS_VERSION --ghc $GHC_VERSION For example: -Install HLS 1.6.1.0 for GHC 8.10.7: +Install HLS 1.7.0.0 for GHC 8.10.7, or for multiple GHC versions: ```bash -ghcup compile hls -v 1.6.1.0 --ghc 8.10.7 +ghcup compile hls -v 1.7.0.0 --ghc 8.10.7 +ghcup compile hls -v 1.7.0.0 --ghc 8.10.7 --ghc 9.2.1 ``` -Install HLS 1.7.0.0 for multiple GHC versions: -``` -ghcup compile hls -v 1.7.0.0 --ghc 8.10.7 --ghc 8.8.4 -``` - -Install HLS from master: +Install HLS from master, or a specific commit: ``` ghcup compile hls -g master --ghc 9.2.1 -``` - -Use a different `cabal.project` for a GHC version: -``` -ghcup compile hls -v 1.7.0.0 --ghc 9.2.1 --cabal-project cabal.project +ghcup compile hls -g 510bd51e46fea8fb51ddfaa60bba505f0663497d --ghc 9.2.1 ``` Check `ghcup compile hls --help` for a full list of compilation options. From 82cb638cc005ac88506e928c681ead6113e259f4 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Wed, 6 Jul 2022 21:46:35 +0100 Subject: [PATCH 6/6] Minor fixes --- docs/installation.md | 15 +++++++------ docs/supported-versions.md | 44 +++++++++++++++++++------------------- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 246e1f7883..e231fb9ee6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,27 +19,28 @@ You can check if HLS is available for your platform via `ghcup` here: