Skip to content

docs: Add multiple backend support to C API docs #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions docs/c-api/backends.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Multiple Backends in the C API

Wasmer's C API now supports multiple backends, allowing you to choose the most appropriate WebAssembly runtime for your specific use case.

## Available Backends

The C API supports the following backends:

- **UNIVERSAL** (sys): The default backend that supports multiple compilers (Cranelift, LLVM, Singlepass)
- **V8**: Google's V8 JavaScript engine
- **WAMR**: WebAssembly Micro Runtime
- **WASMI**: A WebAssembly interpreter written in Rust
- **JSC**: JavaScriptCore engine

## Selecting a Backend

You can select a backend when creating a new engine configuration:



## Default Backend

The default backend is determined by the features enabled during compilation. The priority order is:

1. If a specific `*-default` feature is enabled (e.g., `sys-default`, `v8-default`, etc.), that backend is used
2. Otherwise, the first available backend in the following order is used: sys, wamr, wasmi, v8, js, jsc

## Engine-Specific Configuration

Each backend has its own specific configuration options. The C API now provides engine-specific functions to configure each backend.

### Universal (sys) Backend Configuration

The Universal backend supports multiple compilers and configuration options:



## Breaking Changes

This update introduces several breaking changes to the C API:

1. Functions that were implicitly tied to the `sys` engine are now explicitly scoped with the `sys` prefix:
- `wasm_config_canonicalize_nans` → `wasm_config_sys_canonicalize_nans`
- `wasm_config_set_target` → `wasm_config_set_sys_target`
- `wasm_config_push_middleware` → `wasm_config_sys_push_middleware`
- `wasm_config_set_compiler` → `wasm_config_set_sys_compiler`

2. Calling engine-specific configuration functions will automatically switch the engine type to the corresponding backend. For example, calling `wasm_config_sys_push_middleware` will set the engine to `UNIVERSAL` regardless of what was previously set.

## Feature Flags

To use a specific backend, you need to enable the corresponding feature when building Wasmer:

- `sys`: Enable the Universal backend
- `v8`: Enable the V8 backend
- `wamr`: Enable the WAMR backend
- `wasmi`: Enable the WASMI backend
- `jsc`: Enable the JSC backend

To set a specific backend as default, use the corresponding `-default` feature:

- `sys-default`: Use the Universal backend as default
- `v8-default`: Use the V8 backend as default
- `wamr-default`: Use the WAMR backend as default
- `wasmi-default`: Use the WASMI backend as default
- `jsc-default`: Use the JSC backend as default

## Example