Release date: 2026-02-25

Chicory 1.7.0 is a big step forward! This release brings WasmGC support across the board, Multi-Memory, and community-driven Threads proposal performance improvements. With these additions, Chicory is getting closer and closer to full Wasm 3.0 compliance.

Highlights​

WasmGC Support​

• Full support for the WasmGC proposal in both the interpreter and compiler, passing the entire spec testsuite! This enables garbage-collected struct and array types in WebAssembly modules.
• Performance improvements are planned for upcoming releases to make this faster.

Multi-Memory Support​

• Implementation of the Multi-Memory proposal, allowing WebAssembly modules to declare and access multiple memory instances simultaneously.
• This is a key building block for static linking of WebAssembly modules and brings Chicory closer to full Wasm 3.0 compliance.

Threads Proposal Improvements​

• Community-contributed fixes to memory wait and notify operations, bringing performance improvements to concurrent WebAssembly execution.
• Moved atomic primitives to Memory for a cleaner architecture and better separation of concerns.
• Fixed test flakiness in atomic fence ordering tests.

Other Improvements​

• WASI: New option to avoid throwing on WASI exit code 0, improving compatibility with modules that call proc_exit(0).
• Compiler: Extended JVM workaround for Java <= 17 to I32_GE_U for improved correctness (see JDK-8376400).

A huge thank you to all contributors for their valuable contributions! Check out the commit history for detailed implementation notes, and as always, we'd love to hear your feedback!

Happy WebAssembly-in-the-JVM coding! 🚀

That statement alone says a lot.

Syntax highlighting is a solved problem. It’s not novel, it’s not research-grade, and yet in the Java ecosystem it still feels complex, expensive, and tedious to integrate. You either end up with half-maintained ports, JNI bindings, or large dependencies that are painful to distribute and maintain.

The real question is: how do we make things that were previously considered complex, expensive, and fragile easy, robust, and boring?

The traditional options (and their cost)​

Sure, with the help of LLMs, it's now much easier than before to port a library from another language to Java. But that’s only the first step. Once you port it, you own it:

• ongoing maintenance
• vulnerability fixes
• bug reports
• releases
• code drift with the upstream

That maintenance burden never goes away.

Fortunately, in many cases, the library we want already exists and is excellent, just not written in Java.

Wasm to the rescue​

WebAssembly changes the equation.

With Wasm, we can reuse libraries written in C, C++, Go, Rust, or even JavaScript, without falling into rewriting or the usual JNI traps:

• no platform-specific builds
• no cross-compilation matrix
• no native binaries to ship
• no “works on my machine” surprises

Everything runs in a sandboxed, lightweight, and portable runtime.

Two candidates: highlight.js and tree-sitter​

When Max asked about highlighting, two obvious candidates came to mind:

• highlight.js
• tree-sitter

highlight.js via QuickJS​

For highlight.js, the fastest proof of concept was to run it inside a JavaScript engine.

Using QuickJs4J https://github.com/roastedroot/quickjs4j

I put together a quick experiment: https://github.com/andreaTP/highlightjs4j

QuickJs4J exists to embed the QuickJS engine into the JVM. As long as a JS library doesn’t depend on browser or Node APIs, QuickJS is a very capable engine and can run surprisingly complex code with ease.

The experiment worked well and validated the approach.

tree-sitter and native performance​

Tree-sitter is even more appealing:

• written in C
• widely used in editors and IDEs
• extremely fast
• grammar-based and precise

Looking around, there are several projects in this space, among others:

• arborium
• syntastica
• lumis

In the end, Lumis stood out: https://github.com/leandrocp/lumis

Why Lumis on Wasm works so well​

Lumis is written in Rust, which already has first-class support for compiling to WebAssembly. Even better, it works out of the box with WASI.

That means:

• printing to stdout just works
• debugging is straightforward
• no weird shims or hacks

This made it a perfect candidate.

Lumis4J: wrapping once, reusing forever​

That’s how Lumis4J started: https://github.com/roastedroot/lumis4j

The idea is simple:

• compile Lumis to Wasm and then to Java Bytecode thanks to Chicory
• write a small Rust wrapper exposing a clean API
• map that API to Java

The Rust side is intentionally minimal. It exposes just enough surface to drive Lumis without leaking implementation details. On the Java side, this maps to a small, idiomatic API that feels native to the JVM:

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());
}

Result:

public class Hello { }

You can easily run a minimal JBang demo:

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

The core of the integration is tiny. What would have been a massive port a few years ago is now just glue code.

Full reuse, zero reimplementation.

Performance: Wizer to the rescue​

Out of the box, Lumis works great. One issue remained: loading a language the first time could take seconds.

Enter Wizer. https://github.com/bytecodealliance/wizer

Wizer is a Wasm pre-initializer. It allows you to pre-load data and state at build time, so the module is already warm at runtime. By preloading grammars and themes, startup time drops dramatically and, even the first invocation, is finally fast.

Shipping the result​

The final library includes:

• all languages
• all themes
• fully battery-included

Numbers:

• around 80Mb of Wasm payload
• compiled to Java bytecode via Chicory
• less than 10Mb final jar

And the resulting artifact is:

• easy to distribute
• no native dependencies
• runs on the JVM and Android
• fully self-contained
• minimal Java dependencies, just the Chicory runtime

