Skip to content

webassembly.md

Latest commit

 

History

History
88 lines (59 loc) · 4.7 KB

webassembly.md

File metadata and controls

88 lines (59 loc) · 4.7 KB
Raw

WebAssembly Support

MarkdownUtilitiesCore supports WebAssembly through the official Swift WASI SDK. The supported baseline is:

  • Swift toolchain: Swift 6.3.1
  • Swift SDK: swift-6.3.1-RELEASE_wasm
  • target: wasm32-unknown-wasip1

The WebAssembly target remains computation-focused. It parses and renders supplied Markdown content, mutates document structures, performs type and rule assessment, resolves RFC 3986 identifiers, and projects supplied YAML without owning filesystem, network, or host runtime behavior.

Install the SDK

The Swift toolchain and WebAssembly SDK versions must match exactly. Install the official Swift 6.3.1 SDK with:

swift sdk install \
  https://download.swift.org/swift-6.3.1-release/wasm-sdk/swift-6.3.1-RELEASE/swift-6.3.1-RELEASE_wasm.artifactbundle.tar.gz \
  --checksum bd47baa20771f366d8beed7970afaa30742b2210097afd15f85427226d8f4cf2

Confirm that SwiftPM can discover it:

swift sdk list

Build and Run

Run the repeatable build and runtime verification:

scripts/build-wasm.sh

The script:

  1. verifies that the matching WebAssembly SDK is installed;
  2. resolves the versions in Package.resolved;
  3. applies version-checked WASI compatibility patches to the Yams, JSONSchema.swift, and swift-toml SwiftPM checkouts;
  4. compiles MarkdownUtilitiesCore for WASI; and
  5. builds and runs MarkdownUtilitiesCoreWasmSmoke.wasm with Swift's bundled WasmKit runtime.

To use an SDK extracted outside SwiftPM's default SDK directory, provide its parent directory with a trailing slash:

SWIFT_WASM_SDKS_PATH=/path/to/swift-sdks/ scripts/build-wasm.sh

Debug artifacts are written beneath .build/wasm32-unknown-wasip1/debug/. The smoke artifact is currently about 69 MB in an unoptimized debug build; this is not a release-size target.

Compatibility Patches

The current resolved dependencies need three narrow source-level adaptations:

  • Yams 6.2.0 uses DBL_DECIMAL_DIG, which is not imported into Swift by the WASI Foundation module. The WASI branch uses 17 significant decimal digits, the round-trip requirement for an IEEE 754 binary64 value.
  • JSONSchema.swift 0.6.0 passes NSNumber directly to CFNumberIsFloatType outside Linux. WASI uses the package's existing Linux-compatible integer check instead.
  • swift-toml's toml++ parser is a C++ target, while the WASI SDK's C++ runtime has exceptions disabled. The WASI branch selects toml++'s exception-free parse-result path, and the build passes -fno-exceptions for C++ sources.

The patches live in scripts/wasm-patches/. The build script verifies the exact dependency revisions before applying them and fails rather than patching an unknown version. All three changes are conditional on WASI and do not alter native behavior.

CoreFoundation also requires the WASI signal and memory-mapping emulation definitions while compiling. The smoke target links the corresponding wasi-emulated-signal and wasi-emulated-mman libraries only on WASI.

DynamicJSON 1.0.2 compiles and runs under WASI without a package patch. Its smoke assertion parses a strict RFC 9535 query and evaluates the ordered located results against an in-memory JSON value. The Core adapter performs only in-memory value conversion, outer limit checks, evaluation, and location-to-node association, so it introduces no host filesystem or network dependency.

The fm-var source primitives also remain host-neutral. Core resolves identifiers and composes YAML from supplied strings; a WASI embedding is responsible for providing an absolute containing URI and authorized immutable resource bytes. Concrete filesystem and network providers are intentionally outside the WASI Core target.

Smoke Coverage

IntegrationTests/WasmCoreSmoke/ verifies representative behavior across the dependency boundary:

  • YAML frontmatter through Yams/libYAML and TOML frontmatter through swift-toml;
  • Markdown AST parsing of headings, task lists, and tables through MarkdownSyntax and swift-cmark;
  • Markdown rendering; and
  • draft 2020-12 JSON Schema and Markdown type assessment; and
  • strict RFC 9535 parsing and ordered nodelist evaluation through DynamicJSON; and
  • RFC 3986 source resolution plus YAML 1.2.2 Core Schema projection through Yams.

The root package owns the smoke target, so it uses the same Package.resolved versions as the library. A separate path-dependent integration package would resolve its own transitive dependency versions.

Current Scope

This workflow produces and executes a WASI module. It does not yet define a stable JavaScript ABI, optimize or package a release artifact, or integrate with a specific JavaScript or Workers host. Those layers should build on the verified Core module without introducing host I/O into MarkdownUtilitiesCore.