The Substrate VM Project

Substrate VM is an internal project name for the technology behind GraalVM Native Image. This guide shows how to set up a development environment for the project.

To get started, install mx. Then point the JAVA_HOME variable to a JDK that supports a compatible version of the JVM Compiler Interface (JVMCI). JVMCI is a privileged, low-level interface to the JVM that can read metadata from the VM, such as method bytecode, and install machine code into the VM. Obtain JVMCI-enabled:


For compilation, native-image depends on the local toolchain. Install glibc-devel, zlib-devel (header files for the C library and zlib) and gcc, using a package manager available on your OS. Some Linux distributions may additionally require libstdc++-static.

Unlike Linux or macOS platforms, building native images on Windows requires meeting certain prerequisites. The required Microsoft Visual C++ (MSVC) version depends on the JDK version that GraalVM is based on. For GraalVM distribution based on JDK 8, you will need MSVC 2010 SP1 version. The recommended installation method is using Microsoft Windows SDK 7.1:

  1. Download the SDK file GRMSDKX_EN_DVD.iso from Microsoft.
  2. Mount the image by opening F:\Setup\SDKSetup.exe directly. For GraalVM distribution based on JDK 11, you will need MSVC 2017 15.5.5 or later version.

The last prerequisite, common for both GraalVM distribution based on JDK 11 and JDK 8, is the proper Developer Command Prompt for your version of Visual Studio. On Windows, the native-image tool only works when it is executed from the x64 Native Tools Command Prompt.

cd substratevm
mx build

echo "public class HelloWorld { public static void main(String[] args) { System.out.println(\"Hello World\"); } }" >
mx native-image HelloWorld

To build polyglot images, refer to the documentation in the VM suite.

Build Script #

Using Native Image in a development environment requires the mx tool to be installed first, so that it is on your PATH. Visit the MX Homepage for more details.

In the main directory, invoke mx help to see the list of commands. Most of the commands are inherited from the Graal and Truffle code bases. More information on a specific command is available by running mx help <command>. The most important commands are:

  • build: compile all Java and native code
  • clean: remove all compilation artifacts
  • ideinit: create project files for Eclipse and other common IDEs See the documentation on IDE integration for details.

Building images #

After running mx build you can use mx native-image to build native images. You can specify the main entry point, i.e., the application you want to create the image for. For more information run mx native-image --help.

A native image generation is performed by a Java program, a Native Image builder, that runs on a JVMCI-enabled JDK. You can debug it with a regular Java debugger. Use mx native-image --debug-attach to start native image generation so that it waits for a Java debugger to attach first (by default, at port 8000). In Eclipse, use the debugging configuration substratevm-localhost-8000 to attach to it. This debugging configuration is automatically generated by mx ideinit.

If you have to debug the compiler graphs that are built as part of an image, proceed to the debugging page. You can use the Ideal Graph Visualizer (IGV) tool to view individual compilation steps:

mx igv &>/dev/null &
mx native-image HelloWorld -H:Dump= -H:MethodFilter=HelloWorld.*

Options #

More information about options and the important distinction between hosted and runtime options is available here.

Project Structure #

The list of projects is defined in a custom format in the file mx.substratevm/ It is never necessary to create new projects in the IDE. Instead, a new project is created by adding it in and running mx ideinit to generate a corresponding IDE project.

Code Formatting #

Style rules and procedures for checking adherence are described in the style guide.

Troubleshooting Eclipse #

Sometimes, Eclipse gives strange error messages, especially after pulling a bigger changeset. Also, projects are frequently added or removed, leading to error messages about missing projects if you do not import new projects. The following should reset everything:

  • Delete all projects in Eclipse
  • mx clean
  • mx ideclean
  • mx fsckprojects
  • mx build
  • mx ideinit
  • Import all projects into Eclipse again

License #

The Substrate VM project is licensed under the GPL 2 with Classpath Exception.