lsp-bridge

Lsp-bridge's goal is to become the fastest LSP client in Emacs.

Lsp-bridge uses python's threading technology to build caches that bridge Emacs and LSP server. Lsp-bridge will provide smooth completion experience without compromise to slow down emacs' performance.

Installation

Install Python dependencies: python-epc
Install Elisp dependencies:

Clone or download this repository (path of the folder is the <path-to-lsp-bridge> used below).
Add following code in your ~/.emacs:

(add-to-list 'load-path "<path-to-lsp-bridge>")

(require 'yasnippet)
(yas-global-mode 1)

(require 'lsp-bridge)
(global-lsp-bridge-mode)

Usage

lsp-bridge is design for out the box. After installing the LSP server command corresponding to the open file, you can write the code directly without additional settings.

There are two modes in lsp-bridge:

When detecting the .git directory (to judge by command git rev-parse-is-inside-work-tree), lsp-bridge scan the entire directory files to provide completion
When the .git directory was not detected, lsp-bridge only provided a single file complementary to the open file

If you expect lsp-bridge to automatically scan the files of the entire project, please execute the git init command in the project root directory.

Commands

lsp-bridge-find-def: jump to the definition
lsp-bridge-find-def-other-window: jump to the definition in other-window
lsp-bridge-find-impl: jump to the implementation
lsp-bridge-find-impl-other-window: jump to the implementation in other-window
lsp-bridge-return-from-def: return to the location before calling lsp-bridge-find-def
lsp-bridge-find-references: traverse across code references (forked from color-rg.el)
lsp-bridge-lookup-documentation: lookup documentation of symbol under the cursor
lsp-bridge-popup-documentation-scroll-up: scroll up popup document.
lsp-bridge-popup-documentation-scroll-down: scroll down popup document.
lsp-bridge-rename: rename symbol under the cursor
lsp-bridge-jump-to-next-diagnostic: Jump to the next diagnostic position
lsp-bridge-jump-to-prev-diagnostic: Jump to the previous diagnostic position
lsp-bridge-list-diagnostics: List all diagnostic information
lsp-bridge-ignore-current-diagnostic: Insert comment to ignore the current diagnosis
lsp-bridge-signature-help-fetch: show signature help in minibuffer manually (move cursor to parameters area will show signature help automatically)
lsp-bridge-insert-common-prefix: insert common prefix of candidates
lsp-bridge-restart-process: restart lsp-bridge process (only used for development)
acm-doc-scroll-up: API document window scroll up
acm-doc-scroll-down: API document window scroll down

Options

lsp-bridge-completion-popup-predicates: the predicate function for completion menu, completion menu popup after all the functions pass
lsp-bridge-completion-stop-commands: completion menu will not popup if these commands are executed
lsp-bridge-completion-hide-characters: completion menu will not popup when cursor after those characters
lsp-bridge-diagnostics-fetch-idle: diagnostic delay, start pulling diagnostic information 1 second after stopping typing
lsp-bridge-enable-diagnostics: code diagnostic, enable by default
lsp-bridge-enable-candidate-doc-preview: preview of the candidate document, enable by default
lsp-bridge-enable-signature-help: show function parameter in minibufer, disable by default
lsp-bridge-org-babel-lang-list: list of language to support org-mode code block completion
lsp-bridge-disable-backup: forbidden version manage of emacs, enable by default
lsp-bridge-enable-log: enable the LSP message log, disable by default
lsp-bridge-enable-debug: enable program debugging, disable by default
lsp-bridge-python-command: The path of the python command, if you use conda, you may customize this option
lsp-bridge-signature-function: The function used for displaying signature info
acm-backend-lsp-enable-auto-import: automatic insert import code, enable by default
acm-candidate-match-function: The complete menu matching algorithm, the algorithm prefix of orderless-* needs to be installed additional orderless
acm-enable-doc: Whether the complete menu display the help document
acm-enable-icon: Whether the complete menu shows the icon
acm-snippet-insert-index: The display position of snippet candidate in the complementary menu

Customize language server configuration

The default configuration of for each language server is stored at lsp-bridge/langserver.

Anyway you can customize server configuration with the following priority:

lsp-bridge-get-lang-server-by-project: write your own function to get server configuration based on project-path and file-path, this function is nil by default
lsp-bridge-lang-server-extension-list: load server configuration based on file extension, such as, we launch volar server instead javascript server when open *.vue file
lsp-bridge-lang-server-mode-list: load server configuration based on major-mode

Add support for new language?

Create configuration file under lsp-bridge/langserver, such as pyright.json for pyright (windows user please uses pyright_windows.json, macOS user please uses pyright_darwin.json).
Add (mode . server_name) to lsp-bridge-lang-server-mode-list in lsp-bridge.el, such as (python-mode . "pyright").
Add new mode-hook to lsp-bridge-default-mode-hooks in lsp-bridge.el.

Welcome to send PR to help us improve support for LSP servers, thanks for your contribution!

Supported language servers

Index	LSP Server	Language	Note
1	clangd	c, c++
2	pyright	python	`pip install pyright`
3	solargraph	ruby
4	rust-analyzer	rust
5	elixirLS	elixir	please ensure that the `elixir-ls` release directory is in your system PATH at first
6	gopls	go	make sure gopls in PATH, please do `ln -s ~/go/bin/gopls ~/.local/bin`, and do `go mod init` first
7	hls	haskell
8	dart-analysis-server	dart
9	metals	scala
10	typescript	typescript, javascript
11	ocamllsp	ocaml
12	erlang-ls	erlang
13	texlab	latex
14	eclipse.jdt.ls	java	please ensure that `org.eclipse.jdt.ls.product/target/repository/bin` is in your system PATH at first
15	clojure-lsp	clojure
16	bash-language-server	bash
17	volar	vue
18	sumneko	lua	please ensure `bin` under sumneko installation is in your system PATH at first
19	wxml-language-server	wxml
20	vscode-html-language-server	html
21	vscode-css-language-server	css
22	elm-language-server	elm
23	intelephense	php
24	yaml-language-server	yaml	`npm install -g yaml-language-server`
25	zls	zig	execute `zls config` to generate configuration for zls. see Configuration Options
26	groovy-language-server	groovy	Create a script "groovy-language-server" in PATH, with `$JAVA_HOME/bin/java -jar <path>/groovy-language-server-all.jar`

TODO:

Code action

Features that won't be supported

The goal of lsp-bridge is to become the fastest LSP client in Emacs, not a complete implementation of LSP protocol.

Emacs can do better for the following tasks, we will not reinvent the wheel in lsp-bridge:

Code formatting: each LSP server has its own formatting specification, we can gain finer control using Emacs' builtin formatting tool.
Syntax highlighting: Tree-sitter is a wonderful incremental parsing library for syntax highlighting.
Xref: Xref's mechanism is synchronous, but lsp-bridge is completely asynchronous. I recommended binding your xref key to a wrapper function that combines xref and lsp-bridge together.

Join development

The following is the framework of lsp-bridge:

The following is the directory structure of the lsp-bridge project:

File	Explanation
lsp-bridge.el	Elisp main logic part that provides custom options and elisp functions for python sub-process calls like code jumping, renaming, etc.
lsp-bridge-epc.el	Communicating with lsp-bridge python sub-process, which mainly implements elisp IPC to connect to python EPC for data serialization, sending, receiving, and deserialization
lsp-bridge-ref.el	Framework of code referencing, providing references viewing, batch renames, regex filtering of reference results, etc. The core code is forked from color-rg.el
lsp-bridge-jdtls.el	Provide java language third-party library jumping function
lsp-bridge.py	Python main logic part that provides event loop, message scheduling and status management
acm/acm.el	Asynchronous completion menu, specially designed for lsp-bridge backend, supports LSP, elisp, words and other backend
core/fileaction.py	Tracking the status of each file, processing LSP response messages, calling Emacs elisp function
core/lspserver.py	LSP message processing module, mainly to analyze, send and receive LSP messages, and ensure that the sequence of LSP requests conforms with the LSP protocol specification
core/utils.py	Utility functions of convenience for each module call
core/mergedeep.py	JSON information merger is mainly used to send custom options to LSP server
core/hanlder/	The implementation of sending and receiving LSP message, where init.py is a base class
langserver	The configurations of the LSP servers, each server corresponding to a JSON file that defines the name of the server, language ID, starting command, options, etc.

Please read LSP Specification and The Design of lsp-bridge first.

Then turn on option lsp-bridge-enable-log and happy hacking! ;)

FAQ

Why lsp-bridge can't complete the code of other files in the project directory?

lsp-bridge relies on git to find the project path. lsp-bridge will enter a single file mode if it cannot find git information. You need to find the project path and execute git init command to solve this problem.

When you open the *.json file, why is it always prompting [LSP-BRIDGE] error: cann’t find command for *.json, disable lsp-bride-mode. ?

Because Emacs defaults to set the mode of json file to js-mode, you need to install json-mode to solve this problem.

Report bug

Please use emacs -q and load a minimal setup with only lsp-bridge to verify that the bug is reproducible. If emacs -q works fine, probably something is wrong with your Emacs config.

If the problem still exists, please report it here with *lsp-bridge* buffer content, it contains many clues that can help us locate the problem faster.

If you get a segfault error, please use the following way to collect crash information:

Install gdb and turn on option lsp-bridge-enable-debug
Use the command lsp-bridge-stop-process to stop the current process
Restart lsp-bridge, send issue with *lsp-bridge* buffer content when next crash

sauricat/lsp-bridge