Switch branches/tags
Find file History
Latest commit 7b1e51b Nov 15, 2018
Failed to load latest commit information.
ci_includes Encapsulate more AMD64 specifics in SVM. Oct 17, 2018
mx.substratevm Add missing -noverify for Java8 image building Nov 10, 2018
src [GR-7356] Add ProfileBooleanNode for MethodHandle profiling and castR… Nov 15, 2018
C-API.md [GR-11909] Remove the support to pass an Isolate to C entry point, re… Nov 2, 2018
DYNAMIC_PROXY.md Support for java.lang.reflect.Proxy. Jun 13, 2018
ImplementingNativeMethodsInJavaWithSVM.md [GR-11909] Remove the support to pass an Isolate to C entry point, re… Nov 2, 2018
JCA-SECURITY-SERVICES.md Update sunec error message and documentation. Oct 5, 2018
JNI.md Allow writing final fields via JNI/reflection only when explictly req… Oct 25, 2018
LICENSE.md Add Substrate VM Dec 13, 2017
LIMITATIONS.md Update LIMITATIONS.md now that we implement `Reference.enqueue()` and… Nov 5, 2018
OPTIONS.md [GR-5221] Remove references to `-R:YoungGenerationSize=` and `-R:OldG… Apr 6, 2018
PROPERTIES.md Add docu for using system properties in substratevm Nov 10, 2018
README.md Remove python image building from svm gate Oct 3, 2018
REFLECTION.md Allow writing final fields via JNI/reflection only when explictly req… Oct 25, 2018
REPORTS.md Enhance analysis call tree and image heap object tree reports. Mar 7, 2018
RESOURCES.md Add example usage info in IncludeResources docu Oct 25, 2018
STYLE.md Minor revisions Feb 23, 2018
URL-PROTOCOLS.md Https URL protocol and security services support. Sep 18, 2018


Substrate VM


Substrate VM is a framework that allows ahead-of-time (AOT) compilation of Java applications under closed-world assumption into executable images or shared objects (ELF-64 or 64-bit Mach-O).

Quick start

Install mx and point JAVA_HOME to a labsjdk.

For compilation native-image depends on the local toolchain, so make sure: glibc-devel, zlib-devel (header files for the C library and zlib) and gcc are available on your system.

After cloning the repository, run

cd substratevm
mx build

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

To build truffle-based images please refer to the documentation in the VM suite.

Build Script

Using Substrate VM requires the mx tool to be installed first, so that it is on your path. Visit the MX Homepage for more details.

Substrate VM requires a JDK 8 with JVMCI. It is available from OTN.

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. The most important commands for the Substrate VM are listed below. More information on the parameters of a command is available by running mx help <command>

  • 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.

Native image generation is performed by a Java program that runs on JDK 8 with JVMCI. 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 find yourself having to debug into the Graal level of SubstrateVM, you should read the Graal debugging page. You can use Ideal Graph Visualizer to view individual compilation steps:

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

Images and Entry Points

An SVM image can be built as a standalone executable, which is the default, or as a shared library by passing --shared to native-image. For an image to be useful, it needs to have at least one entry point method.

For executables, SVM supports Java main methods with a signature that takes the command-line arguments as an array of strings:

public static void main(String[] arg) { /* ... */ }

For shared libraries, SVM provides the @CEntryPoint annotation to specify entry point methods that should be exported and callable from C. Entry point methods must be static and may only have non-object parameters and return types – this includes Java primitives, but also Word types (including pointers). One of the parameters of an entry point method has to be of type IsolateThread or Isolate. This parameter provides the current thread's execution context for the call. For example:

@CEntryPoint static int add(IsolateThread thread, int a, int b) {
    return a + b;

Shared library builds generate an additional C header file. This header file contains declarations for the SVM C API, which allows creating isolates and attaching threads from C code, as well as declarations for each entry point in user code. The generated C declaration for the above example is:

int add(graal_isolatethread_t* thread, int a, int b);

Both executable images and shared library images can have an arbitrary number of entry points, for example to implement callbacks or APIs.


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/suite.py. It is never necessary to create new projects in the IDE. Instead, a new project is created by adding it in suite.py 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 the 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


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