Skip to content

Update documentation for swiftly #1905

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.

Sign up for GitHub

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

Merged
merged 6 commits into from
Oct 29, 2025
Merged

Update documentation for swiftly #1905

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
eae4953
update documentation for swiftly
matthewbastien Oct 28, 2025
0a2784a
consistent naming for `Swift: Select Toolchain...` command
matthewbastien Oct 28, 2025
39d026f
use more direct wording in the present tense
matthewbastien Oct 28, 2025
921df92
include instructions for opening an existing Swift project
matthewbastien Oct 28, 2025
0de9d84
use the full command name instead of just saying `toolchain selection`
matthewbastien Oct 28, 2025
a935951
add links to more swiftly docs
matthewbastien Oct 29, 2025
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
9 changes: 7 additions & 2 deletions userdocs/userdocs.docc/Articles/Topics/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

Install the Swift extension via the VS Code Marketplace.

The Swift extension is supported on macOS, Linux, and Windows.
The Swift extension is supported on macOS, Linux, and Windows. To set it up:
1. Install Swift from the [Swift.org website](https://www.swift.org/install).
2. Install [Visual Studio Code](https://code.visualstudio.com/Download).
3. Install the Swift extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode).

To install, firstly ensure you have [Swift installed on your system](https://www.swift.org/install/). Then [install the Swift extension](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode). Once your machine is ready, you can get started with the **Swift: Create New Project...** command.
Once your machine is ready, you can start writing Swift code:
* Use the **`Swift: Create New Project...`** command from the command palette to initialize a new project.
* Navigate to **`File > Open Folder`** in the menu bar to open an existing project on your machine.
29 changes: 27 additions & 2 deletions userdocs/userdocs.docc/Articles/Topics/supported-toolchains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,39 @@ Feature | Minimum Toolchain Required
Debugging with `lldb-dap` | 6.0
<doc:docc-live-preview> | 6.2

## Toolchain Management

The Swift extension automatically detects installations of the Swift toolchain in your environment. It looks for a `swift` binary available in `PATH` and, if one cannot be found, prompts you to [install a toolchain from Swift.org](https://www.swift.org/install).

If you have multiple Swift toolchains installed on your system, use the command `Swift: Select Toolchain...` to tell the extension which toolchain to use. The command shows you a list of all the toolchains that VS Code found on your system and lets you switch between them.

@Video(
source: "toolchain-selection.mp4",
alt: "A video showing a VS Code window. The command palette is opened to run the 'Swift: Select Toolchain...' command which is then used to select Xcode as the preferred toolchain.",
poster: "toolchain-selection.png"
)

## Swiftly Support

The extension supports toolchains managed by [swiftly](https://github.com/swiftlang/swiftly), the Swift toolchain installer and manager. For instructions on installing swiftly see the [installation instructions on Swift.org](https://www.swift.org/install).
The extension supports toolchains managed by [swiftly](https://github.com/swiftlang/swiftly), the Swift toolchain installer and manager. This is the recommended way of installing Swift toolchains on macOS and Linux. For instructions on installing swiftly see the [installation instructions on Swift.org](https://www.swift.org/install).
Copy link
Contributor

@rbenegal rbenegal Oct 28, 2025

Choose a reason for hiding this comment

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

Would it be better to use swiftly (in monospace font) instead of just swiftly everywhere to make sure people understand that we're referring to the tool and not the adverb?

Copy link
Member Author

@matthewbastien matthewbastien Oct 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I'm on the fence about this one. Swiftly's documentation always refers to itself as swiftly without the monospace and all lower-case (even when it's at the start of a sentence which is interesting). I also don't think that the monospaced font is super distinguishable between the standard font in the compiled documentation unless it's made bold as well.


You can choose a swiftly managed toolchain to use from the `> Swift: Select Toolchain` menu.
Choose a swiftly managed toolchain to use from the `> Swift: Select Toolchain...` menu.

If you do `swiftly use` on the command line you must restart VS Code or do `> Developer: Reload Window` in order for the VS Code Swift extension to start using the new toolchain.

### Installing Toolchains

The Swift extension can use swiftly to install toolchains on your behalf. This allows you to discover, install, and configure Swift toolchains directly from the VS Code interface without needing to use the command line.

Before using the toolchain installation feature, ensure you meet the following requirements:

* **Swiftly 1.1.0 or newer** - The installation feature requires swiftly version 1.1.0 or newer
* **Administrator Privileges** - On Linux systems, administrator privileges may be required to execute post-installation scripts

You can access the installation commands via the `Swift: Select Toolchain...` command, or by running the following commands directly:
- **`Swift: Install Swiftly Toolchain...`** - installs stable Swift toolchains via swiftly
- **`Swift: Install Swiftly Snapshot Toolchain...`** - installs snapshot Swift toolchains via swiftly

### .swift-version Support

Swiftly can use a special `.swift-version` file in the root of your package so that you can share your toolchain preference with the rest of your team. The VS Code Swift extension respects this file if it exists and will use the toolchain specified within it to build and test your package.
Expand Down
Binary file added userdocs/userdocs.docc/Resources/toolchain-selection.mp4
View file
Open in desktop
Binary file not shown.
Binary file added userdocs/userdocs.docc/Resources/toolchain-selection.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.