README.md

static-ls

static-ls ("static language server") is a hie files and hiedb based language server heavily inspired by halfsp, which reads static project information to provide IDE functionality through the language server protocol. static-ls will not generate this information on its own and instead will rely on the user to generate this information via separate programs

Supported static sources of information currently include:

• hiefiles
• hiedb

The goal of static-ls is to provide a high-speed, low-memory solution for large projects for which haskell-language-server tends to take up too much memory on recompilation. Haskell-language-server is recommended if you are not experiencing these issues. static-ls is meant to work on enterprise size projects where aforementioned constraints can be an issue. static-ls tends to work better standalone as a code navigation tool since project edits require re-indexing of hie files but also works reasonably well for editing with a program such as ghcid to watch files for compilation and the -fdefer-type-errors flag.

In the future we plan to use more sources of static information such as interface files to fetch documentation or ghcid's output to fetch diagnostics

Currently only ghc 9.4.4 and 9.6.1 are explicitly supported but I'm happy to add support for other versions of ghc if desired

Usage

1. Compile your project with ide info -fwrite-ide-info and -hiedir .hiefiles

   For a better UX, the following flags are strongly recommended.

   - -fdefer-type-errors
   - -Werror=deferred-type-errors
   - -Werror=deferred-out-of-scope-variables
   - -fno-defer-typed-holes
   

   These flags will allow hie files to be refreshed even if compilation fails to type check and will ensure that type check failures are still thrown as errors.

   • If you're using hpack you can add:

       ghc-options:
         - -fwrite-ide-info
         - -hiedir .hiefiles
         - -fdefer-type-errors
         - -Werror=deferred-type-errors
         - -Werror=deferred-out-of-scope-variables
         - -fno-defer-typed-holes
     

     to your package.yaml. See this project's package.yaml or static-ls.cabal for examples
   • You may instead add the following to your cabal.project.local file:

     ignore-project: False
     program-options:
       ghc-options:
         -fdefer-type-errors
         -Werror=deferred-type-errors
         -Werror=deferred-out-of-scope-variables
         -fno-defer-typed-holes
     

2. Index your project in hiedb running:

     hiedb -D .hiedb index .hiefiles --src-base-dir .
   

   from your workspace root. If you're on an older version of hiedb where the --src-base-dir argument is not available use:

     hiedb -D .hiedb index .hiefiles
   

   entr is also recommended if you want file watching functionality:

   find -L .hiefiles | entr hiedb -D .hiedb index /_       
   

3. Point your language client to the static-ls binary and begin editing! (See Editor Setup for instructions if you're not sure how)

ghcid is recommended to refresh hie files but compiling with cabal build should work as well

Features

static-ls supports the following lsp methods:

• textDocument/references
  • Note that find references only works on top level definitions and can be slow for functions which are used frequently

• textDocument/hover
  • Provides type information and definition location on hover

• textDocument/definition
  • Works on both local and top level definitions

Limitations

• Must be compiled on the same version of ghc as the project
• You will need to re-index your hie files once you edit your project

Editor setup

Instructions for editor setup

neovim - coc.nvim

call :CocConfig and copy the following in:

{
  "languageserver": {
    "static-ls": {
      "command": "static-ls",
      "rootPatterns": ["*.cabal", "stack.yaml", "cabal.project", "package.yaml", "hie.yaml"],
      "filetypes": ["haskell"]
    },
  },
}

Visual Studio Code

1. Install the Haskell language extension

2. Open the extension settings

3. Scroll down until you see "Server Executable Path" and set the path to the path of your static-ls binary

Alternatively you can also in your workspace's ./vscode/settings.json you can use the following:

{
  "haskell.manageHLS": "PATH",
  "haskell.serverExecutablePath": "static-ls",
  "haskell.serverExtraArgs": ""
}

(Note haskell.serverExecutablePath should be the path to your binary).