Mandrel: A specialized distribution of GraalVM for Quarkus

When we first announced Mandrel, we explained why Red Hat needed a downstream distribution of GraalVM. We were most interested in GraalVM's native image capability, specifically in the context of Quarkus. In this article, we explain what Mandrel is and what it's not. We'll introduce some of Mandrel's technical features and offer a short demonstration of using Mandrel with Quarkus.

What is Mandrel?

Mandrel focuses on GraalVM's native-image component in order to provide an easy way for Quarkus users to generate native images for their applications. Developers using Quarkus should be able to go all the way from Java source code to lean, native, platform-dependent applications running on Linux. This capability is vital for deploying to containers in a cloud-native application development model.

We've deliberately made no promises about other uses of GraalVM within Mandrel. A full distribution of GraalVM is much more than native-image: It has polyglot support; the Truffle framework, which supports efficient interpreter implementation; an LLVM compiler back end for native-image; the libgraal JIT compiler as a replacement for HotSpot’s C2 server compiler; and much more. Mandrel is a small subset of GraalVM's functionality. We support it for the native-image use case in projects like Quarkus.

Why Mandrel?

Mandrel lets us remove the parts of GraalVM that we don't need and focus on native-image. It reduces the codebase we have to maintain and test. Mandrel lets us use upstream OpenJDK 11 instead of Labs OpenJDK 11, the base Java Development Kit for GraalVM CE. Red Hat has a team to support OpenJDK for Red Hat customers, so using upstream OpenJDK was a natural fit for Mandrel. Red Hat also has a strong history of being involved in OpenJDK upstream, and currently leads the OpenJDK 11u stream of the jdk-updates OpenJDK project.

Through our leadership in these projects, we've made stable changes that improved GraalVM, and thus Mandrel. Because Red Hat is an upstream-first company, we try to get patches upstream from the start. So far, we've augmented GraalVM CE with debugging capabilities (using the -g flag) for both Linux and Windows, and we're actively working with Oracle Labs to add JDK Flight Recorder support to native-image. Once integrated, developers will be able to use JDK Flight Recorder to observe and trace behavior and performance challenges in their applications whether they run in JVM-mode or natively.

GraalVM components in Mandrel

To deliver GraalVM's native-image feature via Mandrel, we build only the Substrate VM framework, along with its dependencies. This includes the GraalVM SDK and the GraalVM compiler. All other GraalVM components, like Truffle and Sulong, are not part of Mandrel, and we don't build them.

Apart from the GraalVM SDK and compiler, the Substrate VM also depends on a base JDK and a native-compiler toolchain. Mandrel uses upstream OpenJDK 11 builds and the GNU Compiler Collection (GCC) to satisfy these dependencies, whereas GraalVM uses Labs OpenJDK 11 and supports both the GCC and LLVM toolchains.

We tend to think of Mandrel as an extension to OpenJDK—mostly JAR files and very few native binaries. In fact, our productized Mandrel image only adds two RPMs on top of a regular java-11-openjdk-static-libs installation from base RHEL.

Building Mandrel

GraalVM is built using mx, a tool written in Python. All the dependencies between the different GraalVM components are defined through mx suites, and parts of the build process are defined as mx extensions. As a result, mx is an integral part of Mandrel's build process, as well. Extending the mx suites to support both GraalVM and Mandrel builds turned out to be difficult. It was especially challenging to combine that effort with reducing the components being built and splitting the build steps, which we did to support building different parts on different build systems.

Our current solution is using mandrel-packaging to build Mandrel. This tooling handles removing unnecessary dependencies from otherwise needed mx suites, and it invokes the necessary commands in the correct order. The mandrel-packaging tool also lets us build Mandrel in three steps: First, we generate the Java parts (JAR files and Maven artifacts); then, the native parts (GraalVM’s static libraries); and finally, we assemble them with OpenJDK 11 to produce a native-image-capable runtime.

Here are the basic instructions for building Mandrel's current version from source, using OpenJDK 11 as the basis:

$ curl -sL https://github.com/AdoptOpenJDK/openjdk11-upstream-binaries/releases/download/jdk-11.0.10%2B9/OpenJDK11U-jdk_x64_linux_11.0.10_9.tar.gz -o jdk.tar.gz
$ curl -sL https://github.com/AdoptOpenJDK/openjdk11-upstream-binaries/releases/download/jdk-11.0.10%2B9/OpenJDK11U-static-libs_x64_linux_11.0.10_9.tar.gz -o jdk-static-libs.tar.gz
$ export JAVA_HOME=$(pwd)/openjdk-11
$ mkdir ${JAVA_HOME}
$ tar xf jdk.tar.gz -C ${JAVA_HOME} --strip-components=1
$ tar xf jdk-static-libs.tar.gz -C ${JAVA_HOME} --strip-components=1
$ git clone --depth 1 --branch 5.279.1 https://github.com/graalvm/mx
$ git clone --depth 1 --branch mandrel-21.0.0.0-Final \
  https://github.com/graalvm/mandrel 
