Enable Experimental Background Indexing

Background indexing in SourceKit-LSP is enabled by default in Swift 6.1 toolchains and is available as an experimental feature for Swift 6.0 toolchains.

Behavior Without Background Indexing

With background indexing disabled, 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.

Set Up

1. Install the Swift 6.0 toolchain or install Xcode 16.
2. Enable the experimental background-indexing feature by creating a configuration file at ~/.sourcekit-lsp/config.json with the following contents:

{
  "backgroundIndexing": true,
  "backgroundPreparationMode": "enabled"
}

Known issues

• 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

Filing issues

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 .build folder, if possible.