graalwasm-embed-c-code-guide

Embed C in Java Using GraalWasm

The example below demonstrates how to compile a C function to WebAssembly and run it embedded in a Java application.

Prerequisites

To complete this guide, you need the following:

• GraalVM JDK
• Emscripten compiler frontend
• Maven

1. Setting up the Maven Project

To follow this guide, generate the application from the Maven Quickstart Archetype:

mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DgroupId=com.example -DartifactId=demo -DinteractiveMode=false

cd demo

1.1. Adding the Polyglot API and GraalWasm Dependencies

The GraalVM Polyglot API can be easily added as a Maven dependency to your Java project. The GraalWasm artifact should be on the Java module or class path too.

Add the following set of dependencies to the <dependencies> section of your project's pom.xml:

• To add the Polyglot API:

  <!-- <dependencies> -->
  <dependency>
      <groupId>org.graalvm.polyglot</groupId>
      <artifactId>polyglot</artifactId>
      <version>25.0.2</version>
  </dependency>
  <!-- </dependencies> -->

• To add GraalWasm:

  <!-- <dependencies> -->
  <dependency>
      <groupId>org.graalvm.polyglot</groupId>
      <artifactId>wasm</artifactId>
      <version>25.0.2</version>
      <type>pom</type>
  </dependency>
  <!-- </dependencies> -->

2. Setting Up C Code

Next, write a C function and compile it into a WebAssembly module.

2.1. Writing C Code

Put the following C program in src/main/c/floyd.c:

#include <stdio.h>

void floyd(int rows) {
    int number = 1;
    for (int i = 1; i <= rows; i++) {
        for (int j = 1; j <= i; j++) {
            printf("%d ", number);
            ++number;
        }
        printf(".\n");
    }
}

int main() {
    floyd(10);
    return 0;
}

Note that floyd is defined as a separate function and can be exported.

2.2. Compiling C Code to WebAssembly

Compile the C code using the most recent version of the Emscripten compiler frontend:

mkdir -p target/classes/com/example

emcc --no-entry -s EXPORTED_FUNCTIONS=_floyd -o target/classes/com/example/floyd.wasm src/main/c/floyd.c

The exported functions must be prefixed by _. If you reference that function in the Java code, the exported name should not contain the underscore.

It produces a standalone file floyd.wasm in target/classes/com/example/, which enables you to load the file as a resource.

Using Maven to Compile C Code

You can automate the C compilation and make it a part of the Maven build process by adding the following plugin configuration to the <build> section of the pom.xml file.

<!-- <build> -->
<plugins>
  <plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>1.2.1</version>
    <executions>
      <execution>
        <id>create-output-directory</id>
        <phase>generate-resources</phase>
        <goals>
          <goal>exec</goal>
        </goals>
        <configuration>
          <executable>mkdir</executable>
          <commandlineArgs>-p ${project.build.outputDirectory}/com/example/</commandlineArgs>
        </configuration>
      </execution>
      <execution>
        <id>compile-c-into-wasm</id>
        <phase>generate-resources</phase>
        <goals>
          <goal>exec</goal>
        </goals>
        <configuration>
          <executable>emcc</executable>
          <commandlineArgs>--no-entry -s EXPORTED_FUNCTIONS=_floyd -o ${project.build.outputDirectory}/com/example/floyd.wasm ${project.basedir}/src/main/c/floyd.c</commandlineArgs>
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>
<!-- </build> -->

This binds the exec-maven-plugin:exec goal to the generate-resources phase of the build lifecycle. The exec goal runs mkdir and emcc with the same command line arguments as above, ensuring that the generated WebAssembly module file is included as a resource file in the final JAR file.

3. Using the WebAssembly Module from Java

Now you can embed this WebAssembly function in a Java application. Put the following in src/main/java/com/example/App.java:

package com.example;

import java.io.IOException;
import java.net.URL;

import org.graalvm.polyglot.Context;
import org.graalvm.polyglot.Source;
import org.graalvm.polyglot.Value;

public class App {
   public static void main(String[] args) throws IOException {
       // Find the WebAssembly module resource
       URL wasmFile = App.class.getResource("floyd.wasm");
       Source source = Source.newBuilder("wasm", wasmFile).build();

       // Create Wasm context
       try (Context context = Context.newBuilder("wasm").option("wasm.Builtins", "wasi_snapshot_preview1").build()) {
           // Compile and instantiate the module
           Value module = context.eval(source);
           Value instance = module.newInstance();

           // Get the exports member from the module instance
           Value exports = instance.getMember("exports");

           // Invoke an exported functions
           exports.invokeMember("_initialize");
           exports.invokeMember("floyd", 10);

           // Or if you need to call a function multiple times
           Value floyd = exports.getMember("floyd");
           floyd.execute(4);
           floyd.execute(8);
       }
   }
}

4. Using Java functions from WebAssembly

You can also call Java functions from WebAssembly by importing them into your WebAssembly modules. For this example, let's try to move the logic which computes the next element of the output (by doing an integer increment) to a Java function.

We need to add the following to our C file to declare an external function whose implementation we will provide in Java:

extern int javaInc(int number)
__attribute__((
    __import_module__("env"),
    __import_name__("java-increment"),
));

This introduces an import in the resulting WebAssembly module. The import will pull a function named java-increment from the imported module env. Within our C code, this function will be available under the name javaInc. We can update our floyd function to use javaInc like so:

void floyd(int rows) {
    int number = 1;
    for (int i = 1; i <= rows; i++) {
        for (int j = 1; j <= i; j++) {
            printf("%d ", number);
            number = javaInc(number);
        }
        printf(".\n");
    }
}

Then, in our Java application, we pass in an import object when instantiating our WebAssembly module. This import object maps module names to module objects, with each module object mapping function names to function definitions.

...
import java.util.Map;
import org.graalvm.polyglot.proxy.ProxyExecutable;
import org.graalvm.polyglot.proxy.ProxyObject;

public class App {

    public static Object javaIncrement(Value... v) {
        return Value.asValue(v[0].asInt() + 1);
    }

    public static void main(String[] args) throws IOException {
            ...
            // Compile and instantiate the module with host function
            Value module = context.eval(source);
            Value instance = module.newInstance(ProxyObject.fromMap(
                Map.of("env", ProxyObject.fromMap(
                        Map.of("java-increment", (ProxyExecutable) App::javaIncrement)
                ))
            ));
            ...
        }
    }
}

5. Building and Testing the Application

Compile and run this Java application with Maven:

./mvnw package
./mvnw exec:exec

The expected output should contain the first 10 lines of Floyd's triangle, printed using the C function:

1 .
2 3 .
4 5 6 .
7 8 9 10 .
11 12 13 14 15 .
16 17 18 19 20 21 .
22 23 24 25 26 27 28 .
29 30 31 32 33 34 35 36 .
37 38 39 40 41 42 43 44 45 .
46 47 48 49 50 51 52 53 54 55 .

Conclusion

By following this guide, you have learned how to:

• Compile C code to a WebAssembly module and export C functions as WebAssembly exports.
• Load WebAssembly modules in Java using GraalWasm.
• Call functions exported from C in your Java application.

Learn More

You can learn more at:

• GraalWasm Reference Manual
• GraalVM Embedding Languages Documentation
• GraalWasm on GitHub