### Install Project Dependencies

Source: https://github.com/dylibso/chicory/blob/main/docs/README.md

Installs all necessary dependencies for the project. Run this command in the project's root directory.

```bash
$ npm install
```

--------------------------------

### Quick Maven Install (Skip Tests)

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Performs a quick installation, skipping all tests and checks for faster builds.

```bash
mvn -Dquickly
```

--------------------------------

### Start Local Development Server

Source: https://github.com/dylibso/chicory/blob/main/docs/README.md

Starts a local development server and opens the website in a browser. Changes are reflected live without a server restart.

```bash
$ npm run start
```

--------------------------------

### Download Example Wasm Module

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

Download a pre-built WebAssembly module for testing purposes.

```bash
curl -sL https://raw.githubusercontent.com/andreaTP/first-chicory-blog/main/dynamic-loading/example.wasm --output example.wasm
```

--------------------------------

### Download WASI Module Example

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/wasi.md

Use curl to download a sample WASI-compiled module for testing.

```bash
curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/hello-wasi.wat.wasm > hello-wasi.wasm
```

--------------------------------

### Run Spec Tests in One Shot

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Executes the 'runtime-tests' module, including the installation step which also runs the tests.

```bash
mvn install -pl runtime-tests -am
```

--------------------------------

### Lower-Level Instance Creation

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/linking.md

This demonstrates the lower-level sequence of creating an instance, which involves getting import values, parsing the module, building the instance with imports, and registering it with the store. The shorthand `store.instantiate()` is generally recommended.

```java
var imports = store.toImportValues();
var m = Parser.parse(new File("./logger.wasm"));
var instance = Instance.builder(m).withImportValues(imports).build();
store.register("logger", instance);
```

--------------------------------

### Function Call with Arguments and Return

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyMemory.approved.txt

This example shows the generated bytecode for a function call. It loads an argument, calls a specific function group, stores the result, and returns it in an array.

```java
public static call_1(Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;[J)[J
    ALOAD 2
    ICONST_0
    LALOAD
    ALOAD 1
    ALOAD 0
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineFuncGroup_0.func_1 (JLcom/dylibso/chicory/runtime/Memory;Lcom/dylibso/chicory/runtime/Instance;)J
    LSTORE 3
    ICONST_1
    NEWARRAY T_LONG
    DUP
    ICONST_0
    LLOAD 3
    LASTORE
    ARETURN
```

--------------------------------

### Run Module Unit Tests

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Executes only the unit tests for a specific module (e.g., 'runtime') after it has been installed.

```bash
mvn test -pl runtime
```

--------------------------------

### Generate and Run Spec Tests

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Installs the 'runtime-tests' module to generate test classes and then runs the full spec test suite.

```bash
mvn install -pl runtime-tests -am -DskipTests
mvn surefire:test -pl runtime-tests
```

--------------------------------

### Download Wasm Module

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/cpu.md

Download a Wasm module for testing purposes. This is a prerequisite for the following examples.

```bash
curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/infinite-loop.c.wasm > infinite-loop.wasm
```

--------------------------------

### Maven Install Skipping Tests

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Installs artifacts while skipping all tests, useful for development when tests are not immediately needed.

```bash
mvn install -DskipTests
```

--------------------------------

### Maven Proxy Configuration

Source: https://github.com/dylibso/chicory/blob/main/CONTRIBUTING.md

Example of how to configure Maven to use a corporate proxy for downloading dependencies, particularly relevant for plugins that fetch external resources like test suites.

```bash
mvn -Dhttps.proxyHost=... -Dhttps.proxyPort=...
```

--------------------------------

### Build and Test Chicory Runtime

Source: https://github.com/dylibso/chicory/blob/main/CONTRIBUTING.md

Commands to build the Chicory runtime from source using Maven. Includes options for a full build with tests, a quick install, development mode, and code formatting.

```bash
mvn clean install
```

```bash
mvn -Dquickly
```

```bash
mvn -Ddev <...goals>
```

