Haskell IDE Engine

This project aims to be the universal interface to a growing number of Haskell tools, providing a full-featured and easy to query backend for editors and IDEs that require Haskell-specific functionality.

We are currently focusing on using the Language Server Protocol as the interface via which we talk to clients.

• Haskell IDE Engine
  • Features
  • Installation
    • Installation with stack or Nix
    • ArchLinux
  • Configuration
  • Editor Integration
    • Using HIE with VS Code, Sublime Text, Vim/Neovim, Atom, Oni, Emacs or Spacemacs
  • Docs on hover/completion
  • Contributing
    • Planned Features
    • This is not yet another ghc-mod or ide-backend project
    • It's time to join the project!
  • Architecture
    • 1. BIOS layer
    • 2. Plugin layer
    • 3. IDE interfacing layer
  • Documentation
  • Troubleshooting

Features

• Supports plain GHC projects, cabal projects(sandboxed and non sandboxed) and stack projects

• Fast due to caching of compile info

• Uses LSP, so should be easy to integrate with a wide selection of editors

• Diagnostics via hlint and GHC warnings/errors

  

• Code actions and quick fixes via apply-refact

  

• Type information and documentation(via haddock) on hover

  

• Jump to definition

  

• List all top level definitions

  

• Highlight references in document

  

• Completion

  

• Formatting via brittany

  

• Renaming via HaRe

  

• Add packages to cabal and hpack package files

  

• Typo quick fixes

  

• Add missing imports (via hsimport)

  

Installation

Note: The version on branch hie-0.1.0.0 supports GHC 8.0.2. This is not supported in master.

On linux derivatives you will need to do the equivalent of before building

sudo apt install libicu-dev libtinfo-dev

Getting the source for GHC 8.2.1, 8.2.2, 8.4.2, 8.4.3

HIE builds from source code, so first,

$ git clone https://github.com/haskell/haskell-ide-engine --recursive
$ cd haskell-ide-engine

Getting the source for GHC 8.0.2

HIE builds from source code, so first,

$ git clone https://github.com/haskell/haskell-ide-engine
$ cd haskell-ide-engine
$ git checkout hie-0.1.0.0
$ git submodule update --init

Installation with stack

To install HIE, you need Stack version >= 1.7.1

In order to support both stack and cabal, hie requires cabal-install as well.

If it is not already installed, install it, one of the ways is

stack install cabal-install

To install all supported GHC versions, name them as expected by the VS Code plugin, and also build a local hoogle database, you need the make tool (on Windows, see the further advice below). Use the command:

make build-all

Then add

"languageServerHaskell.useHieWrapper": true

to VS Code user settings.

Otherwise, do one of the following.

For GHC 8.4.3

Using master

stack install

For GHC 8.4.2

Using master

stack --stack-yaml=stack-8.4.2.yaml install

For GHC 8.2.2

Using master

stack --stack-yaml=stack-8.2.2.yaml install

Using branch hie-0.1.0.0

stack install

For GHC 8.2.1

stack --stack-yaml=stack-8.2.1.yaml install

For GHC 8.0.2 (only via branch hie-0.1.0.0)

stack --stack-yaml=stack-8.0.2.yaml install

Installation on Windows

The make tool

If the make tool is not already available on your path (in Command Prompt, try commands where make or stack exec where -- make to investigate; in PowerShell, try where.exe make or stack exec where -- make), it can be added to the stack environment with the command:

stack exec pacman -- -S make

The make build-all command is then accessible using the command:

stack exec make -- build-all

For users of Cygwin, the Cygwin installer also provides the make tool as an option.

Alternatively, the Windows batch file make-build-all.bat can substitute for make build-all on systems without the make command.

Long paths

In order to avoid problems with long paths on Windows you can do the following:

1. Edit the group policy: set "Enable Win32 long paths" to "Enabled". Works only for Windows 10

2. Clone the haskell-ide-engine to the root of your logical drive (e.g. to E:\hie)

Installation with Nix

Follow the instructions at https://github.com/domenkozar/hie-nix

ArchLinux

An haskell-ide-engine-git package is available on the AUR.

Using Aura:

# aura -A haskell-ide-engine-git

Configuration

There are some settings that can be configured via a settings.json file:

{
    "languageServerHaskell": {
        "hlintOn": Boolean,
        "maxNumberOfProblems": Number
    }
}

• VS Code: These settings will show up in the settings window
• LanguageClient-neovim: Create this file in $projectdir/.vim/settings.json or set g:LanguageClient_settingsPath

Editor Integration

Note to editor integrators: there is now a hie-wrapper executable, which is installed alongside the hie executable. When this is invoked in the project root directory, it attempts to work out the GHC version used in the project, and then launch the matching hie executable.

All of the editor integrations assume that you have already installed HIE (see above) and that stack put the hie binary in your path (usually ~/.local/bin on linux and macOS).

Using HIE with VS Code

Install from the VSCode marketplace, or manually from the repository vscode-hie-server.

Using VS Code with Nix

.config/nixpkgs/config.nix sample:

with import <nixpkgs> {};

let
  hie = (import (fetchFromGitHub {
                   owner="domenkozar";
                   repo="hie-nix";
                   rev="e3113da";
                   sha256="05rkzjvzywsg66iafm84xgjlkf27yfbagrdcb8sc9fd59hrzyiqk";
                 }) {}).hie84;
in
{
  allowUnfree = true;
  packageOverrides = pkgs: rec {

    vscode = pkgs.vscode.overrideDerivation (old: {
      postFixup = old.postFixup + ''
        wrapProgram $out/bin/code --prefix PATH : ${lib.makeBinPath [hie]}
      '';
    });

  };
}

Using HIE with Sublime Text