But most importantly, it is secure.

The Wasm sandbox uses a heap fully separated from the JVM heap. Any memory bugs or vulnerabilities at the C or Rust level surface as normal Java exceptions, not undefined behavior, not crashes, not security nightmares.

The bigger picture​

WebAssembly is a W3C standard. More and more libraries are quietly adding Wasm support to run in browsers, and that same support can be reused outside the browser, including on the JVM.

We should expect this trend to steadily continue.

Conclusion​

Being able to reuse complex, high-quality libraries everywhere, while staying within JVM boundaries, feels like a superpower.

Wasm unlocks scenarios that used to be impractical or outright impossible in Java, and it does so with less code, less risk, and less maintenance.

Thanks for reading. I hope it’s clear by now, syntax highlighting was just the excuse ✨

Release date: 2025-11-10

Chicory 1.6.0 brings Java Platform Module System (JPMS) support, significant performance improvements with directory-backed caching, enhanced Threads proposal support, and Extended Constant Expressions. This release also adds Java 25 support and improves the developer experience with better APIs.

Highlights​

Java Platform Module System (JPMS) Support​

• Full Java module definitions (module-info.java) added across all Chicory modules, enabling proper module boundaries and encapsulation.
• Chicory is now fully compatible with Java 9+ module system requirements, making it easier to use in modular Java applications.

Directory-Backed Runtime Compiler Cache​

• New experimental directory-based cache implementation for the runtime compiler, significantly improving startup performance for repeated module executions.
• Thread-safe and process-safe cache implementation using atomic file operations.
• Cache entries are stored as JAR files, keyed by module digest, enabling fast subsequent loads without recompilation.

Enhanced Threads Proposal Support​

• Atomic fence instruction implementation, completing the Threads proposal support for proper memory ordering in concurrent WebAssembly execution.
• Full spec-compliant atomic operations for multi-threaded WebAssembly modules.

Extended Constant Expressions Proposal​

• Implementation of the Extended Constant Expressions proposal, enabling more complex constant expressions in WebAssembly modules.
• Supports advanced constant evaluation capabilities in WebAssembly modules.

Other Improvements​

• CompiledModule Interface: New interface to make it easier to work with multiple build-time compiled modules, improving the developer experience.
• Performance Optimization: Cache WasmModule in static fields to avoid parsing modules multiple times.
• Java 25 Support: Full compatibility with the latest Java release.
• API Improvements: Sanitized method and field names in annotation processor for better code generation.
• Bug Fixes: Fixed WASI testsuite returning unsupported operation errors.

A huge thank you to all contributors for their valuable contributions. Check out the commit history for detailed implementation notes, and as always, let us know how it performs in your workloads!

Happy WebAssembly-in-the-JVM coding! 🚀

Release date: 2025-07-04

Chicory 1.5.0 introduces full support for both the WebAssembly Exception Handling and Threads proposals, implemented across both the compiler and interpreter. This release ensures spec-compliant control flow and concurrent execution for your WebAssembly modules on the JVM.

Highlights​

WebAssembly Exception Handling Support​

• Implemented the official WebAssembly Exception Handling proposal in the compiler, complementing existing interpreter support.
• End-to-end exception handling support: compiler and interpreter fully round-trip exception constructs across boundaries.

WebAssembly Threads Proposal Implementation​

• Added support for the Threads proposal in both compiler and interpreter.

Other Improvements​

• Increased CI coverage running nightly the Zig standard library testsuite

A huge thank you, as usual, to all contributors for bringing full WebAssembly Exception Handling and Threads support to Chicory across both compiler and interpreter. Check out the commit history for detailed implementation notes, and as always, let us know how it performs in your workloads!

Happy WebAssembly-in-the-JVM coding! 🚀

🎓 Compiler Graduates from Experimental​

After extensive development and testing, the Compiler is now officially stable. It enables the compilation of WebAssembly modules into plain Java bytecode at build time or runtime, offering improved performance and seamless integration into Java applications.

Key Benefits:

• Performance: Faster execution by eliminating interpretation overhead.
• Integration: Generates standard Java bytecode, facilitating integration with existing Java tools and libraries.
• Stability: Extensively tested to ensure reliability across various use cases(with real-world modules like CPython, SQLite, etc.).

🏷️ Annotations are Now Stable​

The annotation system has matured and is now considered stable too. It provides high level APIs to for exports and host function's declaration and usage, enhancing developer productivity and code clarity.

Highlights:

• Ease of Use: Simplifies configuration through familiar Java annotations.
• Flexibility: Allows fine-grained control over module behavior and integration.

🧪 Progress Towards WasmGC with Reference Types​

Chicory 1.4.0 lays the groundwork for supporting WebAssembly's Garbage Collection(WasmGC) proposal, including reference types. This advancement moves us closer to full compliance with emerging WebAssembly proposals, enabling more modules to run efficiently.

🙌 Acknowledgments​

We extend our heartfelt thanks to the community contributors whose efforts have been instrumental in this release. Your feedback, code contributions, and support continue to drive Chicory forward.

For a detailed list of changes and contributions, please refer to the commit history.

⚠️ Migration Guide​

As we transition out of an experimental phase, the old experimental modules are not going to be supported anymore. In this guide you can find the notes on how to move to the stable release of the functionalities. If there is any missing detail, please, don't be afraid to open an issue asking for clarifications.

