Set of macros designed to help creating and implementing WebAssembly APIs and bindings, designed to run in the Ark environment.

See also the private Ark documentation for details of how things work, motivation behind this crate, as well as thorough examples of what it can do.

The problem

Implementing WebAssembly FFI (foreign function interfaces) by hand is tedious and doesn't allow using idiomatic Rust, like taking or returning non-plain types (user structs, enum, etc. but also idiomatic Rust types like Result/String and so on and so forth).

The solution

This crate provides macros that are designed to work together to solve this particular problem, and allow the usage of high-level patterns in APIs.

User-side ark_bindgen macro

This macro applies on a mod defined in a Rust file that is to be compiled to WebAssembly. The output of this macro depends on whether it's running on the host or not:

• On the host, this will create an HostShim trait, that contains a few static internal methods, as well as methods mirroring the extern C function declarations, using high-level, idiomatic Rust patterns. This macro can be partially implemented automatically with the host_exports macro, described below.
• In user code, this will also create the trait as well as a safe Rust mod containing functions with the same signatures as in the declaration.

Here are the different kind of declarations one can do with it:

// TODO reinclude, see also #4516 //rust,ignore //#![doc = include_str!("../../api-ffi/src/ffi/example_automatic.rs")] //

Host-side host_export macro

This macro applied on impl blocks for the HostShim trait generated by the above macro. An end user only needs to implement the _shim functions in the trait, and get the rest implemented for free by this macro.

// TODO reinclude, see also #4516 //rust,ignore //#![doc = include_str!("../../../components/module-host/src/host_api/examples/automatic_macro.rs")] //

test macro

This macro is designed to replicate the behavior of #[test] in Rust modules compiled to WebAssembly.