Substrate VM

Introduction

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. After cloning the repository, run

cd substratevm
mx build

mkdir svmbuild
echo "public class HelloWorld { public static void main(String[] args) { System.out.println(\"Hello World\"); } }" > svmbuild/HelloWorld.java
$JAVA_HOME/javac svmbuild/HelloWorld.java
mx image -cp $PWD/svmbuild -H:Class=HelloWorld -H:Name=helloworld
svmbuild/helloworld

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 implementation. 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.
• image: Create the native image. You can specify the main entry point, i.e., the application you want to create the image for.
• eclipseinit: Create Eclipse projects. See the Eclipse section here for more details.

The native image generator is a normal Java program that runs on JDK 8 with JVMCI. You can debug it with the normal Java debugger. Execute mx -d image to start the native image generator so that it waits for a Java debugger to connect. In Eclipse, use the debugging configuration "substratevm-localhost-8000" to attach Eclipse to it. The debugging configuration is automatically generated by the eclipseinit command.

If you find yourself having to debug into the Graal level of SubstrateVM, you should read the Graal debugging page.

Images and Entry Points

An SVM image can be built as a standalone executable or as a shared library. The kind of image can be selected by passing either -H:Kind=EXECUTABLE or -H:Kind=SHARED_LIBRARY to mx 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). The first parameter 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;
}

To initialize an isolate or attach a thread from C, the following API is available:

int graal_create_isolate(graal_create_isolate_params_t* params, graal_isolate_t** isolate);
int graal_attach_thread(graal_isolate_t* isolate, graal_isolatethread_t** thread);
graal_isolate_t* graal_current_isolate(graal_isolatethread_t* thread);
graal_isolatethread_t* graal_current_thread(graal_isolate_t* isolate);
int graal_detach_thread(graal_isolatethread_t* thread);
int graal_tear_down_isolate(graal_isolate_t* isolate);

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

Options

More information about options, and the important distinction of hosted vs. runtime options, is available here.

Using the Ideal Graph Visualizer (igv)

Occasionally your image will fail to build because of some issue with Graal. One can watch the transformations Graal makes during compilation with the Ideal Graph Visualizer:

mx igv &
mx image -H:Class=HelloWorld -H:Dump= -H:MethodFilter=HelloWorld.*

There is an old users guide in chapter 4 of Thomas Wuerthinger's master's thesis.

Project Structure

The list of projects is defined in a custom format in the file "mx.substratevm/suite.py". Never create an Eclipse project manually. Instead, modify "suite.py" and run "mx eclipseinit".

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 eclipseinit
• Import all projects into Eclipse again

Eclipse Plugins

The following Eclipse plugins should be installed (the URL gives the update site that you register in Eclipse in the "Help->Install New Software" dialog):

• Checkstyle: reports checkstyle violations in Eclipse, making it unnecessary to run mx.sh checkstyle manually to identify errors. http://eclipse-cs.sf.net/update/

Checkstyle and Code Formatting

The Eclipse projects are configured with quite restrictive error rules and checkstyle rules. When you save a file in Eclipse, it will be automatically formatted according to our code formatting rules. The goal is to have no Warnings (and obviously no Errors) reported by Eclipse.

The preconfigured rules have grown over time and proved to be useful - but when you bring convincing arguments they can be changed. The configuration includes some magic comments which can be used to relax checking in particular regions of code.

Source code formatting can be disabled with magic comments:

//@formatter:off

//@formatter:on

You can also disable comment-reformatting using

/*-
 *
 */

The default checkstyle rules are defined in src/com.oracle.svm.core/.checkstyle_checks.xml and define various magic comments, including

//Checkstyle: stop method name check

//Checkstyle: resume method name check

and analogously for other checks that can be disabled (including a general "stop" and "resume"). Of course, ensuring judicious use of these comments is a matter for code review.

If a project requires its own set of checkstyle rules, this can be specified in the mx/projects file by changing the value of the project's checkstyle attribute (which, by default, references com.oracle.svm.core). If specific files should be excluded from checkstyle, this can be done, but (apparently) only at whole-directory granularity. To do so, add a file

src//.checkstyle.exclude

to the project. The format is one directory name per line, with directories named relative to the project root. Don't forget to 'git add' the file, since it will be ignored by default.

If you pull a changeset which adds or removes checkstyle XML files, you may get inappropriate style warnings/errors in Eclipse until you 'mx eclipseinit' and then Clean the affected projects. (This can be particularly confusing because you'll see Checkstyle behaviour which is inconsistent with the contents of the on-disk checkstyle XML files.)