• Make sure HIE is installed (see above) and that the directory stack put the hie binary in is in your path
  • (usually ~/.local/bin on unix)
• Install LSP using Package Control
• From Sublime Text, press Command+Shift+P and search for Preferences: LSP Settings
• Paste in these settings. Make sure to change the command path to your hie

"clients": {
  "haskell-ide-engine": {
    "command": ["hie"],
    "scopes": ["source.haskell"],
    "syntaxes": ["Packages/Haskell/Haskell.sublime-syntax"],
    "languageId": "haskell",
  },
},

Now open a haskell project with Sublime Text. You should have these features available to you:

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

Using HIE with Vim or Neovim

As above, make sure HIE is installed. These instructions are for using the LanguageClient-neovim client.

vim-plug

If you use vim-plug, then you can do this by e.g. including the following line in the Plug section of your init.vim:

Plug 'autozimu/LanguageClient-neovim', {
    \ 'branch': 'next',
    \ 'do': './install.sh'
    \ }

and issuing a :PlugInstall command within neovim.

Vim 8.0

Clone LanguageClient-neovim into ~/.vim/pack/XXX/start/, where XXX is just a name for your "plugin suite".

Sample ~/.vimrc

set rtp+=~/.vim/pack/XXX/start/LanguageClient-neovim
let g:LanguageClient_serverCommands = { 'haskell': ['hie-wrapper'] }

You'll probably want to add some mappings for common commands:

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 Ctrl+xCtrl+o (<C-x><C-o>) to open up the auto-complete menu, or for asynchronous auto-completion, follow the setup instructions on LanguageClient.

If you'd like diagnostics to be highlighted, add a highlight group for ALEError/ALEWarning/ALEInfo, or customize g:LanguageClient_diagnosticsDisplay:

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:

let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']

Using HIE with Atom

Make sure HIE is installed, then install the two Atom packages atom-ide-ui and ide-haskell-hie,

$ apm install language-haskell atom-ide-ui ide-haskell-hie

Using HIE with Emacs

Install HIE along with the following emacs packages:

lsp-mode lsp-ui lsp-haskell

Make sure to follow the instructions in the README of each of these packages.

Using HIE with Spacemacs

Install HIE, and then add the following to your .spacemacs config,

(defun dotspacemacs/layers ()
  "..."
  (setq-default
   ;; ...
   dotspacemacs-configuration-layers
   '(
     lsp
     (haskell :variables ;; Or optionally just haskell without the variables.
              haskell-completion-backend 'ghci
              haskell-process-type 'stack-ghci)
     )
   dotspacemacs-additional-packages '(
      (lsp-haskell :location (recipe :fetcher github :repo "emacs-lsp/lsp-haskell"))
      )
    ;; ...
    ))

and then activate lsp-haskell in your user-config section,

(defun dotspacemacs/user-config ()
  "..."
  (require 'lsp-haskell)
  (add-hook 'haskell-mode-hook #'lsp-haskell-enable)
  )

Now you should be able to use HIE in Spacemacs. I still recommend checking out lsp-ui and lsp-mode.

Using HIE with Oni

Oni (a Neovim GUI) added built-in support for HIE, using stack, in #1918. If you need to change the configuration for HIE, you can overwrite the following settings in your ~/.config/oni/config.tsx file (accessible via the command palette and Configuration: Edit User Config),

export const configuration = {
  "language.haskell.languageServer.command": "stack",
  "language.haskell.languageServer.arguments": ["exec", "--", "hie"],
  "language.haskell.languageServer.rootFiles": [".git"],
  "language.haskell.languageServer.configuration": {},
}

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

Contributing

Planned Features

• Multiproject support
• Project wide references
• Cross project find definition
• New-build support
• HaRe refactorings
• More code actions
• Cross project/dependency Find Definition
• Case splitting, type insertion etc.

This is not yet another ghc-mod or ide-backend project

Both the ghc-mod and ide-backend maintainers have agreed to contribute code to this new repository and then rebase the old repos on this. The reason we're using a new repo instead of modifying one of the existing ones is so that the existing projects experience no disruption during this migration process. If this was a new set of people starting a new project without support from existing projects, I'd agree with you. But Alan's reached out to existing players already, which is an important distinction.

This project is not started from scratch:

1. See why we should supersede previous tools
2. Check the list of existing tools and functionality
3. See more other tools and IDEs for inspiration

It's time to join the project!

❤️ Haskell tooling dream is near, we need your help! ❤️

• Register in our google group mailing list.
• Join our IRC channel at #haskell-ide-engine on freenode.
• Fork this repo and hack as much as you can.
• Ask @alanz or @hvr to join the project.

Architecture

Below you find a short overview of the main architectural layers of haskell-ide-engine. For more info have a look in the docs folder at the root of this project, especially:

• The Architecture discussion
• The Protocol discussion
• The Design discussion

1. BIOS layer

ghc-mod stays an AGPL project, and is used for its "awesome sauce" in terms of the BIOS functions that it does so well. This interface is straightforward to use, and if a license-constrained user wants to do something else it is also easy to replace, if there is strong control of the operating environment.

2. Plugin layer

A layer providing a point to integrate tools and existing functions, probably including ghci.

3. IDE interfacing layer

The focus is currently on LSP as the protocol we use to interface with IDEs.

Existing transports are still functional for the time being.

Documentation

All the documentation is in the docs folder at the root of this project.

Troubleshooting

macOS: Got error while processing diagnostics: unable to load package integer-gmp-1.0.2.0

Rename the file at ~/.stack/programs/x86_64-osx/ghc-8.4.3/lib/ghc-8.4.3/integer-gmp-1.0.2.0/HSinteger-gmp-1.0.2.0.o to a temporary name. Should be fixed in GHC 8.8.1.