```bash
mvn spotless:apply
```

--------------------------------

### Instantiate Wasm Module with Host Function

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/host-functions.md

Instantiate a Wasm module in Chicory, providing the defined host function to the store. This allows the Wasm module to call the host function during its execution. The example registers the 'console.log' host function and then exports and applies a function named 'logIt' from the instantiated module.

```java
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.ImportValues;
import com.dylibso.chicory.runtime.Store;

// instantiate the store
var store = new Store();
// registers `console.log` in the store
store.addFunction(func);
var instance = store.instantiate("logger", Parser.parse(new File("./logger.wasm")));
var logIt = instance.export("logIt");
logIt.apply();
// should print "Hello, World!" 10 times
```

--------------------------------

### Parse Entire Wasm Module

Source: https://github.com/dylibso/chicory/blob/main/wasm/README.md

Use this method to parse the entire Wasm module into memory. It's the simplest way to get started.

```java
import com.dylibso.chicory.wasm.Parser;

var is = ClassLoader.getSystemClassLoader().getResourceAsStream("compiled/count_vowels.rs.wasm");
var module = Parser.parse(is);
var customSection = module.customSections().get(0);
System.out.println("First custom section: " + customSection.name());
```

--------------------------------

### Accept Memory and Instance as Arguments

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2024-11-08-chicory-1.0.0-M1.md

Host functions can accept com.dylibso.chicory.runtime.Instance and com.dylibso.chicory.runtime.Memory as input arguments.

```java
@WasmExport
public int fdFdstatGet(Memory memory, int fd, int buf) {
    ...
}
```

--------------------------------

### Prepare Maven for Android Tests

Source: https://github.com/dylibso/chicory/blob/main/android-tests/README.md

Run this command to prepare the Maven build for Android testing. It produces relevant artifacts in the `local-repo` directory.

```bash
mvn -Dandroid-prepare
```

--------------------------------

### CompiledMachineFuncGroup_0 func_0 Implementation

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyTailCall.approved.txt

Implements a specific function (func_0) with conditional logic and tail call setup.

```Java
final class com/dylibso/chicory/$gen/CompiledMachineFuncGroup_0 {

  public static func_0(IIILcom/dylibso/chicory/runtime/Memory;Lcom/dylibso/chicory/runtime/Instance;)I
    ILOAD 0
    INVOKESTATIC com/dylibso/chicory/runtime/OpcodeImpl.I32_EQZ (I)I
    IFEQ L0
    ILOAD 1
    GOTO L1
   L0
    ILOAD 0
    ICONST_1
    INVOKESTATIC com/dylibso/chicory/runtime/OpcodeImpl.I32_EQ (II)I
    IFEQ L2
    ILOAD 2
    GOTO L1
   L2
    ILOAD 0
    ICONST_1
    ISUB
    ILOAD 2
    ILOAD 1
    ILOAD 2
    IADD
    ISTORE 7
    ISTORE 6
    ISTORE 5
    ICONST_3
    NEWARRAY T_LONG
    DUP
    ICONST_0
    ILOAD 5
    I2L
    LASTORE
    DUP
    ICONST_1
    ILOAD 6
    I2L
    LASTORE
    DUP
    ICONST_2
    ILOAD 7
    I2L
    LASTORE
    ICONST_0
    SWAP
    ALOAD 4
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.setTailCall (I[JLcom/dylibso/chicory/runtime/Instance;)V
    ICONST_0
    IRETURN
   L1
    IRETURN


```

--------------------------------

### Build Module and Dependencies (Skip Tests)

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Builds a specific module (e.g., 'runtime') and its dependencies, skipping tests for faster propagation of artifacts.

```bash
mvn install -pl runtime -am -DskipTests
```

--------------------------------

### Instantiate Host Module and Build Imports

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/annotations.md

Instantiate your host module and use `ImportValues.builder()` to create the necessary imports for Wasm execution.

