bradyt / lsp-mode

Emacs client/library for the Language Server Protocol

Emacs Language Server Client

Overview

Client for Language Server Protocol (v3.0). lsp-mode aims to provide IDE-like experience by providing optional integration with the most popular Emacs packages like company, flycheck and projectile.

This release is breaking refer to the configuration section for upgrade instruction.

Note: if you still want to use the legacy lsp-mode refer to melpa stable.

Note: if your server is still not ported to the new interface, please file a bug in the corresponding repo.

• Diagnostics (via builtin flymake when Emacs > 26 or flycheck/lsp-ui)
• Code completion - using company-lsp or builtin complete-at-point
• Hovers - using lsp-ui
• Code actions - using lsp-execute-code-action or lsp-ui
• Code outline - using builtin imenu or helm-imenu
• Code navigation - using builtin xref
• Code lens (references/implementations) - using builtin xref
• Highlights
• Code formatting
• Debugger - dap-mode

What’s new in lsp.el?

• lsp-mode now have single entry point lsp for all language and based on the major mode starts the corresponding language servers.
• flymake integration.
• lsp automatically enables and configures company-lsp, lsp-ui, yasnippet, or flymake if they are present so no additional configuration is needed except installing the packages. That behavior could be disabled by setting lsp-auto-configure to nil.
• lsp-mode ships with several predefined servers located in lsp-clients.el which does not require additional package. For the more complex Language Servers like Eclipse JDT, ccls, cquery and haskell we still require separate package due to relatively high code base.
• lsp-mode handles automatically server failures by asking the user whether he/she wants to restart the server.
• introduced new command lsp-describe-session which replaces the existing one lsp-capabilities. The command lists the folders that are part of the workspace and the servers that are associated with the corresponding folder.
• lsp-mode displays information about the running server and it’s status in the modeline.
• lsp-define-stdio-client and lsp-define-tcp-client are replaced with lsp-register-client
• lsp rely on projectile or project.el now only for suggesting project root. Once you open new file in a project and start lsp it will provide several options(import project, blacklist project, select other directory root). Once you select a root it will be persisted and used for the next sessions.
• lsp-mode now supports multiple language servers per single file and workspace.
• changed lsp-mode to more sensible defaults.
• Removed all synchronous calls from the server startup.
• Implemented better multi-folder support.

Installation

Install via melpa

The recommended way to install lsp-mode is via package.el - the built-in package manager in Emacs. lsp-mode is available on the two major package.el community maintained repos - MELPA Stable and MELPA.

M-x package-install [RET] lsp-mode [RET]

Spacemacs

lsp-mode is included in spacemacs. Add lsp to dotspacemacs-configuration-layers and configure the language that you want to use to be backed by lsp backend.

Configuration

Add the following line in your configuration file:

