Merge pull request #1448 from ahoppen/simplify-background-indexing-instructions

Simplify instructions to enable background indexing to not require building SourceKit-LSP

Author: ahoppen

CONTRIBUTING.md

@@ -68,6 +68,9 @@ If you want test your changes to SourceKit-LSP inside your editor, you can point
 "swift.sourcekit-lsp.serverPath": "/path/to/sourcekit-lsp/.build/arm64-apple-macosx/debug/sourcekit-lsp",
 ```
 
+> [!NOTE]
+> VS Code will note that that the `swift.sourcekit-lsp.serverPath` setting is deprecated. That’s because mixing and matching versions of sourcekit-lsp and Swift toolchains is generally not supported, so the settings is reserved for developers of SourceKit-LSP, which includes you. You can ignore this warning, If you have the `swift.path` setting to a recent [Swift Development Snapshot](https://www.swift.org/install).
+
 > [!TIP]
 > The easiest way to debug SourceKit-LSP is usually to write a test case that reproduces the behavior and then debug that. If that’s not possible, you can attach LLDB to the sourcekit-lsp launched by your and set breakpoints to debug. To do so on the command line, run
 > ```bash

Documentation/Enable Experimental Background Indexing.md

@@ -2,35 +2,23 @@
 
 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.
 
-> [!WARNING]
-> Background indexing is still an experimental feature and still has some non-trivial limitations and bugs (see the known issues).
-
 ## Set Up
 
-Background indexing is still under active, rapid development, so please build SourceKit-LSP from the `main` branch using the following commands. Things are changing rapidly, so rebuilding daily is not a bad practice.
-
-```bash
-$ git clone https://github.com/apple/sourcekit-lsp.git
-$ cd sourcekit-lsp
-$ swift package update
-$ swift build -c release
-```
-
-Next, point your editor to use the just-built copy of SourceKit-LSP and enable background indexing by passing `--experimental-feature background-indexing` to sourcekit-lsp. In VS Code, this can be done by adding the following to your settings.json
-```json
-"swift.sourcekit-lsp.serverPath": "/path/to/sourcekit-lsp/.build/release/sourcekit-lsp",
-"swift.sourcekit-lsp.serverArguments": [ "--experimental-feature", "background-indexing" ],
-```
-
-Background indexing requires a Swift 6 toolchain. You can download Swift 6 nightly toolchains from https://www.swift.org/download/#swift-60-development.
+1. Install a `main` or `release/6.0` Swift Development Snapshot from https://www.swift.org/install.
+2. 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`: `"swift.path": "/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin"`
+   - In VS Code on other platforms, you need to set the `swift.path` to the `usr/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.
+3. Enable the experimental `background-indexing` feature.
+   - In VS Code, add the following to your `settings.json`: `"swift.sourcekit-lsp.serverArguments": [ "--experimental-feature", "background-indexing" ]`
+   - In other editors, change the invocation that launches `sourcekit-lsp` to pass the `--experimental-feature background-indexing` command line arguments. The exact steps vary by your setup.
 
 ## Known issues
 
-- Not really a background indexing related issue but Swift nightly toolchain snapshots are crashing on macOS 14.4 and 14.5 (swift#73327)[https://github.com/apple/swift/issues/73327]
-  - Workaround: Run the toolchains on an older version of macOS, if possible
 - Background Indexing is only supported for SwiftPM projects [#1269](https://github.com/apple/sourcekit-lsp/issues/1269), [#1271](https://github.com/apple/sourcekit-lsp/issues/1271)
 - If a module or one of its dependencies has a compilation error, it cannot be properly prepared for indexing because we are running a regular `swift build` to generate its modules [#1254](https://github.com/apple/sourcekit-lsp/issues/1254) rdar://128683404
-  - Workaround: Ensure that your files dependencies are in a buildable state to get an up-to-date index and proper cross-module functionality
+  - Workaround 1: Ensure that your files dependencies are in a buildable state to get an up-to-date index and proper cross-module functionality
+  - Workaround 2: Enable the `swiftpm-prepare-for-indexing` experimental feature, which continues to build Swift module even in the presence of errors.
 - 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](https://github.com/apple/sourcekit-lsp/issues/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](https://github.com/apple/sourcekit-lsp/issues/1270)
@@ -40,5 +28,5 @@ Background indexing requires a Swift 6 toolchain. You can download Swift 6 night
 ## Filing issues
 
 If you hit any issues that are not mentioned above, please [file a GitHub issue](https://github.com/apple/sourcekit-lsp/issues/new/choose) and attach the following information, if possible:
-- A diagnostic bundle generated by running `path/to/sourcekit-lsp diagnose --toolchain path/to/the/toolchain/you/are/using`
-- Your project including the `.index-build` folder.
+- A diagnostic bundle generated by running `path/to/sourcekit-lsp diagnose`.
+- Your project including the `.index-build` folder, if possible.