-
Notifications
You must be signed in to change notification settings - Fork 272
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1438 from ahoppen/6.0/merge-main-2024-06-06
Merge `main` into `release/6.0`
- Loading branch information
Showing
42 changed files
with
838 additions
and
598 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| * **Explanation**: <!-- A description of the issue being fixed or enhancement being made. This can be brief, but it should be clear. --> | ||
| * **Scope**: <!-- An assessment of the impact/importance of the change. For example, is the change a source-breaking language change, etc. --> | ||
| * **Issue**: <!-- The GitHub Issue link if the change fixes/implements an issue/enhancement --> | ||
| * **Original PR**: <!-- Pull Request link from main branch --> | ||
| * **Risk**: <!-- What is the (specific) risk to the release for taking this change? --> | ||
| * **Testing**: <!-- What specific testing has been done or needs to be done to further validate any impact of this change? --> | ||
| * **Reviewer**: <!-- One or more code owners for the impacted components should review the change. Technical review can be delegated by a code owner or otherwise requested as deemed appropriate or useful. --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,166 @@ | ||
| By submitting a pull request, you represent that you have the right to license | ||
| your contribution to Apple and the community, and agree by submitting the patch | ||
| that your contributions are licensed under the [Swift | ||
| license](https://swift.org/LICENSE.txt). | ||
| # Contributing | ||
|
|
||
| --- | ||
| This document contains notes about development and testing of SourceKit-LSP. | ||
|
|
||
| Before submitting the pull request, please make sure you have [tested your | ||
| changes](https://github.com/apple/swift/blob/main/docs/ContinuousIntegration.md) | ||
| and that they follow the Swift project [guidelines for contributing | ||
| code](https://swift.org/contributing/#contributing-code). | ||
| ## Building & Testing | ||
|
|
||
| SourceKit-LSP is a SwiftPM package, so you can build and test it using anything that supports packages - opening in Xcode, Visual Studio Code with [Swift for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=sswg.swift-lang) installed, or through the command line using `swift build` and `swift test`. See below for extra instructions for Linux and Windows | ||
|
|
||
| SourceKit-LSP builds with the latest released Swift version and all its tests pass or, if unsupported by the latest Swift version, are skipped. Using the `main` development branch of SourceKit-LSP with an older Swift versions is not supported. | ||
|
|
||
| > [!TIP] | ||
| > SourceKit-LSP’s logging is usually very useful to debug test failures. On macOS these logs are written to the system log by default. To redirect them to stderr, build SourceKit-LSP with the `SOURCEKITLSP_FORCE_NON_DARWIN_LOGGER` environment variable set to `1`: | ||
| > - In VS Code: Add the following to your `settings.json`: | ||
| > ```json | ||
| > "swift.swiftEnvironmentVariables": { "SOURCEKITLSP_FORCE_NON_DARWIN_LOGGER": "1" }, | ||
| > ``` | ||
| > - In Xcode | ||
| > 1. Product -> Scheme -> Edit Scheme… | ||
| > 2. Select the Arguments tab in the Run section | ||
| > 3. Add a `SOURCEKITLSP_FORCE_NON_DARWIN_LOGGER` environment variable with value `1` | ||
| > - On the command line: Set the `SOURCEKITLSP_FORCE_NON_DARWIN_LOGGER` environment variable to `1` when running tests, e.g by running `SOURCEKITLSP_FORCE_NON_DARWIN_LOGGER=1 swift test --parallel` | ||
| > [!TIP] | ||
| > Other useful environment variables during test execution are: | ||
| > - `SKIP_LONG_TESTS`: Skips tests that usually take longer than 1 second to execute. This significantly speeds up test time, especially with `swift test --parallel` | ||
| > - `SOURCEKITLSP_KEEP_TEST_SCRATCH_DIR`: Does not delete the temporary files created during test execution. Allows inspection of the test projects after the test finishes. | ||
| ### Linux | ||
| The following dependencies of SourceKit-LSP need to be installed on your system | ||
| - libsqlite3-dev libncurses5-dev python3 | ||
| You need to add `<path_to_swift_toolchain>/usr/lib/swift` and `<path_to_swift_toolchain>/usr/lib/swift/Block` C++ search paths to your `swift build` invocation that SourceKit-LSP’s dependencies build correctly. Assuming that your Swift toolchain is installed to `/`, the build command is | ||
| ```sh | ||
| $ swift build -Xcxx -I/usr/lib/swift -Xcxx -I/usr/lib/swift/Block | ||
| ``` | ||
| ### Windows | ||
|
|
||
| You must provide the following dependencies for SourceKit-LSP: | ||
| - SQLite3 ninja | ||
|
|
||
| ```cmd | ||
| > 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\Block | ||
| ``` | ||
|
|
||
| The 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. | ||
|
|
||
| ### Devcontainer | ||
|
|
||
| You can develop SourceKit-LSP inside a devcontainer, which is essentially a Linux container that has all of SourceKit-LSP’s dependencies pre-installed. The [official tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) contains information of how to set up devcontainers in VS Code. | ||
|
|
||
| Recommended Docker settings for macOS are: | ||
| - General | ||
| - "Choose file sharing implementation for your containers": VirtioFS (better IO performance) | ||
| - Resources | ||
| - CPUs: Allow docker to use most or all of your CPUs | ||
| - Memory: Allow docker to use most or all of your memory | ||
|
|
||
| ## Using a locally-built sourcekit-lsp in an editor | ||
|
|
||
| If you want test your changes to SourceKit-LSP inside your editor, you can point it to your locally-built `sourcekit-lsp` executable. The exact steps vary by editor. For VS Code, you can add the following to your `settings.json`. | ||
|
|
||
| ```json | ||
| "swift.sourcekit-lsp.serverPath": "/path/to/sourcekit-lsp/.build/arm64-apple-macosx/debug/sourcekit-lsp", | ||
| ``` | ||
|
|
||
| > [!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 | ||
| > $ lldb --wait-for --attach-name sourcekit-lsp | ||
| > ``` | ||
| > | ||
| > If you are developing SourceKit-LSP in Xcode, go to Debug -> Attach to Process by PID or Name. | ||
| ## Selecting a Toolchain | ||
| When SourceKit-LSP is installed as part of a toolchain, it finds the Swift version to use relative to itself. When building SourceKit-LSP locally, it picks a default toolchain on your system, which usually corresponds to the toolchain that is used if you invoke `swift` without any specified path. | ||
| To adjust the toolchain that should be used by SourceKit-LSP (eg. because you want to use new `sourcekitd` features that are only available in a Swift open source toolchain snapshot but not your default toolchain), set the `SOURCEKIT_TOOLCHAIN_PATH` environment variable to your toolchain when running SourceKit-LSP. | ||
| ## Logging | ||
| SourceKit-LSP has extensive logging to the system log on macOS and to `/var/logs/sourcekit-lsp` or stderr on other platforms. | ||
| To show the logs on macOS, run | ||
| ```sh | ||
| log show --last 1h --predicate 'subsystem CONTAINS "org.swift.sourcekit-lsp"' --info --debug | ||
| ``` | ||
| Or to stream the logs as they are produced: | ||
| ``` | ||
| log stream --predicate 'subsystem CONTAINS "org.swift.sourcekit-lsp"' --level debug | ||
| ``` | ||
| SourceKit-LSP masks data that may contain private information such as source file names and contents by default. To enable logging of this information, run | ||
| ```sh | ||
| sudo log config --subsystem org.swift.sourcekit-lsp --mode private_data:on | ||
| ``` | ||
| To enable more verbose logging on non-macOS platforms, launch sourcekit-lsp with the `SOURCEKITLSP_LOG_LEVEL` environment variable set to `debug`. | ||
| ## Formatting | ||
| SourceKit-LSP is formatted using [swift-format](http://github.com/apple/swift-format) to ensure a consistent style. | ||
| To format your changes run the formatter using the following command | ||
| ```bash | ||
| swift package format-source-code | ||
| ``` | ||
| If you are developing SourceKit-LSP in VS Code, you can also run the *Run swift-format* task from *Tasks: Run tasks* in the command palette. | ||
| ## Authoring commits | ||
| Prefer to squash the commits of your PR (*pull request*) and avoid adding commits like “Address review comments”. This creates a clearer git history, which doesn’t need to record the history of how the PR evolved. | ||
| We prefer to not squash commits when merging a PR because, especially for larger PRs, it sometimes makes sense to split the PR into multiple self-contained chunks of changes. For example, a PR might do a refactoring first before adding a new feature or fixing a bug. This separation is useful for two reasons: | ||
| - During review, the commits can be reviewed individually, making each review chunk smaller | ||
| - In case this PR introduced a bug that is identified later, it is possible to check if it resulted from the refactoring or the actual change, thereby making it easier find the lines that introduce the issue. | ||
| ## Opening a PR | ||
| To submit a PR you don't need permissions on this repo, instead you can fork the repo and create a PR through your forked version. | ||
| For more information and instructions, read the GitHub docs on [forking a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). | ||
| Once you've pushed your branch, you should see an option on this repository's page to create a PR from a branch in your fork. | ||
| ## Opening a PR for Release Branch | ||
| In order for a pull request to be considered for inclusion in a release branch (e.g. `release/6.0`) after it has been cut, it must meet the following requirements: | ||
| 1. The title of the PR should start with the tag `[{swift version number}]`. For example, `[6.0]` for the Swift 6.0 release branch. | ||
| 1. The PR description must include the following information: | ||
| ```md | ||
| * **Explanation**: A description of the issue being fixed or enhancement being made. This can be brief, but it should be clear. | ||
| * **Scope**: An assessment of the impact/importance of the change. For example, is the change a source-breaking language change, etc. | ||
| * **Issue**: The GitHub Issue link if the change fixes/implements an issue/enhancement. | ||
| * **Original PR**: Pull Request link from the `main` branch. | ||
| * **Risk**: What is the (specific) risk to the release for taking this change? | ||
| * **Testing**: What specific testing has been done or needs to be done to further validate any impact of this change? | ||
| * **Reviewer**: One or more code owners for the impacted components should review the change. Technical review can be delegated by a code owner or otherwise requested as deemed appropriate or useful. | ||
| ``` | ||
| > [!TIP] | ||
| > The PR description can be generated using the [release_branch.md](https://github.com/apple/sourcekit-lsp/blob/main/.github/PULL_REQUEST_TEMPLATE/release_branch.md) [pull request template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). To use this template when creating a PR, you need to add the query parameter: | ||
| > ``` | ||
| > ?expand=1&template=release_branch.md | ||
| > ``` | ||
| > to the PR URL, as described in the [GitHub documentation on using query parameters to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request). | ||
| > This is necessary because GitHub does not currently provide a UI to choose a PR template. | ||
| All changes going into a release branch must go through pull requests that are approved and merged by the corresponding release manager. | ||
| ## Review and CI Testing | ||
| After you opened your PR, a maintainer will review it and test your changes in CI (*Continuous Integration*) by adding a `@swift-ci Please test` comment on the pull request. Once your PR is approved and CI has passed, the maintainer will merge your pull request. | ||
| Only contributors with [commit access](https://www.swift.org/contributing/#commit-access) are able to approve pull requests and trigger CI. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Background Indexing | ||
|
|
||
| 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" ], | ||
| ``` | ||
|
|
||
| ## Known issues | ||
|
|
||
| - The only supported toolchain for background indexing are currently [Swift 6.0 nightly toolchain snapshots](https://www.swift.org/download/#swift-60-development). Older toolchains are not supported and the nightly toolchains from `main` are having issues because building a target non-deterministically builds for tools or the destination [#1288](https://github.com/apple/sourcekit-lsp/pull/1288#issuecomment-2111400459) [rdar://128100158](rdar://128100158) | ||
| - 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 | ||
| - 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) | ||
| - The initial indexing might take 2-3x more time than a regular build [#1254](https://github.com/apple/sourcekit-lsp/issues/1254), [#1262](https://github.com/apple/sourcekit-lsp/issues/1262), [#1268](https://github.com/apple/sourcekit-lsp/issues/1268) | ||
| - Spurious re-indexing of ~10-20 source files when `swift build` writes a header to the build directory [rdar://128573306](rdar://128573306) | ||
|
|
||
| ## 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. |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.