aa54383b5d
doom-etc-dir will be renamed to doom-data-dir, to better reflect its purpose, and align it with XDG_DATA_HOME (where it will be moved to in v3, where Doom will begin to obey XDG directory conventions more closely). |
||
|---|---|---|
| .. | ||
| autoload | ||
| +eglot.el | ||
| +lsp.el | ||
| config.el | ||
| doctor.el | ||
| packages.el | ||
| README.org | ||
:tools lsp
Description unfold
This module integrates language servers into Doom Emacs. They provide features you'd expect from IDEs, like code completion, realtime linting, language-aware imenu/xref integration, jump-to-definition/references support, and more.
As of this writing, this is the state of LSP support in Doom Emacs:
| Module | Major modes | Default language server |
|---|---|---|
| :lang cc | c-mode, c++-mode, objc-mode | ccls, clangd |
| :lang clojure | clojure-mode | clojure-lsp |
| :lang csharp | csharp-mode | omnisharp |
| :lang elixir | elixir-mode | elixir-ls |
| :lang fsharp | fsharp-mode | Mono, .NET core |
| :lang go | go-mode | go-langserver |
| :lang haskell | haskell-mode | haskell-language-server |
| :lang java | java-mode | lsp-java |
| :lang javascript | js2-mode, rjsx-mode, typescript-mode | ts-ls, deno-ls |
| :lang julia | julia-mode | LanguageServer.jl |
| :lang ocaml | tuareg-mode | ocaml-language-server |
| :lang php | php-mode | php-language-server |
| :lang purescript | purescript-mode | purescript-language-server |
| :lang python | python-mode | lsp-python-ms |
| :lang ruby | ruby-mode | solargraph |
| :lang rust | rust-mode | rls |
| :lang scala | scala-mode | metals |
| :lang sh | sh-mode | bash-language-server |
| :lang swift | swift-mode | sourcekit |
| :lang web | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin |
| :lang zig | zig-mode | zls |
Maintainers
This module has no dedicated maintainers. Become a maintainer?
Module flags
- +eglot
- Use Eglot instead of LSP-mode to implement the LSP client in Emacs.
- +peek
-
Use
lsp-ui-peekwhen looking up definitions and references with functionality from the :tools lookup module.
Packages
Hacks
No hacks documented for this module.
TODO Changelog
This module does not have a changelog yet.
Installation
Enable this module in your doom! block.
To get LSP working, you'll need to do three things:
- Enable this module,
- Install a language server appropriate for your targeted language(s).
- Enable the +lsp flag on the :lang modules you want to enable LSP support for.
Different languages will need different language servers, some of which lsp-mode will prompt you to auto-install, but eglot will not.
A table that lists available language servers and how to install them can be found on the lsp-mode project README. The documentation of the module for your targeted language will contain brief instructions as well.
For eglot users, a list of default servers supported is on Eglot's README, including instructions to register your own.
TODO Usage
🔨 This module's usage documentation is incomplete. Complete it?
LSP-powered project search
Without the +eglot flag, and when :completion ivy, :completion helm or :completion vertico is active, LSP is used to search a symbol indexed by the LSP server:
| Keybind | Description |
|---|---|
| SPC c j | Jump to symbol in current workspace |
| SPC c J | Jump to symbol in any workspace |
Differences between eglot and lsp-mode
The two projects are large and actively developed, so without writing a novel, it can only be compared in (very) broad strokes:
- lsp-mode tends to be more featureful, beginner-friendly (e.g. offers to
install servers for you and has more helpful documentation), and has a user
experience that feels familiar to modern editors/IDEs, but at the cost of
performance (at baseline) and complexity (it has more moving parts and
reinvents a number of wheels to achieve a slicker UI, like
lsp-ui-peek,lsp-ui-sideline, etc). - eglot has fewer bells and whistles: it relies on built-in Emacs functionality more (eldoc, xref, capf, project.el, etc), offers less pre-configuration for you, and is more performant than lsp-mode (again, at baseline). It also works with TRAMP out-of-the-box (lsp-mode needs some extra configuration).
💬 I recommend beginners use lsp-mode. More experienced users may also opt to disable many of its inessential features to gain back some ground on performance and complexity costs.
All that said, it's easy to switch between the two implementations by swapping in/out the +lsp or +eglot flag when enabling this module.
TODO Configuration
🔨 This module's configuration documentation is incomplete. Complete it?
Turn off lsp-mode's intrusive features
Many users may not like how many UI elements that lsp-mode adds. They have some excellent documentation outlining what these features are called and how to turn them off.
Troubleshooting
My language server is not found
Check the entry in the FAQ about "Doom can't find my executables/doesn't inherit
the correct PATH"
LSP/Eglot is not started automatically in my buffer
Make sure that you have enabled the +lsp flag on the appropriate module(s) (in
your doom! block in $DOOMDIR/init.el):
:lang
-python
+(python +lsp)
LSP is slow
Follow lsp-tuning-guide to further fine-tune LSP mode performance.
Frequently asked questions
This module has no FAQs yet. Ask one?
TODO Appendix
🔨 This module has no appendix yet. Write one?