```java
import com.dylibso.chicory.runtime.ImportValues;

var demo = new Demo();
var imports = ImportValues.builder().addFunction(demo.toHostFunctions()).build();
```

--------------------------------

### CompiledMachineFuncGroup_0 Function Implementation

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.functions10.approved.txt

Implements `func_0` which increments its integer argument by 1. This is a basic example of a WebAssembly function translated to Java bytecode.

```java
public static func_0(ILcom/dylibso/chicory/runtime/Memory;Lcom/dylibso/chicory/runtime/Instance;)I
    ILOAD 0
    ICONST_1
    IADD
    IRETURN
```

--------------------------------

### Full Build and Test with Maven

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Executes a clean build of the project and runs all associated tests.

```bash
mvn clean install
```

--------------------------------

### CompiledMachine Indirect Call Handling

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyTailCall.approved.txt

Handles indirect function calls, including table lookups, type checking, and potential tail call setup.

```Java
  public static call_indirect_0(IIIIILcom/dylibso/chicory/runtime/Memory;Lcom/dylibso/chicory/runtime/Instance;)I
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.checkInterruption ()V
    ALOAD 6
    ILOAD 4
    INVOKEVIRTUAL com/dylibso/chicory/runtime/Instance.table (I)Lcom/dylibso/chicory/runtime/TableInstance;
    ASTORE 7
    ALOAD 7
    ILOAD 3
    INVOKEVIRTUAL com/dylibso/chicory/runtime/TableInstance.requiredRef (I)I
    ISTORE 8
    ALOAD 7
    ILOAD 3
    INVOKEVIRTUAL com/dylibso/chicory/runtime/TableInstance.instance (I)Lcom/dylibso/chicory/runtime/Instance;
    ASTORE 9
    ALOAD 9
    IFNULL L0
    ALOAD 9
    ALOAD 6
    IF_ACMPNE L1
   L0
    ILOAD 0
    ILOAD 1
    ILOAD 2
    ALOAD 5
    ALOAD 6
    ILOAD 8
    LOOKUPSWITCH
      0: L2
      default: L3
   L2
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineFuncGroup_0.func_0 (IIILcom/dylibso/chicory/runtime/Memory;Lcom/dylibso/chicory/runtime/Instance;)I
    IRETURN
   L3
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.throwIndirectCallTypeMismatch ()Ljava/lang/RuntimeException;
    ATHROW
   L1
    ICONST_3
    NEWARRAY T_LONG
    DUP
    ICONST_0
    ILOAD 0
    I2L
    LASTORE
    DUP
    ICONST_1
    ILOAD 1
    I2L
    LASTORE
    DUP
    ICONST_2
    ILOAD 2
    I2L
    LASTORE
    ICONST_0
    ILOAD 8
    ALOAD 9
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.callIndirect ([JIILcom/dylibso/chicory/runtime/Instance;)[J
    ICONST_0
    LALOAD
    L2I
    IRETURN
}

```

--------------------------------

### Download WASM Module

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/wasi.md

Download a sample WASI-enabled WebAssembly module using curl.

```bash
curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/greet-wasi.rs.wasm > greet-wasi.wasm
```

--------------------------------

### Instantiate WASM Module with a Store

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2024-11-08-chicory-1.0.0-M1.md

Utilize the `Store` utility to manage host functions and instantiate modules. This approach simplifies the management of related modules and their associated host functions.

```java
// instantiate the store
var store = new Store();
// registers a host function in the store
store.addFunction(myFunction);
// create a named `instance` with name `logger`
var module = Parser.parse(new File("logger.wasm"));
var instance = store.instantiate("logger", module);
```

--------------------------------

### Invoke Exported Wasm Function

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/index.md

Get a handle to an exported Wasm function and invoke it. Remember to map Java types to 'long' for arguments and handle the returned array of values.

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

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

--------------------------------

### Create Quarkus Application

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

Use the Quarkus CLI to scaffold a new server-side application.

```bash
quarkus create
```

--------------------------------

