Skip to content

Commit 9618df8

Browse files
committed
Add documentation about each module's purpose and move some files between modules
The purpose of the different modules wasn’t clearly defined, which lead to inconsistent responsibilities between the different modules. Define each module’s purpose and move a few files between modules to satisfy these definitions. There are a few more larger changes that will need to be made for a fully consistent module structure. These are FIXMEs in the new Modules.md document and I’ll address them in follow-up PRs.
1 parent a4ab8c4 commit 9618df8

27 files changed

+165
-62
lines changed

Documentation/Modules.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Modules
2+
3+
The SourceKit-LSP package contains the following non-testing modules.
4+
5+
### BuildServerProtocol
6+
7+
Swift types to represent the [Build Server Protocol (BSP) specification, version TODO](TODO). These types should also be usable when implementing a BSP client and thus this module should not have any dependencies other than the LanguageServerProtocol module, with which it shares some types.
8+
9+
FIXME: Add link for BSP and version
10+
11+
### CAtomics
12+
13+
Implementation of atomics for Swift using C. Once we can raise our deployment target to use the `Atomic` type from the Swift standard library, this module should be removed.
14+
15+
### CSKTestSupport
16+
17+
FIXME: Can we remove this?
18+
19+
### Csourcekitd
20+
21+
Header file defining the interface to sourcekitd. This should stay in sync with [sourcekitd.h](TODO) in the Swift repository.
22+
23+
### Diagnose
24+
25+
A collection of subcommands to the `sourcekit-lsp` executable that help SourceKit-LSP diagnose issues.
26+
27+
### InProcessClient
28+
29+
A simple type that allows launching a SourceKit-LSP server in-process, communicating in terms of structs from the `LanguageServerProtocol` module.
30+
31+
This should be the dedicated entry point for clients that want to run SourceKit-LSP in-process instead of launching a SourceKit-LSP server out-of-process and communicating with it using JSON RPC.
32+
33+
### LanguageServerProtocol
34+
35+
Swift types to represent the [Language Server Protocol (LSP) specification, version 3.17](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/). These types should also be usable when implementing an LSP client and thus this module should not have any dependencies.
36+
37+
### LanguageServerProtocolJSONRPC
38+
39+
A connection to or from a SourceKit-LSP server. Since message parsing can fail, it needs to handle errors in some way and the design decision here is to use LSPLogging, which hardcodes `org.swift.sourcekit-lsp` as the default logging subsystem and thus makes the module unsuitable for generic clients.
40+
41+
### LSPLogging
42+
43+
Types that are API-compatible with OSLog to allow logging to OSLog when building for Darwin platforms and logging to stderr or files on non-Darwin platforms. This should not be dependent on any LSP specific types and be portable to other packages.
44+
45+
FIXME: Rename the module to SKLogging
46+
47+
### LSPTestSupport
48+
49+
FIXME: Merge this module with SKTestSupport
50+
51+
### SemanticIndex
52+
53+
Contains the interface with which SourceKit-LSP queries the semantic index, adding up-to-date checks on top of the indexstore-db API. Also implements the types that manage background indexing.
54+
55+
### SKCore
56+
57+
FIXME: Currently serves two independent purposes and should be split up into two modules
58+
59+
#### BuildSystem
60+
61+
Defines the queries SourceKit-LSP can ask of a a build system, like getting compiler arguments for a file. Finding a target’s dependencies or preparing a target.
62+
63+
This includes:
64+
- BuildConfiguration.swift
65+
- BuildServerBuildSystem.swift
66+
- BuildSetup.swift
67+
- BuildSystem.swift
68+
- BuildSystemDelegate.swift
69+
- BuildSystemManager.swift
70+
- CompilationDatabase.swift
71+
- CompilationDatabaseBuildSystem.swift
72+
- FallbackBuildSystem.swift
73+
- FileBuildSettings.swift
74+
- IndexTaskID.swift
75+
- MainFilesProvider.swift
76+
- PathPrefixMapping.swift
77+
- SplitShellCommand.swift
78+
- WorkspaceType.swift
79+
80+
#### ToolchainRegistry
81+
82+
Discovers Swift toolchains on the system.
83+
84+
- Toolchain.swift
85+
- ToolchainRegistry.swift
86+
- XCToolchainPlist.swift
87+
88+
89+
### SKSupport
90+
91+
Contains SourceKit-LSP-specific helper functions. These fall into three different categories:
92+
- Extensions on top of `swift-tools-support-core`
93+
- Functionality that can only be implemented by combining two lower-level modules that don't have a shared dependency, like `LSPLogging` + `LanguageServerProtocol`
94+
- Types that should be sharable by the different modules that implement SourceKit-LSP but that are not generic enough to fit into `SwiftExtensions`, like `ExperimentalFeatures`.
95+
96+
### SKSwiftPMWorkspace
97+
98+
Implements the `BuildSystem` protocol for Swift packages.
99+
100+
FIXME: Merge this into the BuildSystem module once SKCore is split.
101+
102+
### SKTestSupport
103+
104+
A collection of utilities useful for writing tests for SourceKit-LSP and which are not specific to a single test module.
105+
106+
### sourcekit-lsp
107+
108+
This executable target that produces the `sourcekit-lsp` binary.
109+
110+
### SourceKitD
111+
112+
A Swift interface to talk to sourcekitd.
113+
114+
### SourceKitLSP
115+
116+
This is the core module that implements the SourceKit-LSP server.
117+
118+
### SwiftExtensions
119+
120+
Extensions to the Swift standard library and Foundation. Should not have any other dependencies. Any types in here should theoretically make senses to put in the Swift standard library or Foundation and they shouldn't be specific to SourceKit-LSP
121+

