Docs

Getting Started

Install Dependency

To use the runtime, you need to add the com.dylibso.chicory:runtime dependency to your dependency management system.

Maven

<dependency>
  <groupId>com.dylibso.chicory</groupId>
  <artifactId>runtime</artifactId>
  <version>DOCS_PLACEHOLDER_VERSION</version>
</dependency>

Gradle

implementation 'com.dylibso.chicory:runtime:DOCS_PLACEHOLDER_VERSION'

Install the CLI (experimental)

The Chicory CLI is available for download on Maven at the link:

https://repo1.maven.org/maven2/com/dylibso/chicory/cli/<version>/cli-<version>.sh

you can download the latest version and use it locally by typing:

export VERSION=$(wget -q -O - https://api.github.com/repos/dylibso/chicory/tags --header "Accept: application/json" | jq -r '.[0].name')
wget -O chicory https://repo1.maven.org/maven2/com/dylibso/chicory/cli/${VERSION}/cli-${VERSION}.sh
chmod a+x chicory
./chicory

Loading and Instantiating Code

First your Wasm module must be loaded from disk and then "instantiated". Let's download a test module . This module contains some code to compute factorial:

Download from the link or with curl:

curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm > factorial.wasm

Now let's load this module and instantiate it:

import com.dylibso.chicory.runtime.ExportFunction;
import com.dylibso.chicory.wasm.types.Value;
import com.dylibso.chicory.wasm.WasmModule;
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.Instance;
import java.io.File;

// point this to your path on disk
WasmModule module = Parser.parse(new File("./factorial.wasm"));
Instance instance = Instance.builder(module).build();

You can think of the module as of inert code, and the instance is the run-time representation of that code: a virtual machine ready to execute.

Invoking an Export Function

Wasm modules, like all code modules, can export functions to the outside world. This module exports a function called "iterFact". We can get a handle to this function using Instance#export(String):

ExportFunction iterFact = instance.export("iterFact");

iterFact can be invoked with the apply() method. We must map any Java types to a Wasm type and do the reverse when we want to go back to Java. This export function takes an i32 argument. We can use a method like Value#asInt() on the return value to get back the Java integer:

long result = iterFact.apply(5)[0];
System.out.println("Result: " + result); // should print 120 (5!)

Note: Functions in Wasm can have multiple returns but here we're just taking the first returned value.