This document contains notes about development and testing of SourceKit-LSP.
For maximum compatibility with toolchain components such as the Swift Package Manager, the only supported way to develop SourceKit-LSP is with the latest toolchain snapshot. We make an effort to keep the build and tests working with the latest release of Swift, but this is not always possible.
-
Install the latest "Trunk Development (main)" toolchain snapshot from https://swift.org/download/#snapshots. If you're looking for swift-5.x, use the
swift-5.x-branchof SourceKit-LSP with the latest swift-5.x toolchain snapshot. See Toolchains for more information. -
Build the language server executable
sourcekit-lspusingswift build. See Building for more information. -
Configure your editor to use the newly built
sourcekit-lspexecutable and the toolchain snapshot. See Editors for more information about editor integration. -
Build the project you are editing with
swift buildusing the toolchain snapshot. The language server depends on the build to provide module dependencies and to update the global index.
Install the latest snapshot from https://swift.org/download/#snapshots. SourceKit-LSP builds with the latest toolchain snapshot of the corresponding branch (e.g. to build the main branch, use the latest main snapshot of the toolchain). See Toolchains for more information about supported toolchains.
SourceKit-LSP is built using the Swift Package Manager. For a standard debug build on the command line:
$ export TOOLCHAINS=swift
$ swift package update
$ swift buildInstall the following dependencies of SourceKit-LSP:
- libsqlite3-dev libncurses5-dev python3
$ swift package update
$ swift build -Xcxx -I<path_to_swift_toolchain>/usr/lib/swift -Xcxx -I<path_to_swift_toolchain>/usr/lib/swift/BlockAfter building, the server will be located at .build/debug/sourcekit-lsp, or a similar path, if you passed any custom options to swift build. Editors will generally need to be provided with this path in order to run the newly built server - see Editors for more information about configuration.
SourceKit-LSP is designed to build against the latest SwiftPM, so if you run into any issue make sure you have the most up-to-date dependencies by running swift package update.
The user must provide the following dependencies for SourceKit-LSP:
- SQLite3
- ninja
> swift build -Xcc -I<absolute path to SQLite header search path> -Xlinker -L<absolute path to SQLite library search path> -Xcc -I%SDKROOT%\usr\include -Xcc -I%SDKROOT%\usr\include\BlockThe header and library search paths must be passed to the build by absolute path. This allows the clang importer and linker to find the dependencies.
Additionally, as SourceKit-LSP depends on libdispatch and the Blocks runtime, which are part of the SDK, but not in the default search path, need to be explicitly added.
SourceKit-LSP should run out of the box using the Swift official Docker images. To build sourcekit-lsp from source and run its test suite, follow the steps in the Linux section. In the official docker images, the toolchain is located at /.
If you are seeing slow compile times, you will most likely need to increase the memory available to the Docker container.
SourceKit-LSP depends on tools such as sourcekitd and clangd, which it loads at runtime from an installed toolchain.
Use the latest toolchain snapshot from https://swift.org/download/#snapshots. SourceKit-LSP is designed to be used with the latest toolchain snapshot of the corresponding branch.
| SourceKit-LSP branch | Toolchain |
|---|---|
| main | Trunk Development (main) |
| swift-5.2-branch | Swift 5.2 Development |
| swift-5.1-branch | Swift 5.1.1+ |
Note: there is no branch of SourceKit-LSP that supports Swift 5.0.
After installing the toolchain, SourceKit-LSP needs to know the path to the toolchain.
-
On macOS, the toolchain is installed in
/Library/Developer/Toolchains/with an.xctoolchainextension. The most recently installed toolchain is symlinked as/Library/Developer/Toolchains/swift-latest.xctoolchain. If you opted to install for the current user only in the installer, the same paths will be under the home directory, e.g.~/Library/Developer/Toolchains/. -
On Linux, the toolchain is wherever the snapshot's
.tar.gzfile was extracted.
Your editor may have a way to configure the toolchain path directly via a configuration setting, or it may allow you to override the process environment variables used when launching sourcekit-lsp. See Editors for more information.
Otherwise, the simplest way to configure the toolchain is to set the following environment variable to the absolute path of the toolchain.
SOURCEKIT_TOOLCHAIN_PATH=<toolchain>You can attach LLDB to SourceKit-LSP and set breakpoints to debug. You may want to instruct LLDB to wait for the sourcekit-lsp process to launch and then start your editor, which will typically launch SourceKit-LSP as soon as you open a Swift file:
$ lldb -w -n sourcekit-lspIf you are using the Xcode project, go to Debug, Attach to Process by PID or Name.
You can configure SourceKit-LSP to print log information from SourceKit to stderr by setting the following environment variable:
SOURCEKIT_LOGGING="N"Where "N" configures the log verbosity and is one of the following numbers: 0 (error), 1 (warning), 2 (info), or 3 (debug).
As much as is practical, all code should be covered by tests. New tests can be added under the Tests directory and should use XCTest. The rest of this section will describe the additional tools available in the SKTestSupport module to make it easier to write good and efficient tests.
Tests that run longer than approx. 1 second are only executed if the the SOURCEKIT_LSP_ENABLE_LONG_TESTS environment variable is set to YES or 1. This, in particular, includes the crash recovery tests.