Crate ark_api_macros[][src]

Expand description

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")] //

ark_test macro

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

Attribute Macros

Replaces a mod block by another one that augments type/struct/external function declarations to make them more concise, ergonomic and pleasant to use.

Macro emulating the behavior of the standard #[test] macro, but for module code compiled to WebAssembly. Such a test can then be executed with ark using ark module test.

Replaces an impl block of an HostShim trait (generated by the ark_bindgen macro) by an augmented one that automatically implements some functions, making it more ergonomic and pleasant to use.