(require 'lsp-mode)
(add-hook 'XXX-mode-hook #'lsp)

where XXX could be major mode like python, java, c++. Alternatively, if you want to minimize you configuration you may use prog-mode-hook. In case you do that, lsp will try to start for each programming mode and echo a message when there is no client registered for the current mode or if the corresponding server is not present. In addition, lsp-mode will automatically detect and configure lsp-ui and company-lsp. To turn off that behavior you could set lsp-auto-configure to nil.

use-package

Replace (require 'lsp-mode) with the following if you use use-package.

(use-package lsp-mode
  :commands lsp
  :init
  (setq ...))

(use-package lsp-ui :commands lsp-ui-mode)
(use-package company-lsp :commands company-lsp)

Supported languages

Some of the servers are directly supported by lsp-mode by requiring lsp-clients.el while other require installing additional package which provide server specific functionality.

Language	Language Server	Built-in	Installation command	Debugger
Bash	bash-language-server	Yes	npm i -g bash-language-server
C++	ccls	emacs-ccls	ccls
C++	clangd	Yes	clangd
C++	cquery	emacs-cquery	cquery
CSS	css	Yes	npm install -g vscode-css-languageserver-bin
Dart	dart_language_server	Yes	pub global activate dart_language_server
Elixir	elixir-ls	Yes	elixir-ls
Go	go-langserver	Yes	go get -u github.com/sourcegraph/go-langserver
Groovy	groovy-language-server	Yes	groovy-language-server
HTML	html	Yes	npm install -g vscode-html-languageserver-bin
Haskell	IDE engine	lsp-haskell	IDE engine
Java	Eclipse JDT LS	lsp-java	Automatic by lsp-java	Yes
Javascript/Typescript	javascript-typescript-stdio	Yes	npm i -g javascript-typescript-langserver
Ocaml	ocaml-language-server	Yes	ocaml-language-server
PHP	php-language-server	Yes	php-language-server
Python	pyls	Yes	pip install ‘python-language-server[all]’	Yes
Ruby	solargraph	Yes	gem install solargraph	Yes
Rust	rls	Yes	rls
Scala	lsp-scala	TBD
Vue	vue-language-server	Yes	npm install -g vue-language-server

Commands

• lsp-describe-session - Display session folders and running servers.
• lsp-describe-thing-at-point - Display help for the thing at point.
• lsp-execute-code-action - Execute code action.
• lsp-format-buffer - Format current buffer
• lsp-goto-implementation - Go to implementation
• lsp-goto-type-definition - Go to type definition
• lsp-rename - Rename symbol at point
• lsp-restart-workspace - Restart project
• lsp-symbol-highlight - Highlight all relevant references to the symbol under point.
• lsp-workspace-folders-add - Add workspace folder
• lsp-workspace-folders-remove - Remove workspace folder
• lsp-workspace-folders-switch - Switch workspace folder
• imenu or helm-imenu - display document structure.
• completion-at-point - display completion using built-in emacs completion-at-point framework.
• lsp-find-definition - to find the definition for the symbol under point.
• lsp-find-references - Find references for the symbol under point.

Configuration

• lsp-print-io - If non-nil, print all messages to and from the language server to *Messages*.
• lsp-inhibit-message - If non-nil, inhibit the message echo via inhibit-message.
• lsp-report-if-no-buffer - If non nil the errors will be reported even when the file is not open.
• lsp-keep-workspace-alive - If non nil keep workspace alive when the last workspace buffer is closed.
• lsp-enable-snippet - Enable/disable snippet completion support.
• lsp-auto-guess-root - Automatically guess the project root using projectile/project.
• lsp-restart - Defines how server exited event must be handled.
• lsp-session-file - Automatically guess the project root using projectile/project.
• lsp-auto-configure - Auto configure lsp-mode. When set to t lsp-mode will auto-configure lsp-ui and company-lsp.
• lsp-document-sync-method - How to sync the document with the language server.
• lsp-auto-execute-action - Auto-execute single action.
• lsp-eldoc-render-all - Define whether all of the returned by document/onHover will be displayed. If lsp-markup-display-all is set to nil eldoc will show only the symbol information.
• lsp-enable-completion-at-point - Enable completion-at-point integration.
• lsp-enable-xref - Enable xref integration.
• lsp-prefer-flymake - If you prefer flycheck and lsp-ui-flycheck is available, (setq lsp-prefer-flymake nil).
• lsp-enable-indentation - Indent regions using the file formatting functionality provided by the language server.
• lsp-enable-on-type-formatting - Enable textDocument/onTypeFormatting integration.
• lsp-before-save-edits - If non-nil, lsp-mode will apply edits suggested by the language server before saving a document.
• lsp-imenu-show-container-name - Display the symbol’s container name in an imenu entry.
• lsp-imenu-container-name-separator - Separator string to use to separate the container name from the symbol while displaying imenu entries.
• lsp-imenu-sort-methods - How to sort the imenu items. The value is a list of kind, name or position. Priorities are determined by the index of the element.
• lsp-response-timeout - Number of seconds to wait for a response from the language server before timing out.
• lsp-hover-enabled - If non-nil, eldoc will display hover info when it is present. In case both signature and hover info are present and lsp-signature-enabled is t eldoc will display signature info.
• lsp-signature-enabled - If non-nil, eldoc will display signature info when it is present.

Hooks

lsp-mode provides a handful of hooks that can be used to extend and configure the behaviour of language servers. A full list of hooks is available in the ./doc/API.org.

Adding support for languages

See API docs

Here it is the minimal configuration that is needed for new language server registration. Refer to the documentation of lsp-client.el for the additional settings supported on registration time. lsp-language-id-configuration must be updated to contain the corresponding mode -> language id - in this case (python-mode . "python")

(lsp-register-client
 (make-lsp-client :new-connection (lsp-stdio-connection "pyls")
                  :major-modes '(python-mode)
                  :server-id 'pyls))

FAQ

How to configure a server with local variables?

Add lsp server call to hack-local-variables-hook which runs right after the local variables are loaded.

(add-hook 'hack-local-variables-hook
          (lambda () (when (derived-mode-p 'XXX-mode) (lsp))))

I have multiple language servers registered for language FOO. Which one will be used when opening a project?

The one with highest priority wins. lsp-clients.el predefined servers have priority -1, lower than external packages (priority 0 if unspecified).

See also

• dap-mode - Debugger integration for lsp-mode.
• eglot - An alternative minimal LSP implementation.