### Instantiate WASI Module with Chicory

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/wasi.md

Instantiate a WASI module by providing host functions and configuring WASI options. The module runs implicitly upon instantiation.

```java
import com.dylibso.chicory.log.SystemLogger;
import com.dylibso.chicory.wasi.WasiOptions;
import com.dylibso.chicory.wasi.WasiPreview1;
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.Store;

import java.io.File;

var logger = new SystemLogger();
// let's just use the default options for now
var options = WasiOptions.builder().build();
// create our instance of wasip1
var wasi = WasiPreview1.builder().withOptions(options).build();
// create the module and connect the host functions
var store = new Store().addFunction(wasi.toHostFunctions());
// instantiate and execute the main entry point
store.instantiate("hello-wasi", Parser.parse(new File("hello-wasi.wasm")));
```

--------------------------------

### Define a Host Function in Java

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/host-functions.md

Define a Java host function that a Wasm module can import. This example implements a 'console.log' function that reads a string from Wasm memory and prints it to standard output. It requires the namespace, function name, Wasm type signature, and a lambda to handle the invocation.

```java
import com.dylibso.chicory.runtime.Instance;
import com.dylibso.chicory.runtime.HostFunction;
import com.dylibso.chicory.wasm.types.ValType;
import com.dylibso.chicory.wasm.types.FunctionType;

var func = new HostFunction(
    "console",
    "log",
    FunctionType.of(
        List.of(ValType.I32, ValType.I32),
        List.of()
    ),
    (Instance instance, long... args) -> {
        var len = (int) args[0];
        var offset = (int) args[1];
        var message = instance.memory().readString(offset, len);
        System.out.println(message);
        return null;
    });
```

--------------------------------

### Build and Run Fuzz Tests

Source: https://github.com/dylibso/chicory/blob/main/fuzz/README.md

Build the project and run fuzz tests with default or custom iteration counts.

```bash
# Build everything first
mvn -B install -DskipTests -Dquickly

# Run fuzz tests with default 10 iterations per instruction type
mvn -B verify -pl fuzz -DskipTests=false

# Run with custom iteration count
mvn -B verify -pl fuzz -DskipTests=false -Dfuzz.test.iterations=50
```

--------------------------------

### Load and Instantiate Wasm Module

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/index.md

Load a WebAssembly module from a file and instantiate it to create a runnable instance. Ensure the file path is correct.

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

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

--------------------------------

### Build and Highlight with Lumis4J

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2026-02-02-syntax-highlight.md

Use Lumis.builder to configure language, theme, and formatter, then highlight code. Ensure Lumis is closed using try-with-resources.

```java
try (Lumis lumis = Lumis.builder()
                        .withLang(Lang.JAVA)
                        .withTheme(Theme.CATPPUCCIN_FRAPPE)
                        .withFormatter(Formatter.HTML_INLINE)
                        .build()) {
    var htmlResult = lumis.highlight("public class Hello { }");
    System.out.println(htmlResult.string());
}
```

--------------------------------

### Instantiate Module with SIMD Support

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/simd.md

When parsing a WebAssembly module, provide a `SimdInterpreterMachine` factory to the instance builder to enable SIMD instructions. SIMD support requires Wasm validation to be enabled.

```java
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.Instance;
import com.dylibso.chicory.simd.SimdInterpreterMachine;

var module = Parser.parse(new File("your.wasm"));
var instance = Instance.builder(module).withMachineFactory(SimdInterpreterMachine::new).build();
```

--------------------------------

### Build Native Container Image

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

Build the Docker container image using the specified Dockerfile.

```bash
docker build -f src/main/docker/Dockerfile.native-scratch -t chicory/getting-started .
```

--------------------------------

### FOO Machine Implementation

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyI32Renamed.approved.txt

The FOO class implements the Machine interface for executing WebAssembly code. It handles direct calls to the instance's memory and includes error handling for StackOverflowError.