ArtifactId renames​

The ArtifactId of the modules have changed in this way:

Package names​

The name of the Java packages changed

Maven plugin​

Two main changes specific to the Maven plugin:

• The name of the goal of the compiler changed from wasm-aot-gen to compile
• The name configuration corresponds to the name of the generated class, i.e. the "Module" suffix is not added anymore automatically

With incredible contributions from Hiram Chirino, Chicory's ahead-of-time (AOT) compiler continues to mature, bringing us one step closer to leaving the experimental phase behind.

Highlights include:

• 🧠 No More Param Limits: The previous cap of 255 function parameters? Gone.
• 🏗️ Bye-Bye ClassTooLargeError: We've refactored code generation for large WASM modules to avoid hitting JVM class size limits.

🛠️ Bug Fixes & Improvements

This release includes the usual refinements and one particularly notable fix:

• 💡 Random, Now Smarter: To resolve issues with native-image compilation, we've changed the default random source in WasiOptions from SecureRandom to ThreadLocalRandom. This makes it more compatible with GraalVM.

If your application relies on the previous behavior, you can restore it with:

WasiOptions.builder()
  .withRandom(new SecureRandom())
  .build();

For a full list of changes and commits, check out the commit history.

🚀 Exception Handling​

The Exception Handling proposal, now at Phase 4, has been implemented in the interpreter.

🔧 WasmModuleInterface​

This is a breaking change in the experimental module: host-module-processor-experimental.
Exports now generate a class instead of an interface, enabling caching for faster lookups and invocations.

🔁 Tail Call Support​

Tail call opcodes are now recognized in the compiler, improving optimization potential.

📢 Join the Chicory Community​

A huge thank you to all our contributors for their exceptional work on this release!

Try out Chicory 1.2.0 today and let us know what you think! 🚀

SIMD Support​

After extensive development and testing, Chicory now fully supports SIMD instructions in the interpreter. This implementation leverages the experimental Vector API available in Java 21+, unlocking substantial performance gains for workloads that can take advantage of parallel processing.

Find out how to enable SIMD in your project by visiting the documentation.

Optimized Memory Management​

Memory management is now highly customizable, allowing fine-tuned control based on your application’s needs. Additionally, we’ve a new optimized Memory implementation to deliver the best possible performance, informed by real-world benchmarks and user feedback.

Learn how to configure memory settings in the documentation.

Improved Android Support​

We've enhanced our Android compatibility by introducing automated checks in CI and reducing the minimum supported API level to 28.

Join the Chicory Community​

Chicory continues to evolve, and we encourage you to upgrade to 1.1.0 to take advantage of these improvements. A huge thank you to all our contributors for making this project even better!

With this release, we’re introducing a “Who Uses Chicory?” section in the main README. If you’re using Chicory in your projects, we’d love to hear about it!

Try out Chicory 1.1.0 today, and let us know what you think!

Christmas is a time of tradition, and I’m delighted to continue the one we started last year. On this very same date and blog, we unveiled the development of Chicory: Chicory: WebAssembly on the JVM.

WebAssembly continues to grow steadily and strongly, much like we’ve come to expect from web technologies ([link to this year Edoardo’s blog]). While it’s not perfect yet, the ecosystem is expanding. For instance, CPython 3.13 is now officially released for WASI, and SQLite has added official support for WebAssembly builds using Emscripten.

This year, I’m thrilled to share an exciting announcement: Chicory, the pure Java WebAssembly runtime, has reached its first stable release: 1.0.0!

Last year, we unpacked a toolbox. This year, we’re unwrapping a heartfelt photo album, showcasing the magical journey that brought us to this incredible milestone.

The Cover​

Let’s start with the cover!

Chicory now has a brand-new official website: chicory.dev. We’re continuously improving and updating it. A curious detail for the most attentive visitors: the documentation is tested continuously in CI using a clever combination of JJest + Approval Tests powered by JBang. This ensures that every code snippet displayed in the docs can be successfully compiled by users.

At the forefront of this release is the prominent 1.0.0, marking Chicory’s first stable release. But what does that really mean? Over the past 12 months, we’ve been rapidly developing the engine, and early adopters likely noticed significant changes to the public API. There were several reasons for this:

• we learned a lot about WebAssembly along the way.
• we improved the API, making it more intuitive for those familiar with other runtimes.
• we introduced additional modules, ensuring they integrate seamlessly.
• we focused on performance, eliminating bottlenecks from the public API.

What to expect?​

With 1.0.0, we’re committing to maintaining compatibility with this API. It’s time to dive in confidently, knowing that the code you write won’t become outdated early.

Beyond the public API, we’re proud to say Chicory is now stable and useful to start providing active support for it.

The Family Picture​

When you open the cover, the first thing you see is a traditional, unmissable family photo.

Here are the key members of our Chicory family:

• The basic building block: wasm This is the core module, responsible for handling the nitty-gritty details of the WebAssembly specification. It provides idiomatic Java APIs for working with arbitrary binary Wasm modules.

• The main character: runtime At its core, this is the interpreter we introduced last year. Now, it supports the full V1 WASM specification(except simd) along with some additional "proposals". While it’s slow compared to other options, it’s extremely reliable and portable. We take pride in its readability, making it a pleasure to hack on!

