|
| 1 | +# BSP Extensions |
| 2 | + |
| 3 | +SourceKit-LSP extends the BSP protocol in the following ways. |
| 4 | + |
| 5 | +## `build/initialize` |
| 6 | + |
| 7 | +`InitializeBuildResultDataKind` can be `sourceKit`, in which case `InitializeBuildResultData` contains the following data. |
| 8 | + |
| 9 | +```ts |
| 10 | +export interface SourceKitInitializeBuildResponseData { |
| 11 | + /** The directory to which the index store is written during compilation, ie. the path passed to `-index-store-path` |
| 12 | + * for `swiftc` or `clang` invocations **/ |
| 13 | + indexStorePath?: string; |
| 14 | + |
| 15 | + /** The path at which SourceKit-LSP can store its index database, aggregating data from `indexStorePath` */ |
| 16 | + indexDatabasePath?: string; |
| 17 | + |
| 18 | + /** Whether the build server supports the `buildTarget/prepare` request */ |
| 19 | + supportsPreparation?: bool; |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +## `buildTarget/didChange` |
| 24 | + |
| 25 | +`changes` can be `null` to indicate that all targets have changed. |
| 26 | + |
| 27 | +## `buildTarget/prepare` |
| 28 | + |
| 29 | +The prepare build target request is sent from the client to the server to prepare the given list of build targets for editor functionality. |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +The server communicates during the initialize handshake whether this method is supported or not by setting `supportsPreparation` in `SourceKitInitializeBuildResponseData`. |
| 34 | + |
| 35 | +- method: `buildTarget/prepare` |
| 36 | +- params: `PrepareParams` |
| 37 | + |
| 38 | +```ts |
| 39 | +export interface PrepareParams { |
| 40 | + /** A list of build targets to prepare. */ |
| 41 | + targets: BuildTargetIdentifier[]; |
| 42 | + |
| 43 | + /** A unique identifier generated by the client to identify this request. |
| 44 | + * The server may include this id in triggered notifications or responses. **/ |
| 45 | + originId?: OriginId; |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +## `builtTarget/sources` |
| 50 | + |
| 51 | +`SourceItemDataKind` can be `sourceKit` in which case `SourceItem.data` contains the following data. |
| 52 | + |
| 53 | +```ts |
| 54 | +export interface SourceKitSourceItemData { |
| 55 | + /** The language of the source file. If `nil`, the language is inferred from the file extension. */ |
| 56 | + language? LanguageId; |
| 57 | + |
| 58 | + /** Whether the file is a header file that is clearly associated with one target. |
| 59 | + * |
| 60 | + * For example header files in SwiftPM projects are always associated to one target and SwiftPM can provide build |
| 61 | + * settings for that header file. |
| 62 | + * |
| 63 | + * In general, build systems don't need to list all header files in the `buildTarget/sources` request: Semantic |
| 64 | + * functionality for header files is usually provided by finding a main file that includes the header file and |
| 65 | + * inferring build settings from it. Listing header files in `buildTarget/sources` allows SourceKit-LSP to provide |
| 66 | + * semantic functionality for header files if they haven't been included by any main file. **/ |
| 67 | + isHeader?: bool; |
| 68 | +} |
| 69 | +``` |
| 70 | +
|
| 71 | +## `textDocument/sourceKitOptions` |
| 72 | +
|
| 73 | +The `TextDocumentSourceKitOptionsRequest` request is sent from the client to the server to query for the list of compiler options necessary to compile this file in the given target. |
| 74 | +
|
| 75 | +The build settings are considered up-to-date and can be cached by SourceKit-LSP until a `buildTarget/didChange` is sent for the requested target. |
| 76 | +
|
| 77 | +The request may return `nil` if it doesn't have any build settings for this file in the given target. |
| 78 | +
|
| 79 | +- method: `textDocument/sourceKitOptions` |
| 80 | +- params: `TextDocumentSourceKitOptionsParams` |
| 81 | +- result: `TextDocumentSourceKitOptionsResult` |
| 82 | +
|
| 83 | +```ts |
| 84 | +export interface TextDocumentSourceKitOptionsRequest { |
| 85 | + /** The URI of the document to get options for */ |
| 86 | + textDocument: TextDocumentIdentifier; |
| 87 | + |
| 88 | + /** The target for which the build setting should be returned. |
| 89 | + * |
| 90 | + * A source file might be part of multiple targets and might have different compiler arguments in those two targets, |
| 91 | + * thus the target is necessary in this request. **/ |
| 92 | + target: BuildTargetIdentifier; |
| 93 | + |
| 94 | + /** The language with which the document was opened in the editor. */ |
| 95 | + language: LanguageId; |
| 96 | +} |
| 97 | + |
| 98 | +export interface TextDocumentSourceKitOptionsResult { |
| 99 | + /** The compiler options required for the requested file. */ |
| 100 | + compilerArguments: string[]; |
| 101 | + |
| 102 | + /** The working directory for the compile command. */ |
| 103 | + workingDirectory?: string; |
| 104 | +} |
| 105 | +``` |
| 106 | +
|
| 107 | +## `window/workDoneProgress/create` |
| 108 | +
|
| 109 | +Request from the build server to SourceKit-LSP to create a work done progress. |
| 110 | +
|
| 111 | +Definition is the same as in LSP. |
| 112 | +
|
| 113 | +## `workspace/buildTargets` |
| 114 | +
|
| 115 | +`BuildTargetTag` can have the following additional values |
| 116 | +
|
| 117 | +```ts |
| 118 | +export interface BuildTargetTag { |
| 119 | + // ... |
| 120 | + |
| 121 | + /** This is a target of a dependency from the project the user opened, eg. a target that builds a SwiftPM dependency. */ |
| 122 | + export const Dependency = "dependency"; |
| 123 | + |
| 124 | + /** This target only exists to provide compiler arguments for SourceKit-LSP can't be built standalone. |
| 125 | + * |
| 126 | + * For example, a SwiftPM package manifest is in a non-buildable target. **/ |
| 127 | + export const NotBuildable = "not-buildable"; |
| 128 | +} |
| 129 | +``` |
| 130 | +
|
| 131 | +`BuildTargetDataKind` can be `sourceKit` in which case `BuildTarget.data` contains the following data. |
| 132 | +
|
| 133 | +
|
| 134 | +```ts |
| 135 | +export interface SourceKitBuildTarget { |
| 136 | + /** The toolchain that should be used to build this target. The URI should point to the directory that contains the |
| 137 | + * `usr` directory. On macOS, this is typically a bundle ending in `.xctoolchain`. If the toolchain is installed to |
| 138 | + * `/` on Linux, the toolchain URI would point to `/`. |
| 139 | + * |
| 140 | + * If no toolchain is given, SourceKit-LSP will pick a toolchain to use for this target. **/ |
| 141 | + toolchain?: URI; |
| 142 | +} |
| 143 | +``` |
| 144 | +
|
| 145 | +## `workspace/didChangeWatchedFiles` |
| 146 | +
|
| 147 | +Notification sent from SourceKit-LSP to the build system to indicate that files within the project have been modified. |
| 148 | +
|
| 149 | +Definition is the same as in LSP. |
| 150 | +
|
| 151 | +## `workspace/waitForBuildSystemUpdates` |
| 152 | +
|
| 153 | +This request is a no-op and doesn't have any effects. |
| 154 | +
|
| 155 | +If the build system is currently updating the build graph, this request should return after those updates have finished processing. |
| 156 | +
|
| 157 | +- method: `workspace/waitForBuildSystemUpdates` |
| 158 | +
|
| 159 | +## `$/progress` |
| 160 | +
|
| 161 | +Notification from the build server to SourceKit-LSP to update a work done progress created using `window/workDoneProgress/create`. |
| 162 | +
|
| 163 | +Definition is the same as in LSP. |
0 commit comments