-
Notifications
You must be signed in to change notification settings - Fork 79
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
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
There are several project templates to choose from: | ||
- `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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
 |
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 Workspace Settings | ||
|
||
Keep in mind that Workspace Settings take precedence over User Settings. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe for the |
||
|
||
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. |
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> |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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.", | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ideas for the future:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ya or link to install page on swift.org There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The There was a problem hiding this comment. Choose a reason for hiding this commentThe 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" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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)", | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we create our own |
||
"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.", | ||
plemarquand marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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" | ||
} | ||
} | ||
] | ||
} | ||
], | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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)
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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", | ||
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.