• The system interface layer: wasi This module provides an implementation of Wasi Preview 1, still a widely supported compilation target for languages like Go, Rust, and C++. In our experience, it enables Chicory to run various real-world Wasm modules effectively. While there are limitations, you’re encouraged to roll your own implementation when the provided one doesn’t suffice.

• The mandatory: log This module allows(when necessary) decoupling from the Java Platform Logging (JEP 264), which isn’t available on Android devices.

• The cool kid: wabt External tools like wat2wasm(for converting WebAssembly Text format .wat files to binary) and wast2json(for parsing .wast files and emitting .wasm files and .json assertion description) are essential for building Chicory. These incredibly valuable tools officially ship as Wasm modules. We bundle a pure Java executable version (through Chicory, of course) to make them easily consumable as Jar artifacts.

• Finally, the: bom This module keeps all the others aligned and smiling for the camera.

The Newborns​

Turning the first page reveals a collection of little creatures, freshly born and still in need of nurturing before they fully join the family. These modules are released with the -experimental suffix and placed in the relevant experimental namespace to indicate they’re not yet fully mature.

We encourage you to try them out and explore their potential, but keep in mind that they may not yet offer full stability as they grow towards maturity.

• The one eager to start walking: aot-experimental AoT stands for “Ahead Of Time.” This module translates Wasm to Java Bytecode (at the right distance, they look surprisingly similar!), generating pure Java artifacts from Wasm modules. Compiling and running modules dynamically requires some reflection, and this module depends on ASM. While it’s incredibly fast, there are still some rough edges to refine.

• The lightweight companion to the first one: aot-maven-plugin-experimental This lightweight Maven plugin makes it easy to use the AoT translator at compile time. The resulting artifacts are persisted to disk, eliminating the need for external dependencies or runtime reflection. However, this approach sacrifices dynamic module loading.

• The quiet one that flies under the radar: cli-experimental This CLI allows you to quickly evaluate Chicory directly in the comfort of your terminal.

• The twins: host-module-annotations-experimental & host-module-processor-experimental These consist of annotations and the corresponding annotation processor, making it easier to integrate Chicory through a higher-level, fully Java-idiomatic, generated API.

The Travel Memories​

Turning another page takes us through a colorful spread of memories, showcasing the countless places where Wasm has made its mark across the software world. These moments are as diverse as they are inspiring, reminding us that WebAssembly is truly everywhere! Here’s a glimpse, in no particular order:

• Through a refracted spectrum: With our great friends at JRuby, we got Prism running as a pure Java artifact, enabling the bootstrapping of JRuby without any native dependencies.

• From the deserts: A Wasm Camel found its way into a low-level integration.

• Large highways: Kafka Connect and Apache Pulsar opened up the road to polyglot data transformations built on message queues.

• A river capturing every ripple: Debezium uses Wasm plugins to track Change Data Capture events as they flow through your data streams.

• The wrought iron gate: Keycloak stands tall, demonstrating pluggable Policy Providers in languages beyond Java.

• From the shallow waters of a river: A (Kafka Proxy)Kroxy opens its jaws, providing unprecedented extensibility.

• A friendly agent: OPA(Open Policy Agent) policy issues policy fees on our virtual dashboard. Thankfully, we avoided the speed trap by removing the network!

• Comfortably eating data on the Java train: SQLite offers a tasty and safer option for data consumption.

• In the middle of a gray sky of clouds: A Spark lights up Big Data processing in new ecosystems.

• Timeless snapshots: Rusty gems like Ocrs, Photon, and others are the must-have selfies of this journey.

The Parties​

Exploring the software world is always a thrill, but the most valuable part of the journey is meeting, chatting, and spending time with others who share your passions.

We’ve been fortunate to be accepted at various events, proudly taking the stage to showcase our juggling skills with compilers, runtimes, and integrations.

If you’d like to experience our journey firsthand, here are a few highlights you can watch:

• Wasm I/O 2024: The ultimate destination for anyone building with WebAssembly. A small but top-notch gathering of experts pushing the boundaries of this technology. Check out our talk: Chicory: Creating a Language-Native Wasm Runtime by Benjamin Eckel / Andrea Peruffo.

• Dylibso Insiders: A comprehensive and approachable retelling of Chicory’s journey. Dive into the full story with: Chicory, a JVM Native WebAssembly Runtime by Benjamin Eckel.

• Devoxx BE 2024: The largest Java conference in Europe and a pivotal moment for Chicory. We connected with new and old friends, paving the way for the future. Watch our talk: Meet Chicory, exploit the power of WebAssembly on the server side! by Andrea Peruffo.

The Race Day​

This year, GraalWASM by Oracle was announced as "production ready", and we’ve had the pleasure of chatting with the incredible team behind the project.

Picture an adrenaline-filled drag race: vehicles lined up at the starting line, tires burning, and engines roaring. Naturally, you’re curious about how they perform when the rubber meets the road.

These benchmarks are preliminary, and more work is needed before drawing any definitive conclusions. However, we’d like to share the results of running this suite on a dedicated machine, encouraging you to take a closer look and explore further.

Removing the outliers of the interpreters, a close up look at the Photon benchmark:

The results highlight the distinct design choices of each project:

