[[https://melpa.org/#/lsp-mode][file:https://melpa.org/packages/lsp-mode-badge.svg]]
[[https://stable.melpa.org/#/lsp-mode][file:https://stable.melpa.org/packages/lsp-mode-badge.svg]]
[[https://gitter.im/emacs-lsp/lsp-mode][file:https://badges.gitter.im/emacs-lsp/lsp-mode.svg]]
[[https://travis-ci.org/emacs-lsp/lsp-mode][file:https://travis-ci.org/emacs-lsp/lsp-mode.svg?branch=master]]

#+ATTR_HTML: align="center"; margin-right="auto"; margin-left="auto"
[[examples/logo.png]]

* Language Server Protocol Support for Emacs
  #+caption: LSP mode
  [[file:examples/head.png]]

** Table of Contents                                      :TOC_4_gh:noexport:
- [[#language-server-protocol-support-for-emacs][Language Server Protocol Support for Emacs]]
  - [[#why][Why?]]
  - [[#overview][Overview]]
  - [[#installation][Installation]]
    - [[#install-via-melpa][Install via melpa]]
  - [[#configuration][Configuration]]
    - [[#install-language-server][Install language server]]
    - [[#configure-lsp-mode][Configure lsp-mode]]
      - [[#vanilla-emacs][Vanilla Emacs]]
      - [[#spacemacs][Spacemacs]]
      - [[#use-package][use-package]]
      - [[#docker][Docker]]
    - [[#how-does-it-work][How does it work?]]
  - [[#supported-languages][Supported languages]]
  - [[#commands][Commands]]
  - [[#settings][Settings]]
  - [[#screenshots][Screenshots]]
  - [[#extensions][Extensions]]
    - [[#tramp][TRAMP]]
      - [[#how-does-it-work-1][How does it work?]]
      - [[#sample-configuration][Sample configuration]]
      - [[#dealing-with-stderr][Dealing with stderr]]
  - [[#limitations][Limitations]]
    - [[#file-watches][File watches]]
  - [[#contributions][Contributions]]
    - [[#members][Members]]
  - [[#troubleshooting][Troubleshooting]]
  - [[#adding-support-for-languages][Adding support for languages]]
    - [[#registering-server][Registering server]]
    - [[#sections][Sections]]
  - [[#faq][FAQ]]
  - [[#see-also][See also]]

** Why?
   - ❤️ *Community Driven*
   - 💎 *Fully featured* - supports *all* features in Language Server Protocol v3.14.
   - 🚀 *Easy to configure* - works out of the box and automatically upgrades if additional packages are present
   - 🌟 *Flexible* - could be configured as full-blown IDE with flashy UI or minimal distraction free
** Overview
   Client for [[https://github.com/Microsoft/language-server-protocol/][Language Server Protocol]] (v3.14). [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]] aims to provide IDE-like experience by providing optional integration with the most popular Emacs packages like ~company~, ~flycheck~ and ~projectile~.

   - Non-blocking asynchronous calls
   - Real-time Diagnostics/linting (via builtin ~flymake~ when Emacs > 26, requires flymake>=1.0.5 or [[https://github.com/flycheck/flycheck][flycheck]]/[[https://github.com/emacs-lsp/lsp-ui][lsp-ui]])
   - Code completion - using [[https://github.com/tigersoldier/company-lsp][company-lsp]] or builtin ~completion-at-point~
   - Hovers - using [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
   - Code actions - using ~lsp-execute-code-action~ or [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
   - Code outline - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][imenu]] or ~helm-imenu~
   - Code navigation - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]]
   - Code lens (references/implementations) - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]]
   - Highlights
   - Formatting
   - Debugger - [[https://github.com/yyoncho/dap-mode/][dap-mode]]
   - Helm integration - [[https://github.com/emacs-lsp/helm-lsp/][helm-lsp]]
   - Ivy integration - [[https://github.com/emacs-lsp/lsp-ivy/][lsp-ivy]]
   - Treemacs integration - [[https://github.com/emacs-lsp/lsp-treemacs][lsp-treemacs]]
   - Semantic highlighting (as currently implemented by JDT LS and unreleased builds of clangd, cf. [[https://github.com/microsoft/vscode-languageserver-node/pull/367][Semantic highlighting spec]])
** Installation
*** Install via melpa
    The recommended way to install ~lsp-mode~ is via ~package.el~ - the built-in package manager in Emacs. ~lsp-mode~ is available on the two major ~package.el~ community maintained repos - [[http://stable.melpa.org][MELPA Stable]] and [[http://melpa.org][MELPA]].

    M-x ~package-install~ [RET] ~lsp-mode~ [RET]
** Configuration
*** Install language server
    Check the table bellow with the list of supported servers and the corresponding instructions on how to install the server.
*** Configure lsp-mode
**** Vanilla Emacs
     You could go minimal and use ~lsp-mode~ as it is without external packages with the built-in ~flymake~ and ~completion-at-point~ or you could install the following extensions for better experience:
     - install [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]] for [[https://github.com/flycheck/flycheck][flycheck]] integration and higher level UI modules.
     - install [[https://github.com/tigersoldier/company-lsp][company-lsp]] if you want to use ~company-mode~ for completion.
     - install [[https://github.com/emacs-lsp/lsp-treemacs][lsp-treemacs]] for project wide error overview.
     - install [[https://github.com/emacs-lsp/helm-lsp][helm-lsp]] provides on type completion for =xref-apropos=.
     - install [[https://github.com/emacs-lsp/dap-mode][dap-mode]] if your language is supported by the debugger.
     #+BEGIN_SRC emacs-lisp
       (require 'lsp-mode)
       (add-hook 'XXX-mode-hook #'lsp)
     #+END_SRC
     where ~XXX~ could be major mode like ~python~, ~java~, ~c++~. Alternatively, if you want to minimize you configuration you may use ~prog-mode-hook~. In case you do that, ~lsp~ will try to start for each programming mode and echo a message when there is no client registered for the current mode or if the corresponding server is not present. In addition, ~lsp-mode~ will automatically detect and configure [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]] and [[https://github.com/tigersoldier/company-lsp][company-lsp]]. To turn off that behavior you could set ~lsp-auto-configure~ to ~nil~.

     To defer LSP server startup (and DidOpen notifications) until the buffer is visible you can use ~lsp-deferred~ instead of ~lsp~:
     #+BEGIN_SRC emacs-lisp
       (add-hook 'XXX-mode-hook #'lsp-deferred)
     #+END_SRC
**** Spacemacs
     [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]] is included in spacemacs develop branch. Add ~lsp~ to ~dotspacemacs-configuration-layers~ and configure the language that you want to use to be backed by ~lsp~ backend.
**** use-package
     Replace ~(require 'lsp-mode)~ with the following if you use use-package.
     #+BEGIN_SRC emacs-lisp
       (use-package lsp-mode
         :hook (XXX-mode . lsp)
         :commands lsp)

       ;; optionally
       (use-package lsp-ui :commands lsp-ui-mode)
       (use-package company-lsp :commands company-lsp)
       (use-package helm-lsp :commands helm-lsp-workspace-symbol)
       (use-package lsp-treemacs :commands lsp-treemacs-errors-list)
       ;; optionally if you want to use debugger
       (use-package dap-mode)
       ;; (use-package dap-LANGUAGE) to load the dap adapter for your language
     #+END_SRC

     To defer LSP server startup (and DidOpen notifications) until the buffer is visible you can use ~lsp-deferred~ instead of ~lsp~:
     #+BEGIN_SRC emacs-lisp
       (use-package lsp-mode
         :hook (XXX-mode . lsp-deferred)
         :commands (lsp lsp-deferred))
     #+END_SRC
**** Docker
     Refer to [[https://github.com/emacs-lsp/lsp-docker/][lsp-docker]] README which provide a guide how you can run =lsp-mode= in =docker= container.
*** How does it work?
    ~lsp-mode~ has predefined list of server configurations (loaded in ~lsp-clients.el~) containing a mapping from ~major-mode~ to the server configuration or by using activation function. In addition to the default server configuration located in ~lsp-clients.el~ there are few languages servers which require separate package(check [[#supported-languages][Supported languages]]). When you open a file from a particular project ~lsp-mode~ and call ~lsp~ command ~lsp-mode~ will look for server registrations able to handle current file. If there is such client ~lsp-mode~ will look for the project root. If you open a file from the project for the first time you will be prompted to define the current project root. Once the project root is selected it is saved in ~lsp-session~ file and it will be loaded the next time you start Emacs so you no longer will be asked for a project root when you open a file from that project. Later if you want to change the project root you may use ~lsp-workspace-folder-remove~ to remove the project and call ~lsp-workspace-folder-add~ to add the root. If you want to force starting a particular language server in a file you may use ~C-u~ ~M-x~ ~lsp~ which will prompt you to select language server to start.
** Supported languages
   Some of the servers are directly supported by ~lsp-mode~ by requiring
   ~lsp-clients.el~ while others require installing additional packages which provide
   server specific functionality.

   | Language              | Language Server                           | Built-in      | Installation command                                                                                    | Debugger                     |
   |-----------------------+-------------------------------------------+---------------+---------------------------------------------------------------------------------------------------------+------------------------------|
   | Ada                   | [[https://github.com/AdaCore/ada_language_server][ada_language_server]]                       | Yes           | [[https://github.com/AdaCore/ada_language_server#install][Installation instructions]]                                                                               | Yes (gdb)                    |
   | Angular               | [[https://github.com/angular/vscode-ng-language-service/][vscode-ng-language-service]]                | Yes           | [[https://github.com/emacs-lsp/lsp-mode/wiki/Install-Angular-Language-server][Installation instructions]]                                                                               | Not relevant                 |
   | Bash                  | [[https://github.com/mads-hartmann/bash-language-server][bash-language-server]]                      | Yes           | npm i -g bash-language-server                                                                           |                              |
   | C++                   | [[https://github.com/MaskRay/ccls][ccls]]                                      | [[https://github.com/MaskRay/emacs-ccls][emacs-ccls]]    | [[https://github.com/MaskRay/ccls][ccls]]                                                                                                    | Yes (gdb or lldb)            |
   | C++                   | [[https://clang.llvm.org/extra/clangd.html][clangd]]                                    | Yes           | [[https://clang.llvm.org/extra/clangd.html][clangd]]                                                                                                  | Yes (gdb or lldb)            |
   | C++                   | [[https://github.com/cquery-project/cquery][cquery]]                                    | [[https://github.com/cquery-project/emacs-cquery][emacs-cquery]]  | [[https://github.com/cquery-project/cquery][cquery]]                                                                                                  | Yes (gdb or lldb)            |
   | C#                    | [[https://github.com/OmniSharp/omnisharp-roslyn][OmniSharp-Roslyn]]                          | Yes           | [[https://github.com/OmniSharp/omnisharp-roslyn][OmniSharp-Roslyn]]                                                                                        | No                           |
   | Clojure               | [[https://github.com/snoe/clojure-lsp][clojure-lsp]]                               | Yes           | [[https://github.com/snoe/clojure-lsp][clojure-lisp]]                                                                                            |                              |
   | Crystal               | [[https://github.com/crystal-lang-tools/scry][scry]]                                      | Yes           | [[https://github.com/crystal-lang-tools/scry][scry]]                                                                                                    |                              |
   | CSS/LessCSS/SASS/SCSS | [[https://github.com/vscode-langservers/vscode-css-languageserver-bin][css]]                                       | Yes           | npm install -g vscode-css-languageserver-bin                                                            |                              |
   | Dart                  | [[https://github.com/dart-lang/sdk/blob/master/pkg/analysis_server/tool/lsp_spec/README.md][dart_analysis_server]]                      | Yes           | built into dart-sdk                                                                                     |                              |
   | Dockerfile            | [[https://github.com/rcjsuen/dockerfile-language-server-nodejs][dockerfile-language-server-nodejs]]         | Yes           | npm install -g dockerfile-language-server-nodejs                                                        |                              |
   | Dart                  | [[https://github.com/natebosch/dart_language_server][dart_language_server]]                      | Yes           | pub global activate dart_language_server                                                                |                              |
   | Elixir                | [[https://github.com/JakeBecker/elixir-ls][elixir-ls]]                                 | Yes           | [[https://github.com/JakeBecker/elixir-ls][elixir-ls]]                                                                                               | Yes                          |
   | Elm                   | [[https://github.com/elm-tooling/elm-language-server][elmLS]]                                     | Yes           | npm i -g @elm-tooling/elm-language-server, or clone the repository and follow installation instructions | No                           |
   | Erlang                | [[https://github.com/erlang-ls/erlang_ls][erlang_ls]]                                 | Yes           | [[https://github.com/erlang-ls/erlang_ls][erlang_ls]]                                                                                               |                              |
   | F#                    | [[https://github.com/fsharp/FsAutoComplete][fsautocomplete]]                            | Yes           | Automatic by [[https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-fsharp.el][lsp-fsharp]]                                                                                 | No                           |
   | Fortran               | [[https://github.com/hansec/fortran-language-server][fortran-language-server]]                   | Yes           | pip install fortran-language-server                                                                     | Yes                          |
   | Go                    | [[https://github.com/golang/tools/tree/master/gopls][gopls]]                                     | Yes           | ~go get golang.org/x/tools/gopls@latest~ [[https://github.com/golang/tools/blob/master/gopls/doc/user.md#installation][docs]]                                                           | Yes                          |
   | Go                    | [[https://github.com/saibing/bingo][bingo]]                                     | Yes           | [[https://github.com/saibing/bingo/wiki/Install][bingo]]                                                                                                   | Yes                          |
   | Groovy                | [[https://github.com/palantir/language-servers][groovy-language-server]]                    | Yes           | [[https://github.com/palantir/language-servers][groovy-language-server]]                                                                                  |                              |
   | Hack                  | [[https://docs.hhvm.com/hhvm/][hhvm]]                                      | Yes           | [[https://docs.hhvm.com/hhvm/installation/introduction][hhvm]]                                                                                                    |                              |
   | HTML                  | [[https://github.com/vscode-langservers/vscode-html-languageserver][html]]                                      | Yes           | npm install -g vscode-html-languageserver-bin                                                           |                              |
   | Haskell               | [[https://github.com/haskell/haskell-ide-engine][IDE engine]]                                | [[https://github.com/emacs-lsp/lsp-haskell][lsp-haskell]]   | [[https://github.com/haskell/haskell-ide-engine][IDE engine]]                                                                                              |                              |
   | Lua                   | [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua]]                                   | Yes           | [[https://github.com/emacs-lsp/lsp-mode/wiki/Install-EmmyLua-Language-server][Installation]]                                                                                            |                              |
   | Java                  | [[https://github.com/eclipse/eclipse.jdt.ls][Eclipse JDT LS]]                            | [[https://github.com/emacs-lsp/lsp-java][lsp-java]]      | Automatic by [[https://github.com/emacs-lsp/lsp-java][lsp-java]]                                                                                   | Yes                          |
   | JavaScript/TypeScript | [[https://github.com/theia-ide/typescript-language-server][typescript-language-server]]  (recommended) | Yes           | npm i -g typescript-language-server; npm i -g typescript                                                | Yes (Firefox/Chrome)         |
   | JavaScript/TypeScript | [[https://github.com/sourcegraph/javascript-typescript-langserver][javascript-typescript-stdio]]               | Yes           | npm i -g javascript-typescript-langserver                                                               | Yes (Firefox/Chrome)         |
   | JavaScript Flow       | [[https://flow.org][flow]] (add-on if working on a Flow file)   | Yes           | [[https://flow.org][flow]]                                                                                                    | Yes (Firefox/Chrome)         |
   | Julia                 | [[https://github.com/non-Jedi/lsp-julia][lsp-julia]]                                 | [[https://github.com/non-Jedi/lsp-julia][lsp-julia]]     | [[https://github.com/JuliaEditorSupport/LanguageServer.jl][LanguageServer.jl]]                                                                                       |                              |
   | Kotlin                | [[https://github.com/fwcd/KotlinLanguageServer][kotlin-language-server]]                    | Yes           | [[https://github.com/fwcd/KotlinLanguageServer][kotlin-language-server]]                                                                                  |                              |
   | OCaml                 | [[https://github.com/ocaml-lsp/ocaml-language-server][ocaml-language-server]]                     | Yes           | [[https://github.com/ocaml-lsp/ocaml-language-server][ocaml-language-server]]                                                                                   |                              |
   | OCaml                 | [[https://github.com/merlin/ocaml][merlin]]                                    | Yes           | [[https://github.com/ocaml/merlin][merlin]]                                                                                                  |                              |
   | PHP(recommended)      | [[https://github.com/bmewburn/vscode-intelephense][intelephense]]                              | Yes           | npm i intelephense -g                                                                                   | Yes                          |
   | PHP                   | [[https://github.com/felixfbecker/php-language-server][php-language-server]]                       | Yes           | [[https://github.com/felixfbecker/php-language-server][php-language-server]]                                                                                     | Yes                          |
   | Powershell            | [[https://github.com/PowerShell/PowerShellEditorServices][PowerShellEditorServices]]                  | Yes           | Automatic                                                                                               | Yes                          |
   | Python                | [[https://github.com/palantir/python-language-server][pyls]]                                      | Yes           | pip install 'python-language-server[all]'                                                               | Yes                          |
   | Python(Microsoft)     | [[https://github.com/Microsoft/python-language-server][Microsoft Python Language Server]]          | [[https://github.com/andrew-christianson/lsp-python-ms/][lsp-python-ms]] | [[https://github.com/andrew-christianson/lsp-python-ms/][lsp-python-ms]]                                                                                           | Yes                          |
   | R                     | [[https://github.com/REditorSupport/languageserver][languageserver]]                            | Yes           | [[https://github.com/andrew-christianson/lsp-python-ms/][languageserver]]                                                                                          | No                           |
   | Ruby                  | [[https://github.com/castwide/solargraph][solargraph]]                                | Yes           | gem install solargraph                                                                                  | Yes                          |
   | Rust                  | [[https://github.com/rust-lang-nursery/rls][rls]]                                       | Yes           | [[https://github.com/rust-lang-nursery/rls][rls]]                                                                                                     | Yes                          |
   | Rust                  | [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]]                             | Yes           | [[https://github.com/rust-analyzer/rust-analyzer#language-server-quick-start][rust-analyzer]]                                                                                           |                              |
   | Scala                 | [[https://scalameta.org/metals][Metals]]                                    | Yes           | [[https://scalameta.org/metals/docs/editors/emacs.html][Metals]]                                                                                                  |                              |
   | Swift                 | [[https://github.com/apple/sourcekit-lsp][sourcekit-LSP]]                             | [[https://github.com/emacs-lsp/lsp-sourcekit][lsp-sourcekit]] | [[https://github.com/apple/sourcekit-lsp][sourcekit-LSP]]                                                                                           | Yes (via llvm debug adapter) |
   | Terraform             | [[https://github.com/juliosueiras/terraform-lsp][terraform-lsp]]                             | No            | Git clone outside of ~$GOPATH~; go install. (Requires go > 1.11)                                        | No                           |
   | TeX, LaTeX, etc.      | [[https://github.com/astoff/digestif][Digestif]]                                  | Yes           | luarocks install --server=http://luarocks.org/dev digestif                                              |                              |
   | VHDL                  | [[http://www.vhdltool.com][VHDL Tool]]                                 | Yes           | Download from http://www.vhdltool.com/download                                                          | No                           |
   | Vimscript             | [[https://github.com/iamcco/vim-language-server][vim-language-server]]                       | Yes           | npm install -g vim-language-server                                                                      | n/a                          |
   | Vue                   | [[https://github.com/vuejs/vetur/tree/master/server][vue-language-server]]                       | Yes           | npm install -g vue-language-server                                                                      | Yes (Firefox/Chrome)         |
   | XML                   | [[https://github.com/angelozerr/lsp4xml][lsp4xml]]                                   | Yes           | Download from [[https://github.com/angelozerr/lsp4xml/releases][lsp4xml releases]]                                                                          |                              |
   | YAML                  | [[https://github.com/redhat-developer/yaml-language-server][yaml]]                                      | Yes           | npm install -g yaml-language-server                                                                     |                              |
** Commands
   - ~lsp-describe-session~ - Display session folders and running servers.
   - ~lsp-describe-thing-at-point~ - Display help for the thing at point.
   - ~lsp-execute-code-action~ - Execute code action
   - ~lsp-format-buffer~ - Format current buffer
   - ~lsp-organize-imports~ - Organize library imports
   - ~lsp-goto-implementation~ - Go to implementation
   - ~lsp-goto-type-definition~ - Go to type definition
   - ~lsp-rename~ - Rename symbol at point
   - ~lsp-restart-workspace~ - Restart project
   - ~lsp-symbol-highlight~ - Highlight all relevant references to the symbol under point.
   - ~lsp-workspace-folders-add~ - Add workspace folder
   - ~lsp-workspace-folders-remove~ - Remove workspace folder
   - ~lsp-workspace-folders-open~ - Open a project directory in dired
   - ~imenu~ or ~helm-imenu~ - display document structure.
   - ~completion-at-point~ - display completion using built-in emacs ~completion-at-point~ framework.
   - ~lsp-find-definition~ - to find the definition for the symbol under point.
   - ~lsp-find-references~ - Find references for the symbol under point.
   - ~lsp-disconnect~ - Disconnect the buffer from the language server.
   - ~lsp-lens-show~ - Show lenses in the current file
   - ~lsp-lens-hide~ - Hide lenses in the current file
   - ~lsp-lens-mode~  - Turn on/off lenses in the current file.
   - ~lsp-avy-lens~ - Click lens using ~avy~
   - ~lsp-signature-activate~ - activate signature help. Bound to ~C-S-SPC~ by default.
   - ~lsp-signature-next~ - show next signature. Bound to ~M-n~ when signature help is activated.
   - ~lsp-signature-previous~ - show previous signature. Bound to ~M-p~ when signature help is activated.
   - ~lsp-signature-stop~ - cancel signature help. Bound to ~C-c C-k~ when signature help is activated.
** Settings
   - ~lsp-log-io~ - If non-nil, print all messages to and from the language server to ~*lsp-log*~.
   - ~lsp-print-performance~ - If non-nil, print performance info. to ~*lsp-log*~.
   - ~lsp-inhibit-message~ - If non-nil, inhibit the message echo via ~inhibit-message~.
   - ~lsp-report-if-no-buffer~ - If non nil the errors will be reported even when the file is not open.
   - ~lsp-keep-workspace-alive~ - If non nil keep workspace alive when the last workspace buffer is closed.
   - ~lsp-enable-snippet~ - Enable/disable snippet completion support.
   - ~lsp-auto-guess-root~ - Automatically guess the project root using projectile/project. Do *not* use this setting unless you are familiar with =lsp-mode= internals and you are sure that all of your projects are following =projectile=/=project.el= conventions.
   - ~lsp-restart~ - Defines how server exited event must be handled.
   - ~lsp-session-file~ - File where session information is stored.
   - ~lsp-auto-configure~ - Auto configure ~lsp-mode~. When set to t ~lsp-mode~ will auto-configure ~lsp-ui~ and ~company-lsp~.
   - ~lsp-document-sync-method~ - How to sync the document with the language server.
   - ~lsp-auto-execute-action~ - Auto-execute single action.
   - ~lsp-eldoc-render-all~ - Display all of the info returned by ~document/onHover~. If this is nil, ~eldoc~ will show only the symbol information.
   - ~lsp-enable-completion-at-point~ - Enable ~completion-at-point~ integration.
   - ~lsp-enable-xref~ - Enable xref integration.
   - ~lsp-prefer-flymake~ - If you prefer flycheck and ~lsp-ui-flycheck~ is available, ~(setq lsp-prefer-flymake nil)~. If set to ~:none~ neither of two will be enabled.
   - ~lsp-enable-indentation~ - Indent regions using the file formatting functionality provided by the language server.
   - ~lsp-enable-on-type-formatting~ - Enable ~textDocument/onTypeFormatting~ integration.
   - ~lsp-before-save-edits~ - If non-nil, ~lsp-mode~ will apply edits suggested by the language server before saving a document.
   - ~lsp-imenu-show-container-name~ - Display the symbol's container name in an imenu entry.
   - ~lsp-imenu-container-name-separator~ - Separator string to use to separate the container name from the symbol while displaying imenu entries.
   - ~lsp-imenu-sort-methods~ - How to sort the imenu items. The value is a list of ~kind~, ~name~ or ~position~. Priorities are determined by the index of the element.
   - ~lsp-response-timeout~ - Number of seconds to wait for a response from the language server before timing out.
   - ~lsp-enable-file-watchers~ - If non-nil lsp-mode will watch the files in the workspace if the server has requested that.
   - ~lsp-server-trace~ - Request trace mode on the language server.
   - ~lsp-enable-semantic-highlighting~ - Enable experimental semantic highlighting support
   - ~lsp-enable-imenu~ - If non-nil, automatically enable imenu integration when server provides ~textDocument/documentSymbol~.
   - ~lsp-signature-auto-activate~ - Auto activate signature when trigger char is pressed.
   - ~lsp-signature-render-documentation~ - Include signature documentation in signature help.
   - ~lsp-enable-text-document-color~ - Enable ~textDocument/documentColor~ when server supports it.
** Screenshots
   - RUST Completion with company-lsp
     [[file:examples/completion.png]]
   - Typescript references using lsp-ui
     [[file:examples/references.png]]
   - Debugging Python using dap-mode
     [[file:examples/python_debugging.png]]
   - Call hierarchy via ccls
     [[file:examples/call-hierarchy-ccls.png]]
   - Metals Doctor
     [[file:examples/metals-doctor.png]]
   - Semantic highlighting as provided by clangd (built from unreleased 10.0 branch). In this screenshot, all other font-locking has been disabled (hence no syntax highlighting of comments or basic keywords such as ~auto~)
     [[file:examples/clangd_semantic_highlighting.png]]

** Extensions
*** TRAMP
    LSP mode has support for tramp buffers with the following requirements:
    - The language server has to be present on the remote server.
    - Having multi folder language server (like [[https://github.com/eclipse/eclipse.jdt.ls][Eclipse JDT LS]]) cannot have local and remote workspace folders.
**** How does it work?
     ~lsp-mode~ detects whether a particular file is located on remote machine and looks for a client which matches current file and it is marked as ~:remote?~ t. Then ~lsp-mode~ starts the client through tramp.
**** Sample configuration
     Here it is example how you can configure python language server to work when using ~TRAMP~. Note that if you are trying to convert existing language server configuration you should copy all of it's properties(e. g. ~:request-handlers~, ~activation-fn~, etc).
     #+BEGIN_SRC emacs-lisp
       (lsp-register-client
        (make-lsp-client :new-connection (lsp-tramp-connection "binary-or-full-path")
                         :major-modes '(python-mode)
                         :remote? t
                         :server-id 'pyls-remote))
     #+END_SRC
**** Dealing with stderr
    With TRAMP, Emacs does not have an easy way to distinguish stdout and stderr, so when the underlying LSP process writes to stderr, it breaks the ~lsp-mode~ parser. As a workaround, ~lsp-mode~ is redirecting stderr to ~/tmp/<process-name>-<id>~stderr~.
** Limitations
*** File watches
    When some of the workspaces that are active in the current project requests file notifications via ~workspace/didChangeWatchedFiles~ ~lsp-mode~ will start monitoring each of the folders in the workspace for changes. In case your project contains a lot of files you might want to disable file monitoring via ~lsp-enable-file-watchers~ (you may use dir-locals).
** Contributions
   Contributions are very much welcome.

*** Members
    Here it is a list of the current =lsp-mode= members and what they are primary working on/responsible for.
    | Member         | Responsible for:                   |
    |----------------+------------------------------------|
    | [[https://github.com/TOTBWF][TOTBWF]]         | =F#=                               |
    | [[https://github.com/brotzeit][brotzeit]]       | =Rust=                             |
    | [[https://github.com/dsyzling][dsyzling]]       | =Scala=                            |
    | [[https://github.com/kurnevsky][kurnevsky]]      | =Scala= & =Rust=                   |
    | [[https://github.com/seagle0128][seagle0128]]     | =Go= & =MS Python Language Server= |
    | [[https://github.com/sebastiansturm][sebastiansturm]] | =lsp-mode= core & =C++=            |
    | [[https://github.com/vibhavp][vibhavp]]        | =lsp-mode= core                    |
    | [[https://github.com/yyoncho][yyoncho]]        | =lsp-mode= core and =Java=         |

** Troubleshooting
   - set ~lsp-log-io~ to ~t~ to inspect communication between client and the server. Use =lsp-workspace-show-log= to switch to the corresponding log buffer.
   - ~lsp-describe-session~ will show the current projects roots + the started severs and allows inspecting the server capabilities.
   #+caption: Describe session
   [[file:examples/describe.png]]
** Adding support for languages
*** Registering server
    Here it is the minimal configuration that is needed for new language server registration. Refer to the documentation of ~lsp-client.el~ for the additional settings supported on registration time. ~lsp-language-id-configuration~ must be updated to contain the corresponding mode -> language id - in this case ~(python-mode . "python")~
    #+BEGIN_SRC emacs-lisp
      (defvar lsp-language-id-configuration
        '(...
         (python-mode . "python")
         ...))
      ;; if you are adding the support for your language server in separate repo use
      ;; (add-to-list 'lsp-language-id-configuration '(python-mode . "python"))

      (lsp-register-client
       (make-lsp-client :new-connection (lsp-stdio-connection "pyls")
                        :major-modes '(python-mode)
                        :server-id 'pyls))
    #+END_SRC

If the language server supports environment variables to control additional behavior, you can register that by using the ~:environment-fn~ function, like the Bash language client does:

    #+BEGIN_SRC emacs-lisp
      (lsp-register-client
       (make-lsp-client :new-connection (lsp-stdio-connection '("bash-language-server" "start"))
                        :major-modes '(sh-mode)
                        :priority -1
                        :environment-fn (lambda ()
                                          (("EXPLAINSHELL_ENDPOINT" . lsp-bash-explainshell-endpoint)
                                           ("HIGHLIGHT_PARSING_ERRORS" . lsp-bash-highlight-parsing-errors)))
                        :server-id 'bash-ls))
    #+END_SRC

~lsp-bash-explainshell-endpoint~ and ~lsp-bash-highlight-parsing-errors~ are language client ~defcustom~ that expose supported server environment settings in a type-safe way. If you change any of those variables, restart the language server with ~lsp-restart-workspace~ for the changes to be applied.

*** Sections
    ~lsp-mode~ provides tools to bridge emacs ~defcustom~ as a language configuration sections properties(see [[https://microsoft.github.io/language-server-protocol/specification#workspace_configuration][specification workspace/configuration]]). In addition you may use ~lsp-generate-settings~ from [[https://github.com/emacs-lsp/lsp-mode/blob/master/scripts/lsp-generate-settings.el][Generate Settings script]] to generate ~defcustom~ from ~package.json~ VScode plugin manifest. Example:
    #+BEGIN_SRC emacs-lisp
      (defcustom lsp-foo-language-server-property "bar"
        "Demo property."
        :group 'foo-ls
        :risky t)

      (lsp-register-custom-settings '(("foo.section.property" lsp-foo-language-server-property)))

      (lsp-configuration-section  "foo")
      ;; =>  (("foo" ("settings" ("property" . "bar"))))
    #+END_SRC
** FAQ
   - How do I troubleshoot "Server FOO-LS:pid exited with status signal. Do you want to restart it? (y or n)"?
     - This message indicates that the language server has crashed for some
       reason. You may check the server stderr which is =*FOO-LS::stderr*=. If
       you get this message on startup you may try to run the exact command that
       =lsp-mode= is running in the terminal. You may find it in =*lsp-log*=
       buffer.
   - How to configure a server with local variables?
     - Add ~lsp~ server call to ~hack-local-variables-hook~ which runs right after the local variables are loaded.
       #+BEGIN_SRC emacs-lisp
         (add-hook 'hack-local-variables-hook
                   (lambda () (when (derived-mode-p 'XXX-mode) (lsp))))
       #+END_SRC
   - I have multiple language servers registered for language FOO. Which one will be used when opening a project?
     - The one with highest priority wins. ~lsp-clients.el~ predefined servers have
       priority -1, lower than external packages (priority 0 if unspecified). If a
       server is registered with ~:add-on?~ flag set to ~t~ it will be started in
       parallel to the other servers that are registered for the current mode.
   - I have multiple language servers for language =FOO= and I want to select the server per project, what can I do?
     - You may create =dir-local= for each of the projects and specify list of
       =lsp-enabled-clients=. This will narrow the list of the clients that are
       going to be tested for the project.
   - The completion does not work fine and inserts arguments and placeholders, what I am doing wrong?
     - Snippet support works only with =company-lsp= so if you are using
       =completion-at-point= the snippets won't be expanded and you should
       either disable them by setting =lsp-enable-snippet= to =nil= or you
       should switch to =company-lsp=. Note also that =company-tng= frontend
       does not support snippet expansion(see [[https://github.com/company-mode/company-mode/issues/891][company-mode#891]])
   - How to automatically follow =lsp-ui-log=?
     - Go into the log buffer and execute the following snippet(source: [[https://stackoverflow.com/questions/12663061/emacs-auto-scrolling-log-buffer][Emacs auto scrolling log buffer]])
     #+begin_src elisp
       (set (make-local-variable 'window-point-insertion-type) t)
     #+end_src
   - I am getting "Package ‘spinner-1.7.3’ is unavailable" when trying to install =lsp-mode=.
     - This is caused by GPG keys used by the ELPA package manager not being up
      to date. You may fix by installing: [[https://elpa.gnu.org/packages/gnu-elpa-keyring-update.html][gnu-elpa-keyring-update]]
** See also
   - [[https://github.com/emacs-lsp/lsp-docker/][lsp-docker]] - provide docker image with preconfigured language servers with corresponding emacs configuration.
   - [[https://github.com/sebastiencs/company-box/][company-box]] - =company= frontend with icons.
   - [[https://github.com/yyoncho/dap-mode][dap-mode]] - Debugger integration for ~lsp-mode~.
   - [[https://github.com/joaotavora/eglot][eglot]] - An alternative minimal LSP implementation.
