emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs(:tools): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:29:27 +02:00 • committed by Henrik Lissner
parent a226655486
commit 6da20e45bd
21 changed files with 1401 additions and 748 deletions
Download patch file Download diff file Expand all files Collapse all files

182
modules/tools/lsp/README.org
View file

@ -1,81 +1,77 @@
#+TITLE: tools/lsp
#+DATE: March 05, 2019
#+SINCE: v2.1
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools lsp][Issues]] ↖ [[doom-module-source:tools/lsp][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+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,15 +80,19 @@ 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
@ -100,21 +100,39 @@ easy way to switch out lsp client implementations so you can test for yourself
which one you prefer.
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=, ...).
(~lsp-ui-peek~, ~lsp-ui-sideline~, ...), while eglot is more barebones with a
closer integration with "more basic" emacs packages ([[doom-package:][eldoc]], [[doom-package:][xref]], ...).
* 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
* 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