• Chicory’s pure interpreter Its focus on simplicity and portability comes with a trade-off: slower performance.

• GraalWASM GraalWasm delivers great performance using Graal JIT, when available, to compile WASM directly to machine code.

• Chicory’s AoT translator Produces pure bytecode artifacts that achive competitive performance on any standard JVM.

The Road Ahead​

We’ve already bought our tickets for the next leg of this journey, and the adventure has only just begun. We’re eager to explore wilder and uncharted territories, confident that exciting times lie ahead.

Here’s what we’re looking forward to:

• Integrations and usage of Chicory Expanding its availability in major frameworks and products.

• Spec Proposals compliance Achieving full compliance with WebAssembly standards, including Exception Handling, Garbage Collection, and full support for SIMD.

• Maturity and stability of -experimental modules Refining these modules by removing limitations, fixing bugs, and ironing out their APIs.

• Speed We have not spent much time on performance, and it's time to take a serious stab at it.

We’re excited to connect with the community along the way, whether at local JUGs, conferences, or meetups. If you’re curious about WebAssembly and its growing impact on development, don’t hesitate to reach out—we’d love to hear from you!

The Back Cover​

None of this would have been possible without the help of incredible contributors. On the back cover, you’ll find the names of some of the key authors who made this journey possible:

• David Philips: Outstanding work on Wasi and the AoT translator.
• Edoardo Vacchi: His mark is visible in the Store and public API as he joined the brawl.
• Daniel Perano: Instrumental in contributing the first steps of the AoT compiler.
• Ben Eckel That shaped the initial foundation of the project.
• The Team at Dylibso: For their continuous support and collaboration throughout this journey.

As we close this chapter, we hope these snapshots have entertained and inspired you during the festivities. The journey doesn’t end here—come along and join us!

originally published on Java Advent 2024 edition

Despite the little time from the previous version there are a bunch of relevant changes.

API breaking changes​

The name of com.dylibso.chicory.wasm.Module was clashing with the automatic import of java.lang.Module, making it inconvenient in some situations, and we renamed it to com.dylibso.chicory.wasm.WasmModule.

Features​

To maximize compatibility with the spec, we implemented the Tail-Call Optimization Proposal in the interpreter.

We bootstrapped the implementation of the missing SIMD opcodes in a layered way, we are keeping compatibility with Java 11 when they are not necessary, and we started encoding those with the upcoming Vector API. There is a lot of work that can be easily parallelized here, come and join the effort if this sounds like an exciting challenge to you!

AOT improvements​

We finished making modules compiled at build time with the aot-maven-plugin-experimental completely self-contained! You can now emit a binary that runs pure Java Bytecode and only depends on the Chicory runtime library: the original WASM file is not needed. The WasmModule is now provided by the compiled code. Additionally, we changed the Maven configuration so that you now specify the class name prefix rather than the Machine class name. See the documentation for Build-time AOT for more details.

Documentation​

A number of improvements happened in the documentation site, making the project more accessible to newcomers. We are happy to hear feedback and integrate improvements when you find gaps!

Conclusion​

Chicory is quickly stabilizing, and we have also to thank all of our wonderful contributors: without you we would not be where we are today!

Check out Chicory 1.0.0-M2 and we are looking forward to hear from you!

In the previous months we concentrated on correctness and spec-compliance of our WebAssembly runtime; now it is time to harden the codebase and make it a solid platform to build upon.

This release is somewhat special:

• first of all, you will notice we have a brand-new website. We are continuously working on improving the documentation to make it a convenient and detailed resource to get started
• but also, this release marks the beginning of our path toward a final 1.0 version.

The reason why this release took some time is we wanted to get many things right. In this release:

• we updated the public API, including a new way to write host functions
• some modules are now marked as experimental
• we are now more confident in the Ahead-of-Time translator: this translator is a drop-in replacement for the interpreter, and is 100% compatible with the specs that we support in interpreter mode (aot is currently marked as experimental).
• we improved our WASI implementation

Let's take a look in detail.

Public API​

In the name of simplicity and readability (but also encapsulation), we refactored a lot of code, so we made some important changes to our public API. You will find all the updated instructions on the docs.

There is now a clearer boundary between Parser, Module and Instance:

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

We have also introduced a new unified mechanism to define host functions and instantiate collections of related modules together, all at once. We call this utility the Store:

// 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);

You can read more about the Store in the docs.

Host Functions​

We changed the signature for HostFunction. This is probably the biggest surface change you will notice. Not only has the order of the arguments changed, but also their types:

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

Specifically, you will notice that function arguments and return values are all now arrays of primitive longs. This coincided with a huge refactoring/rewrite of the internals of our engine.

Such long values are treated as raw bits, and should be usually converted back and forth to the appropriate types by downcasting or using the public methods of the Value class

For instance, in the example above, we know it is safe to assume that those longs were originally widened integers.

We have however introduced a higher-level abstraction for convenience.

Generated Host Modules​

The new HostFunction API gives you raw access to the arguments of a function as they are represented in the Wasm runtime, but it can be inconvenient to use. Thus, we are now also providing an annotation processor to express HostFunctions in a more ergonomic way.

This feature requires you to depend on the experimental annotation processor:

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

You can now annotate a class as @HostModule("your-wasm-module-name") and export instance members of such a class by annotating them as @WasmExport.