Package.swift

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,9 @@ let package = Package(
220220
.testTarget(
221221
name: "SemanticIndexTests",
222222
dependencies: [
223-
"SemanticIndex"
223+
"LSPLogging",
224+
"SemanticIndex",
225+
"SKTestSupport",
224226
],
225227
swiftSettings: strictConcurrencySettings
226228
),
@@ -343,7 +345,6 @@ let package = Package(
343345
dependencies: [
344346
"Csourcekitd",
345347
"LSPLogging",
346-
"SKSupport",
347348
"SwiftExtensions",
348349
.product(name: "SwiftToolsSupport-auto", package: "swift-tools-support-core"),
349350
],
@@ -399,6 +400,7 @@ let package = Package(
399400
"LSPLogging",
400401
"LSPTestSupport",
401402
"LanguageServerProtocol",
403+
"SemanticIndex",
402404
"SKCore",
403405
"SKSupport",
404406
"SKTestSupport",

Sources/LanguageServerProtocolJSONRPC/JSONRPCConnection.swift

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,12 @@ import LanguageServerProtocol
1919
import struct CDispatch.dispatch_fd_t
2020
#endif
2121

22-
/// A connection between a message handler (e.g. language server) in the same process as the connection object and a remote message handler (e.g. language client) that may run in another process using JSON RPC messages sent over a pair of in/out file descriptors.
22+
/// A connection between a message handler (e.g. language server) in the same process as the connection object and a
23+
/// remote message handler (e.g. language client) that may run in another process using JSON RPC messages sent over a
24+
// pair of in/out file descriptors.
2325
///
24-
/// For example, inside a language server, the `JSONRPCConnection` takes the language service implementation as its `receiveHandler` and itself provides the client connection for sending notifications and callbacks.
26+
/// For example, inside a language server, the `JSONRPCConnection` takes the language service implementation as its
27+
// `receiveHandler` and itself provides the client connection for sending notifications and callbacks.
2528
public final class JSONRPCConnection: Connection {
2629

2730
/// A name of the endpoint for this connection, used for logging, e.g. `clangd`.

Sources/SKCore/CMakeLists.txt

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
11

22
add_library(SKCore STATIC
3+
BuildConfiguration.swift
34
BuildServerBuildSystem.swift
45
BuildSetup.swift
56
BuildSystem.swift
67
BuildSystemDelegate.swift
78
BuildSystemManager.swift
89
CompilationDatabase.swift
910
CompilationDatabaseBuildSystem.swift
10-
Debouncer.swift
11-
ExperimentalFeatures.swift
1211
FallbackBuildSystem.swift
1312
FileBuildSettings.swift
1413
IndexTaskID.swift
1514
MainFilesProvider.swift
1615
PathPrefixMapping.swift
1716
SplitShellCommand.swift
18-
TaskScheduler.swift
1917
Toolchain.swift
2018
ToolchainRegistry.swift
19+
WorkspaceType.swift
2120
XCToolchainPlist.swift)
2221
set_target_properties(SKCore PROPERTIES
2322
INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_Swift_MODULE_DIRECTORY})

Sources/SKSupport/CMakeLists.txt

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
11

22
add_library(SKSupport STATIC
33
Atomics.swift
4-
BuildConfiguration.swift
54
ByteString.swift
65
Connection+Send.swift
7-
dlopen.swift
6+
Debouncer.swift
87
DocumentURI+CustomLogStringConvertible.swift
8+
ExperimentalFeatures.swift
99
FileSystem.swift
1010
LineTable.swift
11-
PipeAsStringHandler.swift
1211
Process+Run.swift
13-
Random.swift
14-
Result.swift
1512
SwitchableProcessResultExitStatus.swift
16-
WorkspaceType.swift
1713
)
1814
set_target_properties(SKSupport PROPERTIES
1915
INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_Swift_MODULE_DIRECTORY})
File renamed without changes.

Sources/SKSupport/LineTable.swift

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,6 @@
1212

1313
import LSPLogging
1414

15-
#if canImport(os)
16-
import os
17-
#endif
18-
1915
public struct LineTable: Hashable, Sendable {
2016
@usableFromInline
2117
var impl: [String.Index]

0 commit comments

Comments
 (0)