```java
public final class FOO implements com/dylibso/chicory/runtime/Machine {

  private final Lcom/dylibso/chicory/runtime/Instance; instance

  public <init>(Lcom/dylibso/chicory/runtime/Instance;)V
    ALOAD 0
    INVOKESPECIAL java/lang/Object.<init> ()V
    ALOAD 0
    ALOAD 1
    PUTFIELD FOO.instance : Lcom/dylibso/chicory/runtime/Instance;
    RETURN

  public call(I[J)[J
    TRYCATCHBLOCK L0 L1 L1 java/lang/StackOverflowError
   L0
    ALOAD 0
    GETFIELD FOO.instance : Lcom/dylibso/chicory/runtime/Instance;
    DUP
    INVOKEVIRTUAL com/dylibso/chicory/runtime/Instance.memory ()Lcom/dylibso/chicory/runtime/Memory;
    ILOAD 1
    ALOAD 2
    INVOKESTATIC FOOMachineCall.call (Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;I[J)[J
    ARETURN
   L1
    INVOKESTATIC FOOShaded.throwCallStackExhausted (Ljava/lang/StackOverflowError;)Ljava/lang/RuntimeException;
    ATHROW
}
```

--------------------------------

### Configure WASI Disk Access with Jimfs

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/wasi.md

Set up WASI options to provide access to a virtual file system using Google's Jimfs library. This allows WASI modules to perform file operations within a controlled, in-memory environment.

```java
import com.google.common.jimfs.Configuration;
import com.google.common.jimfs.Jimfs;

try (FileSystem fs = Jimfs.newFileSystem(Configuration.unix().toBuilder().setAttributeViews("unix").build())) {
    Path source = Path.of("my-source");
    Path target = fs.getPath("my-source");
    com.dylibso.chicory.wasi.Files.copyDirectory(source, target);

    var wasi = WasiOptions.builder().withDirectory(target.toString(), target).build();

    // ...
}
```

--------------------------------

### Run Containerized Application

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

Run the built Docker container, exposing port 8080.

```bash
docker run -i --rm -p 8080:8080 chicory/getting-started
```

--------------------------------

### CompiledMachine Initialization and Call Handling

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyFloat.approved.txt

Handles the initialization of a CompiledMachine instance and provides a method for calling WebAssembly functions. It includes error handling for StackOverflowError during execution.

```java
public final class com/dylibso/chicory/$gen/CompiledMachine implements com/dylibso/chicory/runtime/Machine {

  private final Lcom/dylibso/chicory/runtime/Instance; instance

  public <init>(Lcom/dylibso/chicory/runtime/Instance;)V
    ALOAD 0
    INVOKESPECIAL java/lang/Object.<init> ()V
    ALOAD 0
    ALOAD 1
    PUTFIELD com/dylibso/chicory/$gen/CompiledMachine.instance : Lcom/dylibso/chicory/runtime/Instance;
    RETURN

  public call(I[J)[J
    TRYCATCHBLOCK L0 L1 L1 java/lang/StackOverflowError
   L0
    ALOAD 0
    GETFIELD com/dylibso/chicory/$gen/CompiledMachine.instance : Lcom/dylibso/chicory/runtime/Instance;
    DUP
    INVOKEVIRTUAL com/dylibso/chicory/runtime/Instance.memory ()Lcom/dylibso/chicory/runtime/Memory;
    ILOAD 1
    ALOAD 2
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineMachineCall.call (Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;I[J)[J
    ARETURN
   L1
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.throwCallStackExhausted (Ljava/lang/StackOverflowError;)Ljava/lang/RuntimeException;
    ATHROW
}
```

--------------------------------

### Build and Instantiate Wasm Instance

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/memory.md

Parse the Wasm file and build an instance. Export the `count_vowels` function for later use.

```java
import com.dylibso.chicory.runtime.ExportFunction;
import com.dylibso.chicory.runtime.Instance;
import com.dylibso.chicory.wasm.Parser;

Instance instance = Instance.builder(Parser.parse(new File("./count_vowels.wasm"))).build();
ExportFunction countVowels = instance.export("count_vowels");
```

