rdunnington / bytebox

Standalone WebAssembly VM.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Bytebox

Markdown Logo

Bytebox is a WebAssembly VM.

Getting started

Requirements

Bytebox currently builds with Zig 0.13.x to avoid churn on zig master.

To run the tests:

  • wasm-tools is required to run the wasm testsuite. You can install it via the rust toolchain cargo install wasm-tools or directly from the release page.
  • python3 is required to run the wasi testsuite. You may need to run python3 -m pip install -r test/wasi/wasi-testsuite/test-runner/requirements.txt to ensure the wasi test runner has all the necessary dependencies installed.

Run Tests

git clone --recurse-submodules https://github.com/rdunnington/bytebox.git
cd bytebox
zig build test-unit # run builtin zig unit tests
zig build test-wasm # run official wasm spec testsuite
zig build test-wasi # run official wasi spec testsuite
zig build test-mem64 # run memory64 compat test
zig build test # run all of the above in parallel (output will not be pretty!)

Usage

You can use the standalone runtime to load and execute WebAssembly programs:

zig build run -- <file> [function] [function args]...

Or embed Bytebox in your own programs:

// build.zig
const std = @import("std");

pub fn build(b: *std.build.Builder) void {
    const exe = b.addExecutable("my_program", "src/main.zig");
    exe.addPackage(std.build.Pkg{
        .name = "bytebox",
        .source = .{ .path = "bytebox/src/core.zig" }, // submodule in the root dir
    });
    exe.setTarget(b.standardTargetOptions(.{}));
    exe.setBuildMode(b.standardReleaseOptions());
    exe.install();
    const run = exe.run();
    const step = b.step("run", "runs my_program");
    step.dependOn(&run.step);
}

// main.zig
const std = @import("std");
const bytebox = @import("bytebox");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    var allocator: std.mem.Allocator = gpa.allocator();

    const wasm_data: []u8 = try std.fs.cwd().readFileAlloc(allocator, "example.wasm", 1024 * 128);
    defer allocator.free(wasm_data);

    const module_def = try bytebox.createModuleDefinition(allocator, .{});
    defer module_def.destroy();
    try module_def.decode(wasm_data);

    const module_instance = try bytebox.createModuleInstance(.Stack, module_def, allocator);
    defer module_instance.destroy();
    try module_instance.instantiate(.{});
}

Inter-language FFI is also supported. See src/bytebox.h for an overview in C. To use bytebox as a static library, link with the built library in zig-out/lib/. Note that Zig assumes a default stack size of 8MB, so you'll need to ensure the same in your program.

Status

This project is still in the alpha stage.

Legend Meaning
βœ… Implemented
❌ TODO
πŸ’€ Not planned/Removed from spec

WebAssembly support:

Status Feature
βœ… WebAssembly 1.0
βœ… Sign extension instructions
βœ… Non-trapping float-to-int conversion
βœ… Multiple values
βœ… Reference types
βœ… Table instructions
βœ… Multiple tables
βœ… Bulk memory and table instructions
βœ… Vector instructions
Status Feature
βœ… args_get
βœ… args_sizes_get
βœ… environ_get
βœ… environ_sizes_get
βœ… clock_res_get
βœ… clock_time_get
βœ… fd_advise
βœ… fd_allocate
βœ… fd_close
βœ… fd_datasync
βœ… fd_fdstat_get
βœ… fd_fdstat_set_flags
πŸ’€ fd_fdstat_set_rights
βœ… fd_filestat_get
βœ… fd_filestat_set_size
βœ… fd_filestat_set_times
βœ… fd_pread
βœ… fd_prestat_get
βœ… fd_prestat_dir_name
βœ… fd_pwrite
βœ… fd_read
βœ… fd_readdir
βœ… fd_renumber
βœ… fd_seek
❌ fd_sync
βœ… fd_tell
βœ… fd_write
βœ… path_create_directory
βœ… path_filestat_get
βœ… path_filestat_set_times
❌ path_link
βœ… path_open
❌ path_readlink
βœ… path_remove_directory
❌ path_rename
βœ… path_symlink
βœ… path_unlink_file
❌ poll_oneoff
βœ… proc_exit
πŸ’€ proc_raise
❌ sched_yield
βœ… random_get
❌ sock_accept
❌ sock_recv
❌ sock_send
❌ sock_shutdown

Roadmap

These tasks must be completed to enter alpha:

  • API ergonomics pass
  • Documentation
  • General TODO/code cleanup
  • Crash hardening/fuzzing

To enter beta:

  • No breaking API changes after this point
  • Performance competitive with other well-known interpreters (e.g. micro-wasm-runtime, wasm3)

To have a 1.0 release:

  • Tested with a wide variety of wasm programs
  • Successfully used in other beta-quality projects

About

Standalone WebAssembly VM.

License:MIT License


Languages

Language:Zig 99.1%Language:C 0.7%Language:Python 0.2%Language:Shell 0.0%