They will generate a HostFunction called wasm_module_name.your_function_name.

For instance, the following generates a HostFunction called wasi_snapshot_preview1.fd_close:

@HostModule("wasi_snapshot_preview1")
public final class WasiPreview1 {
    ...
    @WasmExport
    public int fdClose(int fd) {
        ...
    }
}

As you might have noticed from the example above, we are now using this feature ourselves to implement the WASI host functions.

The annotation processor generates a companion <YourClassName>_ModuleFactory, with a static member <YourClassName>_ModuleFactory#toHostFunctions(<YourClassName>).

This static member returns an array of HostFunctions that perform the conversion between raw longs to the type signature you have declared.

You can expose this member in the most convenient way for your end users.

For instance in this case:

@HostModule("wasi_snapshot_preview1")
public final class WasiPreview1 {
    ...

    public HostFunction[] toHostFunctions() {
        return WasiPreview1_ModuleFactory.toHostFunctions(this);
    }
    ...
}

Supported Types​

Supported input and output types for @WasmExport are primitives int, long, float, double, which correspond to WASM types I32, I64, F32, F64.

We also support java.lang.String arguments, provided that they are only passed as an input value, and they are annotated. We support two annotations:

• @Buffer: the code generator translates the String value to a pair of integers:
  • the first is the index of (or pointer to) the start of the string UTF-8 bytes in the linear memory
  • the second is the length of the string in bytes
• @CString: the code generator translates the String into an index (pointer to) the beginning of a null-terminated string of UTF-8 bytes

For instance:

@WasmExport
public int pathFilestatSetTimes(
        int fd,
        int lookupFlags,
        @Buffer String rawPath,
        long accessTime,
        long modifiedTime,
        int fstFlags) {
    ...
}

is translated to the host function wasi_snapshot_preview1.path_filestat_set_times with a signature equivalent to:

public long[] path_filestat_set_times(
    long fd            // ValueType.I32
    long lookup_flags  // ValueType.I32
    long raw_path_ptr  // ValueType.I32 => string pointer
    long raw_path_size // ValueType.I32 => string length
    long access_time   // ValueType.I64
    long modified_time // ValueType.I64
    long fst_flags     // ValueType.I32
)

You can additionally accept com.dylibso.chicory.runtime.Instance and com.dylibso.chicory.runtime.Memory as input arguments; for example:

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

Experimental Modules​

We are now clearly marking some modules as experimental: while we might still need to introduce a few breaking changes here and there before the final 1.0 release throughout the codebase, we explicitly call a module experimental if it is still under development and might be reworked in the near future.

You might notice that some old modules might have changed their name: for instance, aot is now called aot-experimental and the package name has been renamed from com.dylibso.chicory.aot to com.dylibso.chicory.experimental.aot

Nonetheless, we invite you to try them and welcome any feedback.

Ahead of Time Translation​

Chicory has been initially developed as a Java interpreter for WebAssembly; but it has soon acquired a bytecode translator from Wasm bytecode to Java bytecode. This is what we call the Ahead-of-Time backend. The Ahead-of-Time backend is a drop-in replacement for the interpreter, and it passes 100% of the same spec tests that the interpreter already supports.

You can instantiate a module by explicitly providing a MachineFactory. The default Machine implementation is the InterpreterMachine. You can opt in to the AoT mode by writing:

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

You must add the dependency for AoT:

<dependency>
  <groupId>com.dylibso.chicory</groupId>
  <artifactId>aot-experimental</artifactId>
</dependency>

This will translate every module you instantiate into Java bytecode on-the-fly and in-memory. The resulting code is usually expected to evaluate faster and consume less memory. This was already present in our last release.

With 1.0.0-M1 we are also introducing a new mode of execution: build-time code generation. This mode of execution reduces startup time and will remove the need for distributing the original Wasm binary.

• this improves startup time because the translation occurs only once, when you are packaging your application
• it virtually allows you to distribute Wasm modules as self-contained jars, making it a convenient way to distribute software that was not originally meant to run on the Java platform
• it still maintains the same performance properties as the in-memory compiler (in fact, the compilation backend is virtually the same)

The translation is performed during your build using a Maven plug-in.

Build-Time Ahead-of-Time Translation​

Note: This mode of execution requires configuring a Maven plug-in.

An example can be found in the Chicory codebase. The WABT suite of tools allows manipulating Wasm bytecode in a number of ways. For instance, the wat2wasm tool takes WAT source files (written in "WebAssembly Text Format") and translates them into Wasm.

The WABT tool set is written in C++, and the tools can be compiled to Wasm themselves. So, in the wabt submodule in the Chicory codebase, we translate the Wasm version of wat2wasm into Java bytecode so that we can invoke it without calling a native executable.

<build>
  <plugins>
    <plugin>
      <groupId>com.dylibso.chicory</groupId>
      <artifactId>aot-maven-plugin-experimental</artifactId>
      <executions>
        <execution>
          <id>wat2wasm</id>
          <goals>
            <goal>wasm-aot-gen</goal>
          </goals>
          <configuration>
            <!-- Translate the Wasm binary `wat2wasm` into bytecode -->
            <wasmFile>src/main/resources/wat2wasm</wasmFile>
            <!-- Generate the following class file as a result -->
            <name>com.dylibso.chicory.wabt.Wat2WasmModule</name>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Refer to the wabt module in the Chicory codebase to see how we expose the wat2wasm tool as a library.

