Unnamed repository; edit this file 'description' to name the repository.
Auto merge of #14024 - meliache:update-split-emacs-documentation, r=lnicola
Update documentation for emacs and split it for LSP-mode and Eglot
Emacs has now two LSP clients, the more minimalistic and lightweight [Eglot](https://joaotavora.github.io/eglot) and the extensive though a bit bloated [LSP Mode](https://github.com/emacs-lsp/lsp-mode). Eglot will soon be shipped with Emacs29. Both have rust-analyzer enabled by default and require no further setup other then being installed and enabled. `lsp-rust.el` is not required anymore.
The base-installation for each of those modes is so easy now that I don't think an enumerated list is necessary, both packages can be installed via the standard `M-x package-install` and the installation is a one-liner that I provide.
Configuration is only necessary for supporting the rust-analyzer extensions to the LSP protocol, which are built into LSP mode and require an [extension-package](https://github.com/nemethf/eglot-x) for Eglot.
But for further documentation, including the LSP extensions, I link against official documentation where possible to avoid duplicating efforts having to continually update this to stay up-to-date.
I rewrote most of the original emacs documentation, but the [linked blog](https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/) post by `@rksm` seems still being actively updated with updates to LSP mode, so I kept the link. That blog post is opinionated, I personally use different packages which achieve similar end results (Eglot instead of LSP-mode, corfu instead of capf, vertico instead of helm etc.). But if someone doesn't already have an extensive Emacs configuration, I think this is not a bad starting point.
Disclaimer: I'm a Rust beginner, which is why I read the rust-analyzer setup docs. So I necessarily know how most Rust experts use Emacs. But I'm an experienced Emacs user who uses several other programming languages via LSP-mode support in Emacs. I used both, initially LSP-mode and recently migrated to Eglot.
Also I'm not an experienced in writing asciidoc and I didn't do a local test-built, hopefully the html builds in the way I imagine it. So I recommend to check that aspect of the PR. Maybe the documentation is in the CI build-artifacts?
This is a duplicate of a PR to the old rust-analyzer project https://github.com/rust-analyzer/rust-analyzer.github.io/pull/197, which I made because I didn't know that the documentation now lives here.
| -rw-r--r-- | docs/user/manual.adoc | 41 |
1 files changed, 34 insertions, 7 deletions
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc index b0c3f3e63c..2cd1188c9d 100644 --- a/docs/user/manual.adoc +++ b/docs/user/manual.adoc @@ -234,16 +234,43 @@ $ brew install rust-analyzer === Emacs -Note this excellent https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/[guide] from https://github.com/rksm[@rksm]. - Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>. -Emacs support is maintained as part of the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP] package in https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[lsp-rust.el]. +To use `rust-analyzer`, you need to install and enable one of the two popular two popular LSP client implementations for Emacs, https://github.com/joaotavora/eglot[Eglot] or https://github.com/emacs-lsp/lsp-mode[LSP Mode]. Both enable `rust-analyzer` by default in rust buffers if it is available. + +==== Eglot + +Eglot is the more minimalistic and lightweight LSP client for Emacs, integrates well with existing Emacs functionality and will be built into Emacs starting from release 29. + +After installing Eglot, e.g. via `M-x package-install` (not needed from Emacs 29), you can enable it via the `M-x eglot` command or load it automatically in `rust-mode` via + +[source,emacs-lisp] +---- +(add-hook 'rust-mode-hook 'eglot-ensure) +---- + +For more detailed instructions and options see the https://joaotavora.github.io/eglot[Eglot manual] (also available from Emacs via `M-x info`) and the +https://github.com/joaotavora/eglot/blob/master/README.md[Eglot readme]. + +Eglot does not support the rust-analyzer extensions to the language-server protocol and does not aim to do so in the future. The https://github.com/nemethf/eglot-x#rust-analyzer-extensions[eglot-x] package adds experimental support for those LSP extensions. + +==== LSP Mode + +LSP-mode is the original LSP-client for emacs. Compared to Eglot it has a larger codebase and supports more features, like LSP protocol extensions. +With extension packages like https://github.com/emacs-lsp/lsp-mode[LSP UI] it offers a lot of visual eyecandy. +Further it integrates well with https://github.com/emacs-lsp/dap-mode[DAP mode] for support of the Debug Adapter Protocol. + +You can install LSP-mode via `M-x package-install` and then run it via the `M-x lsp` command or load it automatically in rust buffers with + +[source,emacs-lisp] +---- +(add-hook 'rust-mode-hook 'lsp-deferred) +---- + +For more information on how to set up LSP mode and its extension package see the instructions in the https://emacs-lsp.github.io/lsp-mode/page/installation[LSP mode manual]. +Also see the https://emacs-lsp.github.io/lsp-mode/page/lsp-rust-analyzer/[rust-analyzer section] for `rust-analyzer` specific options and commands, which you can optionally bind to keys. -1. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions]. -2. Set `lsp-rust-server` to `'rust-analyzer`. -3. Run `lsp` in a Rust buffer. -4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys. +Note the excellent https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/[guide] from https://github.com/rksm[@rksm] on how to set-up Emacs for Rust development with LSP mode and several other packages. === Vim/NeoVim |