Background indexing in SourceKit-LSP is available as an experimental feature. This guide shows how to set up background indexing and which caveats to expect.
By default SourceKit-LSP does not update its global index in the background or build Swift modules in the background. Thus, a lot of cross-module or global functionality is limited if the project hasn't been built recently. For example consider two modules: Lib
and Exec
, where Exec
depends on Lib
: Without background indexing, if a function is added to Lib
, completion/jump to definition/etc in Exec
would not be able to see that function until after a build. Background indexing solves that issue.
- Install a
main
orrelease/6.0
Swift Development Snapshot from https://www.swift.org/install or install the Xcode 16 beta. - Point your editor to the newly installed toolchain.
- In VS Code on macOS this can be done by adding the following to your
settings.json
:- For open source toolchains
"swift.path": "/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin"
- When installing the Xcode 16 beta
"swift.path": "/Applications/Xcode-beta.app/Library/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin"
- For open source toolchains
- In VS Code on other platforms, you need to set the
swift.path
to theusr/bin
directory of your toolchain’s install location. - Other editors likely also have a way to pick the Swift toolchain, the exact steps vary by your setup.
- In VS Code on macOS this can be done by adding the following to your
- Enable the experimental
background-indexing
feature by creating a configuration file with the following contents at~/.sourcekit-lsp/config.json
with the following contents:
{
"backgroundIndexing": true
}
- Background Indexing is only supported for SwiftPM projects #1269, #1271
- If you change a function in a way that changes its USR but keeps it API compatible (such as adding a defaulted parameter), references to it will be lost and not re-indexed automatically #1264
- Workaround: Make some edit to the files that had references to re-index them
- The index build is currently completely separate from the command line build generated using
swift build
. Building does not update the index (break your habits of always building!) #1270 - The initial indexing might take 2-3x more time than a regular build #1262, #1268
If you hit any issues that are not mentioned above, please file a GitHub issue and attach the following information, if possible:
- A diagnostic bundle generated by running
path/to/sourcekit-lsp diagnose
. - Your project including the
.index-build
folder, if possible.