WebAssembly System Interface Improvements​

Besides using the new Host Module annotation processor, we introduced many more WASI functions. This improves the compatibility of our engine with the output of the majority of compilers targeting wasip1; at this point, the most used functions should be all supported. Refer to the WASI docs for details.

Conclusion​

Chicory has come a long way since its first release, and we have also to thank all of our wonderful contributors: without you we would not be where we are today!

There is still some way to go before our final release, but we are already looking forward to what you will be building. Check out Chicory 1.0.0-M1 right now and let us know what you think!

A zero dependency Wasm runtime for the JVM​

INTRO​

In a lot of cultures, during Christmas time, Santa would distribute toys and presents to the good kids around. If you are reading Java Advent Of Code, that means that you care about Java and I’m sure you are a good one who deserves a present!

Let me be your Santa today and I’ll show you a new shiny present:

From the outside, the box looks small. We are not going to find any full-fledged framework to write Enterprise applications.

On the front, there are pictures of mythical integrations and fancy plugin systems, but a note on the back catches the attention: “requires assembly”. Gotcha, this is the kind of educational toy that requires us to read the guide to make some sense out of the pieces.

Are you ready for the unboxing?
Here you have a fancy early version of a Wasm interpreter called Chicory!

Whaaaat????
What does that even mean?
Don’t get upset, the instructions are detailed, let’s go through them together.

WebAssembly (Wasm)​

From Wiki we can read:

defines a portable binary-code format and a corresponding text format for executable programs as well as software interfaces for facilitating interactions between such programs and their host environment.

https://en.wikipedia.org/wiki/WebAssembly

Ok, I get it, it’s another bytecode format to express programs, but how and why should we use it? Is the JVM bytecode not good enough?

Wasm has some different characteristics that give it an advantage over the JVM for some use cases. Because it was born on the web, Wasm has a sandboxed memory model which prevents modules from reading memory or jumping to code outside of their own scope. And by default, Wasm will not allow you to access any system resources such as files or networks. Wasm also has no concepts of objects or heap and that means it can run low-level languages very efficiently. This makes Wasm an ideal candidate for running untrusted / third party code written in a variety of languages.

Included pieces​

Wasm has something like an assembly language that maps directly to its instructions. You can write this by hand, but like Assembly, you typically don't. Fortunately, we do have much better and higher level languages to solve the nitty-gritty problems of the low-level for us.

Many of the most popular languages are starting to offer the possibility of TARGETING WASM, translating your program written in a high-level programming language into a series of Wasm instructions.

Often, the instructions for educational games are informative, but you don’t truly understand it until you play it yourself. Let’s connect the first pieces and compile a simple program to Wasm.

The program:

Compile with:

rustc count\_vowels.rs \--target=wasm32-unknown-unknown \--crate-type=cdylib \-C opt-level=0 \-C debuginfo=0 \-o count\_vowels.wasm

For simplicity, you can use the provided Dockerfile.

Now that we have a `.wasm` file to try things out we need “something” to run the instructions.

Without getting too fancy and cutting nuances off we have two main options:

• Another compiler: This should be able to take the `wasm` format and translate it to machine code that a computer can run (e.g. wasm2c)
• An interpreter: This will process the content of the `wasm` file directly executing the instructions.

Chicory, as of today, is a Pure Java (no dependencies other than the Java standard library) interpreter and there are tradeoffs to consider here:

• Compiler:
  • PRO: fast execution
  • CONS: needs a “developer” toolchain to be executed, more opportunity for security vulnerabilities
• Interpreter:
  • PRO: self-contained and easily portable, less opportunity for security vulnerabilities
  • CONS: can be slow for heavy compute programs

More specifically a compiler can apply optimizations and transformations before emitting the target output, effectively making the resulting binary, usually, better in terms of speed and efficiency.
An interpreter instead can directly run WASM code without the need for additional toolchains, this makes it a natural fit for running arbitrary, user-defined functions unknown at compile time of your application.

Chicory is doing a direct mapping from the Wasm format to the JVM's native primitives, which doesn’t need any advanced technique like introspection and, more importantly, reflection making it a great candidate for embedding in GraalVM native-image binaries.

Using our experience and test suite of the interpreter engine, we're also working on a compiler from Wasm to JVM Bytecode. As demonstrated in the Go ecosystem with Wazero both an interpreter and a compiler are extremely useful for different use cases.

Now, let’s stop looking at the separately sold additional pieces of our present and keep reading the instructions :-)

Usage instructions​

When we start thinking about the possible use cases for a WASM interpreter, the sky's the limit. But, let’s look closer at the examples to see how we can employ such technology.

• Enable polyglot plugin systems
  Kroxylicious is a pluggable proxy for Kafka, it enables you to write “filters” in Java to perform various kinds of operations, for example, data manipulation of the messages.
  In this example you can see how to plug in the Chicory interpreter and automagically offer support for plugins written in other languages. Extism is another great example of an ultra-portable plug-in system.

• Reuse of libraries from different ecosystems
  It’s not always desirable to rewrite a functionality in multiple different languages, for the sake of speed, correctness and maintenance.