--------------------------------

### Parse and Instantiate WASM Module

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2024-11-08-chicory-1.0.0-M1.md

Use `Parser` to parse a WebAssembly module and `Instance.builder` to create an instance. This demonstrates the basic workflow for loading and running a WASM module.

```java
var module = Parser.parse("path/to/your.wasm");
var instance = Instance.builder(module).build();
```

--------------------------------

### Build Static Website Content

Source: https://github.com/dylibso/chicory/blob/main/docs/README.md

Generates the static content for the website, typically placed in the 'build' directory. This content can be hosted on any static hosting service.

```bash
$ npm run build
```

--------------------------------

### Instance Method Call with TableSwitch

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyMemory.approved.txt

This snippet illustrates how a method call is handled using a TABLESWITCH instruction based on an integer argument. It dispatches to different function groups or throws an exception for unknown cases.

```java
final class com/dylibso/chicory/$gen/CompiledMachineMachineCall {

  public <init>()V
    ALOAD 0
    INVOKESPECIAL java/lang/Object.<init> ()V
    RETURN

  public static call(Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;I[J)[J
    ALOAD 0
    ALOAD 1
    ALOAD 3
    ILOAD 2
    TABLESWITCH
      0: L0
      1: L1
      default: L2
   L0
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineFuncGroup_0.call_0 (Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;[J)[J
    ARETURN
   L1
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineFuncGroup_0.call_1 (Lcom/dylibso/chicory/runtime/Instance;Lcom/dylibso/chicory/runtime/Memory;[J)[J
    ARETURN
   L2
    ILOAD 2
    INVOKESTATIC com/dylibso/chicory/$gen/CompiledMachineShaded.throwUnknownFunction (I)Ljava/lang/RuntimeException;
    ATHROW
}
```

--------------------------------

### Run Lumis4J Demo with JBang

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2026-02-02-syntax-highlight.md

Execute a minimal JBang demo script to showcase Lumis4J functionality.

```bash
jbang https://gist.github.com/andreaTP/6945e9ff3223686b600fda184ae94e2f
```

--------------------------------

### Registering a Host Function

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/linking.md

Register a host function, like console.log, to the Store. This involves defining the function's name, type, and implementation, then adding it to the Store.

```java
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.Instance;
import com.dylibso.chicory.runtime.HostFunction;
import com.dylibso.chicory.runtime.Store;
import com.dylibso.chicory.wasm.types.ValType;
import com.dylibso.chicory.wasm.types.FunctionType;

var func = new HostFunction(
    "console",
    "log",
    FunctionType.of(
        List.of(ValType.I32, ValType.I32),
        List.of()
    ),
    (Instance instance, long... args) -> { // decompiled is: console_log(13, 0);
        var len = (int) args[0];
        var offset = (int) args[1];
        var message = instance.memory().readString(offset, len);
        println(message);
        return null;
    });

// instantiate the store
var store = new Store();
// registers `console.log` in the store
store.addFunction(func);
```

--------------------------------

### Convert Wat to Wasm and Execute

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/tools.md

Use `wat2wasm` to parse WebAssembly text format into binary, then instantiate and execute a function from the resulting module. This is useful when Chicory lacks a native Wasm text format parser.

```java
import com.dylibso.chicory.wabt.Wat2Wasm;
// or
import com.dylibso.chicory.tools.wasm.Wat2Wasm;

var wasm = Wat2Wasm.parse(
    "(module (func (export \"add\") (param $x i32) (param $y i32) (result i32)"
    + " (i32.add (local.get $x) (local.get $y))))");

var moduleInstance = Instance.builder(Parser.parse(wasm)).build();

var addFunction = moduleInstance.export("add");
var result = addFunction.apply(1, 41)[0];

System.out.println(result);
```

--------------------------------

### Configure `build-helper-maven-plugin` for IDE Support

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/build-time-compiler.md

