mirror of
https://github.com/microsoft/language-server-protocol.git
synced 2025-12-23 08:48:16 +00:00
Initial comments
This commit is contained in:
Erich Gamma
parent
5ba54984f5
commit
bfad6aa43e
4 changed files with 43 additions and 27 deletions
|
|
@ -147,8 +147,6 @@ GEM
|
|||
jekyll (~> 3.3)
|
||||
jekyll-titles-from-headings (0.2.0)
|
||||
jekyll (~> 3.3)
|
||||
jekyll-toc (0.4.0)
|
||||
nokogiri (~> 1.6)
|
||||
jekyll-watch (1.5.1)
|
||||
listen (~> 3.0)
|
||||
jemoji (0.8.0)
|
||||
|
|
@ -180,7 +178,7 @@ GEM
|
|||
ffi (>= 0.5.0, < 2)
|
||||
rouge (1.11.1)
|
||||
safe_yaml (1.0.4)
|
||||
sass (3.5.3)
|
||||
sass (3.5.4)
|
||||
sass-listen (~> 4.0.0)
|
||||
sass-listen (4.0.0)
|
||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
||||
|
|
@ -203,12 +201,11 @@ PLATFORMS
|
|||
DEPENDENCIES
|
||||
github-pages
|
||||
jekyll (= 3.4.3)
|
||||
jekyll-toc
|
||||
jemoji
|
||||
tzinfo-data
|
||||
|
||||
RUBY VERSION
|
||||
ruby 2.3.5p376
|
||||
ruby 2.4.3p205
|
||||
|
||||
BUNDLED WITH
|
||||
1.16.0
|
||||
|
|
|
|||
|
|
@ -4,23 +4,22 @@ layout: singlePage
|
|||
sectionid: howItWorks
|
||||
---
|
||||
|
||||
A language server runs in its own process and tools like VS Code communicate with the server using the language protocol over JSON-RPC. Another nice side effect of the language server operating in a dedicated process is that performance issues related to a single process model are avoided. The actual transport channel can either be `stdio`, `sockets`, `named pipes`, or `node ipc` if both the client and server are written in Node.js.
|
||||
|
||||
Below is an example for how a tool and a language server communicate during a routine editing session:
|
||||
A language server runs as a separate process and development tools communicate with the server using the language protocol over JSON-RPC. Below is an example for how a tool and a language server communicate during a routine editing session:
|
||||
|
||||
** To Do ** Replace VS Code in the diagram with Development Tool to make it VS Code neutral
|
||||
|
||||
|
||||
* **The user opens a file (referred to as a *document*) in the tool**: The tool notifies the language server that a document is open ('textDocument/didOpen'). From now on, the truth about the contents of the document is no longer on the file system but kept by the tool in memory.
|
||||
* **The user opens a file (referred to as a *document*) in the tool**: The tool notifies the language server that a document is open ('textDocument/didOpen'). From now on, the truth about the contents of the document is no longer on the file system but kept by the tool in memory. The contents now has to be synchronized between the tool and the language server.
|
||||
|
||||
* **The user makes edits**: The tool notifies the server about the document change ('textDocument/didChange') and the semantic information of the program is updated by the language server. As this happens, the language server analyses this information and notifies the tool with the detected errors and warnings ('textDocument/publishDiagnostics').
|
||||
* **The user makes edits**: The tool notifies the server about the document change ('textDocument/didChange') and the language representation of the document is updated by the language server. As this happens, the language server analyses this information and notifies the tool with the detected errors and warnings ('textDocument/publishDiagnostics').
|
||||
|
||||
* **The user executes "Go to Definition" on a symbol in the editor**: The tool sends a 'textDocument/definition' request with two parameters: (1) the document URI and (2) the text position from where the Go to Definition request was initiated to the server. The server responds with the document URI and the position of the symbol's definition inside the document.
|
||||
* **The user executes "Go to Definition" on a symbol of an open document**: The tool sends a 'textDocument/definition' request with two parameters: (1) the document URI and (2) the text position from where the 'Go to Definition' request was initiated to the server. The server responds with the document URI and the position of the symbol's definition inside the document.
|
||||
|
||||
* **The user closes the document (file)**: A 'textDocument/didClose' notification is sent from the tool, informing the language server that the document is now no longer in memory and that the current contents is now up to date on the file system.
|
||||
* **The user closes the document (file)**: A 'textDocument/didClose' notification is sent from the tool informing the language server that the document is now no longer in memory. The current contents is now up to date on the file system.
|
||||
|
||||
This example illustrates how the protocol communicates with the language server at the level of editor features like "Go to Definition", "Find all References". The data types used by the protocol are editor or IDE 'data types' like the currently open text document and the position of the cursor. The data types are not at the level of a programming language domain model which would usually provide abstract syntax trees and compiler symbols (for example, resolved types, namespaces, ...). This simplifies the protocol significantly.
|
||||
This example illustrates how the protocol communicates with the language server at the level of document references (URIs) and document positions. These data types are programming language neutral and apply to all programming languages. The data types are not from the domain model typically abstract syntax trees and compiler symbols (for example, resolved types, namespaces, ...) from a language implementation. The fact, that the data types are simple and apply to all all languages simplifies the protocol significantly. It is much simpler to standardize a text document URI or a cursor position compared with standardizing an abstract syntax tree and compiler symbols across different programming languages.
|
||||
|
||||
Now let's look at the 'textDocument/definition' request in more detail. Below are the payloads that go between the client tool and the language server for the "Go to Definition" request in a C++ document.
|
||||
Now let's look at the 'textDocument/definition' request in more detail. Below are the payloads that go between the development tool and the language server for the "Go to Definition" request in a C++ document.
|
||||
|
||||
This is the request:
|
||||
|
||||
|
|
@ -63,14 +62,18 @@ This is the response:
|
|||
}
|
||||
```
|
||||
|
||||
In retrospect, describing the data types at the level of the editor rather than at the level of the programming language model is one of the reasons for the success of the language server protocol. It is much simpler to standardize a text document URI or a cursor position compared with standardizing an abstract syntax tree and compiler symbols across different programming languages.
|
||||
|
||||
When a user is working with different languages, VS Code typically starts a language server for each programming language. The example below shows a session where the user works on Java and SASS files.
|
||||
When a user is working with different languages, a development tools usually starts a language server for each programming language. The example below shows a session where the user works on Java and SASS files.
|
||||
|
||||
|
||||
|
||||
We quickly learned that not every language server can support all features defined by the protocol. We therefore introduced the concept of 'capabilities'. With capabilities, the client and server announces their supported feature set. As an example, a server announces that it can handle the 'textDocument/definition' request, but it might not handle the 'workspace/symbol' request. Similarly, clients can announce that they are able to provide 'about to save' notifications before a document is saved, so that a server can compute textual edits to automatically format the edited document.
|
||||
Not every language server can support all features defined by the protocol. LSP therefore defines 'capabilities'. A capability defines a related group of language features. A development tools and the language server announce their supported feature set. As an example, a server announces that it can handle the 'textDocument/definition' request, but it might not handle the 'workspace/symbol' request. Similarly, development tools can announce that they are able to provide 'about to save' notifications before a document is saved, so that a server can compute textual edits to automatically format the edited document.
|
||||
|
||||
The actual integration of a language server into a particular tool is not defined by the language server protocol and is left to the tool implementors. Some tools integrate language servers generically by having an extension that can start and talk to any kind of language server. Others, like VS Code, create a custom extension per language server, so that an extension is still able to provide some custom language features.
|
||||
**Notice** the actual integration of a language server into a particular tool is not defined by the language server protocol and is left to the tool implementors.
|
||||
|
||||
To simplify the implementation of language servers and clients, there are libraries or SDKs for the client and server parts. These libraries are provided for different languages. For example, we maintain a [language client npm module](https://www.npmjs.com/package/vscode-languageclient) to ease the integration of a language server into a VS Code extension and another [language server npm module](https://www.npmjs.com/package/vscode-languageserver) to write a language server using Node.js. This is the current [list](https://github.com/Microsoft/language-server-protocol/wiki/Protocol-Implementations#sdks) of support libraries.
|
||||
## Libraries (SDKs) for LSP providers and consumers
|
||||
|
||||
To simplify the implementation of language servers and clients, there are libraries or SDKs:
|
||||
|
||||
- *Development tool SDKs* each development tool typically provides a library for integrating language servers. For example, for JavaScript/TypeScript there is a [language client npm module](https://www.npmjs.com/package/vscode-languageclient)
|
||||
|
||||
- *Language Server SDKs* for the different implementation languages there is an SDK to implement a language server in a particular language. For example, to implementat a language server using Node.js there is [language server npm module](https://www.npmjs.com/package/vscode-languageserver).
|
||||
|
|
|
|||
15
index.html
15
index.html
|
|
@ -6,7 +6,7 @@ layout: default
|
|||
<div class="container">
|
||||
<h1>Language Server Protocol</h1>
|
||||
<p>
|
||||
The Language Server protocol is used between a tool (the client) and a language smartness provider (the server) to integrate features like auto complete, goto definition, find all references and alike into the tool.
|
||||
The Language Server Protocol (LSP) defines the protocol used between an editor or IDE to talk to a language server that provides language features like auto complete, goto definition, find all references.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -18,7 +18,8 @@ layout: default
|
|||
<div class="col-lg-12">
|
||||
<h2 class="header-light regular-pad">What is the Language Server Protocol?</h2>
|
||||
<blockquote>
|
||||
<p>Supporting rich editing features like code auto-completions or "Go to Definition" for a programming language in an editor or IDE is traditionally very challenging and time consuming. Usually it requires writing a domain model (a scanner, a parser, a type checker, a builder and more) in the programming language of the editor or IDE. Things would be a lot easier if a development tool could reuse existing libraries. However, these libraries are usually implemented in the programming language itself (for example, good C/C++ domain models are implemented in C/C++). Integrating a C/C++ library into an editor written in TypeScript is technically possible but hard to do. Alternatively, we can run the library in its own process and use inter-process communication to talk to it. The messages sent back and forth form a protocol. The language server protocol (LSP) is the product of standardizing the messages exchanged between a development tool and a language server process.</p>
|
||||
<p>Implementing language support like auto complete, goto definition, or type hovering for a programming language for different development tools is a significant effort. Each development tool provides different APIs for language extenders. Moreover, an extension has to be implemented in the implementation language of the tool itself. This requires to implement the smartness for a language multiple times and this in different languages. It is not possible to share this language smartness across tools. The idea behind a <i>Language Server</i> is to provide the language smarts inside a server and using inter process communication and a protocl between the development tool and the this server to support a particular language. When each language server provides a different protocol then the tool integrator has to integrate support for each language differently. The idea behind the <i>Language Server Protocol</i> is to standardize this protocol and therefore to simplify the integration of different language servers in a development tool. This is a win for both the language provider and the development tool provider!
|
||||
</p>
|
||||
</blockquote>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -28,24 +29,24 @@ layout: default
|
|||
<div class="row">
|
||||
<div class="col-lg-4">
|
||||
<h1 class="text-center"><i class="fa fa-cogs" aria-hidden="true"></i></h1>
|
||||
<a href='{{ "/howItWorks" | prepend: site.baseurl }}'><h3 class="text-center">How the LSP Works</h3></a>
|
||||
<a href='{{ "/howItWorks" | prepend: site.baseurl }}'><h3 class="text-center">How the Protocol Works</h3></a>
|
||||
<p>
|
||||
A language server runs in its own process and tools like VS Code communicate with the server using the language protocol over JSON-RPC.
|
||||
The protocol defines format of the messages sent using JSON-RPC between development tool and the language server.
|
||||
</p>
|
||||
</div>
|
||||
<div class="col-lg-4">
|
||||
<h1 class="text-center"><i class="fas fa-code-branch" aria-hidden="true"></i></h1>
|
||||
{% assign sorted = site.implementors | sort: 'index' %}
|
||||
<a href = "{{ sorted.first.url | prepend: site.baseurl }}"><h3 class="text-center">Implementors</h3></a>
|
||||
<a href = "{{ sorted.first.url | prepend: site.baseurl }}"><h3 class="text-center">Supporters</h3></a>
|
||||
<p>
|
||||
There are three different kinds of LSP implementors: server providing editing features for programming language, tool integrations and LSP SDKs.
|
||||
The LSP has been implemented for many languages and many development tools integrate these language servers. To simplify the implementation and integration of LSP there are different libraries/SDKs provided.
|
||||
</p>
|
||||
</div>
|
||||
<div class="col-lg-4">
|
||||
<h1 class="text-center"><i class="far fa-clock" aria-hidden="true"></i></h1>
|
||||
<a href='{{ "/specification" | prepend: site.baseurl }}'><h3 class="text-center">Specification</h3></a>
|
||||
<p>
|
||||
Version 3.0 of the protocol has been around for some time. Our current focus is to stabilize and clarify the specification.
|
||||
The lastet version of the protocol specification is version 3.0.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
15
notes.md
Normal file
15
notes.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
### General
|
||||
- make the doc VS Code neutral. e.g. VS Code => Development tool
|
||||
- make the diagrams VS Code neutral where possible
|
||||
- do not use WE use the LSP
|
||||
- Terminology
|
||||
- Development Tool instead of client
|
||||
- implementations instead of implementors?
|
||||
|
||||
### Contents
|
||||
- needs link back to the language server repo for filing issues etc. Add a contributing section with links to the repo
|
||||
- link from protocol to screenshots illustrating how this is exposed (can we link to the VS Code images, have a separate page).
|
||||
- glossary? development tool (not client), language server, SDK
|
||||
|
||||
### Layout
|
||||
- home page: less space below the header page
|
||||
Loading…
Add table
Add a link
Reference in a new issue