swiftwasm / wasmkit

WebAssembly Runtime written in Swift

WasmKit

WasmKit is a standalone and embeddable WebAssembly runtime implementation written in Swift.

Usage

The best way to learn how to use WasmKit is to look at the Examples directory.

Command Line Tool

WasmKit provides a command line tool to run WebAssembly binaries compliant with WASI.

$ git clone https://github.com/swiftwasm/WasmKit.git
$ cd WasmKit
$ swift run wasmkit-cli run ./Examples/wasm/hello.wasm
Hello, World!

As a Library

Swift Package Manager

You can use WasmKit as a Swift Package Manager dependency by adding the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/swiftwasm/WasmKit.git", from: "0.0.5"),
],

You can find API documentation on the Swift Package Index.

Features

• Minimal dependencies
  • The core runtime engine depends only on swift-system.
  • No Foundation dependency
• Compact and embeddable
  • Debug build complete in 5 seconds¹
• Batteries included
  • WASI support, WAT parser, etc.

Supported Platforms

WasmKit engine works on all major platforms supported by Swift. It is continuously tested on macOS, Ubuntu, and Windows, and should work on the following platforms:

• macOS 10.13+, iOS 12.0+, tvOS 12.0+, watchOS 6.0+
• Ubuntu 20.04+
• Windows 10+

Implementation Status

Category	Feature	Status
WebAssembly MVP	Parsing binary format	✅ Implemented
	Parsing text format (WAT)	✅ Implemented
	Execution	✅ Implemented
	Validation	🚧 Partially implemented
WebAssembly Proposal	Reference types	✅ Implemented
	Bulk memory operations	✅ Implemented
	Mutable globals	✅ Implemented
	Sign-extension operators	✅ Implemented
	Non-trapping float-to-int conversions	✅ Implemented
	Memory64	✅ Implemented
	Threads and atomics	🚧 Parser implemented
WASI	WASI Preview 1	✅ Implemented

Minimum Supported Swift Version

The minimum supported Swift version of WasmKit is 5.8, which is the version used to bootstrap the Swift toolchain in ci.swift.org.

Testing

To run the WasmKit test suite, you need to checkout the test suite repositories first.

# Checkout test suite repositories
$ ./Vendor/checkout-dependency
# Run tests
$ swift test

Acknowledgement

This project was originally developed by @akkyie, and is now maintained by the community.

Footnotes

1. On a 2020 Mac mini (M1, 16GB RAM) with Swift 5.10. Measured by swift package resolve && swift package clean && time swift build --product PrintAdd. ↩

wasmkit's Issues

CMake build

Test on Windows

• Parser
• Interpreter
• WASI

Make WASI deterministic

At the moment it seems like there are two sources of nondeterminism in WASI:

1. The random number generator, which is hardcoded to swift_stdlib_random
2. The clocks, hardcoded to the real system clocks

What if we allowed these to be overridden by user-provided Swift.RandomNumberGenerator and Swift.Clock types respectively? We could default to SystemRandomNumberGenerator and ContinuousClock + SuspendingClock.

To my understanding, enabling these to be overridden would allow for fully deterministic execution of WASI binaries while also serving as Dependency Injection points for solid testability.

Tagging a release

I was going to add the package to https://swiftpm.co/ to make it more discoverable. The catalog requires it to have at least a single release. @akkyie would you mind if I tag 0.0.1 now?

Why memory is empty

I imported the wasm file to parse the wasm output data. The memory is empty.

wat file

(module
 (type $0 (func (result i32)))
 (memory $0 1)
 (data $0 (i32.const 1036) ",")
 (data $0.1 (i32.const 1048) "\02\00\00\00\16\00\00\00h\00e\00l\00l\00o\00 \00w\00o\00r\00l\00d")
 (export "getHelloWorld" (func $assembly/index/getHelloWorld))
 (export "memory" (memory $0))
 (func $assembly/index/getHelloWorld (result i32)
  i32.const 1056
 )
)

