diff --git a/docs/installation.md b/docs/installation.md index 12abc3aa23..e231fb9ee6 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,45 +14,52 @@ 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 hls -v 1.6.1.0 --ghc 8.10.7 +# `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 ``` -Install HLS for multiple GHC versions: -``` -ghcup compile hls -v 1.6.1.0 --ghc 8.10.7 --ghc 8.8.4 +Make sure to check `ghcup compile hls --help` for more complete help. + +Examples: + +Install HLS 1.7.0.0 for GHC 8.10.7, or for multiple GHC versions: +```bash +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.3 ``` -Use a different `cabal.project` for a GHC version: +Install HLS from master, or a specific commit: ``` -ghcup compile hls -v 1.6.1.0 --ghc 9.2.1 --cabal-project cabal.project +ghcup compile hls -g master --ghc 9.2.3 +ghcup compile hls -g 510bd51e46fea8fb51ddfaa60bba505f0663497d --ghc 9.2.3 ``` -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 @@ -87,15 +87,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: @@ -120,7 +111,7 @@ If you are using [`chocolatey`](https://chocolatey.org/) to manage your installa ```bash choco install haskell-language-server -```` +``` ## Visual Studio Code @@ -131,7 +122,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 @@ -143,6 +134,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. @@ -157,6 +149,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. diff --git a/docs/supported-versions.md b/docs/supported-versions.md index 2140906abf..3948daeab1 100644 --- a/docs/supported-versions.md +++ b/docs/supported-versions.md @@ -4,40 +4,52 @@ The current support for different GHC versions is given in the following table. -| GHC version | Last supporting HLS version | Deprecation status | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -| 9.2.3 | [current](https://github.com/haskell/haskell-language-server/releases/latest) ([partial](https://github.com/haskell/haskell-language-server/issues/2982)) -| 9.2.2 | [current](https://github.com/haskell/haskell-language-server/releases/latest) ([partial](https://github.com/haskell/haskell-language-server/issues/2982)) -| 9.2.1 | [1.7.0.0](https://github.com/haskell/haskell-language-server/releases/tag/1.7.0.0) | deprecated | -| 9.0.2 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | | -| 9.0.1 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated | -| 8.10.7 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | | -| 8.10.6 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated | -| 8.10.5 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/tag/1.5.1) | deprecated | -| 8.10.4 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | -| 8.10.3 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | -| 8.10.2 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | -| 8.10.1 | [0.9.0](https://github.com/haskell/haskell-language-server/releases/tag/0.9.0) | deprecated | -| 8.8.4 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | will be deprecated after LTS and HLS full support for ghc-9.2 | -| 8.8.3 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/1.5.1) | deprecated | -| 8.8.2 | [1.2.0](https://github.com/haskell/haskell-language-server/releases/tag/1.2.0) | deprecated | -| 8.6.5 | [current](https://github.com/haskell/haskell-language-server/releases/latest) | will be deprecated after LTS and HLS full suppot for ghc-9.2 | -| 8.6.4 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | - -GHC versions not in the list have never been supported by HLS, or are not planned. LTS stands for [Stackage](https://www.stackage.org/) Long Term Support. +Last supporting HLS version: +- "next": this GHC version is supported in master, and will be in the next released version of HLS. +- "latest": this GHC version is one of the actively supported versions (see below) and is supported in the latest released version of HLS. +- specific version number: this GHC version is no longer one of the actively supported versions, and the last version of HLS which supports it is listed. + +Support status (see the support policy below for more details): +- "supported": this version of GHC is currently actively supported +- "deprecated": this version of GHC was supported in the past, but is now deprecated +- "will be deprecated ...": this version of GHC has special deprecation conditions that deviate from the support policy +- "partial": not all features and plugins work, see the plugin support table and any linked issues for more details + +| GHC version | Last supporting HLS version | Support status | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| 9.2.3 | next | supported, ([partial](https://github.com/haskell/haskell-language-server/issues/2982)) | +| 9.2.2 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | supported, ([partial](https://github.com/haskell/haskell-language-server/issues/2982)) | +| 9.2.1 | [1.7.0.0](https://github.com/haskell/haskell-language-server/releases/tag/1.7.0.0) | deprecated | +| 9.0.2 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | supported | +| 9.0.1 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated | +| 8.10.7 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | supported | +| 8.10.6 | [1.6.1.0](https://github.com/haskell/haskell-language-server/releases/tag/1.6.1.0) | deprecated | +| 8.10.5 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/tag/1.5.1) | deprecated | +| 8.10.4 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | +| 8.10.3 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | +| 8.10.2 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | +| 8.10.1 | [0.9.0](https://github.com/haskell/haskell-language-server/releases/tag/0.9.0) | deprecated | +| 8.8.4 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | will be deprecated after LTS and HLS full support for ghc-9.2 | +| 8.8.3 | [1.5.1](https://github.com/haskell/haskell-language-server/releases/1.5.1) | deprecated | +| 8.8.2 | [1.2.0](https://github.com/haskell/haskell-language-server/releases/tag/1.2.0) | deprecated | +| 8.6.5 | [latest](https://github.com/haskell/haskell-language-server/releases/latest) | will be deprecated after LTS and HLS full suppot for ghc-9.2 | +| 8.6.4 | [1.4.0](https://github.com/haskell/haskell-language-server/releases/tag/1.4.0) | deprecated | + + +GHC versions not in the list have never been supported by HLS. LTS stands for [Stackage](https://www.stackage.org/) Long Term Support. The policy for when we deprecate support for versions of GHC is given below. The table reflects that, but we may decide to deviate from it for good reasons. Additionally, some plugins do not have support for some GHC versions, as shown in the following table. As such, the functionality provided by those plugins is not available in HLS when using a GHC version which they do not support. -Sometimes a plugin will be supported in the prebuilt binaries but not in a HLS binary installed from Hackage. +Sometimes a plugin will be supported in the pre-built binaries but not in a HLS binary installed from Hackage. ### Plugins support by GHC version | Plugin | Unsupported GHC versions | |-------------------------------------|--------------------------| | `hls-alternate-number-plugin` | | -| `hls-brittany-plugin` | 9.2 | +| `hls-brittany-plugin` | 9.2 | | `hls-call-hierarchy-plugin` | | | `hls-class-plugin` | | | `hls-eval-plugin` | | @@ -66,11 +78,27 @@ In the future, we may extend the existing discovery mechanisms (`haskell-languag Users of a deprecated minor version (where the major version is still supported) can try building the latest HLS from source, which will likely still work, since the GHC API tends to remain compatible across minor versions. +### Using GHC versions not yet supported in a HLS release + +Some users may wish to use a version of GHC that is not yet supported by a released version of HLS. +In particular, this means that pre-built binaries will not be available for that GHC version. + +The easiest thing to do in this case is to build HLS from source yourself. +This can be done easily with `ghcup`, see the examples for `ghcup compile` on the [installation page](./installation.md). + +Generally, if a version of GHC is supported by HLS on master _or_ is a new minor version of a GHC version that is supported by HLS on master, then compiling from source is likely to work. +Major versions of GHC which are not supported by HLS on master are extremely unlikely to work. + ## GHC version deprecation policy ### Major versions -A major GHC version is a "legacy" version if it is 3 or more major versions behind the GHC version used in the newest Stackage LTS. +A major GHC version is a "legacy" version if it is 3 or more major versions behind the latest GHC version that is + +1. Fully supported by HLS +2. Used in the a Stackage LTS + +For example, if 9.2 is the latest major version fully supported by HLS and used in a Stackage LTS, then the 8.8 major version and older will be legacy. HLS will support all non-legacy major versions of GHC. @@ -86,15 +114,15 @@ We will warn users about the upcoming deprecation of a GHC version in the notes ### Why deprecate older versions of GHC? -`haskell-language-server`(HLS) is highly tied to the ghc api. This imposes a high maintenance cost: +`haskell-language-server`(HLS) is highly tied to the GHC API. This imposes a high maintenance cost: - The codebase is littered with conditional logic, -- We own auxiliary packages to support older versions of ghc. +- We own auxiliary packages to support older versions of GHC. - CI has to cover all the supported versions. -So we need to limit the ghc support to save maintainers and contributors time and reduce CI resources. +So we need to limit the GHC support to save maintainers and contributors time and reduce CI resources. -At same time we aim to support the right balance of ghc versions to minimize impact to final users. +At same time we aim to support the right balance of GHC versions to minimize impact to final users. ### What factors do we take into account when deprecating a version? diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 153f34275a..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. @@ -139,12 +146,10 @@ Normally, we ship binaries for multiple versions and `haskell-language-server-wr If you see an error about HLS being compiled with the wrong version of GHC, then you either need to install the correct one (if you installed it yourself), or there is something going wrong with the wrapper selecting the right HLS binary to launch. -### Unsupported GHC version +### Unsupported GHC version or missing binaries HLS does not support every GHC version - there are a lot of them! -Please see the [supported versions page](./supported-versions.md) for more information. - -In particular, support for GHC 9.0 and 9.2 is only partial; some features are unavailable with GHC >= 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