Skip to content
A library for building Haskell IDE tooling
Haskell Other
  1. Haskell 99.0%
  2. Other 1.0%
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cbits update copyright notices (#2499) Sep 10, 2019
docs Copy the content of #159 to the setup guide (#164) Oct 13, 2019
exe Fix progress reporting (#153) Oct 17, 2019
extension Fix progress reporting (#153) Oct 17, 2019
img Make the README a little prettier (#1949) Sep 10, 2019
include Cleanup GHC API version checks Sep 16, 2019
src/Development/IDE Fix progress reporting (#153) Oct 17, 2019
test Fix progress reporting (#153) Oct 17, 2019
.ghci Add -Iinclude where it's needed (#86) Sep 19, 2019
.gitignore Ignore the stack.yaml.lock files (#141) Sep 30, 2019
.hlint.yaml Fix hlint cpp includes (#76) Sep 16, 2019
CHANGELOG.md Add changelog boilerplate (#111) Sep 23, 2019
LICENSE add CI config after extraction Sep 10, 2019
README.md Add eglot instruction to Emacs section of README (#169) Oct 16, 2019
azure-pipelines.yml Use a separate finder cache for each typecheck call (#148) Oct 2, 2019
fmt.sh Enable HLint Sep 10, 2019
ghcide.cabal Switch to new releases of haskell-lsp and lsp-test (#171) Oct 18, 2019
hie.yaml Use a stack cradle in hie.yaml (#121) Sep 25, 2019
install.bat Rename hie-core to ghcide (#2820) Sep 10, 2019
stack-ghc-lib.yaml Switch to new releases of haskell-lsp and lsp-test (#171) Oct 18, 2019
stack.yaml Switch to new releases of haskell-lsp and lsp-test (#171) Oct 18, 2019
stack84.yaml Switch to new releases of haskell-lsp and lsp-test (#171) Oct 18, 2019
stack88.yaml Switch to new releases of haskell-lsp and lsp-test (#171) Oct 18, 2019

README.md

ghcide - A library for building Haskell IDE tooling

Note: ghcide was previously called hie-core.

Our vision is that you should build an IDE by combining:

  • hie-bios for determining where your files are, what are their dependencies, what extensions are enabled and so on;
  • ghcide (i.e. this library) for defining how to type check, when to type check, and producing diagnostic messages;
  • A bunch of plugins that haven't yet been written, e.g. hie-hlint and hie-ormolu, to choose which features you want;
  • haskell-lsp for sending those messages to a Language Server Protocol (LSP) server;
  • An extension for your editor. We provide a VS Code extension as extension in this directory, although the components work in other LSP editors too (see below for instructions using Emacs).

There are more details about our approach in this blog post.

Features

ghcide already exports the following features via the lsp protocol:

Feature LSP name
Display error messages (parse errors, typecheck errors, etc.) and enabled warnings. diagnostics
Go to definition in local package definition
Display type and source module of values hover
Remove redundant imports, replace suggested typos for values and module imports, fill type holes, insert missing type signatures, add suggested ghc extensions codeAction (quickfix)
Organize imports codeAction (source.organizeImports)

Using it

Install ghcide

With Nix

See ghcide-nix repository

With Cabal or Stack

First install the ghcide binary using stack or cabal, e.g.

  1. git clone https://github.com/digital-asset/ghcide.git
  2. cd ghcide
  3. cabal install or stack install (and make sure ~/.local/bin is on your $PATH)

It's important that ghcide is compiled with the same compiler you use to build your projects.

Test ghcide

Next, check that ghcide is capable of loading your code. Change to the project directory and run ghcide, which will try and load everything using the same code as the IDE, but in a way that's much easier to understand. For example, taking the example of shake, running ghcide gives some error messages and warnings before reporting at the end:

Files that failed:
 * .\model\Main.hs
 * .\model\Model.hs
 * .\model\Test.hs
 * .\model\Util.hs
 * .\output\docs\Main.hs
 * .\output\docs\Part_Architecture_md.hs
Completed (152 worked, 6 failed)

Of the 158 files in Shake, as of this moment, 152 can be loaded by the IDE, but 6 can't (error messages for the reasons they can't be loaded are given earlier). The failing files are all prototype work or test output, meaning I can confidently use Shake.

The ghcide executable mostly relies on hie-bios to do the difficult work of setting up your GHC environment. If it doesn't work, see the hie-bios manual to get it working. My default fallback is to figure it out by hand and create a direct style hie.yaml listing the command line arguments to load the project.

If you can't get ghcide working outside the editor, see this setup troubleshooting guide. Once you have got ghcide working outside the editor, the next step is to pick which editor to integrate with.

Using with VS Code

You can install the VSCode extension from the VSCode marketplace.

Using with Emacs

If you don't already have MELPA package installation configured, visit MELPA getting started page to get set up. Then, install use-package.

Now you have a choice of two different Emacs packages which can be used to communicate with the ghcide LSP server:

  • lsp-ui
  • eglot

In each case, you can enable support by adding the shown lines to your .emacs:

lsp-ui

;; LSP
(use-package flycheck
  :ensure t
  :init
  (global-flycheck-mode t))
(use-package yasnippet
  :ensure t)
(use-package lsp-mode
  :ensure t
  :hook (haskell-mode . lsp)
  :commands lsp)
(use-package lsp-ui
  :ensure t
  :commands lsp-ui-mode)
(use-package lsp-haskell
 :ensure t
 :config
 (setq lsp-haskell-process-path-hie "ghcide")
 (setq lsp-haskell-process-args-hie '())
 ;; Comment/uncomment this line to see interactions between lsp client/server.
 ;;(setq lsp-log-io t)
)

eglot

(use-package eglot
  :ensure t
  :config
  (add-to-list 'eglot-server-programs '(haskell-mode . ("ghcide" "--lsp"))))

Using with Vim/Neovim

LanguageClient-neovim

Install LanguageClient-neovim

Add this to your vim config:

let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']
let g:LanguageClient_serverCommands = {
    \ 'rust': ['rls'],
    \ 'haskell': ['ghcide', '--lsp'],
    \ }

Refer to :he LanguageClient for more details on usage and configuration.

vim-lsp

Install vim-lsp.

Add this to your vim config:

au User lsp_setup call lsp#register_server({
    \ 'name': 'ghcide',
    \ 'cmd': {server_info->['/your/path/to/ghcide', '--lsp']},
    \ 'whitelist': ['haskell'],
    \ })

To verify it works move your cursor over a symbol and run :LspHover.

coc.nvim

Install coc.nvim

Add this to your coc-settings.json (which you can edit with :CocConfig):

{
  "languageserver": {
    "haskell": {
      "command": "ghcide",
      "args": [
        "--lsp"
      ],
      "rootPatterns": [
        ".stack.yaml",
        ".hie-bios",
        "BUILD.bazel",
        "cabal.config",
        "package.yaml"
      ],
      "filetypes": [
        "hs",
        "lhs",
        "haskell"
      ]
    }
  }
}

Here's a nice article on setting up neovim and coc: Vim and Haskell in 2019

Hacking on ghcide

To build and work on ghcide itself, you can use Stack or cabal, e.g., running stack test will execute the test suite.

Building the extension

For development, you can also the VSCode extension from this repository (see https://code.visualstudio.com/docs/setup/mac for details on adding code to your $PATH):

  1. cd extension/
  2. npm ci
  3. npm run vscepackage
  4. code --install-extension ghcide-0.0.1.vsix

Now opening a .hs file should work with ghcide.

History and relationship to other Haskell IDE's

The code behind ghcide was originally developed by Digital Asset as part of the DAML programming language. DAML is a smart contract language targeting distributed-ledger runtimes, based on GHC with custom language extensions. The DAML programming language has an IDE, and work was done to separate off a reusable Haskell-only IDE (what is now ghcide) which the DAML IDE then builds upon. Since that time, there have been various non-Digital Asset contributors, in addition to continued investment by Digital Asset. All contributions require a Contributor License Agreement that states you license the code under the Apache License.

The Haskell community has various IDE choices, but the one that has been gathering momentum is haskell-ide-engine. Our project owes a debt of gratitude to the haskell-ide-engine. We reuse libraries from their ecosystem, including hie-bios (a likely future environment setup layer in haskell-ide-engine), haskell-lsp and lsp-test (the haskell-ide-engine LSP protocol pieces). We make heavy use of their contributions to GHC itself, in particular the work to make GHC take string buffers rather than files. While ghcide is not a part of haskell-ide-engine, we feel it could form the core of a future version - but such decisions are up to the haskell-ide-engine contributors.

The best summary of the architecture of ghcide is available this talk (slides), given at MuniHac 2019. However, since that talk the project has renamed from hie-core to ghcide, and the repo has moved to this location.

You can’t perform that action at this time.