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 thehost_exports
macro, described below. - In user code, this will also create the trait as well as a
safe
Rustmod
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.