Revise WASI documentation for swift test commands#1595
Conversation
Updated links and commands for running WebAssembly tests with `swift test`, including changes from Wasmtime to WasmKit.
MaxDesiatov
requested review from
briancroom,
grynspan,
harlanhaskins,
jerryjrchen and
stmontgomery
as code owners
Updated commands to use jq for Swift SDK ID extraction.
grynspan
added
documentation
Co-authored-by: Jonathan Grynspan <jgrynspan@apple.com>
Documentation/WASI.md
Outdated
| 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
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.
Documentation/WASI.md
Outdated
| 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
Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Joseph Heck <heckj@mac.com>
Documentation/WASI.md
Outdated
| name): | ||
| WebAssembly runtime such as [WasmKit](https://github.com/swiftwasm/WasmKit). | ||
| 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. |
There was a problem hiding this comment.
A link to the appropriate swift.org download page would be helpful here.
|
Please wrap prose text to 80 columns. Thanks! |
Co-authored-by: Jonathan Grynspan <grynspan@me.com> Co-authored-by: Max Desiatov <m_desiatov@apple.com>
MaxDesiatov
dismissed
heckj’s stale review
Reviewer's feedback fully addressed.
3 participants
Updated links and commands for running WebAssembly tests with
swift test, including changes from Wasmtime to WasmKit.