Merge pull request #1731 from ahoppen/bsp-implementation-documentation

Add a document that describes the basic steps needed to implement a BSP server

Author: ahoppen

Contributor Documentation/BSP Extensions.md

@@ -18,7 +18,8 @@ export interface SourceKitInitializeBuildResponseData {
    * for `swiftc` or `clang` invocations **/
   indexStorePath?: string;
 
-  /** The path at which SourceKit-LSP can store its index database, aggregating data from `indexStorePath` */
+  /** The path at which SourceKit-LSP can store its index database, aggregating data from `indexStorePath`.
+   * This should point to a directory that can be exclusively managed by SourceKit-LSP. Its exact location can be arbitrary. */
   indexDatabasePath?: string;
 
   /** Whether the build server supports the `buildTarget/prepare` request */
@@ -42,9 +43,9 @@ export interface SourceKitInitializeBuildResponseData {
 
 The prepare build target request is sent from the client to the server to prepare the given list of build targets for editor functionality.
 
-To do so, the build server should build Swift modules for all dependencies of this module so that all `import` statements in this module can be resolved.
+To do so, the build server should perform any work that is necessary to typecheck the files in the given target. This includes, but is not limited to: Building Swift modules for all dependencies and running code generation scripts. Compared to a full build, the build server may skip actions that are not necessary for type checking, such as object file generation but the exact steps necessary are dependent on the build system. SwiftPM implements this step using the `swift build --experimental-prepare-for-indexing` command.
 
-The server communicates during the initialize handshake whether this method is supported or not by setting `supportsPreparation` in `SourceKitInitializeBuildResponseData`.
+The server communicates during the initialize handshake whether this method is supported or not by setting `prepareProvider: true` in `SourceKitInitializeBuildResponseData`.
 
 - method: `buildTarget/prepare`
 - params: `PrepareParams`

Contributor Documentation/Implementing a BSP server.md

@@ -0,0 +1,46 @@
+# Implementing a BSP server
+
+SourceKit-LSP can connect to any build system to provide semantic functionality through the [Build Server Protocol (BSP)](https://build-server-protocol.github.io). This is a short guide of the requests and notifications that a BSP server for SourceKit-LSP should implement. For more detailed information, refer to the [BSP spec](https://build-server-protocol.github.io/docs/specification) and the [SourceKit-LSP BSP Extensions](BSP%20Extensions.md). This document just references BSP methods and properties and those specification documents contain their documentation.
+
+## Required lifecycle methods
+
+In order to be launched and shut down successfully, the BSP server must implement the following methods
+
+- `build/initialize`
+- `build/initialized`
+- `build/shutdown`
+- `build/exit`
+
+The `build/initialize` response must have `dataKind: "sourceKit"` and `data.sourceKitOptionsProvider: true`. In order to provide global code navigation features such as call hierarchy and global rename, the build server must set `data.indexDatabasePath` and `data.indexStorePath`.
+
+## Retrieving build settings
+
+In order to provide semantic functionality for source files, the BSP server must provide the following methods:
+
+- `workspace/buildTargets`
+- `buildTarget/sources`
+- `textDocument/sourceKitOptions`
+- `buildTarget/didChange`
+- `workspace/waitForBuildSystemUpdates`
+
+If the build system does not have a notion of targets, eg. because it provides build settings from a file akin to a JSON compilation database, it may use a single dummy target for all source files or a separate target for each source file, either choice will work.
+
+If the build system loads the entire build graph during initialization, it may immediately return from `workspace/waitForBuildSystemUpdates`.
+
+
+## Supporting background indexing
+
+To support background indexing, the build system must set `data.prepareProvider: true` in the `build/initialize` response and implement the `buildTarget/prepare` method.
+
+## Optional methods
+
+The following methods are not necessary to implement for SourceKit-LSP to work but might help with the implementation of the build server.
+
+- `build/logMessage`
+- `window/workDoneProgress/create`
+- `workspace/didChangeWatchedFiles`
+- `$/progress`
+
+## Build server discovery
+
+To make your build server discoverable, create a [BSP connection specification](https://build-server-protocol.github.io/docs/overview/server-discovery) file named `buildServer.json` in the root of your project.

Contributor Documentation/README.md

@@ -3,7 +3,9 @@
 The following documentation documents are primarily intended for developers of SourceKit-LSP.
 
 - [Background Indexing](Background%20Indexing.md)
+- [BSP Extension](BSP%20Extensions.md)
 - [Files To Reindex](Files%20To%20Reindex.md)
+- [Implementing a BSP server](Implementing%20a%20BSP%20server.md)
 - [LSP Extensions](LSP%20Extensions.md)
 - [Logging](Logging.md)
 - [Modules](Modules.md)

Sources/BuildServerProtocol/Messages/BuildTargetPrepareRequest.swift

@@ -21,10 +21,14 @@ public typealias OriginId = String
 /// The prepare build target request is sent from the client to the server to prepare the given list of build targets
 /// for editor functionality.
 ///
-/// To do so, the build server should build Swift modules for all dependencies of this module so that all `import`
-/// statements in this module can be resolved.
+/// To do so, the build server should perform any work that is necessary to typecheck the files in the given target.
+/// This includes, but is not limited to: Building Swift modules for all dependencies and running code generation scripts.
+/// Compared to a full build, the build server may skip actions that are not necessary for type checking, such as object
+/// file generation but the exact steps necessary are dependent on the build system. SwiftPM implements this step using
+/// the `swift build --experimental-prepare-for-indexing` command.
 ///
-/// The server communicates during the initialize handshake whether this method is supported or not.
+/// The server communicates during the initialize handshake whether this method is supported or not by setting
+/// `prepareProvider: true` in `SourceKitInitializeBuildResponseData`.
 public struct BuildTargetPrepareRequest: RequestType, Hashable {
   public static let method: String = "buildTarget/prepare"
   public typealias Response = VoidResponse