doomemacs/modules/tools/lsp/README.org

#+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