• Dynamic functions execution
  GraalVM native-image makes it viable for Java programs to be compiled into static binaries. The downside is that the usage of reflection becomes an obstacle and should be configured Ahead Of Time. This takes out a good slice of “dynamicity”.
  In this example we are including Chicory in a statically built CLI binary that can execute user-provided code provided via the command line.

So, the pictures are nice, now let’s try to write and run an example on our own.

Now we are going to write a Quarkus Web Server from scratch that will expose two endpoints:

• Load code dynamically
• Execute the loaded code on the user input

You can think of it like a mini Java-powered "functions as a service" platform. And with native image, we will be compiling it to native binaries so it should be fast.

Step-by-step​

1. Install the Quarkus CLI and create a standard Quarkus application:

   quarkus create

   This command will automatically scaffold a full-blown server-side application in the folder code-with-quarkus , so open it with your favorite IDE/Editor and we can start to play!

2. Fix the dependencies in pom.xml as shown in this diff:

   
   • use plain RestEasy (as opposed to the default reactive version)
   • add the dependency on Jackson to handle Json objects from your API
   • add the dependency on the Chicory runtime! ( as described in the project Readme )

3. Remove the default content in src/main/java/org/acme and scaffold your implementation with the content available here.
   In the code we are defining a stateful “Service” shared between 2 “Resource”s depending on it:

   • “WasmResource” defines one endpoint able to receive a wasm file in binary format
   • “ComputeResource” is the endpoint that will provide the final “functionality” executing the last wasm function uploaded against the user input
   • the “WasmService” example API exposes two methods to perform the desired operations:
   

4. Fill the empty “WasmService” implementation to finally perform the desired actions using Chicory’s primitives

   
   • “setModule” takes an InputStream and builds a Wasm Module out of it, reading the structure and the instructions contained. The Module will be stored into an example local variable to be reused.
   • “compute” is a method that takes a simple user input (an int !) and perform the rest of the operations:
     • instantiate the module to be ready to run
     • find a declared function named “exported_function”
     • invoke the function passing the user content to it
     • return the result as an “int”

5. Congratulations! You have just written your first application server leveraging a Wasm interpreter! Let’s test it out by running the server in a shell:
   mvn quarkus:dev
   Spin another shell and use the endpoints:

   • let’s first upload a Wasm module, to try things out in an easy way you can use the pre-built example (feel free to modify and recompile it!):

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

     and upload it to the running web-server:

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

   • finally, we can call the “compute” endpoint:

     curl \-v 'http://localhost:8080/compute' \-H 'Content-Type: application/json' \--data-raw '41'
     

   • and we should receive the long-awaited answer:

     {"value":42}
     

     as the compiled example is simply adding 1 to the user input.

6. To make sure that there is nothing that depends on the development environment we can now containerize our application. Drop a file named Dockerfile.native-scratch in the src/main/docker folder of our Quarkus application, and fill it with the following content (adapted from the official documentation):

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" \]  

Build the container image:

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

And run it:

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

You can notice that the final image is built FROM scratch making sure that our application will not be accessing any system-level resource. You can exercise the built image by using the same curl demo commands provided before.

Pretty cool, right?
Now you have a toy server that can run your users' Wasm code against the user input running as a native-image !

You can find all the code we used in this exercise here.

Warranty​

Chicory is in an early stage of development, there are rough edges and the current implementation doesn’t cover the full specification just yet. Although we're missing some pieces of the puzzle, now is a great time to join and help!

If you are brave enough to try things out, please report any failure along with your use case! We are eager to receive early feedback on the current work.

Next​

Thanks for bearing with these instructions, I hope that you are reading this final comment while basking, feeling accomplished, with a working example.

We can silently leave the room, to get back, heads down, implementing the last details of the WebAssembly specification.

This year we have built a little rocket toy, but we strongly believe that this innovation brings great benefits to Java and the ecosystem and we are looking at landing on the Moon and making this project a solid building block for the Java applications of tomorrow!

What else?​

Demo repo:​

​​https://github.com/andreaTP/first-chicory-blog

Acknowledgment/Further reads:​

Edoardo Vacchi has written a series of 2 blog posts to track the progress of Wasm related projects especially targeting Java developers:

• https://www.javaadvent.com/2022/12/webassembly-for-the-java-geek.html
• https://www.javaadvent.com/2023/12/a-return-to-webassembly-for-the-java-geek.html

Similar projects:​

GraalVM implementation of WebAssembly objectives are pretty much the same as Chicory’s, and this implementation is, at the time of writing, somehow more mature and complete.
Chicory’s differentiates itself for a few, but we believe compelling, reasons:

• Zero dependencies: Chicory’s doesn’t need any additional dependency(other than itself obviously)
• No platform lock-in: Chicory’s can, and will always, run on any compatible implementation of the JVM as it’s not based on any opinionated framework.

Bio:​

Andrea Peruffo​

Andrea Peruffo is an all-around software developer with experience in delivering software systems of any kind. He has experience in many different fields, like embedded controllers, cloud infrastructures, PLCs, BigData platforms, FPGAs, microservices etc. etc. Fond in hands-on code development and contributor to several Open Source projects.

Benjamin Eckel​

Benjamin Eckel is the CTO and co-founder of Dylibso, a company focused on accelerating Wasm adoption and tooling.