# scheme-lsp-server ## Table of contents 1. [Introduction](#introduction) 2. [Installing](#installing) 3. [API](#api) 4. [Command-line tool](#cli) 5. [Supported features](#supported-features) 6. [Notes to specific implementations](#specific-implementations) 7. [Known issues](#known-issues) 8. [Existing clients](#existing-clients) 9. [Contributing](#contributing) ## Introduction ** EXPERIMENTAL ** A LSP (Language Server Protocol) server for Scheme. This software aims to support several Scheme implementations. To achieve this, the code is designed to contain as much logic as possible in R7RS Scheme, separating implementation-specific code in different directories. *Note*: this code is still in an early development stage and the API may change. Change suggestions are welcome. ### Supported implementations Currently CHICKEN 5, Gambit 4.9.4+ and Guile 3+ are supported. See [Supported features](#supported-features), [Notes to specific implementations](#specific-implementations) and [Known issues](#known-issues) for more information. ## Installing First a remark. Some LSP clients (like [lsp-scheme](https://codeberg.org/rgherdt/emacs-lsp-scheme) and [vscode-scheme-lsp](https://codeberg.org/rgherdt/vscode-scheme-lsp)) will install an LSP server automatically. If you prefer to install it manually, please follow the instructions below. ### CHICKEN First install some dependencies, including chicken-doc's documentation: ``` $ chicken-install -s apropos chicken-doc srfi-18 $ cd `csi -p '(chicken-home)'` $ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx ``` Then install the LSP server with ``` chicken-install -s lsp-server ``` ### Gambit Note that you need Gambit 4.9.4 or later in order to use this lib. You can install the library and its dependencies by running ``` $ gsi -install \ codeberg.org/rgherdt/srfi \ github.com/ashinn/irregex \ github.com/rgherdt/chibi-scheme \ codeberg.org/rgherdt/scheme-json-rpc/json-rpc \ codeberg.org/rgherdt/scheme-lsp-server/lsp-server ``` You can now import the library using its fully qualified name ``` > (import (codeberg.org/rgherdt/scheme-lsp-server lsp-server)) ``` Instead of installing it, you can also call it by invoking `gsi` with `-:whitelist` ``` $ gsi -:whitelist=codeberg.org/rgherdt/scheme-lsp-server > (import (codeberg.org/rgherdt/scheme-lsp-server lsp-server)) ``` In order to use the command line tool, copy the file `~~userlib/codeberg.org/rgherdt/scheme-lsp-server/@/gambit/gambit-lsp-server` to a directory in your `PATH`. `~~userlib` usually expands to `~/.gambit_userlib`. ### Guile Guile's version of the LSP server is packaged using automake. Make sure Guile 3 **AND** its development libraries are installed. On Debian you can install it using: ``` # apt install guile-3.0 guile-3.0-dev ``` Now switch to the `./guile` folder and run: ``` ./configure && make && sudo make install ``` *Note: Make sure the install dir is in your %load-path and %load-compiled-path`. For example, under Linux, add the following to your `./bashrc` file* ``` export GUILE_LOAD_COMPILED_PATH=...:/usr/local/lib/guile/3.0/site-ccache export GUILE_LOAD_PATH=...:/usr/local/share/guile/site/3.0 ``` ## API ``` [parameter] (lsp-server-log-level) ``` A symbol to control the server's verbosity. It can be either 'error, 'warning, 'info or 'debug. ``` [procedure] (lsp-server-start/stdio) ``` Start an LSP server listening on stdio. ``` [procedure] (lsp-server-start/tcp tcp-port-number) ``` Start an LSP server listening on `tcp-port-number`. ## Command-line tool This programs also comes with command line tools to start the server. They are called `chicken-lsp-server`, `guile-lsp-server` etc. All of them provide the same interface. Run `guile-lsp-server --help` for more information. ## Supported features
  CHICKEN Gambit Guile
Find signature X X X
Find documentation X X X
Autocomplete identifier X X X
Jump to definition X X X
## Notes to specific implementations ### CHICKEN The implementation for "jump to definition" is for now quite limited. I wrote a ctags-inspired code for CHICKEN that scans the project files for definitions. Additionally, the user can set the environment variable `CHICKEN_SOURCE_PATH` to a directory containing the installer's source, so that the server can provide information to internally defined functions. In the future we can refine this solution to be more "project-aware". Ideas are welcome. ### GUILE Most of the current implementation relies on Geiser. We include the corresponding Scheme files in our repository (git submodules was discarded to simplify packaging and automatic installation from LSP clients). ## Known issues ### [Gambit and Guile] No LSP information when library definition is missing Currently the LSP server only compiles (and imports) files that contain a library definition. In Scheme it's common though to separate the library definition and its implementation in different files (as this same library does). This means that if you open an implementation file (i.e. a scheme file without library definition) first, the LSP server won't provide much information. By opening the corresponding library definition (doesn't matter if before of after opening the first file) it should work properly. I experimented with a couple of workarounds for this, but was not 100% satisfied by the result. One idea was to simply compile/import every single file found in a project that contains a library definition. But this would bloat the run-time, and in my experiments lead to weird behavior on some large projects. Ideally we would like to keep track which source files belong to which library definition, but I'm not sure what's the best way to achieve this. ### [CHICKEN] Slow startup on large projects For CHICKEN we scan the project and parse files in order to fetch LSP-related information. On large projects, you may experience a delay until information starts to be received. LSP provides ways of giving feedback to the user when an operation takes a long time, we can add support to it in the future. ## Existing clients ### VSCodium: https://codeberg.org/rgherdt/vscode-scheme-lsp ### Emacs lsp-mode: https://codeberg.org/rgherdt/emacs-lsp-scheme ### Emacs Eglot: https://github.com/joaotavora/eglot Add the following to your `.emacs` configuration: ``` (require 'eglot) (add-to-list 'eglot-server-programs `(scheme-mode . ("guile-lsp-server"))) (add-hook 'scheme-mode-hook 'eglot-ensure) ``` Replace `"guile-lsp-server"` by your chosen scheme implementation. ## Contributing ### Creating an LSP client `scheme-lsp-server` supports two modes. It can either operate by listening on `stdio` (using `lsp-server-start/stdio`) or `TCP` (using `lsp-server-start/tcp`). A command-line tool is available that you can call from your client. Here an example call (analogous to `chicken-lsp-server`): ``` guile-lsp-server --tcp 4242 ``` Leaving out the `--tcp` flag starts the server in `stdio` mode. More information can be obtained with the `guile-lsp-server --help` command as usual. If you create an LSP client using this server, please let me know so we can keep this list up-to-date. ### Ideas on extending support to other Schemes Here are some ideas on how to add support to other Scheme implementation without increasing much code complexity: #### decide which build system to use. Currently we use two build systems: `chicken-install` with its egg definitions, and `autotools` for Guile. Ideally we should come up with a solution that can be used across all supported implementations. Possible candidates are Snow or Akku. Alternatively we could consider extending the existing `autotools` based scripts. Note that this may be irrelevant in some cases. Gambit, for instance, now supports loading libraries directly from `git` repositories. #### create needed portable libraries This library relies on non-standardized features, like TCP support and JSON (indirectly through `scheme-json-rpc` (https://codeberg.org/rgherdt/scheme-json-rpc/). It would be extremely helpful if those bits are solved by separate libraries or SRFIs. Guile's version for JSON-RPC already uses SRFI 180, that can solve the JSON problem. #### contribute to Geiser Since `scheme-lsp-server` uses Geiser, we can get better LSP support by help improving it.