Module(types: [WasmKit.FunctionType(parameters: [], results: [i32])], functions: [WasmKit.GuestFunction(type: 0, defaultLocals: UnsafeBufferPointer(start: 0x00006000022583a0, count: 0), _bodyStorage: nil, materializer: (Function))], tables: [], memories: [WasmKit.Memory(type: WasmKit.Limits(min: 1, max: nil, isMemory64: false))], globals: [], elements: [], dataCount: Optional(2), data: [WasmKit.DataSegment.active(WasmKit.DataSegment.Active(index: 0, offset: [WasmKit.Instruction.numericConst(I32(1036))], initializer: ArraySlice([44]))), WasmKit.DataSegment.active(WasmKit.DataSegment.Active(index: 0, offset: [WasmKit.Instruction.numericConst(I32(1048))], initializer: ArraySlice([2, 0, 0, 0, 22, 0, 0, 0, 104, 0, 101, 0, 108, 0, 108, 0, 111, 0, 32, 0, 119, 0, 111, 0, 114, 0, 108, 0, 100])))], start: nil, imports: [], exports: [WasmKit.Export(name: "hello_world", descriptor: WasmKit.ExportDescriptor.function(0)), WasmKit.Export(name: "memory", descriptor: WasmKit.ExportDescriptor.memory(0))], customSections: [WasmKit.CustomSection(name: "sourceMappingURL", bytes: ArraySlice([18, 46, 47, 114, 101, 108, 101, 97, 115, 101, 46, 119, 97, 115, 109, 46, 109, 97, 112]))])

Fatal error when running: Examples/wasm/fib.wasm

the example from README doesn't seem to work

WasmKit on main ❯ swift run wasmkit-cli run Examples/wasm/fib.wasm fib i32:10
Building for debugging...
[1/1] Write swift-version--58304C5D6DBC2206.txt
Build complete! (0.11s)
CLI/Run.swift:129: Fatal error: unknown type
zsh: trace trap  swift run wasmkit-cli run Examples/wasm/fib.wasm fib i32:10

Enhance documentation

• Example of WasmKit engine
• API document of WasmKit
• Example and usage of WITOverlayGenerator
• Example and usage of WITExtractor

No LICENSE file

Hi - I'm interested in using WAKit to make a QuickLook extension for .wasm files, but I don't see a LICENSE file in the project so it's not clear whether that's allowed.

Could you please add a LICENSE file? Preferably a non-restrictive license if you're ok with it being reused. Thanks.

Import object

I'm skimming through the project trying to figure out how to use the library. One thing I have not found how to do, which is the import object.

I have the following:

let modInstance = try runtime.instantiate(module: module, externalValues: [
    ExternalValue.function(/*What do I put here?*/)
])

What I want to accomplish is calling a Swift function from wasm.

Any help on this?

Thank you in advance,
Jomy

stackTypeMismatch when using `drop` instruction and when using globals when there is a local

I'm running wasm code with the following:

guard let fileHandle = FileHandle(forReadingAtPath: "./test.wasm") else {
    throw InterpreterError.interpreterReadError
}

defer { fileHandle.closeFile() }

let stream = FileHandleStream(fileHandle: fileHandle)

let module = try WasmParser.parse(stream: stream)
let runtime = Runtime()
let instance = try runtime.instantiate(module: module, externalValues: [])

let result = try runtime.invoke(instance, function: "test")

print(result)

Consider the following wasm code:

(module
    (func $test
        i32.const 1
        drop
    )
    
    (export "test" (func $test))
)

when I run the swift code, invoking the "test" function. It return the following error:

stackTypeMismatch(expected: WAKit.Value, actual: WAKit.Label

WASI Preview 2/component model support

Hey there! Really cool project.

I was curious to see if one someone from the community is interested in adding support for applications that have been compiled against WASI preview 2 and the component model.

For some background context, I'm really interested in embedding a library compiled to WebAssembly into an iOS app. My library has been compiled to WASI via Rust's wasm32-wasi-preview2 target and I'm looking to see how many different devices I can currently embed that library into.

Is there a limitation preventing this project from supporting WASI preview 2 and/or the component model? Are there alternative runtimes available with wasip2 support that you're aware of?

Thank you!

Add fuzzing test targets

Validate all functions ahead of time

We currently validate only executed functions at runtime, but to catch this kind of signature mismatch, it might be worth adding an option to enforce full validation ahead of time.

Faster execution to enable all executable tests in apple/swift

Currently we filter out 2 test cases in Swift's CI due to poor performance issue of WasmKit https://github.com/apple/swift/blob/d6f9401c28b7588b98b72bcf36bfcdac420e2425/utils/swift_build_support/swift_build_support/products/wasmstdlib.py#L140-L142