mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Auto merge of #14024 - meliache:update-split-emacs-documentation, r=lnicola

Browse Source 
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.
This commit is contained in:
bors 2023-01-25 13:05:51 +00:00
commit 85736de3bc
1 changed files with 34 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/user/manual.adoc
View File

@ -234,16 +234,43 @@ $ brew install rust-analyzer
=== Emacs === 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>>. 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.
1. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions]. ==== Eglot
2. Set `lsp-rust-server` to `'rust-analyzer`.
3. Run `lsp` in a Rust buffer. 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.
4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
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.
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 === Vim/NeoVim