Skip to content

Add an extension walkthrough #1572

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vscodeignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
!images/**
!snippets/**
!assets/icons/**
!assets/walkthrough/**
!assets/documentation-webview/**
!assets/swift-docc-render/**
!node_modules/@vscode/codicons/**
12 changes: 12 additions & 0 deletions assets/walkthrough/createNewProject.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
There are several project templates to choose from:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be cool if there was some way we could just generate this from the code. I feel like we'll forget to update this page if we change the template options in the future.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but these descriptions aren't going to 1:1 match the ones from SwiftPM's help documentation so we'd need to craft a description for each one by hand anyway.

- `Library`: A package with a library. Use this to publish code for other packages to consume.
- `Executable`: A package with an executable. Use this for command line utilities.
- `Tool`: A package with an executable that uses Swift Argument Parser. Use this if you plan to have a rich set of command line arguments.
- `Build Tool Plugin`: A package that vents a Swift build tool plugin.
- `Command Plugin`: A package that vends a Swift command plugin.
- `Macro`: A package that vends a Swift macro.
- `Empty`: An empty package with just a `Package.swift` manifest.

Once you select a 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.

Finally, you'll be prompted to select a location for your new project. You can choose any location in your workspace, or create a new folder.
55 changes: 55 additions & 0 deletions assets/walkthrough/images/createNewProject.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/walkthrough/images/projectTypes.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 changes: 40 additions & 0 deletions assets/walkthrough/images/swiftCommands.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 22 additions & 0 deletions assets/walkthrough/images/swiftLogo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/walkthrough/images/testing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions assets/walkthrough/runningTests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
![Testing](./images/testing.png)
10 changes: 10 additions & 0 deletions assets/walkthrough/swiftToolchains.md
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if we can link to other pieces of documentation but perhaps we could link to some documentation on how the extension detects which toolchain it will use? I think the logic is a little tricky since it depends on things like environment variables, is swiftly installed, is Xcode installed etc.


You may be prompted to select where to configure this new path. Your options are to:

- Save it in User Settings
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

similar to what is done for command names, we should show button text as Save it in User Settings and Save in Workspace Setting

- Save it in Workspace Settings

Keep in mind that Workspace Settings take precedence over User Settings.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe for the User Settings tab name too?


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.
3 changes: 3 additions & 0 deletions assets/walkthrough/welcome.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<p align="center">
<img src="./images/swiftLogo.svg" width="300" height="300" alt="Welcome" />
</p>
70 changes: 70 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,76 @@
],
"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": "Installing 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/) for help.",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideas for the future:

  • Can possibly detect automatically if swift is already installed and skip this point if it is?
  • I think this is where the swiftly "Download Swift" command can go once the project is implemented

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ya or link to install page on swift.org

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The open source and Swift forums mentions and links I think we should take out of the install, maybe leave it as a final Get Help step. Seems a little noisy here

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

technically command line tools works too for people who don't want Xcode

"media": {
"markdown": "./assets/walkthrough/welcome.md"
},
"when": "isMac"
},
{
"id": "installing-mac",
"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/) for help.",
"media": {
"markdown": "./assets/walkthrough/welcome.md"
},
"when": "isLinux"
},
{
"id": "installing-mac",
"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/) for help.",
"media": {
"markdown": "./assets/walkthrough/welcome.md"
},
"when": "isWindows"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious to know if this works when using Remote SSH to go from Mac -> Windows or vice versa. The isWindows/isMac/isLinux clauses only check the platform that the UI is running on. However, installing Swift depends on where the extension host is running.

},
{
"id": "creating-new-project",
"title": "Creating a Swift Project",
"description": "✏️ When you open an empty workspace you can use the Create Swift Project button shown in the File Navigator, or you can create a new Swift project using the command palette.\n[Create New Project](command:swift.createNewProject)",
"media": {
"markdown": "assets/walkthrough/createNewProject.md"
}
},
{
"id": "swift-commands",
"title": "Swift Commands",
"description": "🎨 Explore the commands available in the command palette prefixed with \"> Swift:\". You can use the command palette to run any of the commands provided by the Swift extension.\n[Open Command Palette](command:workbench.action.showCommands)",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we create our own Show Swift Commands... command that wraps await vscode.commands.executeCommand("workbench.action.quickOpen", "> Swift:");

"media": {
"svg": "assets/walkthrough/images/swiftCommands.svg",
"altText": "Swift Commands"
}
},
{
"id": "testing",
"title": "Running 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.",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe command to run all tests or use one of the add test target refactorings?

"media": {
"markdown": "assets/walkthrough/runningTests.md"
}
},
{
"id": "selecting-toolchain",
"title": "Selecting a Toolchain",
"description": "🛠️ If you have more than one Swift toolchain installed you can switch between them.",
"markdown": "",
"media": {
"markdown": "assets/walkthrough/swiftToolchains.md"
}
}
]
}
],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideas for some other steps (some of these could be in their own section)

  • Project Panel
  • Useful settings (inlay hints come to mind so that the user is aware of the feature, possibly other useful settings as well)
  • Debugging
  • Project Panel
  • Documentation generation with DocC
  • Tips like hovering over the {} icon to see which swift version you're currently using

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe flag the environment and args settings and that they tie into all tasks?

"icons": {
"swift-icon": {
"description": "The official icon for the Swift programming language",
Expand Down
1 change: 1 addition & 0 deletions src/toolchain/toolchain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -536,6 +536,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) {
Expand Down