+++ /dev/null
-# Running gopls as a daemon
-
-**Note: this feature is new. If you encounter bugs, please [file an
-issue](troubleshooting.md#file-an-issue).**
-
-If you just want to try this out, skip ahead to the [quickstart](#quickstart).
-
-## Background: gopls execution modes
-
-Gopls was originally implemented as an LSP sidecar: a process started by
-editors or editor plugins, and communicated with using jsonrpc 2.0 over
-stdin/stdout. By executing as a stateful process, gopls can maintain a
-significant amount of cache and can eagerly perform analysis on the source code
-being edited.
-
-This execution mode does not work as well when there are many separate editor
-processes or when editor processes are short-lived, as is often the case for
-users of non-IDE editors such as Vim or Emacs. Having many processes means
-having many caches, consuming a significant amount of system resources. Using
-short-lived sessions means paying a start-up cost each time a session is
-created.
-
-To support these types of workflows, a new mode of gopls execution is supported
-wherein a single, persistent, shared gopls "daemon" process is responsible for
-managing all gopls sessions. In this mode, editors still start a gopls sidecar,
-but this sidecar merely acts as a thin "forwarder", responsible for forwarding
-the LSP to the shared gopls instance and recording metrics, logs, and rpc
-traces.
-
-## Quickstart
-
-To use a shared gopls instance you must either manage the daemon process
-yourself, or let the gopls forwarder processes start the shared daemon as
-needed.
-
-### Running with `-remote=auto`
-
-Automatic management of the daemon is easiest, and can be done by passing the
-flag `-remote=auto` to the gopls process started by your editor. This will
-cause this process to auto-start the gopls daemon if needed, connect to it, and
-forward the LSP. For example, here is a reasonable gopls invocation, that sets
-some additional flags for easier [debugging](#debugging):
-```
-$ gopls -remote=auto -logfile=auto -debug=:0 -remote.debug=:0 -rpc.trace
-```
-
-Note that the shared gopls process will automatically shut down after one
-minute with no connected clients.
-
-### Managing the daemon manually
-
-To manage the gopls daemon process via external means rather than having the
-forwarders manage it, you must start a gopls daemon process with the
-`-listen=<addr>` flag, and then pass `-remote=<addr>` to the gopls processes
-started by your editor.
-
-For example, to host the daemon on the TCP port `37374`, do:
-```
-$ gopls -listen=:37374 -logfile=auto -debug=:0
-```
-
-And then from the editor, run
-```
-$ gopls -remote=:37374 -logfile=auto -debug=:0 -rpc.trace
-```
-
-If you are on a POSIX system, you can also use unix domain sockets by prefixing
-the flag values with `unix;`. For example:
-```
-$ gopls -listen="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0
-```
-And connect via:
-```
-$ gopls -remote="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0 -rpc.trace
-```
-
-(Note that these flag values MUST be enclosed in quotes, because ';' is a
-special shell character. For this reason, this syntax is subject to change in
-the future.)
-
-## Debugging
-
-Debugging a shared gopls session is more complicated than a singleton session,
-because there are now two gopls processes involved with handling the LSP. Here
-are some tips:
-
-### Finding logfiles and debug addresses
-
-When running in daemon mode, you can use the `gopls inspect sessions` command
-to find the logfile and debug port for your gopls daemon instance (as well as
-for all its connected clients). By default, this inspects the default daemon
-(i.e. `-remote=auto`). To inspect a different daemon, use the `-remote` flag
-explicitly: `gopls -remote=localhost:12345 inspect sessions`.
-
-This works whether or not you have enabled `-remote.debug`.
-
-### Traversing debug pages
-
-When `-debug=:0` is passed to gopls, it runs a webserver that serves stateful
-debug pages (see [troubleshooting.md](troubleshooting.md)). You can find the
-actual port hosting these pages by either using the `gopls inspect sessions`
-command, or by checking the start of the logfile -- it will be one of the first
-log messages. For example, if using `-logfile=auto`, find the debug address by
-checking `head /tmp/gopls-<pid>.log`.
-
-By default, the gopls daemon is not started with `-debug`. To enable it, set
-the `-remote.debug` flag on the forwarder instance, so that it invokes gopls
-with `-debug` when starting the daemon.
-
-The debug pages of the forwarder process will have a link to the debug pages of
-the daemon server process. Correspondingly, the debug pages of the daemon
-process will have a link to each of its clients.
-
-This can help you find metrics, traces, and log files for all of the various
-servers and clients.
-
-### Using logfiles
-
-The gopls daemon is started with logging disabled by default. To customize
-this, pass `-remote.logfile` to the gopls forwarder. Using
-`-remote.logfile=auto`, the daemon will log to a default location (on posix
-systems: `/tmp/gopls-daemon-<pid>.log`).
-
-The gopls daemon does not log session-scoped messages: those are instead
-reflected back to the forwarder so that they can be accessed by the editor.
-Daemon logs will only contain global messages, for example logs when sessions
-connect and disconnect.
-
-It is recommended to start the forwarder gopls process with `-rpc.trace`, so
-that its logfile will contain rpc trace logs specific to the LSP session.
-
-## Using multiple shared gopls instances
-
-There may be environments where it is desirable to have more than one shared
-gopls instance. If managing the daemon manually, this can be done by simply
-choosing different `-listen` addresses for each distinct daemon process.
-
-On POSIX systems, there is also support for automatic management of distinct
-shared gopls processes: distinct daemons can be selected by passing
-`-remote="auto;<id>"`. Any gopls forwarder passing the same value for `<id>`
-will use the same shared daemon.
-
-## FAQ
-
-**Q: Why am I not saving as much memory as I expected when using a shared gopls?**
-
-A: As described in [implementation.md](implementation.md), gopls has a concept
-of view/session/cache. Each session and view map onto exactly one editor
-session (because they contain things like edited but unsaved buffers). The
-cache contains things that are independent of any editor session, and can
-therefore be shared.
-
-When, for example, three editor session are sharing a single gopls process,
-they will share the cache but will each have their own session and view. The
-memory savings in this mode, when compared to three separate gopls processes,
-corresponds to the amount of cache overlap across sessions.
-
-Because this hasn't mattered much in the past, it is likely that there is state
-that can be moved out of the session/view, and into the cache, thereby
-increasing the amount of memory savings in the shared mode.
-
-**Q: How do I customize the daemon instance when using `-remote=auto`?**
-
-The daemon may be customized using flags of the form `-remote.*` on the
-forwarder gopls. This causes the forwarder to invoke gopls with these settings
-when starting the daemon. As of writing, we expose the following configuration:
-
-* `-remote.logfile`: the location of the daemon logfile
-* `-remote.debug`: the daemon's debug address
-* `-remote.listen.timeout`: the amount of time the daemon should wait for new
- connections while there are no current connections, before shutting down. If
- `0`, listen indefinitely.
-
-Note that once the daemon is already running, setting these flags will not
-change its configuration. These flags only matter for the forwarder process
-that actually starts the daemon.
projects / dotfiles / .git / blobdiff