ljos/lsp-mode

Emacs client/library for the Language Server Protocol

emacs-lsp

A Emacs Lisp library for implementing clients for servers using Microsoft's Language Server Protocol (v3.0).

The library is designed to integrate with existing Emacs IDE frameworks (completion-at-point, xref (beginning with Emacs 25.1), flycheck, etc).

Note: Starting from version 4.0, flycheck support has been moved to the package lsp-ui

Installation

Clone this repository to a suitable path, and add

(add-to-list 'load-path "<path to emacs-lsp>")
(require 'lsp-mode)

(lsp-define-stdio-client
 ;; This can be a symbol of your choosing. It will be used as a the
 ;; prefix for a dynamically generated function "-enable"; in this
 ;; case: lsp-prog-major-mode-enable
 lsp-prog-major-mode
 "language-id"
 ;; This will be used to report a project's root directory to the LSP
 ;; server.
 (lambda () default-directory)
 ;; This is the command to start the LSP server. It may either be a
 ;; string containing the path of the command, or a list wherein the
 ;; car is a string containing the path of the command, and the cdr
 ;; are arguments to that command.
 '("/my/lsp/server" "and" "args"))

;; Here we'll add the function that was dynamically generated by the
;; call to lsp-define-stdio-client to the major-mode hook of the
;; language we want to run it under.
;;
;; This function will turn lsp-mode on and call the command given to
;; start the LSP server.
(add-hook 'prog-major-mode #'lsp-prog-major-mode-enable)

to your .emacs, where prog-major-mode is the hook variable for a supported programming language major mode.

Adding support for languages

See API docs

Examples

completion

Completion is provided with the native completion-at-point (C-M-i), and should therefore work with any other completion backend. Async completion is provided by company-lsp.

eldoc (Help on hover)

Hover support is provided with eldoc, which should be enabled automatically.

Goto definition

Use M - . (xref-find-definition) to find the definition for the symbol under point.

Symbol references

Use M - ? (xref-find-references) to find the references to the symbol under point.

Symbol Highlighting

Imenu

Add

(require 'lsp-imenu)
(add-hook 'lsp-after-open-hook 'lsp-enable-imenu)

to your init file to enable imenu integration.

With helm-imenu

Rename

Use M - x lsp-rename.

Finer Control of Starting lsp-mode

In order to more finely control the lsp-mode startup, there are a number of customizable variables.

lsp-project-whitelist : Defaults to nil. lsp-project-blacklist : Defaults to nil.

lsp-mode will only be started if the given project root matches one pattern in the whitelist, or does not match any pattern in the blacklist.

There are also the functions lsp-MAJOR-MODE-whitelist-add and lsp-MAJOR-MODE-whitelist-remove to adjust the current buffer project root entry on the whitelist.

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 API documentation.

For example, you can automatically set projectile-project-root by attaching the following function to lsp-before-open-hook:

(defun my-set-projectile-root ()
  (when lsp--cur-workspace
    (setq projectile-project-root (lsp--workspace-root lsp--cur-workspace))))
(add-hook 'lsp-before-open-hook #'my-set-projectile-root)

See also

eglot - An alternative and lighter LSP implementation.