mirror of
https://github.com/haskell/haskell-language-server.git
synced 2024-09-11 08:45:35 +03:00
Add initial sphinx doc site (#2083)
This commit is contained in:
parent
b8b962018c
commit
1ba88ab9ec
9
.readthedocs.yaml
Normal file
9
.readthedocs.yaml
Normal file
@ -0,0 +1,9 @@
|
||||
version: 2
|
||||
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
|
||||
python:
|
||||
version: 3.8
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
861
README.md
861
README.md
@ -19,863 +19,4 @@
|
||||
[badge-codetriage]: https://www.codetriage.com/haskell/haskell-language-server/badges/users.svg
|
||||
[codetriage]:https://www.codetriage.com/haskell/haskell-language-server
|
||||
|
||||
Integration point for [ghcide](https://github.com/haskell/ghcide) and [haskell-ide-engine](https://github.com/haskell/haskell-ide-engine). One IDE to rule
|
||||
them all. Read the [project's
|
||||
background](https://neilmitchell.blogspot.com/2020/01/one-haskell-ide-to-rule-them-all.html).
|
||||
|
||||
- [haskell-language-server](#haskell-language-server)
|
||||
- [Features](#features)
|
||||
- [Installation](#installation)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [ghcup](#ghcup)
|
||||
- [Visual Studio Code](#visual-studio-code)
|
||||
- [Pre-built binaries](#pre-built-binaries)
|
||||
- [Arch Linux](#arch-linux)
|
||||
- [FreeBSD](#freebsd)
|
||||
- [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)
|
||||
- [Installation from Hackage](#installation-from-hackage)
|
||||
- [Installation via Homebrew](#installation-via-homebrew)
|
||||
- [Configuring `haskell-language-server`](#configuring-haskell-language-server)
|
||||
- [Generic server options](#generic-server-options)
|
||||
- [Generic editor options](#generic-editor-options)
|
||||
- [Language-specific server options](#language-specific-server-options)
|
||||
- [Client options](#client-options)
|
||||
- [Configuring your project build](#configuring-your-project-build)
|
||||
- [Configuring your editor](#configuring-your-editor)
|
||||
- [VS Code](#vs-code)
|
||||
- [Sublime Text](#sublime-text)
|
||||
- [Vim or Neovim](#vim-or-neovim)
|
||||
- [Coc](#coc)
|
||||
- [LanguageClient-neovim](#languageclient-neovim)
|
||||
- [vim-plug](#vim-plug)
|
||||
- [Clone the LanguageClient-neovim repo](#clone-the-languageclient-neovim-repo)
|
||||
- [Configuration and sample `~/.vimrc` sections](#configuration-and-sample-vimrc-sections)
|
||||
- [Atom](#atom)
|
||||
- [Emacs](#emacs)
|
||||
- [doom-emacs](#doom-emacs)
|
||||
- [Spacemacs](#spacemacs)
|
||||
- [Kakoune](#kakoune)
|
||||
- [Known limitations](#known-limitations)
|
||||
- [Preprocessor](#preprocessor)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Common issues](#common-issues)
|
||||
- [Difficulties with Stack and `Paths_` modules](#difficulties-with-stack-and-paths_-modules)
|
||||
- [Problems with dynamic linking](#problems-with-dynamic-linking)
|
||||
- [Troubleshooting the server](#troubleshooting-the-server)
|
||||
- [Diagnostic mode](#diagnostic-mode)
|
||||
- [Examining the log](#examining-the-log)
|
||||
- [Troubleshooting the client](#troubleshooting-the-client)
|
||||
- [Contributing](#contributing)
|
||||
- [Style guidelines](#style-guidelines)
|
||||
- [Building haskell-language-server](#building-haskell-language-server)
|
||||
- [Using Cabal](#using-cabal)
|
||||
- [Using Stack](#using-stack)
|
||||
- [Using Nix](#using-nix)
|
||||
- [Flakes support](#flakes-support)
|
||||
- [Introduction tutorial](#introduction-tutorial)
|
||||
- [Test your hacked HLS in your editor](#test-your-hacked-hls-in-your-editor)
|
||||
- [Adding support for a new editor](#adding-support-for-a-new-editor)
|
||||
|
||||
## Features
|
||||
|
||||
- Code evaluation codelens ([Tutorial](plugins/hls-eval-plugin/README.md)):
|
||||
|
||||
![Eval Demo](plugins/hls-eval-plugin/demo.gif)
|
||||
|
||||
- Type information and documentation on hover. Note that currently, in order for docs to be displayed for dependencies, they must have been built with GHC's `-haddock` flag:
|
||||
|
||||
- For cabal:
|
||||
- Add to your global config file (e.g. `~/.cabal/config`):
|
||||
|
||||
```cabal
|
||||
program-default-options
|
||||
ghc-options: -haddock
|
||||
```
|
||||
|
||||
- Or, for a single project, run `cabal configure --ghc-options=-haddock`
|
||||
|
||||
- For stack, add to global `$STACK_ROOT\config.yaml`, or project's `stack.yaml`:
|
||||
|
||||
```cabal
|
||||
ghc-options:
|
||||
"$everything": -haddock
|
||||
```
|
||||
|
||||
This will cause compilation errors if a dependency contains invalid Haddock markup, though from GHC version 9.0, [these will be demoted to warnings](https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377).
|
||||
|
||||
- Integration with [retrie](https://hackage.haskell.org/package/retrie)
|
||||
|
||||
![Retrie](https://i.imgur.com/Ev7B87k.gif)
|
||||
|
||||
- Code lenses for explicit import lists
|
||||
|
||||
![Imports code lens](https://imgur.com/pX9kvY4.gif)
|
||||
|
||||
- Many more (TBD)
|
||||
|
||||
## Installation
|
||||
|
||||
### 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.
|
||||
|
||||
### ghcup
|
||||
|
||||
If you are using [`ghcup`](https://www.haskell.org/ghcup/) to manage your installations, you can install `haskell-language-server` with
|
||||
```
|
||||
ghcup install hls
|
||||
```
|
||||
|
||||
### chocolatey
|
||||
|
||||
If you are using [`chocolatey`](https://chocolatey.org/) to manage your installations in windows, [you can install `haskell-language-server`](https://community.chocolatey.org/packages/haskell-language-server) with
|
||||
```
|
||||
choco install haskell-language-server
|
||||
````
|
||||
|
||||
### Visual Studio Code
|
||||
|
||||
If you are using Visual Studio Code, the [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) will automatically download and install `haskell-language-server` for you.
|
||||
|
||||
### 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.
|
||||
|
||||
### Arch Linux
|
||||
|
||||
The preferred method of installation for development purposes is to use the [haskell-language-server-bin](https://aur.archlinux.org/packages/haskell-language-server-bin) package from AUR.
|
||||
This package contains statically linked binaries for each supported GHC version and `haskell-language-server-wrapper` for automatic GHC version selection.
|
||||
It is updated regularly, requires no additional dependencies, and is independent of other haskell packages you may have on your system, including GHC.
|
||||
Its size is relatively large (approx. 900 MB), but if this is a problem for you, during installation you can disable the GHC versions you will not be using by editing the PKGBUILD file.
|
||||
|
||||
Alternatively, if you want to use **dynamically linked** Haskell packages from `pacman`,
|
||||
you can install the latest pre-compiled version of `haskell-language-server` from [[community]](https://archlinux.org/packages/community/x86_64/haskell-language-server/):
|
||||
|
||||
```
|
||||
sudo pacman -S haskell-language-server
|
||||
```
|
||||
|
||||
In this case, `haskell-language-server` is compiled against the GHC distributed to Arch Linux, so you will need maintain a system wide Haskell development environment, and install GHC from `pacman` as well.
|
||||
See [ArchWiki](https://wiki.archlinux.org/index.php/Haskell) for the details of Haskell infrastructure on Arch Linux.
|
||||
|
||||
### FreeBSD
|
||||
|
||||
HLS is available for installation from official binary packages. Use
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
### 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:
|
||||
|
||||
- [Unicode (ICU)](http://site.icu-project.org/)
|
||||
- [NCURSES](https://www.gnu.org/software/ncurses/)
|
||||
- [Zlib](https://zlib.net/)
|
||||
|
||||
**Debian 9/Ubuntu 18.04 or earlier**:
|
||||
|
||||
```bash
|
||||
sudo apt install libicu-dev libtinfo-dev libgmp-dev zlib1g-dev
|
||||
```
|
||||
|
||||
**Debian 10/Ubuntu 18.10 or later**:
|
||||
|
||||
```bash
|
||||
sudo apt install libicu-dev libncurses-dev libgmp-dev zlib1g-dev
|
||||
```
|
||||
|
||||
**Fedora**:
|
||||
|
||||
```bash
|
||||
sudo dnf install libicu-devel ncurses-devel zlib-devel
|
||||
```
|
||||
|
||||
#### 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/stack.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 <target>
|
||||
```
|
||||
|
||||
or using the existing alias script
|
||||
|
||||
```bash
|
||||
./cabal-hls-install <target>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
The script will install the executables `haskell-language-server-wrapper` and `haskell-language-server`.
|
||||
|
||||
It will copy the latter appending the used ghc version, needed by the wrapper to choose the suitable version
|
||||
for the project at hand.
|
||||
|
||||
So installing the executables directly with `stack install` or `cabal v2-install` may not be enough
|
||||
for it to work properly.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
`hls-8.8.3` target will build the project and install `haskell-language-server-wrapper`,
|
||||
`haskell-language-server`, `haskell-language-server-8.8.3` and `haskell-language-server-8.8`
|
||||
executables.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### Installation from Hackage
|
||||
|
||||
Direct installation from Hackage, while possible via `cabal install haskell-language-server`, is not recommended for most people.
|
||||
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.
|
||||
|
||||
The package can be found here on Hackage: <https://hackage.haskell.org/package/haskell-language-server>
|
||||
|
||||
### Installation via Homebrew
|
||||
|
||||
Homebrew users can install `haskell-language-server` using the following command:
|
||||
|
||||
```bash
|
||||
brew install haskell-language-server
|
||||
```
|
||||
|
||||
This formula contains HLS binaries compiled with GHC versions available via Homebrew; at the moment those are: 8.6.5, 8.8.4, 8.10.4.
|
||||
|
||||
You need to provide your own GHC/Cabal/Stack as required by your project, possibly via Homebrew.
|
||||
|
||||
## Configuring `haskell-language-server`
|
||||
|
||||
Language servers like `haskell-language-server` expose most of their configuration via the client (i.e. the editor).
|
||||
That means that the way in which you configure the settings will depend on the client.
|
||||
|
||||
Most clients (editors) already have an opinion about how settings should be configured!
|
||||
For example, in VS Code you use the graphical Settings tab or `settings.json`, whereas in Emacs you use customization variables.
|
||||
In the [editor configuration section](#configuring-your-editor) we give some pointers for popular editors, but you should consult the documentation for your specific editor if you have trouble.
|
||||
|
||||
However, we can say some high-level things about the kinds of configuration `haskell-language-server` uses, and how to use them.
|
||||
This can sound a bit confusing, but ultimately the client should present you with these options in a user-friendly way that makes sense for that editor.
|
||||
|
||||
### Generic server options
|
||||
|
||||
The LSP protocol is designed to support many useful server configuration options generically.
|
||||
These are sent to the server by the client, and can be controlled without reference to a specific language.
|
||||
|
||||
For example, there are protocol methods for highlighting matching identifiers throughout a document.
|
||||
This is a capability which any server can implement, so the client can decide generically whether to ask the server to do it or not.
|
||||
So your editor can provide a setting to turn this on or off globally, for any language server you might use.
|
||||
|
||||
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by `lsp-mode`.
|
||||
|
||||
### Generic editor options
|
||||
|
||||
Your editor may provide some settings that affect how the information from the language server is used.
|
||||
For example, whether popups are shown, or whether code lenses appear by default.
|
||||
|
||||
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by `lsp-mode`.
|
||||
|
||||
### Language-specific server options
|
||||
|
||||
A specific language server can also have its own configuration options.
|
||||
These are still sent to the server by the client, but they can only be controlled by a specific client that knows about those options.
|
||||
|
||||
For example, `haskell-language-server` allows you to choose the formatting provider which will be used for formatting Haskell source.
|
||||
This option obviously would not make sense for language servers for other languages, or even for other Haskell language servers (which need not even support formatting).
|
||||
|
||||
Here is a list of the additional settings currently supported by `haskell-language-server`, along with their setting key (you may not need to know this) and default:
|
||||
|
||||
- Formatting provider (`haskell.formattingProvider`, default `ormolu`): what formatter to use; one of `floskell`, `ormolu`, `fourmolu`, `stylish-haskell`, or `brittany` (if compiled with the brittany plugin)
|
||||
- Format on imports (`haskell.formatOnImportOn`, default true): whether to format after adding an import
|
||||
- Diagnostics on change (`haskell.diagnosticsOnChange`, default true): (currently unused)
|
||||
- Completion snippets (`haskell.completionSnippetsOn`, default true): whether to support completion snippets
|
||||
- Liquid Haskell (`haskell.liquidOn`, default false): whether to enable Liquid Haskell support (currently unused until the Liquid Haskell support is functional again)
|
||||
- Hlint (`haskell.hlintOn`, default true): whether to enable Hlint support
|
||||
- Max completions (`haskell.maxCompletions`, default 40): maximum number of completions sent to the LSP client.
|
||||
|
||||
Settings like this are typically provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
|
||||
|
||||
### Client options
|
||||
|
||||
A particular client might also have some options of its own, for example to control how the server executable is started.
|
||||
|
||||
Settings like this are typically be provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
|
||||
|
||||
## Configuring your project build
|
||||
|
||||
`haskell-language-server` has to compile your project in order to give you diagnostics, which means that it needs to know how to do so.
|
||||
This is handled by the [`hie-bios`](https://github.com/mpickering/hie-bios) project.
|
||||
|
||||
**For a full explanation of how `hie-bios` determines the project build configuration, and how to configure it manually, refer to the [`hie-bios` README](https://github.com/mpickering/hie-bios/blob/master/README.md).**
|
||||
|
||||
At the moment, `haskell-language-server` has some limited support to automatically detect your project build configuration.
|
||||
The plan is to improve it to handle most use cases.
|
||||
|
||||
However, for now, the most reliable way is to manually configure `hie-bios` using a `hie.yaml` file in the root of the workspace.
|
||||
A `hie.yaml` file **explicitly** describes how to setup the environment to compile the various parts of your project.
|
||||
For that you need to know what *components* your project has, 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 automatically generate `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:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Configuring your editor
|
||||
|
||||
Most editors provide a Haskell-specific extension that provides support for launching `haskell-language-server` and talking to it, as well as [exposing configuration options](#configuring-haskell-language-server).
|
||||
|
||||
Editors typically assume that you have already installed `haskell-language-server` (see above) and that the installation script put the `haskell-language-server` and `haskell-language-server-wrapper` binaries in your `PATH` (usually `~/.local/bin` or `~/.cabal/bin` on Linux and macOS, `%APPDATA%\local\bin` or `%APPDATA%\cabal\bin` on Windows).
|
||||
The exception is VS Code, which can automatically install the binaries if they are not installed already.
|
||||
|
||||
### VS Code
|
||||
|
||||
Install from
|
||||
[the VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=haskell.haskell), or manually from the repository [vscode-haskell](https://github.com/haskell/vscode-haskell).
|
||||
The `haskell-language-server` and `haskell-language-server-wrapper` binaries will be automatically downloaded on an ad-hoc basis, but if you have them already installed on your PATH then it will just use them instead.
|
||||
|
||||
Configuration is done via the "Haskell" section of "Settings".
|
||||
|
||||
### Sublime Text
|
||||
|
||||
- Install [LSP](https://packagecontrol.io/packages/LSP) using [Package Control](https://packagecontrol.io/)
|
||||
- From Sublime Text, go to Preferences and search for LSP Settings
|
||||
- Paste in these settings. Make sure to change the command path to your `haskell-language-server-wrapper`
|
||||
|
||||
```json
|
||||
{
|
||||
"clients": {
|
||||
"haskell-language-server": {
|
||||
"command": ["haskell-language-server-wrapper", "--lsp"],
|
||||
"scopes": ["source.haskell"],
|
||||
"syntaxes": ["Packages/Haskell/Haskell.sublime-syntax"],
|
||||
"languageId": "haskell"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now open a Haskell project with Sublime Text and enable Language Server in the project.
|
||||
You should have these features available:
|
||||
|
||||
1. Errors are underlined in red
|
||||
2. LSP: Show Diagnostics will show a list of hints and errors
|
||||
3. LSP: Format Document will prettify the file
|
||||
|
||||
### Vim or Neovim
|
||||
|
||||
You can use [Coc](https://github.com/neoclide/coc.nvim), [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
|
||||
or any other Vim Language server protocol client.
|
||||
Coc is recommend since it is the only complete LSP implementation for Vim and Neovim and offers snippets and floating documentation out of the box.
|
||||
|
||||
#### Coc
|
||||
|
||||
Follow Coc's [installation instructions](https://github.com/neoclide/coc.nvim).
|
||||
Then issue `:CocConfig` and add the following to your Coc config file.
|
||||
|
||||
```json
|
||||
{
|
||||
"languageserver": {
|
||||
"haskell": {
|
||||
"command": "haskell-language-server-wrapper",
|
||||
"args": ["--lsp"],
|
||||
"rootPatterns": ["*.cabal", "stack.yaml", "cabal.project", "package.yaml", "hie.yaml"],
|
||||
"filetypes": ["haskell", "lhaskell"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### LanguageClient-neovim
|
||||
|
||||
##### vim-plug
|
||||
|
||||
If you use [vim-plug](https://github.com/junegunn/vim-plug), then you can do this by e.g.,
|
||||
including the following line in the Plug section of your `init.vim` or `~/.vimrc`:
|
||||
|
||||
```text
|
||||
Plug 'autozimu/LanguageClient-neovim', {
|
||||
\ 'branch': 'next',
|
||||
\ 'do': 'bash install.sh'
|
||||
\ }
|
||||
```
|
||||
|
||||
and issuing a `:PlugInstall` command within Neovim or Vim.
|
||||
|
||||
##### Clone the LanguageClient-neovim repo
|
||||
|
||||
As an alternative to using [vim-plug](https://github.com/junegunn/vim-plug) shown above, clone [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
|
||||
into `~/.vim/pack/XXX/start/`, where `XXX` is just a name for your "plugin suite".
|
||||
|
||||
##### Configuration and sample `~/.vimrc` sections
|
||||
|
||||
```vim
|
||||
set rtp+=~/.vim/pack/XXX/start/LanguageClient-neovim
|
||||
let g:LanguageClient_serverCommands = { 'haskell': ['haskell-language-server-wrapper', '--lsp'] }
|
||||
```
|
||||
|
||||
You'll probably want to add some mappings for common commands:
|
||||
|
||||
```vim
|
||||
nnoremap <F5> :call LanguageClient_contextMenu()<CR>
|
||||
map <Leader>lk :call LanguageClient#textDocument_hover()<CR>
|
||||
map <Leader>lg :call LanguageClient#textDocument_definition()<CR>
|
||||
map <Leader>lr :call LanguageClient#textDocument_rename()<CR>
|
||||
map <Leader>lf :call LanguageClient#textDocument_formatting()<CR>
|
||||
map <Leader>lb :call LanguageClient#textDocument_references()<CR>
|
||||
map <Leader>la :call LanguageClient#textDocument_codeAction()<CR>
|
||||
map <Leader>ls :call LanguageClient#textDocument_documentSymbol()<CR>
|
||||
```
|
||||
|
||||
Use <kbd>Ctrl+x</kbd><kbd>Ctrl+o</kbd> (`<C-x><C-o>`) to open up the auto-complete menu,
|
||||
or for asynchronous auto-completion, follow the setup instructions on
|
||||
[LanguageClient](https://github.com/autozimu/LanguageClient-neovim).
|
||||
|
||||
If you'd like diagnostics to be highlighted, add a highlight group for `ALEError`/`ALEWarning`/`ALEInfo`,
|
||||
or customize `g:LanguageClient_diagnosticsDisplay`:
|
||||
|
||||
```vim
|
||||
hi link ALEError Error
|
||||
hi Warning term=underline cterm=underline ctermfg=Yellow gui=undercurl guisp=Gold
|
||||
hi link ALEWarning Warning
|
||||
hi link ALEInfo SpellCap
|
||||
```
|
||||
|
||||
If you're finding that the server isn't starting at the correct project root,
|
||||
it may also be helpful to also specify root markers:
|
||||
|
||||
```vim
|
||||
let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']
|
||||
```
|
||||
|
||||
Further configuration can be done by pointing the [`g:LanguageClient_settingsPath`](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
|
||||
variable to the file in which you want to keep your LSP settings.
|
||||
|
||||
### Atom
|
||||
|
||||
Install the two Atom packages [atom-ide-ui](https://atom.io/packages/atom-ide-ui) and [haskell](https://atom.io/packages/haskell),
|
||||
|
||||
```bash
|
||||
$ apm install language-haskell atom-ide-ui haskell
|
||||
```
|
||||
|
||||
### Emacs
|
||||
|
||||
Emacs support is provided by a combination of the following packages:
|
||||
|
||||
[lsp-mode](https://github.com/emacs-lsp/lsp-mode)
|
||||
[lsp-ui](https://github.com/emacs-lsp/lsp-ui)
|
||||
[lsp-haskell](https://github.com/emacs-lsp/lsp-haskell)
|
||||
|
||||
You can install these manually if you are using plain Emacs; instructions for some specific flavours
|
||||
are included below.
|
||||
|
||||
Make sure to check the READMEs of each of these packages, which explain how to configure the
|
||||
various parts of the Emacs integration.
|
||||
In particular, `lsp-haskell` provides customization options for the `haskell-language-server`-specific parts,
|
||||
such as the path to the server executable.
|
||||
|
||||
#### [doom-emacs](https://github.com/hlissner/doom-emacs/tree/develop/modules/lang/haskell#module-flags)
|
||||
|
||||
Manual installation of packages is not required.
|
||||
Enable the lsp module and the haskell lang module with lsp flag in `.doom.d/init.el`:
|
||||
|
||||
``` emacs-lisp
|
||||
:tools
|
||||
lsp
|
||||
;; ...
|
||||
:lang
|
||||
(haskell +lsp)
|
||||
```
|
||||
|
||||
then do `$HOME/.emacs.d/bin/doom sync`
|
||||
|
||||
#### [Spacemacs](https://github.com/syl20bnr/spacemacs)
|
||||
|
||||
Manual installation of packages is not required.
|
||||
Enable the `haskell` layer and the `lsp` layer in your Spacemacs config file:
|
||||
|
||||
```emacs-lisp
|
||||
dotspacemacs-configuration-layers
|
||||
'(
|
||||
haskell
|
||||
lsp
|
||||
;; ...
|
||||
)
|
||||
```
|
||||
|
||||
### [Kakoune](https://github.com/mawww/kakoune)
|
||||
|
||||
1. Grab a copy of [kak-lsp](https://github.com/ul/kak-lsp), and follow the setup instructions.
|
||||
2. Point your `kak-lsp.toml` to `haskell-language-server-wrapper`.
|
||||
|
||||
```toml
|
||||
[language.haskell]
|
||||
filetypes = ["haskell"]
|
||||
roots = ["Setup.hs", "stack.yaml", "*.cabal"]
|
||||
command = "haskell-language-server-wrapper"
|
||||
args = ["--lsp"]
|
||||
```
|
||||
|
||||
## Known limitations
|
||||
|
||||
### Limited GHC 9 Support
|
||||
Currently, GHC 9 support in HLS is in beta stage; some features are unavailable with GHC >= 9.0.1 for the time being.
|
||||
This situation is expected to be resolved in the near future after all the dependent packages support GHC 9.
|
||||
See issue [#297](https://github.com/haskell/haskell-language-server/issues/297) for the supported features in GHC 9 and the status of migration progress.
|
||||
|
||||
### Preprocessor
|
||||
HLS is not yet able to find project preprocessors, which may result in `could not execute: <preprocessor>` errors. This problem is
|
||||
tracked in https://github.com/haskell/haskell-language-server/issues/176 and originally comes from https://github.com/mpickering/hie-bios/issues/125
|
||||
|
||||
As a workaround, you need to ensure the preprocessor is available in the path (install globally with Stack or Cabal, provide in `shell.nix`, etc.).
|
||||
|
||||
Example with `tasty-discover`:
|
||||
|
||||
```haskell
|
||||
{-# OPTIONS_GHC -F -pgmF tasty-discover #-}
|
||||
```
|
||||
|
||||
This returns an error in HLS if 'tasty-discover' is not in the path: `could not execute: tasty-discover`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common issues
|
||||
|
||||
#### Difficulties with Stack and `Paths_` modules
|
||||
|
||||
These are known to be somewhat buggy at the moment: <https://github.com/haskell/haskell-language-server/issues/478>.
|
||||
This issue should be fixed in Stack versions >= 2.5.
|
||||
|
||||
#### Problems with dynamic linking
|
||||
|
||||
As haskell-language-server prebuilt binaries are statically linked, they don't play well with projects using dynamic linking.
|
||||
An usual symptom is the presence of errors containing `unknown symbol` and it is typical in arch linux, where a dynamically linked version of ghc is used.
|
||||
|
||||
The workaround is to use a version of haskell-language-server compiled from source with `-dynamic` enabled`. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273).
|
||||
|
||||
### Troubleshooting the server
|
||||
|
||||
#### Diagnostic mode
|
||||
|
||||
The `haskell-language-server` executable can be run in diagnostic mode, where it will just try to load modules from your project, printing all of its output to stdout.
|
||||
This makes it much easier to see what's going on and to diagnose build-related problems.
|
||||
|
||||
To do this, simply run the executable directly from your shell in the project root.
|
||||
You can either run it without an argument, in which case it will load random modules, or with a path, in which case it will load modules in that file or directory.
|
||||
|
||||
#### Examining the log
|
||||
|
||||
Most clients will launch `haskell-language-server` with `--logfile` to make it write a log file.
|
||||
Please consult the documentation for your client to find out where this is (or how to set it).
|
||||
|
||||
The log will contain all the messages that are sent to the server and its responses.
|
||||
This is helpful for low-level debugging: if you expect a certain action to happen, you can look in the log to see if the corresponding messages are
|
||||
sent, or if there are any errors.
|
||||
|
||||
To get a more verbose, also pass `--debug` to the executable.
|
||||
|
||||
### Troubleshooting the client
|
||||
|
||||
Many clients provide diagnostic information about a LSP session.
|
||||
In particular, look for a way to get the status of the server, the server stderr, or a log of the messages that the client has sent to the server.
|
||||
For example, `lsp-mode` provides all of these (see its [troubleshooting page](https://emacs-lsp.github.io/lsp-mode/page/troubleshooting/) for details).
|
||||
|
||||
The most common client-related problem is the client simply not finding the server executable, so make sure that you have the right `PATH` and you have configured
|
||||
it to look for the right executable.
|
||||
|
||||
## Contributing
|
||||
|
||||
:heart: The Haskell tooling dream is near, we need your help! :heart:
|
||||
|
||||
- Join [our IRC channel](https://web.libera.chat/?channels=#haskell-language-server) at `#haskell-language-server` on [`libera`](https://libera.chat/).
|
||||
- Follow the [Haskell IDE team twitter account](https://twitter.com/IdeHaskell) for updates and help.
|
||||
- Join the [#haskell-tooling channel](https://discord.com/channels/280033776820813825/505370075402862594/808027763868827659) in the Functional Programming discord server. You can join the server via [this invitation](https://discord.gg/9spEdTNGrD).
|
||||
|
||||
### Style guidelines
|
||||
|
||||
The project includes a [`.editorconfig`](https://editorconfig.org) [file](https://github.com/haskell/haskell-language-server/blob/master/.editorconfig) with the editor basic settings used by the project.
|
||||
However, most editors will need some action to honour those settings automatically.
|
||||
For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig).
|
||||
Please, try to follow those basic settings to keep the codebase as uniform as possible.
|
||||
|
||||
### Building haskell-language-server
|
||||
|
||||
The project can be built with both `cabal build` and `stack build`.
|
||||
|
||||
haskell-language-server can also be used with itself. We provide preset samples of `hie.yaml` for Cabal and Stack.
|
||||
|
||||
Note: the `./install/` folder is not directly tied to the project so it has dedicated `./install/hie.yaml.[cbl|stack]`
|
||||
templates.
|
||||
|
||||
#### Using Cabal
|
||||
|
||||
```shell
|
||||
$ cp hie-cabal.yaml hie.yaml
|
||||
$ cp install/hie-cabal.yaml install/hie.yaml
|
||||
```
|
||||
|
||||
#### Using Stack
|
||||
|
||||
```shell
|
||||
$ cp hie-stack.yaml hie.yaml
|
||||
$ cp install/hie-stack.yaml install/hie.yaml
|
||||
$ cp ghcide/hie-stack.yaml ghcide/hie.yaml
|
||||
$ stack build --test --no-run-tests
|
||||
$ cd install
|
||||
$ stack build
|
||||
```
|
||||
|
||||
#### Using Nix
|
||||
|
||||
The instructions below show how to set up a Cachix binary cache and open a nix shell for local development.
|
||||
|
||||
```shell
|
||||
$ cachix use haskell-language-server
|
||||
$ nix-shell
|
||||
$ cabal update
|
||||
$ cabal build
|
||||
```
|
||||
|
||||
##### Flakes support
|
||||
|
||||
If you are using nix 2.4 style command (enabled by `experimental-features = nix-command`),
|
||||
you can use `nix develop` instead of `nix-shell` to enter the development shell. To enter the shell with specific GHC versions:
|
||||
|
||||
* `nix develop` or `nix develop .#haskell-language-server-dev` - default GHC version
|
||||
* `nix develop .#haskell-language-server-8104-dev` - GHC 8.10.4
|
||||
* `nix develop .#haskell-language-server-884-dev` - GHC 8.8.4
|
||||
* `nix develop .#haskell-language-server-901-dev` - GHC 9.0.1
|
||||
|
||||
If you are looking for a Nix expression to create haskell-language-server binaries, see https://github.com/haskell/haskell-language-server/issues/122
|
||||
|
||||
To create binaries:
|
||||
|
||||
* `nix build` or `nix build .#haskell-language-server` - default GHC version
|
||||
* `nix build .#haskell-language-server-8104` - GHC 8.10.4
|
||||
* `nix build .#haskell-language-server-884` - GHC 8.8.4
|
||||
* `nix build .#haskell-language-server-901` - GHC 9.0.1
|
||||
|
||||
GHC 8.6.5 is not supported here because `nixpkgs-unstable` no longer maintains the corresponding packages set.
|
||||
|
||||
#### Introduction tutorial
|
||||
|
||||
Pepeiborra [wrote an tutorial](https://github.com/pepeiborra/hls-tutorial) on writing a plugin in HLS.
|
||||
|
||||
#### Test your hacked HLS in your editor
|
||||
|
||||
If you want to test HLS while hacking on it, follow the steps below.
|
||||
|
||||
To do once:
|
||||
|
||||
- Open some codebase on which you want to test your hacked HLS in your favorite editor
|
||||
- Configure this editor to use your custom HLS executable
|
||||
- With Cabal:
|
||||
- On Unix systems: `cabal exec which haskell-language-server`
|
||||
- On Windows: `cabal exec where haskell-language-server`
|
||||
- With Stack: `$(stack path --dist-dir)/build/haskell-language-server/haskell-language-server`
|
||||
|
||||
To do every time you changed code and want to test it:
|
||||
|
||||
- Build HLS
|
||||
- With Cabal: `cabal build exe:haskell-language-server`
|
||||
- With Stack: `stack build haskell-language-server:exe:haskell-language-server`
|
||||
- Restart HLS
|
||||
- With VS Code: `Haskell: Restart Haskell LSP Server`
|
||||
|
||||
### Adding support for a new editor
|
||||
|
||||
Adding support for new editors is fairly easy if the editor already has good support for generic LSP-based extensions.
|
||||
In that case, there will likely be an editor-specific support system for this (like `lsp-mode` for Emacs).
|
||||
This will typically provide instructions for how to support new languages.
|
||||
|
||||
In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](#configuring-haskell-language-server) and
|
||||
for them to configure how the server is started.
|
||||
|
||||
### Sponsorship
|
||||
|
||||
If you want to contribute financially you can do so via [open-collective](https://opencollective.com/haskell-language-server). In the past the funding has been used to sponsor [summer student projects](https://mpickering.github.io/ide/posts/2021-07-22-summer-of-hls.html).
|
||||
Haskell language server implementation. Consult the [project documentation](https://haskell-language-server.readthedocs.io/en/latest/) for more details.
|
||||
|
1
docs/.gitignore
vendored
Normal file
1
docs/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
_build
|
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
0
docs/_static/.gitkeep
vendored
Normal file
0
docs/_static/.gitkeep
vendored
Normal file
0
docs/_templates/.gitkeep
vendored
Normal file
0
docs/_templates/.gitkeep
vendored
Normal file
59
docs/conf.py
Normal file
59
docs/conf.py
Normal file
@ -0,0 +1,59 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'haskell-language-server'
|
||||
copyright = '2021, The Haskell IDE Team'
|
||||
author = 'The Haskell IDE Team'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '1.3.0'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'myst_parser',
|
||||
'sphinx_rtd_theme'
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_logo = "logos/logo-64.png"
|
||||
html_favicon = "logos/logo.svg"
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
361
docs/configuration.md
Normal file
361
docs/configuration.md
Normal file
@ -0,0 +1,361 @@
|
||||
# Configuration
|
||||
|
||||
## Configuring `haskell-language-server`
|
||||
|
||||
Language servers like `haskell-language-server` expose most of their configuration via the client (i.e. the editor).
|
||||
That means that the way in which you configure the settings will depend on the client.
|
||||
|
||||
Most clients (editors) already have an opinion about how settings should be configured!
|
||||
For example, in VS Code you use the graphical Settings tab or `settings.json`, whereas in Emacs you use customization variables.
|
||||
In the [editor configuration section](#configuring-your-editor) we give some pointers for popular editors, but you should consult the documentation for your specific editor if you have trouble.
|
||||
|
||||
However, we can say some high-level things about the kinds of configuration `haskell-language-server` uses, and how to use them.
|
||||
This can sound a bit confusing, but ultimately the client should present you with these options in a user-friendly way that makes sense for that editor.
|
||||
|
||||
### Generic server options
|
||||
|
||||
The LSP protocol is designed to support many useful server configuration options generically.
|
||||
These are sent to the server by the client, and can be controlled without reference to a specific language.
|
||||
|
||||
For example, there are protocol methods for highlighting matching identifiers throughout a document.
|
||||
This is a capability which any server can implement, so the client can decide generically whether to ask the server to do it or not.
|
||||
So your editor can provide a setting to turn this on or off globally, for any language server you might use.
|
||||
|
||||
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by `lsp-mode`.
|
||||
|
||||
### Generic editor options
|
||||
|
||||
Your editor may provide some settings that affect how the information from the language server is used.
|
||||
For example, whether popups are shown, or whether code lenses appear by default.
|
||||
|
||||
Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by `lsp-mode`.
|
||||
|
||||
### Language-specific server options
|
||||
|
||||
A specific language server can also have its own configuration options.
|
||||
These are still sent to the server by the client, but they can only be controlled by a specific client that knows about those options.
|
||||
|
||||
For example, `haskell-language-server` allows you to choose the formatting provider which will be used for formatting Haskell source.
|
||||
This option obviously would not make sense for language servers for other languages, or even for other Haskell language servers (which need not even support formatting).
|
||||
|
||||
Here is a list of the additional settings currently supported by `haskell-language-server`, along with their setting key (you may not need to know this) and default:
|
||||
|
||||
- Formatting provider (`haskell.formattingProvider`, default `ormolu`): what formatter to use; one of `floskell`, `ormolu`, `fourmolu`, `stylish-haskell`, or `brittany` (if compiled with the brittany plugin)
|
||||
- Format on imports (`haskell.formatOnImportOn`, default true): whether to format after adding an import
|
||||
- Diagnostics on change (`haskell.diagnosticsOnChange`, default true): (currently unused)
|
||||
- Completion snippets (`haskell.completionSnippetsOn`, default true): whether to support completion snippets
|
||||
- Liquid Haskell (`haskell.liquidOn`, default false): whether to enable Liquid Haskell support (currently unused until the Liquid Haskell support is functional again)
|
||||
- Hlint (`haskell.hlintOn`, default true): whether to enable Hlint support
|
||||
- Max completions (`haskell.maxCompletions`, default 40): maximum number of completions sent to the LSP client.
|
||||
|
||||
Settings like this are typically provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
|
||||
|
||||
### Client options
|
||||
|
||||
A particular client might also have some options of its own, for example to control how the server executable is started.
|
||||
|
||||
Settings like this are typically be provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
|
||||
|
||||
## Configuring your project build
|
||||
|
||||
`haskell-language-server` has to compile your project in order to give you diagnostics, which means that it needs to know how to do so.
|
||||
This is handled by the [`hie-bios`](https://github.com/mpickering/hie-bios) project.
|
||||
|
||||
**For a full explanation of how `hie-bios` determines the project build configuration, and how to configure it manually, refer to the [`hie-bios` README](https://github.com/mpickering/hie-bios/blob/master/README.md).**
|
||||
|
||||
At the moment, `haskell-language-server` has some limited support to automatically detect your project build configuration.
|
||||
The plan is to improve it to handle most use cases.
|
||||
|
||||
However, for now, the most reliable way is to manually configure `hie-bios` using a `hie.yaml` file in the root of the workspace.
|
||||
A `hie.yaml` file **explicitly** describes how to setup the environment to compile the various parts of your project.
|
||||
For that you need to know what *components* your project has, 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 automatically generate `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:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Configuring your editor
|
||||
|
||||
Most editors provide a Haskell-specific extension that provides support for launching `haskell-language-server` and talking to it, as well as [exposing configuration options](#configuring-haskell-language-server).
|
||||
|
||||
Editors typically assume that you have already installed `haskell-language-server` (see above) and that the installation script put the `haskell-language-server` and `haskell-language-server-wrapper` binaries in your `PATH` (usually `~/.local/bin` or `~/.cabal/bin` on Linux and macOS, `%APPDATA%\local\bin` or `%APPDATA%\cabal\bin` on Windows).
|
||||
The exception is VS Code, which can automatically install the binaries if they are not installed already.
|
||||
|
||||
### VS Code
|
||||
|
||||
Install from
|
||||
[the VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=haskell.haskell), or manually from the repository [vscode-haskell](https://github.com/haskell/vscode-haskell).
|
||||
The `haskell-language-server` and `haskell-language-server-wrapper` binaries will be automatically downloaded on an ad-hoc basis, but if you have them already installed on your PATH then it will just use them instead.
|
||||
|
||||
Configuration is done via the "Haskell" section of "Settings".
|
||||
|
||||
### Sublime Text
|
||||
|
||||
- Install [LSP](https://packagecontrol.io/packages/LSP) using [Package Control](https://packagecontrol.io/)
|
||||
- From Sublime Text, go to Preferences and search for LSP Settings
|
||||
- Paste in these settings. Make sure to change the command path to your `haskell-language-server-wrapper`
|
||||
|
||||
```json
|
||||
{
|
||||
"clients": {
|
||||
"haskell-language-server": {
|
||||
"command": ["haskell-language-server-wrapper", "--lsp"],
|
||||
"scopes": ["source.haskell"],
|
||||
"syntaxes": ["Packages/Haskell/Haskell.sublime-syntax"],
|
||||
"languageId": "haskell"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now open a Haskell project with Sublime Text and enable Language Server in the project.
|
||||
You should have these features available:
|
||||
|
||||
1. Errors are underlined in red
|
||||
2. LSP: Show Diagnostics will show a list of hints and errors
|
||||
3. LSP: Format Document will prettify the file
|
||||
|
||||
### Vim or Neovim
|
||||
|
||||
You can use [Coc](https://github.com/neoclide/coc.nvim), [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
|
||||
or any other Vim Language server protocol client.
|
||||
Coc is recommend since it is the only complete LSP implementation for Vim and Neovim and offers snippets and floating documentation out of the box.
|
||||
|
||||
#### Coc
|
||||
|
||||
Follow Coc's [installation instructions](https://github.com/neoclide/coc.nvim).
|
||||
Then issue `:CocConfig` and add the following to your Coc config file.
|
||||
|
||||
```json
|
||||
{
|
||||
"languageserver": {
|
||||
"haskell": {
|
||||
"command": "haskell-language-server-wrapper",
|
||||
"args": ["--lsp"],
|
||||
"rootPatterns": ["*.cabal", "stack.yaml", "cabal.project", "package.yaml", "hie.yaml"],
|
||||
"filetypes": ["haskell", "lhaskell"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### LanguageClient-neovim
|
||||
|
||||
##### vim-plug
|
||||
|
||||
If you use [vim-plug](https://github.com/junegunn/vim-plug), then you can do this by e.g.,
|
||||
including the following line in the Plug section of your `init.vim` or `~/.vimrc`:
|
||||
|
||||
```text
|
||||
Plug 'autozimu/LanguageClient-neovim', {
|
||||
\ 'branch': 'next',
|
||||
\ 'do': 'bash install.sh'
|
||||
\ }
|
||||
```
|
||||
|
||||
and issuing a `:PlugInstall` command within Neovim or Vim.
|
||||
|
||||
##### Clone the LanguageClient-neovim repo
|
||||
|
||||
As an alternative to using [vim-plug](https://github.com/junegunn/vim-plug) shown above, clone [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
|
||||
into `~/.vim/pack/XXX/start/`, where `XXX` is just a name for your "plugin suite".
|
||||
|
||||
##### Configuration and sample `~/.vimrc` sections
|
||||
|
||||
```vim
|
||||
set rtp+=~/.vim/pack/XXX/start/LanguageClient-neovim
|
||||
let g:LanguageClient_serverCommands = { 'haskell': ['haskell-language-server-wrapper', '--lsp'] }
|
||||
```
|
||||
|
||||
You'll probably want to add some mappings for common commands:
|
||||
|
||||
```vim
|
||||
nnoremap <F5> :call LanguageClient_contextMenu()<CR>
|
||||
map <Leader>lk :call LanguageClient#textDocument_hover()<CR>
|
||||
map <Leader>lg :call LanguageClient#textDocument_definition()<CR>
|
||||
map <Leader>lr :call LanguageClient#textDocument_rename()<CR>
|
||||
map <Leader>lf :call LanguageClient#textDocument_formatting()<CR>
|
||||
map <Leader>lb :call LanguageClient#textDocument_references()<CR>
|
||||
map <Leader>la :call LanguageClient#textDocument_codeAction()<CR>
|
||||
map <Leader>ls :call LanguageClient#textDocument_documentSymbol()<CR>
|
||||
```
|
||||
|
||||
Use <kbd>Ctrl+x</kbd><kbd>Ctrl+o</kbd> (`<C-x><C-o>`) to open up the auto-complete menu,
|
||||
or for asynchronous auto-completion, follow the setup instructions on
|
||||
[LanguageClient](https://github.com/autozimu/LanguageClient-neovim).
|
||||
|
||||
If you'd like diagnostics to be highlighted, add a highlight group for `ALEError`/`ALEWarning`/`ALEInfo`,
|
||||
or customize `g:LanguageClient_diagnosticsDisplay`:
|
||||
|
||||
```vim
|
||||
hi link ALEError Error
|
||||
hi Warning term=underline cterm=underline ctermfg=Yellow gui=undercurl guisp=Gold
|
||||
hi link ALEWarning Warning
|
||||
hi link ALEInfo SpellCap
|
||||
```
|
||||
|
||||
If you're finding that the server isn't starting at the correct project root,
|
||||
it may also be helpful to also specify root markers:
|
||||
|
||||
```vim
|
||||
let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']
|
||||
```
|
||||
|
||||
Further configuration can be done by pointing the [`g:LanguageClient_settingsPath`](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
|
||||
variable to the file in which you want to keep your LSP settings.
|
||||
|
||||
### Atom
|
||||
|
||||
Install the two Atom packages [atom-ide-ui](https://atom.io/packages/atom-ide-ui) and [haskell](https://atom.io/packages/haskell),
|
||||
|
||||
```bash
|
||||
$ apm install language-haskell atom-ide-ui haskell
|
||||
```
|
||||
|
||||
### Emacs
|
||||
|
||||
Emacs support is provided by a combination of the following packages:
|
||||
|
||||
[lsp-mode](https://github.com/emacs-lsp/lsp-mode)
|
||||
[lsp-ui](https://github.com/emacs-lsp/lsp-ui)
|
||||
[lsp-haskell](https://github.com/emacs-lsp/lsp-haskell)
|
||||
|
||||
You can install these manually if you are using plain Emacs; instructions for some specific flavours
|
||||
are included below.
|
||||
|
||||
Make sure to check the READMEs of each of these packages, which explain how to configure the
|
||||
various parts of the Emacs integration.
|
||||
In particular, `lsp-haskell` provides customization options for the `haskell-language-server`-specific parts,
|
||||
such as the path to the server executable.
|
||||
|
||||
#### [doom-emacs](https://github.com/hlissner/doom-emacs/tree/develop/modules/lang/haskell#module-flags)
|
||||
|
||||
Manual installation of packages is not required.
|
||||
Enable the lsp module and the haskell lang module with lsp flag in `.doom.d/init.el`:
|
||||
|
||||
``` emacs-lisp
|
||||
:tools
|
||||
lsp
|
||||
;; ...
|
||||
:lang
|
||||
(haskell +lsp)
|
||||
```
|
||||
|
||||
then do `$HOME/.emacs.d/bin/doom sync`
|
||||
|
||||
#### [Spacemacs](https://github.com/syl20bnr/spacemacs)
|
||||
|
||||
Manual installation of packages is not required.
|
||||
Enable the `haskell` layer and the `lsp` layer in your Spacemacs config file:
|
||||
|
||||
```emacs-lisp
|
||||
dotspacemacs-configuration-layers
|
||||
'(
|
||||
haskell
|
||||
lsp
|
||||
;; ...
|
||||
)
|
||||
```
|
||||
|
||||
### [Kakoune](https://github.com/mawww/kakoune)
|
||||
|
||||
1. Grab a copy of [kak-lsp](https://github.com/ul/kak-lsp), and follow the setup instructions.
|
||||
2. Point your `kak-lsp.toml` to `haskell-language-server-wrapper`.
|
||||
|
||||
```toml
|
||||
[language.haskell]
|
||||
filetypes = ["haskell"]
|
||||
roots = ["Setup.hs", "stack.yaml", "*.cabal"]
|
||||
command = "haskell-language-server-wrapper"
|
||||
args = ["--lsp"]
|
||||
```
|
129
docs/contributing/contributing.md
Normal file
129
docs/contributing/contributing.md
Normal file
@ -0,0 +1,129 @@
|
||||
# Contributing guidelines
|
||||
|
||||
The Haskell tooling dream is near, we need your help!
|
||||
|
||||
- Join [our IRC channel](https://web.libera.chat/?channels=#haskell-language-server) at `#haskell-language-server` on [`libera`](https://libera.chat/).
|
||||
- Follow the [Haskell IDE team twitter account](https://twitter.com/IdeHaskell) for updates and help.
|
||||
- Join the [#haskell-tooling channel](https://discord.com/channels/280033776820813825/505370075402862594/808027763868827659) in the Functional Programming discord server. You can join the server via [this invitation](https://discord.gg/9spEdTNGrD).
|
||||
|
||||
## Style guidelines
|
||||
|
||||
The project includes a [`.editorconfig`](https://editorconfig.org) [file](https://github.com/haskell/haskell-language-server/blob/master/.editorconfig) with the editor basic settings used by the project.
|
||||
However, most editors will need some action to honour those settings automatically.
|
||||
For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig).
|
||||
Please, try to follow those basic settings to keep the codebase as uniform as possible.
|
||||
|
||||
## Building haskell-language-server
|
||||
|
||||
The project can be built with both `cabal build` and `stack build`.
|
||||
|
||||
haskell-language-server can also be used with itself. We provide preset samples of `hie.yaml` for Cabal and Stack.
|
||||
|
||||
Note: the `./install/` folder is not directly tied to the project so it has dedicated `./install/hie.yaml.[cbl|stack]`
|
||||
templates.
|
||||
|
||||
### Using Cabal
|
||||
|
||||
```shell
|
||||
$ cp hie-cabal.yaml hie.yaml
|
||||
$ cp install/hie-cabal.yaml install/hie.yaml
|
||||
```
|
||||
|
||||
### Using Stack
|
||||
|
||||
```shell
|
||||
$ cp hie-stack.yaml hie.yaml
|
||||
$ cp install/hie-stack.yaml install/hie.yaml
|
||||
$ cp ghcide/hie-stack.yaml ghcide/hie.yaml
|
||||
$ stack build --test --no-run-tests
|
||||
$ cd install
|
||||
$ stack build
|
||||
```
|
||||
|
||||
### Using Nix
|
||||
|
||||
The instructions below show how to set up a Cachix binary cache and open a nix shell for local development.
|
||||
|
||||
```shell
|
||||
$ cachix use haskell-language-server
|
||||
$ nix-shell
|
||||
$ cabal update
|
||||
$ cabal build
|
||||
```
|
||||
|
||||
#### Flakes support
|
||||
|
||||
If you are using nix 2.4 style command (enabled by `experimental-features = nix-command`),
|
||||
you can use `nix develop` instead of `nix-shell` to enter the development shell. To enter the shell with specific GHC versions:
|
||||
|
||||
* `nix develop` or `nix develop .#haskell-language-server-dev` - default GHC version
|
||||
* `nix develop .#haskell-language-server-8104-dev` - GHC 8.10.4
|
||||
* `nix develop .#haskell-language-server-884-dev` - GHC 8.8.4
|
||||
* `nix develop .#haskell-language-server-901-dev` - GHC 9.0.1
|
||||
|
||||
If you are looking for a Nix expression to create haskell-language-server binaries, see https://github.com/haskell/haskell-language-server/issues/122
|
||||
|
||||
To create binaries:
|
||||
|
||||
* `nix build` or `nix build .#haskell-language-server` - default GHC version
|
||||
* `nix build .#haskell-language-server-8104` - GHC 8.10.4
|
||||
* `nix build .#haskell-language-server-884` - GHC 8.8.4
|
||||
* `nix build .#haskell-language-server-901` - GHC 9.0.1
|
||||
|
||||
GHC 8.6.5 is not supported here because `nixpkgs-unstable` no longer maintains the corresponding packages set.
|
||||
|
||||
## Introduction tutorial
|
||||
|
||||
See the [tutorial](./plugin-tutorial.md) on writing a plugin in HLS.
|
||||
|
||||
## Test your hacked HLS in your editor
|
||||
|
||||
If you want to test HLS while hacking on it, follow the steps below.
|
||||
|
||||
To do once:
|
||||
|
||||
- Open some codebase on which you want to test your hacked HLS in your favorite editor
|
||||
- Configure this editor to use your custom HLS executable
|
||||
- With Cabal:
|
||||
- On Unix systems: `cabal exec which haskell-language-server`
|
||||
- On Windows: `cabal exec where haskell-language-server`
|
||||
- With Stack: `$(stack path --dist-dir)/build/haskell-language-server/haskell-language-server`
|
||||
|
||||
To do every time you changed code and want to test it:
|
||||
|
||||
- Build HLS
|
||||
- With Cabal: `cabal build exe:haskell-language-server`
|
||||
- With Stack: `stack build haskell-language-server:exe:haskell-language-server`
|
||||
- Restart HLS
|
||||
- With VS Code: `Haskell: Restart Haskell LSP Server`
|
||||
|
||||
## Adding support for a new editor
|
||||
|
||||
Adding support for new editors is fairly easy if the editor already has good support for generic LSP-based extensions.
|
||||
In that case, there will likely be an editor-specific support system for this (like `lsp-mode` for Emacs).
|
||||
This will typically provide instructions for how to support new languages.
|
||||
|
||||
In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](#configuring-haskell-language-server) and
|
||||
for them to configure how the server is started.
|
||||
|
||||
## Building the docs
|
||||
|
||||
The docs are built with [Sphinx](https://www.sphinx-doc.org/en/master/) and [ReadTheDocs](https://docs.readthedocs.io/en/stable/index.html), the documentation for both is helpful.
|
||||
|
||||
To build the docs you need to install some Python prerequisites. You can either `pip install -r docs/requirements.txt`, or simply enter a `nix-shell`.
|
||||
|
||||
Then to build and preview the docs:
|
||||
|
||||
```
|
||||
cd docs
|
||||
make html
|
||||
firefox _build/html/index.html
|
||||
```
|
||||
|
||||
Alternatively, you can build the entire thing as a Nix derivation from the flake with `nix build .#docs`.
|
||||
|
||||
The docs are also built and previewed on every PR, so you can check them from the PR status.
|
||||
|
||||
## Sponsorship
|
||||
|
||||
If you want to contribute financially you can do so via [open-collective](https://opencollective.com/haskell-language-server). In the past the funding has been used to sponsor [summer student projects](https://mpickering.github.io/ide/posts/2021-07-22-summer-of-hls.html).
|
Before Width: | Height: | Size: 140 KiB After Width: | Height: | Size: 140 KiB |
9
docs/contributing/index.rst
Normal file
9
docs/contributing/index.rst
Normal file
@ -0,0 +1,9 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
contributing
|
||||
releases
|
||||
plugin-tutorial
|
Before Width: | Height: | Size: 130 KiB After Width: | Height: | Size: 130 KiB |
36
docs/features.md
Normal file
36
docs/features.md
Normal file
@ -0,0 +1,36 @@
|
||||
# Features
|
||||
|
||||
- Code evaluation codelens ([Tutorial](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-eval-plugin/README.md)):
|
||||
|
||||
![Eval Demo](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-eval-plugin/demo.gif)
|
||||
|
||||
- Type information and documentation on hover. Note that currently, in order for docs to be displayed for dependencies, they must have been built with GHC's `-haddock` flag:
|
||||
|
||||
- For cabal:
|
||||
- Add to your global config file (e.g. `~/.cabal/config`):
|
||||
|
||||
```
|
||||
program-default-options
|
||||
ghc-options: -haddock
|
||||
```
|
||||
|
||||
- Or, for a single project, run `cabal configure --ghc-options=-haddock`
|
||||
|
||||
- For stack, add to global `$STACK_ROOT\config.yaml`, or project's `stack.yaml`:
|
||||
|
||||
```
|
||||
ghc-options:
|
||||
"$everything": -haddock
|
||||
```
|
||||
|
||||
This will cause compilation errors if a dependency contains invalid Haddock markup, though from GHC version 9.0, [these will be demoted to warnings](https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377).
|
||||
|
||||
- Integration with [retrie](https://hackage.haskell.org/package/retrie)
|
||||
|
||||
![Retrie](https://i.imgur.com/Ev7B87k.gif)
|
||||
|
||||
- Code lenses for explicit import lists
|
||||
|
||||
![Imports code lens](https://imgur.com/pX9kvY4.gif)
|
||||
|
||||
- Many more (TBD)
|
14
docs/index.rst
Normal file
14
docs/index.rst
Normal file
@ -0,0 +1,14 @@
|
||||
haskell-language-server
|
||||
=======================
|
||||
|
||||
Integration point for `ghcide <https://github.com/haskell/ghcide>`_ and `haskell-ide-engine <https://github.com/haskell/haskell-ide-engine>`_. One IDE to rule
|
||||
them all. Read the `project's background <https://neilmitchell.blogspot.com/2020/01/one-haskell-ide-to-rule-them-all.html>`_.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
features
|
||||
installation
|
||||
configuration
|
||||
troubleshooting
|
||||
contributing/index
|
220
docs/installation.md
Normal file
220
docs/installation.md
Normal file
@ -0,0 +1,220 @@
|
||||
# Installation
|
||||
|
||||
## 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.
|
||||
|
||||
## ghcup
|
||||
|
||||
If you are using [`ghcup`](https://www.haskell.org/ghcup/) to manage your installations, you can install `haskell-language-server` with
|
||||
```
|
||||
ghcup install hls
|
||||
```
|
||||
|
||||
## chocolatey
|
||||
|
||||
If you are using [`chocolatey`](https://chocolatey.org/) to manage your installations in windows, [you can install `haskell-language-server`](https://community.chocolatey.org/packages/haskell-language-server) with
|
||||
```
|
||||
choco install haskell-language-server
|
||||
````
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
If you are using Visual Studio Code, the [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) will automatically download and install `haskell-language-server` for you.
|
||||
|
||||
## 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.
|
||||
|
||||
## Arch Linux
|
||||
|
||||
The preferred method of installation for development purposes is to use the [haskell-language-server-bin](https://aur.archlinux.org/packages/haskell-language-server-bin) package from AUR.
|
||||
This package contains statically linked binaries for each supported GHC version and `haskell-language-server-wrapper` for automatic GHC version selection.
|
||||
It is updated regularly, requires no additional dependencies, and is independent of other haskell packages you may have on your system, including GHC.
|
||||
Its size is relatively large (approx. 900 MB), but if this is a problem for you, during installation you can disable the GHC versions you will not be using by editing the PKGBUILD file.
|
||||
|
||||
Alternatively, if you want to use **dynamically linked** Haskell packages from `pacman`,
|
||||
you can install the latest pre-compiled version of `haskell-language-server` from [[community]](https://archlinux.org/packages/community/x86_64/haskell-language-server/):
|
||||
|
||||
```
|
||||
sudo pacman -S haskell-language-server
|
||||
```
|
||||
|
||||
In this case, `haskell-language-server` is compiled against the GHC distributed to Arch Linux, so you will need maintain a system wide Haskell development environment, and install GHC from `pacman` as well.
|
||||
See [ArchWiki](https://wiki.archlinux.org/index.php/Haskell) for the details of Haskell infrastructure on Arch Linux.
|
||||
|
||||
## FreeBSD
|
||||
|
||||
HLS is available for installation from official binary packages. Use
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
- [Unicode (ICU)](http://site.icu-project.org/)
|
||||
- [NCURSES](https://www.gnu.org/software/ncurses/)
|
||||
- [Zlib](https://zlib.net/)
|
||||
|
||||
**Debian 9/Ubuntu 18.04 or earlier**:
|
||||
|
||||
```bash
|
||||
sudo apt install libicu-dev libtinfo-dev libgmp-dev zlib1g-dev
|
||||
```
|
||||
|
||||
**Debian 10/Ubuntu 18.10 or later**:
|
||||
|
||||
```bash
|
||||
sudo apt install libicu-dev libncurses-dev libgmp-dev zlib1g-dev
|
||||
```
|
||||
|
||||
**Fedora**:
|
||||
|
||||
```bash
|
||||
sudo dnf install libicu-devel ncurses-devel zlib-devel
|
||||
```
|
||||
|
||||
### 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/stack.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 <target>
|
||||
```
|
||||
|
||||
or using the existing alias script
|
||||
|
||||
```bash
|
||||
./cabal-hls-install <target>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
The script will install the executables `haskell-language-server-wrapper` and `haskell-language-server`.
|
||||
|
||||
It will copy the latter appending the used ghc version, needed by the wrapper to choose the suitable version
|
||||
for the project at hand.
|
||||
|
||||
So installing the executables directly with `stack install` or `cabal v2-install` may not be enough
|
||||
for it to work properly.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
`hls-8.8.3` target will build the project and install `haskell-language-server-wrapper`,
|
||||
`haskell-language-server`, `haskell-language-server-8.8.3` and `haskell-language-server-8.8`
|
||||
executables.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Installation from Hackage
|
||||
|
||||
Direct installation from Hackage, while possible via `cabal install haskell-language-server`, is not recommended for most people.
|
||||
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.
|
||||
|
||||
The package can be found here on Hackage: <https://hackage.haskell.org/package/haskell-language-server>
|
||||
|
||||
## Installation via Homebrew
|
||||
|
||||
Homebrew users can install `haskell-language-server` using the following command:
|
||||
|
||||
```bash
|
||||
brew install haskell-language-server
|
||||
```
|
||||
|
||||
This formula contains HLS binaries compiled with GHC versions available via Homebrew; at the moment those are: 8.6.5, 8.8.4, 8.10.4.
|
||||
|
||||
You need to provide your own GHC/Cabal/Stack as required by your project, possibly via Homebrew.
|
4
docs/requirements.txt
Normal file
4
docs/requirements.txt
Normal file
@ -0,0 +1,4 @@
|
||||
Sphinx==4.0.2
|
||||
sphinx-rtd-theme==0.5.2
|
||||
myst-parser==0.15.1
|
||||
docutils<0.17
|
66
docs/troubleshooting.md
Normal file
66
docs/troubleshooting.md
Normal file
@ -0,0 +1,66 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Known limitations
|
||||
|
||||
### Limited GHC 9 Support
|
||||
Currently, GHC 9 support in HLS is in beta stage; some features are unavailable with GHC >= 9.0.1 for the time being.
|
||||
This situation is expected to be resolved in the near future after all the dependent packages support GHC 9.
|
||||
See issue [#297](https://github.com/haskell/haskell-language-server/issues/297) for the supported features in GHC 9 and the status of migration progress.
|
||||
|
||||
### Preprocessor
|
||||
HLS is not yet able to find project preprocessors, which may result in `could not execute: <preprocessor>` errors. This problem is
|
||||
tracked in https://github.com/haskell/haskell-language-server/issues/176 and originally comes from https://github.com/mpickering/hie-bios/issues/125
|
||||
|
||||
As a workaround, you need to ensure the preprocessor is available in the path (install globally with Stack or Cabal, provide in `shell.nix`, etc.).
|
||||
|
||||
Example with `tasty-discover`:
|
||||
|
||||
```haskell
|
||||
{-# OPTIONS_GHC -F -pgmF tasty-discover #-}
|
||||
```
|
||||
|
||||
This returns an error in HLS if 'tasty-discover' is not in the path: `could not execute: tasty-discover`.
|
||||
|
||||
## Common issues
|
||||
|
||||
### Difficulties with Stack and `Paths_` modules
|
||||
|
||||
These are known to be somewhat buggy at the moment: <https://github.com/haskell/haskell-language-server/issues/478>.
|
||||
This issue should be fixed in Stack versions >= 2.5.
|
||||
|
||||
### Problems with dynamic linking
|
||||
|
||||
As haskell-language-server prebuilt binaries are statically linked, they don't play well with projects using dynamic linking.
|
||||
An usual symptom is the presence of errors containing `unknown symbol` and it is typical in arch linux, where a dynamically linked version of ghc is used.
|
||||
|
||||
The workaround is to use a version of haskell-language-server compiled from source with `-dynamic` enabled`. See more details [here](https://github.com/haskell/haskell-language-server/issues/1160#issuecomment-756566273).
|
||||
|
||||
## Troubleshooting the server
|
||||
|
||||
### Diagnostic mode
|
||||
|
||||
The `haskell-language-server` executable can be run in diagnostic mode, where it will just try to load modules from your project, printing all of its output to stdout.
|
||||
This makes it much easier to see what's going on and to diagnose build-related problems.
|
||||
|
||||
To do this, simply run the executable directly from your shell in the project root.
|
||||
You can either run it without an argument, in which case it will load random modules, or with a path, in which case it will load modules in that file or directory.
|
||||
|
||||
### Examining the log
|
||||
|
||||
Most clients will launch `haskell-language-server` with `--logfile` to make it write a log file.
|
||||
Please consult the documentation for your client to find out where this is (or how to set it).
|
||||
|
||||
The log will contain all the messages that are sent to the server and its responses.
|
||||
This is helpful for low-level debugging: if you expect a certain action to happen, you can look in the log to see if the corresponding messages are
|
||||
sent, or if there are any errors.
|
||||
|
||||
To get a more verbose, also pass `--debug` to the executable.
|
||||
|
||||
## Troubleshooting the client
|
||||
|
||||
Many clients provide diagnostic information about a LSP session.
|
||||
In particular, look for a way to get the status of the server, the server stderr, or a log of the messages that the client has sent to the server.
|
||||
For example, `lsp-mode` provides all of these (see its [troubleshooting page](https://emacs-lsp.github.io/lsp-mode/page/troubleshooting/) for details).
|
||||
|
||||
The most common client-related problem is the client simply not finding the server executable, so make sure that you have the right `PATH` and you have configured
|
||||
it to look for the right executable.
|
27
flake.nix
27
flake.nix
@ -180,6 +180,28 @@
|
||||
ghc8104 = pkgs.hlsHpkgs "ghc8104";
|
||||
ghc901 = ghc901Config.tweakHpkgs (pkgs.hlsHpkgs "ghc901");
|
||||
|
||||
# For markdown support
|
||||
myst-parser = pkgs.python3Packages.callPackage ./myst-parser.nix {};
|
||||
sphinx_rtd_theme = pkgs.python3Packages.sphinx_rtd_theme.overrideAttrs (oldAttrs: {
|
||||
# For https://github.com/readthedocs/sphinx_rtd_theme/pull/1185, otherwise lists are broken locally
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "readthedocs";
|
||||
repo = "sphinx_rtd_theme";
|
||||
rev = "34f81daaf52466366c80003db293d50075c1b896";
|
||||
sha256 = "0rkrsvvqr6g2p3v5vq88jhfp5sd0r1jqjh3vc5y26jn30z8s4fkz";
|
||||
};
|
||||
});
|
||||
pythonWithPackages = pkgs.python3.withPackages (ps: [ps.sphinx myst-parser sphinx_rtd_theme ps.pip]);
|
||||
|
||||
docs = pkgs.stdenv.mkDerivation {
|
||||
name = "hls-docs";
|
||||
src = pkgs.lib.sourceFilesBySuffices ./docs [ ".py" ".rst" ".md" ".png" ".gif" ".svg" ];
|
||||
buildInputs = [ pythonWithPackages ];
|
||||
# -n gives warnings on missing link targets, -W makes warnings into errors
|
||||
buildPhase = ''sphinx-build -n -W . $out'';
|
||||
dontInstall = true;
|
||||
};
|
||||
|
||||
# Create a development shell of hls project
|
||||
# See https://github.com/NixOS/nixpkgs/blob/5d4a430472cafada97888cc80672fab255231f57/pkgs/development/haskell-modules/make-package-set.nix#L319
|
||||
mkDevShell = hpkgs:
|
||||
@ -193,7 +215,7 @@
|
||||
removeAttrs hlsSources ghc901Config.disabledPlugins
|
||||
else
|
||||
hlsSources));
|
||||
buildInputs = [ gmp zlib ncurses capstone tracy (gen-hls-changelogs hpkgs) ]
|
||||
buildInputs = [ gmp zlib ncurses capstone tracy (gen-hls-changelogs hpkgs) pythonWithPackages ]
|
||||
++ (with hpkgs; [
|
||||
cabal-install
|
||||
hlint
|
||||
@ -240,6 +262,9 @@
|
||||
haskell-language-server-8104 = mkExe ghc8104;
|
||||
haskell-language-server-8105 = builtins.throw "GHC 8.10.5 is not available in nixpkgs";
|
||||
haskell-language-server-901 = mkExe ghc901;
|
||||
|
||||
# docs
|
||||
docs = docs;
|
||||
};
|
||||
|
||||
defaultPackage = packages.haskell-language-server;
|
||||
|
33
myst-parser.nix
Normal file
33
myst-parser.nix
Normal file
@ -0,0 +1,33 @@
|
||||
{ lib
|
||||
, buildPythonPackage
|
||||
, fetchPypi
|
||||
, markdown-it-py
|
||||
, mdit-py-plugins
|
||||
, pyyaml
|
||||
, docutils
|
||||
, sphinx
|
||||
}:
|
||||
|
||||
buildPythonPackage rec {
|
||||
pname = "myst-parser";
|
||||
version = "0.15.1";
|
||||
|
||||
src = fetchPypi {
|
||||
inherit pname version;
|
||||
sha256 = "00qnpkfjrn7bqbazm20n3zcci05803cfncvrlvk0rhsbdjiphg3w";
|
||||
};
|
||||
|
||||
propagatedBuildInputs = [
|
||||
markdown-it-py
|
||||
mdit-py-plugins
|
||||
pyyaml
|
||||
docutils
|
||||
sphinx
|
||||
];
|
||||
|
||||
meta = with lib; {
|
||||
description = "An extended commonmark compliant parser, with bridges to docutils & sphinx";
|
||||
homepage = https://github.com/executablebooks/MyST-Parser;
|
||||
license = licenses.mit;
|
||||
};
|
||||
}
|
Loading…
Reference in New Issue
Block a user