merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,81 +1,76 @@
|
|||
#+TITLE: tools/lsp
|
||||
#+DATE: March 05, 2019
|
||||
#+SINCE: v2.1
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :tools lsp
|
||||
#+subtitle: M-x vscode
|
||||
#+created: March 05, 2019
|
||||
#+since: 21.12.0
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#features][Features]]
|
||||
- [[#lsp-powered-project-search][LSP-powered project search]]
|
||||
- [[#differences-between-eglot-and-lsp-mode][Differences between eglot and lsp-mode]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
- [[#my-language-server-is-not-found][My language server is not found]]
|
||||
- [[#lspeglot-is-not-started-automatically-in-my-buffer][LSP/Eglot is not started automatically in my buffer]]
|
||||
|
||||
* Description
|
||||
* 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
|
||||
imenu/xref integration, jump-to-definition/references support, and more.
|
||||
|
||||
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) (you'll
|
||||
find a table mapping languages to available servers [[https://github.com/emacs-lsp/lsp-mode#supported-languages][in the lsp-mode project
|
||||
README]]).
|
||||
3. Enable the =+lsp= flag on the =:lang= modules you want to enable LSP support
|
||||
for. If your language's module doesn't have LSP support, and you know it can
|
||||
(or should), please let us know! In the meantime, you must configure it
|
||||
yourself (described in the Configuration section).
|
||||
[[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 |
|
||||
|------------------+---------------------------------------------------------+---------------------------------------------------------------|
|
||||
| [[../../lang/cc/README.org][:lang cc]] | c-mode, c++-mode, objc-mode | ccls |
|
||||
| [[../../lang/clojure/README.org][:lang clojure]] | clojure-mode | clojure-lsp |
|
||||
| [[../../lang/csharp/README.org][:lang csharp]] | csharp-mode | omnisharp |
|
||||
| [[../../lang/elixir/README.org][:lang elixir]] | elixir-mode | elixir-ls |
|
||||
| [[../../lang/fsharp/README.org][:lang fsharp]] | fsharp-mode | Mono, .NET core |
|
||||
| [[../../lang/go/README.org][:lang go]] | go-mode | go-langserver |
|
||||
| [[../../lang/haskell/README.org][:lang haskell]] | haskell-mode | haskell-language-server |
|
||||
| [[../../lang/java/README.org][:lang java]] | java-mode | lsp-java |
|
||||
| [[../../lang/javascript/README.org][:lang javascript]] | js2-mode, rjsx-mode, typescript-mode | typescript-language-server |
|
||||
| [[../../lang/julia/README.org][:lang julia]] | julia-mode | LanguageServer.jl |
|
||||
| [[../../lang/ocaml/README.org][:lang ocaml]] | tuareg-mode | ocaml-language-server |
|
||||
| [[../../lang/php/README.org][:lang php]] | php-mode | php-language-server |
|
||||
| [[../../lang/python/README.org][:lang python]] | python-mode | lsp-python-ms |
|
||||
| [[../../lang/ruby/README.org][:lang ruby]] | ruby-mode | solargraph |
|
||||
| [[../../lang/rust/README.org][:lang rust]] | rust-mode | rls |
|
||||
| [[../../lang/scala/README.org][:lang scala]] | scala-mode | metals |
|
||||
| [[../../lang/sh/README.org][:lang sh]] | sh-mode | bash-language-server |
|
||||
| [[../../lang/swift/README.org][:lang swift]] | swift-mode | sourcekit |
|
||||
| [[../../lang/web/README.org][:lang web]] | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin |
|
||||
| [[../../lang/purescript/README.org][:lang purescript]] | purescript-mode | purescript-language-server |
|
||||
| [[../../lang/zig/README.org][:lang zig]] | zig-mode | zls |
|
||||
| [[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 |
|
||||
|
||||
** Module Flags
|
||||
+ =+peek= Use =lsp-ui-peek= when looking up definitions and references with
|
||||
functionality from the =:tools lookup= module.
|
||||
+ =+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.
|
||||
** Maintainers
|
||||
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]]
|
||||
+ [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
|
||||
+ [[https://github.com/emacs-lsp/lsp-ivy][lsp-ivy]] (=:completion ivy=)
|
||||
+ [[https://github.com/emacs-lsp/helm-lsp][helm-lsp]] (=:completion helm=)
|
||||
+ [[https://github.com/gagbo/consult-lsp][consult-lsp]] (=:completion vertico=)
|
||||
+ [[https://github.com/joaotavora/eglot][eglot]]
|
||||
** 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.
|
||||
|
||||
* Prerequisites
|
||||
This module has no direct prerequisites, but different languages will need
|
||||
different language servers, which =lsp-mode= will prompt you to auto-install.
|
||||
=eglot= will not.
|
||||
** 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
|
||||
|
|
@ -84,37 +79,78 @@ 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 Features
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
** 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 |
|
||||
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
|
||||
Entering the debate about which one to use would be useless. Doom provides an
|
||||
easy way to switch out lsp client implementations so you can test for yourself
|
||||
which one you prefer.
|
||||
The two projects are large and actively developed, so without writing a novel,
|
||||
it can only be compared in (very) broad strokes:
|
||||
|
||||
Mainly, from a code point of view, lsp-mode has a lot of custom code for UI
|
||||
(=lsp-ui-peek=, =lsp-ui-sideline=, ...), while eglot is more barebones with a
|
||||
closer integration with "more basic" emacs packages (=eldoc=, =xref=, ...).
|
||||
- [[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 can can 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?]]
|
||||
|
||||
* TODO Troubleshooting
|
||||
** 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 added the =+lsp= flag to the language you're using too in
|
||||
your init.el :
|
||||
#+BEGIN_SRC diff
|
||||
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
|
||||
#+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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue