3.2 Buffers, Projects, and Eglot

One of the main strong points of using a language server is that a language server has a broad view of the program: it considers more than just the single source file you are editing. Ideally, the language server should know about all the source files of your program which are written in the language supported by the server. In the language-server parlance, the set of the source files of a program is known as a workspace. The Emacs equivalent of a workspace is a project (see Projects in GNU Emacs Manual). Eglot fully supports Emacs projects, and considers the file in whose buffer Eglot is turned on as belonging to a project. In the simplest case, that file is the entire project, i.e. your project consists of a single file. But there are other more complex projects:

Eglot uses Emacs’s project management infrastructure to figure out which files and buffers belong to what project, so any kind of project supported by that infrastructure is automatically supported by Eglot.

When Eglot starts a server program, it does so in the project’s root directory, which is usually the top-level directory of the project’s directory hierarchy. This ensures the language server has the same comprehensive view of the project’s files as you do.

For example, if you visit the file ~/projects/fooey/lib/x.foo and x.foo belongs to a project rooted at ~/projects/fooey (perhaps because a .git directory exists there), then M-x eglot causes the server program to start with that root as the current working directory. The server then will analyze not only the file lib/x.foo you visited, but likely also all the other *.foo files under the ~/projects/fooey directory.

In some cases, additional information specific to a given project will need to be provided to the language server when starting it. The variable eglot-workspace-configuration (see Customizing Eglot) exists for that purpose. It specifies the parameters and their values to communicate to each language server which needs that.

When Eglot is active for a project, it performs several background activities on behalf of the project and its buffers: