Revise WASI documentation for swift test commands#1595
Revise WASI documentation for swift test commands#1595MaxDesiatov wants to merge 4 commits intomainfrom
swift test commands#1595Conversation
Updated links and commands for running WebAssembly tests with `swift test`, including changes from Wasmtime to WasmKit.
Updated commands to use jq for Swift SDK ID extraction.
Co-authored-by: Jonathan Grynspan <jgrynspan@apple.com>
| swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm" | ||
| ``` | ||
|
|
||
| ## Swift 6.2 |
There was a problem hiding this comment.
Our main branch only supports 6.3 onward, so we can drop documentation for 6.2 outright.
There was a problem hiding this comment.
There are still users of 6.2 out there that may stumble upon this document and find it useful.
There was a problem hiding this comment.
Users of the 6.2 toolchain should refer to the documentation for version 6.2. Our main branch documents itself.
There was a problem hiding this comment.
How would users of the 6.2 toolchain know that? If I'm using Swift Testing for WASI for the first time and searching on GitHub or, if this page was indexed by some other search engine there's no context here that says "these instructions work only for main branch and none of the earlier versions". One would probably have to be a Swift Testing Swift and/or toolchain engineer to orient between branches and click through to a release branch before trying out instructions at the top. I don't think that having this 6.2 section is actively harmful at least until 6.3 or subsequent versions are released, but could be a massive time saver for users of a released version, especially in the absence of different places where this is documented.
There was a problem hiding this comment.
The gist is that we generally want to avoid a decision tree where possible. Since this is a forward transition, with 6.3 or later, then it's to call out there's a different process earlier, we use that version of Swift as the marker, but avoid setting up phrasing that leads to a mental "Look up what version of Swift you're using, then following the process from the list below..." kinds of thing
heckj
left a comment
There was a problem hiding this comment.
Since this is a transition point to where we're getting SDK support in the swift test command, let's phrase it up as a such, using Swift 6.3 as the marker of the transition. I've made some suggestions to the section headers to re-frame it as such, particularly to avoid leading the reader into a mental "lookup model", which referencing different versions of Swift (development chains, Swift 6.2, etc) start to do.
In our ideal world, we'd have a single direct "To test, do this...", but to call out support for teams using testing with earlier versions, our docs have used the "prior to..." sort of setup as a transition flag.
| In Swift development snapshots, running `swift test --swift-sdk <wasm_swift_sdk_id>` is fully | ||
| supported. When you have `jq` installed, you can run this command to compute the Swift SDK ID automatically: |
There was a problem hiding this comment.
| In Swift development snapshots, running `swift test --swift-sdk <wasm_swift_sdk_id>` is fully | |
| supported. When you have `jq` installed, you can run this command to compute the Swift SDK ID automatically: | |
| In Swift 6.3 and later, running `swift test --swift-sdk <wasm_swift_sdk_id>` is build and runs your tests. | |
| Use `jq` to extract the Swift SDK ID automatically to build and test in a single command: |
| [these instructions](https://www.swift.org/documentation/articles/wasm-getting-started.html). | ||
|
|
||
| Because `swift test` doesn't know what WebAssembly environment you'd like to use | ||
| ## Swift Development Snapshots |
There was a problem hiding this comment.
| ## Swift Development Snapshots |
| swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm" | ||
| ``` | ||
|
|
||
| ## Swift 6.2 |
There was a problem hiding this comment.
The gist is that we generally want to avoid a decision tree where possible. Since this is a forward transition, with 6.3 or later, then it's to call out there's a different process earlier, we use that version of Swift as the marker, but avoid setting up phrasing that leads to a mental "Look up what version of Swift you're using, then following the process from the list below..." kinds of thing
| In Swift 6.2 `swift test` doesn't know what WebAssembly environment you'd like to use | ||
| to run your tests, building tests and running them are two separate steps. To | ||
| build tests for WebAssembly, use the following command: |
There was a problem hiding this comment.
| In Swift 6.2 `swift test` doesn't know what WebAssembly environment you'd like to use | |
| to run your tests, building tests and running them are two separate steps. To | |
| build tests for WebAssembly, use the following command: | |
| Prior to Swift 6.3 `swift test` doesn't support using the SDK to indicate the WebAssembly environment to use for tests. | |
| In this case, building tests and running them are two separate steps. | |
| To build tests for WebAssembly, use the following command: |
| Starting with Swift 6.2, WasmKit is included in Swift toolchains for Linux and macOS | ||
| distributed on swift.org. For example, to run tests using | ||
| WasmKit, use the following command (replace `{YOURPACKAGE}` with your package's | ||
| name): |
There was a problem hiding this comment.
| Starting with Swift 6.2, WasmKit is included in Swift toolchains for Linux and macOS | |
| distributed on swift.org. For example, to run tests using | |
| WasmKit, use the following command (replace `{YOURPACKAGE}` with your package's | |
| name): | |
| WasmKit is included in the Swift toolchain for Linux and macOS for Swift 6.2 and later. | |
| Download and install an open-source release toolchain from swift.org to get a toolchain that includes WasmKit. | |
| To run the rests you built previously using the WasmKit runtime, use the following command, replacing `{YOURPACKAGE}` with the name of your package: |
| swift test --swift-sdk "$(swiftc -print-target-info | jq -r '.swiftCompilerTag')_wasm" | ||
| ``` | ||
|
|
||
| ## Swift 6.2 |
There was a problem hiding this comment.
| ## Swift 6.2 | |
| ## Build and Test WebAssembly separately |
Updated links and commands for running WebAssembly tests with
swift test, including changes from Wasmtime to WasmKit.