Skip to content

Latest commit

 

History

History
151 lines (119 loc) · 5.22 KB

README.md

File metadata and controls

151 lines (119 loc) · 5.22 KB

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

Find references

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

Type on hover

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

Find definition

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 Haskell Extension

  2. Open the extension settings Go to tsettings

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

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).