Editor Setup ============= [TOC] This document tells you how to turn a text editor into an integrated development (IDE) for (respectively) the Haskell backend project and the Purescript frontend project. The process should look more or less similar for any editor compatible with the Language Server Protocol (LSP), however each section of this document has been written for the editor we were using while writing it. This means: - VSCode(ium) for the backend - Helix for the frontend Haskell -------- (Written for the VSCode(ium) editor) ### Preliminary Before setting up your editor, you need to know what version of GHC the project relies on and what compatible version of HLS is available. #### GHC version The GHC version is specified around the start of the `cabal.project` file in the `haskell-gargantext` repository. At the time of writing this, for instance, there is a line `with-compiler: ghc-9.4.7` 1. Install [the VSCodium editor](https://vscodium.com/#install) 2. Install [direnv](https://direnv.net/docs/installation.html) on your system 3. Install [GHCup](https://www.haskell.org/ghcup/install/). During the installation process, it will ask you whether to install haskell-language-server (HLS); accept. 4. Install the following VSCodium extensions using VSCodium's built-in package manager (the "Extensions" tab on the left): - [direnv](https://open-vsx.org/extension/cab404/vscode-direnv). Warning: there are several extensions with that name; choose the one by `cab404` - [Haskell](https://open-vsx.org/vscode/item?itemName=haskell.haskell) Restart VSCodium, open the `haskell-gargantext` project. Wait a few seconds; you might get a popup telling you that GHCup needs to download some version of GHC; accept. Now *if everything went well*, you should have Haskell intellisense working in your editor: hover over a symbol to get its type and documentation, right-click a symbol and click "Jump to definition" to jump to its definition, etc. Sadly, there is a good chance that something did go wrong. To help you troubleshoot, here's a rundown of what should have happened under the hood when you opened the project — assuming I didn't misunderstand anything: 1. The `direnv` extension sees the `.envrc` file at the root of the project, and sets the environment variables accordingly (all `.envrc` actually says is to use a Nix shell). 2. The `haskell` extension looks up what version of GHC is needed and tells that to GHCup. 3. If needed, GHCup downloads the right version of GHC for the project and adds it to its collection of GHC compilers in `~/.ghcup/ghc/` 4. Now the `haskell` extension has everything it needs. ### Caveat for Ubuntu 22.* or Debian users If you get glibc errors when trying the recommended setup with vscode, a workaround (apart from upgrading to ubuntu 24.* which will update glibc in a safe way) is to let nix deal with the hls version and ghc version for the project. Update `shell.nix` with : ```nix { pkgs ? import ./nix/pkgs.nix {}, currentPkgs ? import <nixpkgs> {} }: let myBuildInputs = [ pkgs.pkgs.docker-compose currentPkgs.haskell.packages.ghc947 .haskell-language-server pkgs.pkgs.stack ]; in pkgs.pkgs.mkShell { name = pkgs.shell.name; LOCALE_ARCHIVE = if pkgs.pkgs.stdenv.isLinux then "${pkgs.pkgs.glibcLocales}/lib/locale/locale-archive" else ""; #home.sessionVariables.LOCALE_ARCHIVE = "${pkgs.glibcLocales}/lib/locale/locale-archive"; shellHook = pkgs.shell.shellHook; buildInputs = pkgs.shell.buildInputs ++ myBuildInputs; } ``` Install `Nix Environment Selector` plugin in vscode. Then you need to tell your IDE to use the ghc version and hls version installed on the PATH. In vscode "workspace settings (JSON)":  ```json { "haskell.manageHLS": "PATH", "nixEnvSelector.nixFile": "${workspaceFolder}/shell.nix" } ``` Reload the window and wait a bit for the hls server to be up. Intellisense should be working now. ### Emacs My config (seeg) looks like this: ```elisp (use-package eglot :after (:any haskell-mode purescript-mode) :hook ((haskell-mode . eglot-ensure) ;; (haskell-ng-mode . eglot-ensure) (purescript-mode . eglot-ensure)) :config ;; https://haskell-language-server.readthedocs.io/en/latest/configuration.html#emacs (setq-default eglot-workspace-configuration '((haskell (plugin (stan (globalOn . :json-false)))))) ;; disable stan (setf (alist-get 'haskell-mode eglot-server-programs) (eglot-alternatives '(("/home/przemek/.ghcup/bin/haskell-language-server-9.4.7" "--lsp") ("/home/przemek/.ghcup/bin/haskell-language-server-9.4.7~2.5.0.0" "--lsp") ("/home/przemek/.ghcup/bin/haskell-language-server-wrapper" "--lsp")))) (setf (alist-get 'haskell-ng-mode eglot-server-programs) '("/home/przemek/.ghcup/bin/haskell-language-server-9.4.7" "--lsp")) (let ((ps-config '(:purescript (:addNpmPath t :buildCommand "build" :pursExe "/nix/store/r0nq9mzpw4pr4cp77bjkfhz8qbayvzj8-purs-0.15.16-1/bin/purs")))) (setf (alist-get 'purescript-mode eglot-server-programs) `("yarn" "purescript-language-server" "--log" "/home/przemek/purs-lsp.log" "--stdio" "--config" ,(json-encode ps-config)))) :custom (eglot-autoshutdown t) ;; shutdown language server after closing last file (eglot-confirm-server-initiated-edits nil) ;; allow edits without confirmation ) ``` ### Troubleshooting - Try to compile the project once using the instructions in the README before attempting to make HLS work in your editor. - The current HLS version might be too recent to work with your GHC version. To check that and use an adequate HLS version: - Check out the project's GHC version around the beginning of `cabal.project`; - Look up the corresponding "Last supporting HLS version" in [this table](https://haskell-language-server.readthedocs.io/en/latest/support/ghc-version-support.html#current-ghc-version-support-status). For instance, if the project's GHC version is 9.4.7, you need HLS v2.5.0.0 *at most*. - Tell GHCup to compile the corresponding version of HLS based the corresponding version of GHC, with the following command (again, using GHC 9.4.7 as an example): ```shell $ ghcup compile hls --version 2.5.0.0 --ghc 9.4.7 --cabal-update ``` - At least on one occasion, when compiling HLS using the above GHCup command, there was an error due to the zlib library missing. You may try to install the development library that provides zlib (on Ubuntu 24.04, the package was named `zlib1g-dev`) and restart your editor. Purescript ----------- (Written for the Helix editor) 1. Install [Helix](https://docs.helix-editor.com/install.html) 2. Install [Npm](https://docs.npmjs.com/cli/v9/configuring-npm/install) (necessary to install the Purescript language server) 3. Install the Purescript language server using Npm: ``` npm i -g purescript-language-server ``` 4. Compile the frontend at least once: ``` ./bin/install ``` Now the Purescript language server should be running in the editor, however this may not be obvious. To check that it is indeed running, you can: - Open a Purescript file from the project - Save it (the Purescript LSP only registers changes upon saving files) - (In Helix) Place the cursor on some Purescript value, and hit Space, then K. This should show you the type of the value - (In VSCode(ium)) Hover above some value. You should see the type of the value. - (In any editors) Introduce a blatant syntax error, and save the file. Your editor should complain.