2.1 Setting Up LSP Servers

For Eglot to be useful, it must first be combined with a suitable language server. Usually, that means running the server program locally as a child process of Emacs (see Processes in GNU Emacs Lisp Reference Manual) and communicating with it via the standard input and output streams.

The language server program must be installed separately, and is not further discussed in this manual; refer to the documentation of the particular server(s) you want to install.

To use a language server, Eglot must know how to start it and which programming languages each server supports. This information is provided by the variable eglot-server-programs.

Variable: eglot-server-programs ¶

This variable associates major modes with names and command-line arguments of the language server programs corresponding to the programming language of each major mode. It provides all the information that Eglot needs to know about the programming language of the source you are editing.

The value of the variable is an alist, whose elements are of the form (major-mode . server).

The major-mode of the alist elements can be either a symbol of an Emacs major mode or a list of the form (mode :language-id id), with mode being a major-mode symbol and id a string that identifies the language to the server (if Eglot cannot by itself convert the major-mode to the language identifier string required by the server). In addition, major-mode can be a list of several major modes specified in one of the above forms – this means a running instance of the associated server is responsible for files of multiple major modes or languages in the project.

The server part of the alist elements can be one of the following:

(program args…)

This says to invoke program with zero or more arguments args; the program is expected to communicate with Emacs via the standard input and standard output streams.

(program args… :initializationOptions options…)

program is invoked with args but options specifies how to construct the ‘:initializationOptions’ JSON object to pass the server on during the LSP handshake (see Advanced server configuration).

(host port args…)

Here host is a string and port is a positive integer specifying a TCP connection to a remote server. The args are passed to open-network-stream, e.g. if the connection needs to use encryption or other non-default parameters (see Network in GNU Emacs Lisp Reference Manual).

(program args… :autoport moreargs…)

program is started with a command line constructed from args followed by an available server port and the rest of arguments in moreargs; Eglot then establishes a TCP connection with the server via that port on the local host.

function

This should be a function of a single argument: non-nil if the connection was requested interactively (e.g., by the eglot command), otherwise nil. The function should return a value of any of the forms described above. This allows interaction with the user for determining the program to start and its command-line arguments.

Eglot comes with a fairly complete set of associations of major-modes to popular language servers predefined. If you need to add server associations to the default list, use add-to-list. For example, if there is a hypothetical language server program fools for the language Foo which is supported by an Emacs major-mode foo-mode, you can add it to the alist like this:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(foo-mode . ("fools" "--stdio"))))

This will invoke the program fools with the command-line argument --stdio in support of editing source files for which Emacs turns on foo-mode, and will communicate with the program via the standard streams. As usual with invoking programs, the executable file fools should be in one of the directories mentioned by the exec-path variable (see Subprocess Creation in GNU Emacs Lisp Reference Manual), for Eglot to be able to find it.

Sometimes, multiple servers are acceptable alternatives for handling a given major-mode. In those cases, you may combine the helper function eglot-alternatives with the functional form of eglot-server-programs.

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `(foo-mode . ,(eglot-alternatives
                               '(("fools" "--stdio")
                                 ("phewls" "--fast"))))))

If you have fools and phewls installed, the function produced by eglot-alternatives will prompt for the server to use in foo-mode buffers. Else it will use whichever is available.