Add this configuration to your `pom.xml` to ensure that IDEs recognize the generated sources located in `target/generated-sources/chicory-compiler`.

```xml
<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <executions>
        <execution>
        <id>addSource</id>
        <phase>generate-sources</phase>
        <goals>
            <goal>add-source</goal>
        </goals>
        <configuration>
            <sources>
                <source>${project.build.directory}/generated-sources/chicory-compiler</source>
            </sources>
        </configuration>
        </execution>
    </executions>
</plugin>
```

--------------------------------

### Provide Command Line Arguments to WASI

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/wasi.md

Configure WASI options to pass command-line arguments to the WebAssembly module. This is particularly useful for CLI-style WASI applications.

```java
var wasi = WasiOptions.builder().withArguments(List.of("executable-name", "--more", "--options")).build();
```

--------------------------------

### Instantiate WASM Module with Build-Time Compiled Code

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/build-time-compiler.md

Load the bundled module and instantiate it using the pre-compiled code provided by the build-time compiler.

```java
import com.dylibso.chicory.runtime.Instance;

// load the bundled module
var module = Add.load();

// instantiate the module with the pre-compiled code
var instance = Instance.builder(module).
        withMachineFactory(Add::create).
        build();
```

--------------------------------

### Upload Wasm Module to Server

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

Upload the downloaded WebAssembly module to the running Quarkus server via a POST request.

```bash
curl -H 'Content-Type: application/octet-stream' -X POST --data-binary @example.wasm http://localhost:8080/wasm
```

--------------------------------

### Autoformat Code with Maven

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Applies code formatting rules across the project. This command is required before committing code.

```bash
mvn spotless:apply
```

--------------------------------

### Load and Execute Wasm in Java with Chicory

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/examples/rust.md

Demonstrates loading a Wasm module, exporting functions, and interacting with its memory in Java. Ensure the Wasm module has exported functions like 'alloc', 'dealloc', and the target function (e.g., 'count_vowels').

```java
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.runtime.Instance;

var instance = Instance.builder(Parser.parse(new File("count_vowels.rs.wasm"))).build();

var alloc = instance.export("alloc");
var dealloc = instance.export("dealloc");
var countVowels = instance.export("count_vowels");

var memory = instance.memory();
var message = "Hello, World!";
var len = message.getBytes().length;
int ptr = (int) alloc.apply(len)[0];

memory.writeString(ptr, message);

var result = countVowels.apply(ptr, len)[0];
System.out.println(result);
```

--------------------------------

### Build Up to a Specific Module

Source: https://github.com/dylibso/chicory/blob/main/AGENT.md

Builds all modules up to and including a specified module (e.g., 'wasm-tools') and its dependencies, skipping tests.

```bash
mvn install -pl wasm-tools -am -DskipTests
```

--------------------------------

### Instantiate Wasm Module

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/cpu.md

Instantiate a Wasm module using Chicory's Instance builder. This prepares the module for execution.

```java
import com.dylibso.chicory.runtime.ExportFunction;
import com.dylibso.chicory.runtime.Instance;
import com.dylibso.chicory.wasm.Parser;

Instance instance = Instance.builder(Parser.parse(new File("./infinite-loop.wasm"))).build();
ExportFunction function = instance.export("run");
```

--------------------------------

### CompiledMachine Constructor and Instance Field

Source: https://github.com/dylibso/chicory/blob/main/compiler/src/test/resources/com/dylibso/chicory/approvals/ApprovalTest.verifyIterFact.approved.txt

Initializes the CompiledMachine with an Instance and stores it.

```java
public final class com/dylibso/chicory/$gen/CompiledMachine implements com/dylibso/chicory/runtime/Machine {

  private final Lcom/dylibso/chicory/runtime/Instance; instance

  public <init>(Lcom/dylibso/chicory/runtime/Instance;)V
    ALOAD 0
    INVOKESPECIAL java/lang/Object.<init> ()V
    ALOAD 0
    ALOAD 1
    PUTFIELD com/dylibso/chicory/$gen/CompiledMachine.instance : Lcom/dylibso/chicory/runtime/Instance;
    RETURN

```

