Crate wabam

A crate for creating WebAssembly modules.

Example

let mut module = wabam::Module::default();

module.types = vec![
    wabam::func_type!((param) (result)),
    wabam::func_type!((param i32 i32 i32 i32) (result i32)),
];

// Import WASI's `fd_write`, to print to the terminal
let fd_write = wabam::interface::FuncImport {
    module: "wasi_snapshot_preview1".into(),
    name: "fd_write".into(),
    type_idx: 1, // types[1], see above
};
module.imports.functions.push(fd_write);

// Define memory
let memory = wabam::Limit {
    start: 1,
    end: None,
};
module.memories.push(memory);

let text = "Hello, wasm!";
let text_ptr = 12;

// Load the text into memory
let data = wabam::Data::Active {
    mem_index: 0,
    offset: wabam::instr!(i32.const { text_ptr }).into(),
    data: text.into(),
};
module.datas.push(data);

let body = wabam::instrs!(
    (i32.const 0) // Where the `(ptr, len)` pair is
    (i32.const { text_ptr })
    (i32.store) // Write ptr
     
    (i32.const 0) // Where the `(ptr, len)` pair is
    (i32.const { text.len() as i32 })
    (i32.store offset=4) // Write len

    (i32.const 1) // File descriptor, stdout is 1.
    (i32.const 0) // Where the `(ptr, len)` pair is
    (i32.const 1) // How many `(ptr, len)` pairs there are
    (i32.const 8) // Where to write the number of written bytes
    (call 0) // imported functions are at the start of the address space
    // this current function would be 1 (this is important later!)
    (drop) // Ignore the error, this is just an example after all!
);

let func = wabam::functions::Function {
    type_idx: 0, // types[0], see above
    locals: vec![], // no local variables
    body: body.into(),
};
module.functions.push(func);

// Export the start function
let func_export = wabam::interface::Export {
    name: "_start".into(),
    idx: 1, // this is where that's important
};

// Export memory
let mem_export = wabam::interface::Export {
    name: "memory".into(),
    idx: 0,
};
module.exports.functions.push(func_export);
module.exports.memories.push(mem_export);

let output = module.build();

std::fs::write("./hello.wasm", &output).unwrap();

Then run it:

$ wasmtime ./hello.wasm
Hello, wasm!

Modules

• customs
  Customs sections are named series of arbitrary bytes, often used for debug info.
• functions
  The main star of a module, code!
• interface
  Imports and Exports are how modules interface with the outside world.
• tables
  A table is a list of reference values.

Macros

• func_type
  A macro to define a FuncType.
• instr
  A macro for creating Instructions with wat-like syntax
• instrs
  A macro for creating arrays of Instructions with wat-like syntax

Structs

• Error
  An error that occured when reading a module, and where.
• Global
  A global variable
• GlobalType
  The value type and mutability of global variables.
• Limit
  The minimum and optional maximum sizes of tables and memories.
• Module
  A WebAssembly module

Enums

• Data
  A series of bytes to be loaded into linear memory
• ErrorKind
  Errors that can happen when reading a wasm module.
• NumType
  The type of a numeric value.
• RefType
  The type of a reference value.
• ValType
  The type of a value in a function signature, global or local variable, or the stack.
• VecType
  The type of a SIMD vector value.