gopls implementation documentation

This is not intended as a complete description of the implementation, for the most the part the package godoc, code comments and the code itself hold that. Instead this is meant to be a guide into finding parts of the implementation, and understanding some core concepts used throughout the implementation.


Throughout the code there are references to these three concepts, and they build on each other.

At the base is the Cache. This is the level at which we hold information that is global in nature, for instance information about the file system and its contents.

Above that is the Session, which holds information for a connection to an editor. This layer hold things like the edited files (referred to as overlays).

The top layer is called the View. This holds the configuration, and the mapping to configured packages.

The purpose of this layering is to allow a single editor session to have multiple views active whilst still sharing as much information as possible for efficiency. In theory if only the View layer existed, the results would be identical, but slower and using more memory.

Code location

gopls will be developed in the x/tools Go repository; the core packages are in internal/lsp, and the binary and integration tests are located in gopls.

Below is a list of the core packages of gopls, and their primary purpose:

goplsthe main binary, plugins and integration tests
internal/lspthe core message handling package
internal/lsp/cachethe cache layer
internal/cmdthe gopls command line layer
internal/debugfeatures to aid in debugging gopls
internal/lsp/protocolthe types of LSP request and response messages
internal/lsp/sourcethe core feature implementations
internal/memoizea function invocation cache used to reduce the work done
internal/jsonrpc2an implementation of the JSON RPC2 specification