-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update and refine settings descriptions (#957)
* Update and refine settings descriptions - Remove redundant settings descriptions from settings.md, moving any extra information found there in to the setting description shown in the extension settings page. - Add information on how to enable experimental sourcekit-lsp features to settings.md. - Consistently apply markdown formatting to setting descriptions. --------- Co-authored-by: Adam Fowler <[email protected]>
- Loading branch information
1 parent
b3880d6
commit a5335dc
Showing
2 changed files
with
54 additions
and
114 deletions.
There are no files selected for viewing
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,95 +1,35 @@ | ||
| # Extension Settings | ||
|
|
||
| The Visual Studio Code Swift extension comes with a number of settings you can use to control how it works. This document details what each of these settings does. | ||
| The Visual Studio Code Swift extension comes with a number of settings you can use to control how it works. Detailed descriptions of each setting is provided in the extension settings page. | ||
|
|
||
| - **Path** | ||
| This document outlines useful configuration options not covered by the settings descriptions in the extension settings page. | ||
|
|
||
| This is the folder that the `swift` executable can be found in. If this is not set then the extension will look for executables in the PATH environment variable. The extension will also use this setting when looking for other executables it requires like `sourcekit-lsp` and `lldb`. | ||
|
|
||
| - **Build Arguments** | ||
|
|
||
| This is a list of additional arguments passed to the `swift build` calls the extension makes. Argument keys and values should be provided as separate entries in the array e.g. `['-Xswiftc', '-warn-concurrency']`. This setting is only applied to the default build tasks generated by the extension. If you have created custom versions of these tasks in `tasks.json` the setting will not be applied. Instead you will need to edit the arguments list in the `tasks.json` file. | ||
|
|
||
| - **Test Environment Variables** | ||
|
|
||
| This is a list of environment variables to set when running tests. To set environment variables when running an application you should set the `env` field in its launch.json file. The `launch.json` is not available for tests so instead you should use this settings. | ||
|
|
||
| - **Auto Generate Launch Configurations** | ||
|
|
||
| When a SwiftPM project is loaded into Visual Studio Code the Swift extension will automatically generate debug and release launch configurations for [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) for any executable in the package. This setting allows you to disable this if you would prefer to setup your own launch configurations. | ||
|
|
||
| - **Problem Match Compile Errors** | ||
|
|
||
| When this is enabled any errors or warnings from a `swift build` will be listed in the problems view. There is a chance these compile "problems" will double up with "problems" coming from SourceKit-LSP but the list of issues will be more comprehensive. The compile "problems" will only disappear after a `swift build` indicates they are resolved. | ||
|
|
||
| - **Exclude Paths From Package Dependencies** | ||
|
|
||
| This is a list of paths to exclude from the Package Dependency View. | ||
|
|
||
| - **Background Compilation** | ||
|
|
||
| This is an experimental setting which runs `swift build` whenever a file is saved. It is possible the background compilation will clash with any compilation you trigger yourself so this is disabled by default. | ||
|
|
||
| - **Build path** | ||
|
|
||
| The path to a directory that will be used for build artifacts. This path will be added to all swift package manager commands that are executed by vscode-swift extension via `--scratch-path` option. When no value provided - nothing gets passed to swift package manager and it will use its default value of `.build` folder in workspace. You can use absolute path for directory or the relative path, which will use the workspace path as a base. Unfortunately, VS Code does not correctly understand and pass the tilde symbol (~) which represents user home folder under *nix systems. Thus, it should be avoided. | ||
|
|
||
| - **Disable Auto Resolve** | ||
|
|
||
| When the Swift extension starts up and whenever the `Package.swift` or `Package.resolved` files are updated a `swift package resolve` process is run to make sure we have the correct versions of dependencies downloaded. You can disable this process with the disable auto resolve setting. | ||
|
|
||
| ### SourceKit-LSP | ||
| ## SourceKit-LSP | ||
|
|
||
| [SourceKit-LSP](https://github.com/apple/sourcekit-lsp) is the language server used by the the Swift extension to provide symbol completion, jump to definition etc. It is developed by Apple to provide Swift and C language support for any editor that supports the Language Server Protocol. | ||
|
|
||
| - **Server Path** | ||
|
|
||
| The path of the `sourcekit-lsp` executable. As mentioned above the default is to look in the folder where the `swift` executable is found. | ||
|
|
||
| - **Server Arguments** | ||
|
|
||
| This is a list of arguments that will be passed to the SourceKit-LSP. Argument keys and values should be provided as separate entries in the array e.g. `['--log-level', 'debug']`. | ||
|
|
||
| - **Inlay Hints** | ||
|
|
||
| This controls the display of Inlay Hints. Inlay Hints are variable annotations indicating their inferred type. They are only available if you are using Swift 5.6 or later. This setting has been deprecated and now you should use `Editor > Inlay Hints: Enabled`. | ||
|
|
||
| - **Supported Languages** | ||
|
|
||
| This is a configuration setting that allows you to specify the list of languages that the SourceKit-LSP extension should support. The setting accepts an array of language identifiers.e.g. `["swift", "objective-c", "objective-cpp"]` The primary purpose of this configuration is to mitigate conflicts between the SourceKit-LSP and other extensions, such as clangd | ||
|
|
||
| - **Trace: Server** | ||
|
|
||
| Trace the communication between Visual Studio Code and the SourceKit-LSP server. The output from this is sent to an Output Window called "SourceKit Language Server" | ||
|
|
||
| ### Test Coverage | ||
|
|
||
| - **Coverage: Display Report after Run** | ||
|
|
||
| Display the test coverage report after a test coverage has been run. The report includes a list of all your source files and how many lines were hit or missed while running tests, the total number of lines and then the percentage of hit lines. | ||
|
|
||
| - **Coverage: Always Show Status Item** | ||
|
|
||
| The test coverage functionality includes a status item in the status bar at the bottom of the screen. This can be set to be visible all the time or only when test coverage data is displayed. If it is set to be displayed all the time the status item can be used as a button to toggle the display of test coverage data. | ||
|
|
||
| - **Coverage: Colors** | ||
|
|
||
| These four settings are to define the colors used when displaying the test coverage data. They are split into two sections, one for light themes and one for dark themes. Inside each section is a color for the background of lines that are hit during test coverage and a color for the background of lines that are missed during test coverage. | ||
|
|
||
| ### Advanced | ||
|
|
||
| - **Swift Environment Variables** | ||
| ### Background Indexing | ||
|
|
||
| This is a list of environment variables to set when running swift (build, resolve etc). | ||
| If you're using a nightly (`main`) or recent `6.0` toolchain you can enable support for background indexing in Sourcekit-LSP. This removes the need to do a build before getting code completion and diagnostics. | ||
|
|
||
| - **Runtime Path** | ||
| To enable support, set the following Sourcekit-LSP server arguments in your settings.json, or add two new entries to the `Sourcekit-lsp: Server Arguments` entry in the extension settings page. | ||
|
|
||
| Where to find Swift runtime libraries. On Windows the runtime path is added to the `Path` environment variable. This is of less use on macOS and Linux but will be added to `DYLD_LIBRARY_PATH` and `LD_LIBRARY_PATH` environment variables respectively on each platform. This is of use when supporting non-standard SDK layouts on Windows | ||
| ``` | ||
| "swift.sourcekit-lsp.serverArguments": [ | ||
| "--experimental-feature", | ||
| "background-indexing" | ||
| ] | ||
| ``` | ||
|
|
||
| - **SDK** | ||
| ### Support for 'Expand Macro' | ||
|
|
||
| The path of the target SDK to compile against. The default SDK is determined by the environment on macOS and Windows. This is of use when supporting non-standard SDK layouts on Windows and using custom SDKs. This adds the `--sdk` command line parameter to the relevant `swift` calls. | ||
| If you are using a nightly (`main`) toolchain you can enable support for the "Peek Macro" Quick Action, accessible through the light bulb icon when the cursor is on a macro. | ||
|
|
||
| - **Diagnostics** | ||
| To enable support, set the following Sourcekit-LSP server arguments in your settings.json, or add two new entries to the `Sourcekit-lsp: Server Arguments` entry in the extension settings page. | ||
|
|
||
| The Swift extension includes a Swift Output channel that events are logged in. You can access this by selecting menu item `View -> Output` and then selecting `Swift` in the drop down menu. Events like adding new folders, LSP server starting, errors and package resolves/updates are recorded in here. This is all useful information when trying to debug an issue with the extension. Enabling the diagnostics setting will extend this information to include considerably more information. If you want to report a bug with the extension it would be good practice to enable this setting, restart Visual Studio Code and once you have replicated your bug include the contents of the Swift Output channel in the bug report. | ||
| ``` | ||
| "swift.sourcekit-lsp.serverArguments": [ | ||
| "--experimental-feature", | ||
| "show-macro-expansions" | ||
| ] | ||
| ``` |
Oops, something went wrong.