#+title: :tools lsp #+subtitle: M-x vscode #+created: March 05, 2019 #+since: 21.12.0 * Description :unfold: This module integrates [[https://langserver.org/][language servers]] into Doom Emacs. They provide features you'd expect from IDEs, like code completion, realtime linting, language-aware [[doom-package:imenu]]/[[doom-package: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 | |------------------+---------------------------------------------------------+---------------------------------------------------------------| | [[doom-module::lang cc]] | c-mode, c++-mode, objc-mode | ccls, clangd | | [[doom-module::lang clojure]] | clojure-mode | clojure-lsp | | [[doom-module::lang csharp]] | csharp-mode | omnisharp | | [[doom-module::lang elixir]] | elixir-mode | elixir-ls | | [[doom-module::lang fsharp]] | fsharp-mode | Mono, .NET core | | [[doom-module::lang go]] | go-mode | go-langserver | | [[doom-module::lang haskell]] | haskell-mode | haskell-language-server | | [[doom-module::lang java]] | java-mode | lsp-java | | [[doom-module::lang javascript]] | js2-mode, rjsx-mode, typescript-mode | ts-ls, deno-ls | | [[doom-module::lang julia]] | julia-mode | LanguageServer.jl | | [[doom-module::lang ocaml]] | tuareg-mode | ocaml-language-server | | [[doom-module::lang php]] | php-mode | php-language-server | | [[doom-module::lang purescript]] | purescript-mode | purescript-language-server | | [[doom-module::lang python]] | python-mode | lsp-python-ms | | [[doom-module::lang ruby]] | ruby-mode | solargraph | | [[doom-module::lang rust]] | rust-mode | rls | | [[doom-module::lang scala]] | scala-mode | metals | | [[doom-module::lang sh]] | sh-mode | bash-language-server | | [[doom-module::lang swift]] | swift-mode | sourcekit | | [[doom-module::lang web]] | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin | | [[doom-module::lang zig]] | zig-mode | zls | ** Maintainers /This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] ** Module flags - +eglot :: Use [[https://elpa.gnu.org/packages/eglot.html][Eglot]] instead of [[https://github.com/emacs-lsp/lsp-mode][LSP-mode]] to implement the LSP client in Emacs. - +peek :: Use ~lsp-ui-peek~ when looking up definitions and references with functionality from the [[doom-module::tools lookup]] module. ** Packages - [[doom-package:lsp-mode]] - [[doom-package:lsp-ui]] - [[doom-package:lsp-ivy]] ([[doom-module::completion ivy]]) - [[doom-package:helm-lsp]] ([[doom-module::completion helm]]) - [[doom-package:consult-lsp]] ([[doom-module::completion vertico]]) - [[doom-package:eglot]] ** Hacks /No hacks documented for this module./ ** TODO Changelog # This section will be machine generated. Don't edit it by hand. /This module does not have a changelog yet./ * Installation [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] To get LSP working, you'll need to do three things: 1. Enable this module, 2. Install a language server appropriate for your targeted language(s). 3. Enable the [[doom-module:+lsp]] flag on the [[doom-module::lang]] modules you want to enable LSP support for. Different languages will need different language servers, some of which [[doom-package:lsp-mode]] will prompt you to auto-install, but [[doom-package:eglot]] will not. A table that lists available language servers and how to install them can be found [[https://emacs-lsp.github.io/lsp-mode/page/languages/][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 [[https://github.com/joaotavora/eglot/blob/master/README.md#connecting-to-a-server][default servers supported is on Eglot's README]], including instructions to register your own. * TODO Usage #+begin_quote 󱌣 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] #+end_quote ** LSP-powered project search Without the [[doom-module:+eglot]] flag, and when [[doom-module::completion ivy]], [[doom-module::completion helm]] or [[doom-module::completion vertico]] is active, LSP is used to search a symbol indexed by the LSP server: | Keybind | Description | |---------+-------------------------------------| | [[kbd:][SPC c j]] | Jump to symbol in current workspace | | [[kbd:][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: - [[doom-package:lsp-mode]] tends to be more featureful, beginner-friendly (e.g. offers to install servers for you and has more [[https://emacs-lsp.github.io/lsp-mode][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). - [[doom-package: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). #+begin_quote 󰟶 I recommend beginners use lsp-mode. More experienced users may also opt to disable many of [[https://emacs-lsp.github.io/lsp-mode/tutorials/how-to-turn-off/][its inessential features]] to gain back some ground on performance and complexity costs. #+end_quote All that said, it's easy to switch between the two implementations by swapping in/out the [[doom-module:+lsp]] or [[doom-module:+eglot]] flag when [[id:01cffea4-3329-45e2-a892-95a384ab2338][enabling this module]]. * TODO Configuration #+begin_quote 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] #+end_quote ** Turn off lsp-mode's intrusive features Many users may not like how many UI elements that lsp-mode adds. They have [[https://emacs-lsp.github.io/lsp-mode/tutorials/how-to-turn-off/][some excellent documentation]] outlining what these features are called and how to turn them off. * Troubleshooting [[doom-report:][Report an issue?]] ** My language server is not found Check the entry in the [[../../../docs/faq.org][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 [[doom-module:+lsp]] flag on the appropriate module(s) (in your ~doom!~ block in =$DOOMDIR/init.el=): #+begin_src diff :lang -python +(python +lsp) #+end_src ** LSP is slow Follow [[https://emacs-lsp.github.io/lsp-mode/page/performance/#tuning][lsp-tuning-guide]] to further fine-tune LSP mode performance. * Frequently asked questions /This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] * TODO Appendix #+begin_quote 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]] #+end_quote