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