Skip to content

Improve troubleshooting and installation docs a bit #3004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 6, 2022
Merged

Improve troubleshooting and installation docs a bit #3004

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b70f93d
Add material about using versions of GHC that aren't supported yet
michaelpj Jun 30, 2022
ed71897
Add a note about clearing out the build cache
michaelpj Jun 30, 2022
6ef2c6b
Add note about cabal update to ghcup instructions
michaelpj Jun 30, 2022
952ec0c
Minor improvements to installing doc
michaelpj Jun 30, 2022
7de2ca5
Tweak ghcup docs more
michaelpj Jun 30, 2022
82cb638
Minor fixes
michaelpj Jul 6, 2022
5d763d5
Merge branch 'master' into mpj/no-binaries-for-my-ghc
mergify[bot] Jul 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 39 additions & 38 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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: <https://haskell.org/ghcup/install/#supported-platforms>.
You can check if HLS is available for your platform via `ghcup` here: <https://haskell.org/ghcup/install/#supported-platforms>.

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-<GHCVER>.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.
Copy link
Contributor

@sloorush sloorush Jun 30, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we somehow highlight this line a little?

I personally had missed this while skimming through the docs and realized it later on. I think adding it as a note maybe can highlight the point.

Edit: This as in:

the binary will only work with projects that use the same GHC version that built it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section shouldn't be emphasized anyway and there is a section about this on the troubleshooting page already (which hopefully people actually read...).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally there is a lot of stuff in the installation doc, and I wonder if it could be organized better 🤔


### 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

Expand Down Expand Up @@ -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:
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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.
Expand Down
Loading