diff --git a/.vscodeignore b/.vscodeignore index 10751b3fd..b79a99db6 100644 --- a/.vscodeignore +++ b/.vscodeignore @@ -9,6 +9,7 @@ !images/** !snippets/** !assets/icons/** +!assets/walkthrough/** !assets/documentation-webview/** !assets/swift-docc-render/** !node_modules/@vscode/codicons/** diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e1b40d78..d942b8cdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,13 @@ ### Added -- Added Swiftly toolchain management support `.swift-version` files, and integration with the toolchain selection UI ([#1717](https://github.com/swiftlang/vscode-swift/pull/1717) +- A walkthrough for first time extension users ([#1560](https://github.com/swiftlang/vscode-swift/issues/1560)) + +## 2.10.0 - 2025-07-28 + +### Added + +- Added Swiftly toolchain management support `.swift-version` files, and integration with the toolchain selection UI ([#1717](https://github.com/swiftlang/vscode-swift/pull/1717)) - Added code lenses to run suites/tests, configurable with the `swift.showTestCodeLenses` setting ([#1698](https://github.com/swiftlang/vscode-swift/pull/1698)) - New `swift.excludePathsFromActivation` setting to ignore specified sub-folders from being activated as projects ([#1693](https://github.com/swiftlang/vscode-swift/pull/1693)) - New `swift.recordTestDuration` setting to disable capturing test durations, which can improve performance of heavy test runs ([#1745](https://github.com/swiftlang/vscode-swift/pull/1745)) diff --git a/assets/walkthrough/createNewProject.md b/assets/walkthrough/createNewProject.md new file mode 100644 index 000000000..25b637f31 --- /dev/null +++ b/assets/walkthrough/createNewProject.md @@ -0,0 +1,14 @@ +# Create a New Swift Project +![Create new project](./images/createNewProject.gif) + +When you select a project template, you'll be prompted to enter a name for your new project. This will be the name of the folder created in your workspace. You can then choose any location in your workspace, or create a new folder for the project. + +# Opening Existing Projects + +![Open existing project](./images/openProject.gif) + +When you open an existing project with a ``Package.swift`` file the extension will start automatically. + +Tip: You can view more information about the toolchain and other configurations being used for the project by hovering over the `{}` icon in the bottom right corner of the status bar. + +![Hover over {} to see toolchain info](./images/toolchainInfo.png) diff --git a/assets/walkthrough/customizeSettings.md b/assets/walkthrough/customizeSettings.md new file mode 100644 index 000000000..d9075df27 --- /dev/null +++ b/assets/walkthrough/customizeSettings.md @@ -0,0 +1,19 @@ +# Swift Extension Settings + +![Swift Extension Settings](./images/settings.gif) + +The Swift Extension contains several settings you can customize. You can filter settings Swift extension settings by searching for `@ext:swiftlang.swift-vscode`. + +## Inlay Hints + +Some language settings such as those for inlay hints for inferred variable types are turned on by default in VS Code. + +![Disable Inlay Hints](./images/disableInlayHints.gif) + +You can turn off inlay hints for Swift by adding `[swift]` specific settings to your `settings.json` file: + +``` + "[swift]": { + "editor.inlayHints.enabled": "off" + }, +``` diff --git a/assets/walkthrough/images/createNewProject.gif b/assets/walkthrough/images/createNewProject.gif new file mode 100644 index 000000000..fd13aaba7 Binary files /dev/null and b/assets/walkthrough/images/createNewProject.gif differ diff --git a/assets/walkthrough/images/createNewProject.svg b/assets/walkthrough/images/createNewProject.svg new file mode 100644 index 000000000..765e062b6 --- /dev/null +++ b/assets/walkthrough/images/createNewProject.svg @@ -0,0 +1,55 @@ + + + + + + + + + + + + +> Swift: + + + + + + +Swift: Create New Project... +Swift: Create New Swift File... +Swift: Select Toolchain... +Swift: Open Documentation +Swift: Preview Documentation +Swift: Open Package.swift + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/walkthrough/images/debugExecutable.gif b/assets/walkthrough/images/debugExecutable.gif new file mode 100644 index 000000000..47d3ad3ad Binary files /dev/null and b/assets/walkthrough/images/debugExecutable.gif differ diff --git a/assets/walkthrough/images/disableInlayHints.gif b/assets/walkthrough/images/disableInlayHints.gif new file mode 100644 index 000000000..b5b4c4030 Binary files /dev/null and b/assets/walkthrough/images/disableInlayHints.gif differ diff --git a/assets/walkthrough/images/openProject.gif b/assets/walkthrough/images/openProject.gif new file mode 100644 index 000000000..a79ff20e8 Binary files /dev/null and b/assets/walkthrough/images/openProject.gif differ diff --git a/assets/walkthrough/images/previewDocumentation.gif b/assets/walkthrough/images/previewDocumentation.gif new file mode 100644 index 000000000..2868eee21 Binary files /dev/null and b/assets/walkthrough/images/previewDocumentation.gif differ diff --git a/assets/walkthrough/images/runExecutable.gif b/assets/walkthrough/images/runExecutable.gif new file mode 100644 index 000000000..bc59c7841 Binary files /dev/null and b/assets/walkthrough/images/runExecutable.gif differ diff --git a/assets/walkthrough/images/runSwiftExecutable.png b/assets/walkthrough/images/runSwiftExecutable.png new file mode 100644 index 000000000..0d3654d2f Binary files /dev/null and b/assets/walkthrough/images/runSwiftExecutable.png differ diff --git a/assets/walkthrough/images/runTests.gif b/assets/walkthrough/images/runTests.gif new file mode 100644 index 000000000..3f687d663 Binary files /dev/null and b/assets/walkthrough/images/runTests.gif differ diff --git a/assets/walkthrough/images/settings.gif b/assets/walkthrough/images/settings.gif new file mode 100644 index 000000000..f1595a36d Binary files /dev/null and b/assets/walkthrough/images/settings.gif differ diff --git a/assets/walkthrough/images/swiftCommands.svg b/assets/walkthrough/images/swiftCommands.svg new file mode 100644 index 000000000..a200674f3 --- /dev/null +++ b/assets/walkthrough/images/swiftCommands.svg @@ -0,0 +1,40 @@ + + + + + + + + + + + + +> Swift: + + +Swift: Create New Project... +Swift: Create New Swift File... +Swift: Select Toolchain... +Swift: Open Documentation +Swift: Preview Documentation +Swift: Open Package.swift + + + + + + + + + + + + + + + + + + + diff --git a/assets/walkthrough/images/swiftLogo.svg b/assets/walkthrough/images/swiftLogo.svg new file mode 100755 index 000000000..9e97bfaa8 --- /dev/null +++ b/assets/walkthrough/images/swiftLogo.svg @@ -0,0 +1,22 @@ + + + + + + + + diff --git a/assets/walkthrough/images/toolchainInfo.png b/assets/walkthrough/images/toolchainInfo.png new file mode 100644 index 000000000..335da58f2 Binary files /dev/null and b/assets/walkthrough/images/toolchainInfo.png differ diff --git a/assets/walkthrough/previewDocs.md b/assets/walkthrough/previewDocs.md new file mode 100644 index 000000000..526e0caa0 --- /dev/null +++ b/assets/walkthrough/previewDocs.md @@ -0,0 +1,6 @@ +# Preview Documentation +![Preview documentation](./images/previewDocumentation.gif) + +You can preview [documentation written using DocC](https://www.swift.org/documentation/docc/) directly in VS Code by using the Preview Swift Documentation button at the top right of an editor, or by invoking `Swift: Preview Documentation` in the command palette in a `.docc` bundle. + +Note: This feature requires Swift 6.2 or later. \ No newline at end of file diff --git a/assets/walkthrough/runExecutable.md b/assets/walkthrough/runExecutable.md new file mode 100644 index 000000000..522b1aae5 --- /dev/null +++ b/assets/walkthrough/runExecutable.md @@ -0,0 +1,16 @@ +# Run Swift Executables +![Runing a swift executable](./images/runExecutable.gif) + +You can build and run a Swift binary target via the: +1. `Run` or `Debug` CodeLens that appears in the `.swift` file that contains your program's entry point +2. `Project Panel` in the bottom left hand corner of the sidebar under the `Targets` and `Tasks` groups +3. `Tasks` command: You can configure the build tasks through the `launch.json` file in the `.vscode` folder for the project and then select the target you'd like to build with the `Tasks: Run Task` command from the `Command Pallete` +4. `Run Swift executable` editor action in the top right corner of the editor +![Run Swift executable](./images/runSwiftExecutable.png) + + +# Debug Swift Executables + +![Debuging a swift executable](./images/debugExecutable.gif) + +The extension automatically generates the debug and release variants of launch configurations in `launch.json`. You can debug a target by setting a breakpoint and clicking the the `Debug Swift Executable` editor action or through the `Run and Debug` panel in the sidebar. \ No newline at end of file diff --git a/assets/walkthrough/runTests.md b/assets/walkthrough/runTests.md new file mode 100644 index 000000000..2d7cf2c15 --- /dev/null +++ b/assets/walkthrough/runTests.md @@ -0,0 +1,7 @@ +# Run Swift Testing and XCTest Tests +![Run a test](./images/runTests.gif) + +Swift Testing and XCTests tests are detected automatically. You can run tests by: +1. Clicking the ▶ button or right clicking ▶ button beside the line number, and selecting a test variant such as `Debug Test` or `Run with Coverage` +2. Clicking `Run`, `Debug` or `Run w/ Coverage` in the CodeLens +3. Using the `Test Explorer` in the sidebar diff --git a/assets/walkthrough/swiftCommands.md b/assets/walkthrough/swiftCommands.md new file mode 100644 index 000000000..2aa6ccf3d --- /dev/null +++ b/assets/walkthrough/swiftCommands.md @@ -0,0 +1,7 @@ +# Swift Commands + +![Swift Commands](./images/swiftCommands.svg) + +Documentation for commands supported by this extension is available on [swift.org](https://docs.swift.org/vscode/documentation/userdocs/commands/). + +If you don't find the command you're looking for you can [open a new issue](https://github.com/swiftlang/vscode-swift/issues) or [pull request](https://github.com/swiftlang/vscode-swift/pulls). \ No newline at end of file diff --git a/assets/walkthrough/swiftToolchains.md b/assets/walkthrough/swiftToolchains.md new file mode 100644 index 000000000..6c35522d9 --- /dev/null +++ b/assets/walkthrough/swiftToolchains.md @@ -0,0 +1,10 @@ +The Swift extension automatically detects your installed Swift toolchain. However, it also provides a command called `Swift: Select Toolchain...` which can be used to select between toolchains if you have multiple installed. + +You may be prompted to select where to configure this new path. Your options are to: + +- `Save it in User Settings` +- `Save it in Workspace Settings` + +Keep in mind that Workspace Settings take precedence over `User Settings`. + +The Swift extension will then prompt you to reload the extension in order to pick up the new toolchain. The extension will not use the new toolchain until the extension is restarted. \ No newline at end of file diff --git a/assets/walkthrough/welcome.md b/assets/walkthrough/welcome.md new file mode 100644 index 000000000..556c43ae2 --- /dev/null +++ b/assets/walkthrough/welcome.md @@ -0,0 +1,3 @@ +

+ Welcome +

\ No newline at end of file diff --git a/package.json b/package.json index ef1062af8..ba042ad6d 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,99 @@ ], "main": "./dist/src/extension.js", "contributes": { + "walkthroughs": [ + { + "id": "swift-welcome", + "title": "Get Started with Swift for VS Code", + "description": "Learn how to use the Swift extension for VS Code.", + "steps": [ + { + "id": "installing-mac", + "title": "Install Swift", + "description": "Swift is cross-platform! If you already have Xcode installed, you're ready to go. Otherwise, see the instructions to [install on macOS](https://www.swift.org/install).\n Swift is [open source](https://github.com/swiftlang) and community driven!\n Questions? Visit the [Swift forums](https://forums.swift.org/) or the [Swift extension GitHub page](https://github.com/swiftlang/vscode-swift) for help.", + "media": { + "markdown": "./assets/walkthrough/welcome.md" + }, + "when": "isMac" + }, + { + "id": "installing-linux", + "title": "Installing Swift", + "description": "Swift is cross-platform! See the instructions to [install on Linux](https://www.swift.org/install).\n Swift is [open source](https://github.com/swiftlang) and community driven!\n Questions? Visit the [Swift forums](https://forums.swift.org/) or the [Swift extension GitHub page](https://github.com/swiftlang/vscode-swift) for help.", + "media": { + "markdown": "./assets/walkthrough/welcome.md" + }, + "when": "isLinux" + }, + { + "id": "installing-windows", + "title": "Installing Swift", + "description": "Swift is cross-platform! See the instructions to [install on Windows](https://www.swift.org/install).\n Swift is [open source](https://github.com/swiftlang) and community driven!\n Questions? Visit the [Swift forums](https://forums.swift.org/) or the [Swift extension GitHub page](https://github.com/swiftlang/vscode-swift) for help.", + "media": { + "markdown": "./assets/walkthrough/welcome.md" + }, + "when": "isWindows" + }, + { + "id": "creating-new-project", + "title": "Create a Swift project", + "description": "You can create a new Swift project with \n``Swift: Create New Project``\n in the Command Palette. \n[Try it out](command:swift.createNewProject)", + "media": { + "markdown": "assets/walkthrough/createNewProject.md" + } + }, + { + "id": "run-and-debug-executable", + "title": "Run and debug an executable", + "description": "You can run an executable from the Swift file, Command Palette or the Project Panel.", + "media": { + "markdown": "assets/walkthrough/runExecutable.md" + } + }, + { + "id": "testing", + "title": "Run tests", + "description": "Tests are automatically discovered in your project and added to the [Testing View](https://code.visualstudio.com/docs/debugtest/testing#_automatic-test-discovery-in-testing-view).\n Both [XCTest](https://developer.apple.com/documentation/xctest) and [Swift Testing](https://developer.apple.com/xcode/swift-testing/) tests are supported.", + "media": { + "markdown": "assets/walkthrough/runTests.md" + } + }, + { + "id": "documentation", + "title": "Preview DocC documentation", + "description": "Preview documentation written in DocC.", + "media": { + "markdown": "assets/walkthrough/previewDocs.md" + } + }, + { + "id": "swift-commands", + "title": "Swift commands", + "description": "Explore commands available in the Command Palette prefixed with ``> Swift:``\n See documentation for [available commands](https://docs.swift.org/vscode/documentation/userdocs/commands/). \n[Open Command Palette](command:workbench.action.showCommands)", + "media": { + "markdown": "assets/walkthrough/swiftCommands.md" + } + }, + { + "id": "selecting-toolchain", + "title": "Select a toolchain", + "description": "If you have more than one Swift toolchain installed you can switch between them. \n[Select Toolchain](command:swift.selectToolchain)", + "markdown": "", + "media": { + "markdown": "assets/walkthrough/swiftToolchains.md" + } + }, + { + "id": "customize", + "title": "Customize settings", + "description": "Customize language and extension settings. \n[Open Settings](command:workbench.action.openSettings)", + "media": { + "markdown": "assets/walkthrough/customizeSettings.md" + } + } + ] + } + ], "icons": { "swift-icon": { "description": "The official icon for the Swift programming language", diff --git a/src/toolchain/toolchain.ts b/src/toolchain/toolchain.ts index 6914d037e..2f593a9d6 100644 --- a/src/toolchain/toolchain.ts +++ b/src/toolchain/toolchain.ts @@ -496,6 +496,7 @@ export class SwiftToolchain { let str = ""; str += this.swiftVersionString; str += `\nPlatform: ${process.platform}`; + str += `\nVS Code Version: ${vscode.version}`; str += `\nSwift Path: ${this.swiftFolderPath}`; str += `\nToolchain Path: ${this.toolchainPath}`; if (this.runtimePath) { diff --git a/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md b/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md index 98165900d..1c3eae3bb 100644 --- a/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md +++ b/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md @@ -10,8 +10,9 @@ Show a live preview of your Swift documentation while editing. The Swift toolchain provides DocC, which compiles documentation for your Swift package. You can distribute compiled documentation to developers, or host the content. It's what this project used to make its documentation! You can learn more about DocC by reading [the documentation on the Swift organization's website](https://www.swift.org/documentation/docc/). View a side-by-side live preview of your documentation as you edit it with the Swift extension for VS Code. -Access this feature using the Preview Swift Documentation button at the top right of an editor, or be invoking `Swift: Preview Documentation` in the command palette. - This opens up a new editor pane with your rendered documentation: +Access this feature using the Preview Swift Documentation button at the top right of an editor, or by invoking `Swift: Preview Documentation` in the command palette. + +This opens up a new editor pane with your rendered documentation: ![An animation showing how to launch documentation live preview.](docc-live-preview.gif)