docs: add usage guides for WITOverlayGenerator and WITExtractor#343
Open
shivanshu877 wants to merge 2 commits into
Open
docs: add usage guides for WITOverlayGenerator and WITExtractor#343shivanshu877 wants to merge 2 commits into
shivanshu877 wants to merge 2 commits into
Conversation
Addresses the two open items in issue swiftwasm#71 ("Enhance documentation"): - Example and usage of WITOverlayGenerator - Example and usage of WITExtractor Both documents are derived from the source code of the respective modules (WITOverlayGen.swift, WITExtractor.swift) and their SPM plugins (WITOverlayPlugin, WITExtractorPlugin).
MaxDesiatov
requested changes
May 21, 2026
| For scripted use, call the `extract-wit` subcommand directly: | ||
|
|
||
| ```sh | ||
| swift run wit-tool extract-wit \ |
Member
There was a problem hiding this comment.
It doesn't look like these instructions were verified end-to-end, or at least not verified with the state of the repository as I see it? swift run wit-tool won't work. This will fail with error: no executable product named wit-tool
Suggested change
| swift run wit-tool extract-wit \ | |
| swift run WITTool extract-wit \ |
|
|
||
| ```swift | ||
| // Sources/MathLib/MathLib.swift | ||
| public struct Vector2 { |
Member
There was a problem hiding this comment.
IIRC WITExtractor only extracts decls with @_spi(WIT) on them.
| swift run wit-tool extract-wit \ | ||
| --swift-api-digester $(xcrun --find swift-api-digester) \ | ||
| --module-name MyLibrary \ | ||
| --package-name my-library \ |
Member
There was a problem hiding this comment.
the plugin form only accepts --target, --sdk, --output-mapping. It auto-derives the WIT package name from context.package.displayName. This snippet conflates the plugin and the CLI
Three issues: 1. CLI executable name was wrong — `wit-tool` doesn't exist; the Package.swift declares `WITTool`. Changed `swift run wit-tool` to `swift run WITTool`. 2. End-to-end example mixed the plugin form (`--target`) with the CLI `--package-name` arg. The plugin only accepts `--target`, `--sdk`, and `--output-mapping`, and auto-derives the WIT package name from `context.package.displayName`. Reworked the "Running…" snippet to use the plugin form properly, with a parenthetical pointing at the CLI form for callers that need to override the package name. 3. WITExtractor only extracts declarations annotated with `@_spi(WIT)` (confirmed in `Sources/WITExtractor/SourceSummary.swift` line 221). Added a note in the "When to use it" section and applied `@_spi(WIT)` to the example's `Vector2` and `addVectors`.
Author
|
Thanks @MaxDesiatov — all three addressed in
Ready for re-review. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses the two open items in #71 ("Enhance documentation"):
WITOverlayGeneratorWITExtractorBoth documents are derived from reading the source of the respective modules (
WITOverlayGen.swift,WITExtractor.swift) and their SPM plugins (WITOverlayPlugin,WITExtractorPlugin).The intent is the same as the existing module docs in WasmKit's docc bundle — make the WIT tooling discoverable for users coming from outside the project.
Test plan