VsCode extension for Haskell, as a front end for haskell-ide-engine
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Haskell Language Server Client

Client interface to the Language Server Protocol server for Haskell, as provided by the Haskell IDE Engine. Check the requirements for dependencies.

It is still under development! If you want to help, get started by reading Contributing for more details.

Requirements

The language client requires you to manually install the HIE language server,

$ git clone https://github.com/haskell/haskell-ide-engine --recursive
$ cd haskell-ide-engine && make build-all

Alternatively you can just stack install, but make build-all will give you the best setup.

Features

Language server client for haskell using the HIE language server. Supports,

  • Diagnostics via HLint and GHC warnings/errors
  • Code actions and quick-fixes via apply-refact (click the lightbulb)
  • Type information and documentation (via hoogle) on hover
  • Jump to definition (F12 or Go to Definition in command palette)
  • List all top level definitions
  • Highlight references in document
  • Completion
  • Formatting via brittany (^ ⌥ B or Format Document in command palette)
  • Renaming via HaRe (F2 or Rename Symbol in command palette)
  • Multi-root workspace support

Additionally the language server itself features,

  • Supports plain GHC projects, cabal projects (sandboxed and non sandboxed) and stack projects
  • Fast due to caching of compile info

Extension Settings

You can disable HLint and also control the maximum number of reported problems,

"languageServerHaskell.hlintOn": true,
"languageServerHaskell.maxNumberOfProblems": 100,

If the liquid haskell executable is installed, enable using it to process haskell files on save.

"languageServerHaskell.liquidOn": true,

HIE Wrapper

Furthermore, the extension supports multiple ways of initializing hie, depending on your needs. The default one uses the hie-vscode.[sh|bat] file to start hie through. This will attempt to start via hie-wrapper if it is on the vscode path, otherwise fall back to hie. Thehie-wrapper executable is installed using make build, together with the other GHC version specific hie-8.x executables. This will take precedence over hieExecutablePath.

Custom Wrapper

If you need more control, and want to have a custom wrapper, either in your specific project or somewhere else on your computer, you can set a custom wrapper via,

"languageServerHaskell.useCustomHieWrapper": true,
"languageServerHaskell.useCustomHieWrapperPath": "~/wrapper-in-home.sh",

There are a few placeholders which will be expanded:

  • ~, ${HOME} and ${home} will be expanded into your users' home folder.
  • ${workspaceFolder} and ${workspaceRoot} will expand into your current project root.

This can be beneficial if you are using something like nix, to have a wrapper script tailored to your setup. This will take precedence over useHieWrapper and hieExecutablePath.

Enable/disable HIE

You can enable or disable HIE via configuration. This is useful, because multi-root workspaces do not yet allow you to manage extensions at the folder level, which can be necessary.

"languageServerHaskell.enableHIE": true

Path for hie executable

If you hie executable is not on your path, you can manually set it,

"languageServerHaskell.hieExecutablePath": "~/.local/bin/hie"

The path placeholders work here as well. Note that this adds the --lsp argument to the call of this executable.

Docs on Hover/Generating Hoogle DB

For the most current documentation on this, see Docs on Hover/Completion.

HIE supports fetching docs from haddock on hover. It will fallback on using a hoogle db(generally located in ~/.hoogle on linux) if no haddock documentation is found.

To generate haddock documentation for stack projects:

$ cd your-project-directory
$ stack haddock --keep-going

To enable documentation generation for cabal projects, add the following to your ~/.cabal/config

documentation: True

To generate a hoogle database that hie can use

$ cd haskell-ide-engine
$ stack --stack-yaml=<stack.yaml you used to build hie> exec hoogle generate

Manual Installation

Either install the extension via the marketplace (preferred), or if you are testing an unreleased version by,

$ npm install -g vsce
$ git clone https://github.com/alanz/vscode-hie-server
$ cd vscode-hie-server
$ npm install
$ vsce package

This will create a file something like vscode-hie-server-<version>.vsix according to the current version.

In VS Code, open the extensions tab, and click on the ... at the top right of it, and use the Install from VSIX... option to locate and install the generated file.

Using multi-root workspaces

First, check out what multi-root workspaces are. The idea of using multi-root workspaces, is to be able to work on several different Haskell projects, where the GHC version or stackage LTS could differ, and have it work smoothly.

HIE is now started for each workspace folder you have in your multi-root workspace, and several configurations are on a resource (i.e. folder) scope, instead of window (i.e. global) scope.

To showcase the utility of this, let's imagine that we are writing a full-stack Haskell website, and we have three main components:

  • a backend using LTS 10.10 and
  • a frontend using GHCJS and LTS 8.11,
  • a common part that is shared between the two, using LTS 8.11.

One way to be able to work on all these in the same VSCode project is to create a new workspace, and then add each folder to the workspace. This way, they are considered separate entities, and HIE will start separately for each.

You can then define how to start HIE for each of these folders, by going into Settings and then choosing Folder Settings -> <the folder you want>, or just configure the workspace. E.g. the backend and common projects could have a folder settting,

{
  "languageServerHaskell.useCustomHieWrapper": true,
  "languageServerHaskell.useCustomHieWrapperPath": "${workspaceFolder}/hie.sh"
}

to launch HIE via hie.sh inside the backend and common folder, while the frontend, because of using GHCJS, might not want to use HIE, and therefore needs to disable HIE,

{
  "languageServerHaskell.useHieWrapper": false
}

This provides a very flexible way of customizing your setup.

Release Notes

See the Changelog for more details.