$ git clone --depth 1 --branch mandrel-21.0.0.0-Final \
  https://github.com/graalvm/mandrel-packaging
$ $JAVA_HOME/bin/java -ea ./mandrel-packaging/build.java \
  --mx-home $(pwd)/mx --mandrel-repo $(pwd)/mandrel
$ ./mandrel-java11-21.0.0.0-Final/bin/native-image --version
GraalVM Version 21.0.0.0-Final (Mandrel Distribution) (Java Version 11.0.10+9)

Collaboration with Oracle Labs

GraalVM CE 11 is based on Labs OpenJDK 11, a fork of the upstream OpenJDK 11, which is used to build a base JDK with support for libgraal and GraalVM CE. Labs OpenJDK 11 is maintained by the same group that builds GraalVM CE.

Because Graal VM CE is based on Labs OpenJDK 11, the Graal VM team can take advantage of the latest Java-level JVM Compiler Interface (JVMCI) enhancements in Java 11 and enhance them. Because the two projects are so connected, it was impossible to replace Labs OpenJDK 11 with upstream OpenJDK 11 as the build JDK when we started. We collaborated with Oracle Labs to make Mandrel a reality.

We wanted to build with plain OpenJDK 11, and Oracle Labs wanted fewer patches to maintain downstream. This work concluded with a set of patches being merged in the GraalVM codebase and upstream OpenJDK 11. It was a great foundation for further collaboration. Most notably, we needed to get support for building OpenJDK libraries as static variants into OpenJDK 11. Mandrel uses OpenJDK static libraries rather than their shared library counterparts in regular OpenJDK distributions. This lets us link native Java applications into native images, which are dependent on OpenJDK libraries.

Using Mandrel with Quarkus

At the time of this writing, Quarkus is Mandrel's main consumer. Here is a quick demonstration of using Mandrel to generate a native executable for a simple RESTEasy Quarkus application written in Java:

$ echo | mvn io.quarkus:quarkus-maven-plugin:1.12.2.Final:create
$ cd code-with-quarkus
$ ./mvnw -Dnative verify \
         -Dquarkus.native.container-build=true \
         -Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel:20.3-java11
$ ./target/code-with-quarkus-1.0.0-SNAPSHOT-runner  
__  ____  __  _____   ___  __ ____  ______ 
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/  
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \    
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/    
2021-03-08 17:57:40,084 INFO  [io.quarkus] (main) code-with-quarkus 1.0.0-SNAPSHOT native (powered by Quarkus 1.12.2.Final) started in 0.014s. Listening on: http://0.0.0.0:8080
2021-03-08 17:57:40,084 INFO  [io.quarkus] (main) Profile prod activated.  
2021-03-08 17:57:40,084 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
$ curl -w "\n" http://localhost:8080/hello-resteasy
Hello RESTEasy

We first create a simple RESTEasy Quarkus application in the directory, code-with-quarkus. We then compile the Java source code with the Maven wrapper (mvnw), and build the native executable from Java class files using a predefined container image. The -Dnative parameter instructs Maven to generate a native executable, -Dquarkus.native.container-build=true instructs Quarkus to build the native executable using a builder image, and -Dquarkus.native.builder-image=... dictates which builder image to use. Visit the Quarkus guides for more details about this example.

The generated binary, ./target/code-with-quarkus-1.0.0-SNAPSHOT-runner, is a native ELF binary suitable to run on a basic Linux distribution, like a minimal UBI 8 image:

$ file target/code-with-quarkus-1.0.0-SNAPSHOT-runner
target/code-with-quarkus-1.0.0-SNAPSHOT-runner: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0, BuildID[sha1]=b43068dce7c114a0e8d018370a9d47e1e257de44, not stripped

Figure 1 shows the workflow for containerizing a Quarkus application with Mandrel's native-image executable.

Summary

Mandrel is a downstream release of GraalVM, focused on native image compilation of Java applications in Red Hat-backed projects. As such, it is not a GraalVM native-image replacement for all users. For instance, Mandrel does not ship with polyglot or LLVM toolchain support, which some use cases might require. However, Red Hat engineers contribute to upstream GraalVM and work hard to stay up-to-date with upstream GraalVM code.

Mandrel is part of the GraalVM GitHub organization and is being maintained as part of that organization; it's part of the GraalVM ecosystem and we do not intend to change that. That said, Mandrel aims to meet the sustainability needs of projects like Quarkus. Our main goal in that regard is to keep Mandrel versions that are part of the larger Quarkus ecosystem stable and supported throughout their lifecycle in that ecosystem. So, it's likely that we’ll keep certain Mandrel versions updated longer than regular upstream GraalVM CE builds normally would be. Also, because Mandrel depends on OpenJDK 11, we’ll need to keep it up-to-date with OpenJDK's quarterly security fixes.

Please check back regularly for Mandrel releases on our GitHub page. We currently have downloads for Linux and Windows. We usually publish UBI 8-based Linux container images to quay.io at the same time as our GitHub releases or soon after.