Struct CodeBuilder

pub struct CodeBuilder<'a> { /* private fields */ }

Builder-style structure used to create a Module or pre-compile a module to a serialized list of bytes.

This structure can be used for more advanced configuration when compiling a WebAssembly module. Most configuration can use simpler constructors such as:

• Module::new
• Module::from_file
• Module::from_binary

Note that a CodeBuilder always involves compiling WebAssembly bytes to machine code. To deserialize a list of bytes use Module::deserialize instead.

A CodeBuilder requires a source of WebAssembly bytes to be configured before calling compile_module_serialized or compile_module. This can be provided with either the wasm_binary or wasm_binary_file method. Note that only a single source of bytes can be provided.

WebAssembly Text Format

This builder supports the WebAssembly Text Format (*.wat files) through the CodeBuilder::wasm_binary_or_text and CodeBuilder::wasm_binary_or_text_file methods. These methods automatically convert WebAssembly text files to binary. Note though that this behavior is disabled if the wat crate feature is not enabled.

Implementations

impl<'a> CodeBuilder<'a>

pub fn new(engine: &'a Engine) -> CodeBuilder<'a>

Creates a new builder which will insert modules into the specified Engine.

pub fn wasm_binary( &mut self, wasm_bytes: impl Into<Cow<'a, [u8]>>, wasm_path: Option<&'a Path>, ) -> Result<&mut CodeBuilder<'a>, Error>

Configures the WebAssembly binary that is being compiled.

The wasm_bytes parameter must be a binary WebAssembly file. This will be stored within the CodeBuilder for processing later when compilation is finalized.

The optional wasm_path parameter is the path to the wasm_bytes on disk, if any. This may be used for diagnostics and other debugging-related purposes, but this method will not read the path specified.

Errors

This method will return an error if WebAssembly bytes have already been configured.

pub fn wasm_binary_or_text( &mut self, wasm_bytes: &'a [u8], wasm_path: Option<&'a Path>, ) -> Result<&mut CodeBuilder<'a>, Error>

Equivalent of CodeBuilder::wasm_binary that also accepts the WebAssembly text format.

This method will configure the WebAssembly binary to be compiled. The input wasm_bytes may either be the wasm text format or the binary format. If the wat crate feature is enabled, which is enabled by default, then the text format will automatically be converted to the binary format.

Errors

This method will return an error if WebAssembly bytes have already been configured. This method will also return an error if wasm_bytes is the wasm text format and the text syntax is not valid.

pub fn wasm_binary_file( &mut self, file: &'a Path, ) -> Result<&mut CodeBuilder<'a>, Error>

Reads the file specified for the WebAssembly bytes that are going to be compiled.

This method will read file from the filesystem and interpret it as a WebAssembly binary.

A DWARF package file will be probed using the root of file and with a .dwp extension. If found, it will be loaded and DWARF fusion performed.

Errors

This method will return an error if WebAssembly bytes have already been configured.

If file can’t be read or an error happens reading it then that will also be returned.

If DWARF fusion is performed and the DWARF packaged file cannot be read then an error will be returned.

pub fn wasm_binary_or_text_file( &mut self, file: &'a Path, ) -> Result<&mut CodeBuilder<'a>, Error>

Equivalent of CodeBuilder::wasm_binary_file that also accepts the WebAssembly text format.

This method is will read the file at path and interpret the contents to determine if it’s the wasm text format or binary format. The file extension of file is not consulted. The text format is automatically converted to the binary format if the crate feature wat is active.

Errors

In addition to the errors returned by CodeBuilder::wasm_binary_file this may also fail if the text format is read and the syntax is invalid.

pub fn dwarf_package_file( &mut self, file: &Path, ) -> Result<&mut CodeBuilder<'a>, Error>

Explicitly specify DWARF .dwp path.

Errors

This method will return an error if the .dwp file has already been set through CodeBuilder::dwarf_package or auto-detection in CodeBuilder::wasm_binary_file.

This method will also return an error if file cannot be read.

pub fn dwarf_package( &mut self, dwp_bytes: &'a [u8], ) -> Result<&mut CodeBuilder<'a>, Error>

Set the DWARF package binary.

Initializes dwarf_package from dwp_bytes in preparation for DWARF fusion. Allows the DWARF package to be supplied as a byte array when the file probing performed in wasm_file is not appropriate.

Errors

Returns an error if the *.dwp file is already set via auto-probing in CodeBuilder::wasm_binary_file or explicitly via CodeBuilder::dwarf_package_file.

pub fn hint(&self) -> Option<CodeHint>

Returns a hint, if possible, of what the provided bytes are.

This method can be use to detect what the previously supplied bytes to methods such as CodeBuilder::wasm_binary_or_text are. This will return whether a module or a component was found in the provided bytes.

This method will return None if wasm bytes have not been configured or if the provided bytes don’t look like either a component or a module.

pub fn compile_module_serialized(&self) -> Result<Vec<u8>, Error>

Finishes this compilation and produces a serialized list of bytes.

This method requires that either CodeBuilder::wasm_binary or related methods were invoked prior to indicate what is being compiled.

This method will block the current thread until compilation has finished, and when done the serialized artifact will be returned.

Note that this method will never cache compilations, even if the cache feature is enabled.

Errors

This can fail if the input wasm module was not valid or if another compilation-related error is encountered.

impl<'a> CodeBuilder<'a>

pub fn compile_module(&self) -> Result<Module, Error>

Same as CodeBuilder::compile_module_serialized except that a Module is produced instead.

Note that this method will cache compilations if the cache feature is enabled and turned on in Config.