--------------------------------

### Enable Runtime Compilation

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/runtime-compiler.md

Configure the Chicory instance to use the compiler by specifying `MachineFactoryCompiler::compile` as the machine factory.

```java
import com.dylibso.chicory.compiler.MachineFactoryCompiler;
import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.wasm.WasmModule;

var module = Parser.parse(new File("your.wasm"));
var instance = Instance.builder(module).
        withMachineFactory(MachineFactoryCompiler::compile).
        build();
```

--------------------------------

### Instantiate Module with AoT Machine Factory in Java

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2024-11-08-chicory-1.0.0-M1.md

Opt into Ahead-of-Time (AoT) mode by providing the AotMachine::new factory when building an instance. This replaces the default InterpreterMachine.

```java
var module = Parser.parse("path/to/your.wasm");
var instance = Instance.builder(module)
        .withMachineFactory(AotMachine::new)
        .build();
```

--------------------------------

### Prepare JMH Baseline Locally

Source: https://github.com/dylibso/chicory/blob/main/jmh/README.md

Run these scripts to prepare the baseline performance tests from the main branch locally.

```bash
./scripts/build-jmh-main.sh
./scripts/run-jmh-main.sh
```

--------------------------------

### Dockerfile for Native Scratch Image

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2023-12-25-chicory-first.md

A Dockerfile to build a native Quarkus application image using a scratch base for minimal size. It includes steps for cross-compiling musl and zlib for static linking.

```docker
FROM quay.io/quarkus/ubi-quarkus-graalvmce-builder-image:jdk-21 AS build
USER root
RUN microdnf install make gcc
RUN mkdir /musl && \
    curl -L -o musl.tar.gz https://more.musl.cc/11.2.1/x86_64-linux-musl/x86_64-linux-musl-native.tgz && \
    tar -xvzf musl.tar.gz -C /musl --strip-components 1 && \
    curl -L -o zlib.tar.gz https://www.zlib.net/zlib-1.3.tar.gz && \
    mkdir zlib && tar -xvzf zlib.tar.gz -C zlib --strip-components 1 && \
    cd zlib && ./configure --static --prefix=/musl && \
    make && make install && \
    cd .. && rm -rf zlib && rm -f zlib.tar.gz && rm -f musl.tar.gz
ENV PATH="/musl/bin:${PATH}"
USER quarkus
WORKDIR /code
COPY . .
RUN ./mvnw package -Dnative -DskipTests -Dquarkus.native.additional-build-args="--static","--libc=musl"

## Stage 2 : create the final image
FROM scratch
COPY --from=build /code/target/*-runner /application
EXPOSE 8080
ENTRYPOINT [ "/application" ]
```

--------------------------------

### Run a Single Fuzz Reproducer

Source: https://github.com/dylibso/chicory/blob/main/fuzz/README.md

Execute a single fuzz reproducer by setting the seed and test types environment variables.

```bash
export CHICORY_FUZZ_SEED=path/to/seed.txt
export CHICORY_FUZZ_TYPES=numeric,table

mvn -B verify -pl fuzz -DskipTests=false -Dtest="SingleReproTest#singleReproducer"
```

--------------------------------

### Add Host Module Annotations Dependency

Source: https://github.com/dylibso/chicory/blob/main/docs/blog/2024-11-08-chicory-1.0.0-M1.md

Include this dependency to enable the experimental annotation processor for defining host modules.

```xml
<dependency>
  <groupId>com.dylibso.chicory</groupId>
  <artifactId>host-module-annotations-experimental</artifactId>
</dependency>
```

--------------------------------

### Configure Gradle Repositories

Source: https://github.com/dylibso/chicory/blob/main/docs/docs/usage/build-time-compiler.md

Ensure MavenCentral is available in your pluginManagement repositories to download the wasm2class-gradle-plugin.

```kotlin
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
```