Compiling a Java program to native code using GraalVM, from the ground up

GraalVM is a relatively-recent compiler and runtime package that has the capability to support multiple programming languages. It is open-source, but largely maintained and supported commercially by Oracle. An interesting feature, albeit one that is still subject to ongoing development, is its ability to produce true native-code executables that are reasonably self-contained. At the time of writing, the native-code generation feature is not available for all platforms.

This article describes step-by-step how to install GraalVM for Linux, add the 'Native Image' plug-in, and use it to compile some trivial Java programs. We shall see that even very simple programs can present some problems for the technology.

The GraalVM maintainers describe compiling to native code "ahead of time compilation". In my day, we just called that "compilation", and what a JVM did was called "interpretation". Oh, well.

In principle, compiled Java is what we've all been waiting for, at least in the micro-services world. It's difficult to think of anything that runs under a JVM as a micro-anything -- not without a hollow laugh, anyway. GraalVM's compiled Java offers the possibility -- in principle -- of millisecond program load times, and a memory footprint more credible in an environment where there might be hundreds of concurrent micro-services in the same physical host. Because Java is a VM-based language, it's impossible to eliminate the VM completely, but the 'SubstrateVM' runtime used by Native Image is claimed to be relatively lightweight. The picture isn't all as rosy as that, as we shall see.

As with all my software development articles, all steps are carried out on the command line, using no development tools more complicated than a text editor, so all the individual steps are (I hope) clear.

Obtain GraalVM

GraalVM exists in a 'community edition' (CE) and a commercially-supported 'enterprise edition'. Both can be obtained from the GraalVM download page. The community edition is all that is required to follow the examples in this article.

GraalVM CE is installed on Linux by the simple expedient of unpacking the download bundle into any convenient directory. In the examples that follow, I will be using an installation in /home/kevin/lib/graalvm. Of course, you can install GraalVM is a system-wide location if you prefer and if you have access rights.

Install the Native Image plug-in

With the community edition, this should be very straightforward:

$ /path/to/graalvm/gu install native-image

The installation provides the utility

/path/to/graalvm/bin/native-image

Hello, World

Let's start with the simplest possible Java program, to check that everything is installed and set up properly. In any convenient directory, create the file HelloWorld.java, like this:

public class HelloWorld
  {
  public static void main (String[] args)
    {
    System.out.println ("Hello, World");
    }
  }

GraalVM provides a javac compiler, but native-image works on compiled byte-code, not source code. Therefore there's no particular reason to use GraalVM's own javac. Whichever javac you prefer to use, compile the Java (running javac this way will produce a compiled .class file in the same directory as the source, as there is no package definition).

$ javac HelloWorld.java

Now feed the compiled class file into native-image:

$ JAVA_HOME=/path/to/graalvm /path/to/graalvm/bin/native-image \
   -classpath . HelloWorld

native-image can handle collections of class files, and also JAR files. In the latter case, it's still necessary to specify the class that provides the main() method -- the utility won't read it from a JAR manifest, even if there is one.

It's at this point that you might get your first disagreeable surprise: compiling Hello World to a binary will take about a minute. In a sense, that's not surprising -- Java is not a language designed to work this way, and the native-image utility has a great deal of work to do. Still, debugging a program when each change takes a minute to test soon gets old. It's not so bad if running native-image is just the last step in a process where most of the earlier steps are performed by a conventional compiler -- but we aren't quite at that stage yet.

Be that as it may, the native-image should have produced an executable called "helloworld" -- in this case, the binary name is derived from the main class name -- which you can run at the prompt:

$ ./helloworld
Hello, World

Note that the binary is about 2.2Mb in sized in the default, unstripped format. Stripping symbols from it doesn't make it much smaller. It's large compared to a C program that does the same thing, but it's an awful lot smaller than a full-sized JVM and all its runtime dependencies.

This is interesting, also:

$ time java HelloWorld
real	0m0.054s
user	0m0.045s
sys	0m0.017s

$ time ./helloworld 
real	0m0.004s
user	0m0.002s
sys	0m0.005s

These timing figures are pretty consistent and, although I don't think the time utility really provides millisecond precision, it's clear that the native code version starts and finishes in about a tenth the time the traditional JVM needs -- and since the program itself takes little to no time to execute, I think that's a fair estimate of the difference in overheads.

So far, so good.

An HTTP(S) request

We've seen that it's easy enough to compile to native code the Hello World example; time to look at something a bit more complicated. The following code snippet is a program that takes a specified URL, an fetches the content to standard out.

import java.net.*;
import java.io.*;

public class GetUrl 
  {
  public static void main (String[] args)
    {
    if (args.length != 1)
      {
      System.err.println ("Usage: java GetUrl {URL}");
      System.exit (0);
      }
    try
      {
      URL url = new URL (args[0]);
      URLConnection c = url.openConnection();
      InputStream is = c.getInputStream();
      int chr;
      while ((chr = is.read()) > 0)
        {
        System.out.write (chr);
        }
      }
    catch (Throwable e)
      {
      e.printStackTrace();
      }
    }
  }

This program will compile just fine, using the method described for Hello World earlier. But it won't actually run, either with HTTP or HTTPS URLs. Instead, you'll see an error message like this:

Exception in thread "main" com.oracle.svm.core.jdk.UnsupportedFeatureError:
Accessing an URL protocol that was not enabled. The URL protocol http is
supported but not enabled by default. It must be enabled by adding the
-H:EnableURLProtocols=http option to the native-image command.

To be fair, it is at least clear what needs to be done -- for this specific feature, anyway. We need to compile like this:

JAVA_HOME=... /native-image -H:EnableURLProtocols=https \
   -H:EnableURLProtocols=http -classpath . GetUrl

The problem is that I have not been able to find a complete list of features that need to be enabled this way, and I'm not sure whether such a list even exists. Since problems like this do not become apparent until runtime, and they can't be spotted by testing with an ordinary JVM, that significantly increases the testing burden.

Anyway, having fixed this problem it's on to the next one. Although GetUrl now works with HTTP URLs, it fails with HTTPS, like this:

WARNING: The sunec native library, required by the SunEC provider, could not be
loaded. This library is usually shipped as part of the JDK and can be found
under <JAVA_HOME>/jre/lib//libsunec.so. It is loaded at run time via
System.loadLibrary("sunec"), the first time services from SunEC are accessed. 

Again, it's clear what needs to be done, but it's less clear why. libsunec.so is provided with GraalVM, so why is it not just linked with the compiled executable? For testing purposes, we can just copy the library from the GraalVM installation to the current directory, but the application is no longer self-contained. It's also not entirely clear to me whether I can legally distribute this library with my application, or whether I would have to give instructions to end users on how to obtain a copy themselves. Handling SSL is hardly a niche activity in a Java application, and it's surprising that doing so requires these additional steps. I've also heard that the list of SSL certificates that gets built into the executable is truncated, and that it might be necessary to supply a full list; but I've not noticed this problem myself.

Reflection

This is the last example in this article and, in many ways, the most troublesome. Consider this code sample, which converts a number to a String in an extremely convoluted way. I'm not suggesting this is a practical method of coding -- just a way to illustrate a problem.

import java.lang.reflect.*;

public class Reflection 
  {
  public static void main (String[] args)
      throws Exception
    {
    Class c = Class.forName ("java.lang.String");
    Object o = c.newInstance();
    Method m = c.getMethod ("valueOf", int.class);
    Object result = m.invoke (o, 42);
    System.out.println ("result=" + result);
    }
  }

What this rather tortuous code does is to load the String class by name, instantiate it, locate its valueOf method, then call that method on the instance. I've gone to some trouble here never to refer to the String class directly at any point. While this is a pointless exercise here, reflection of this sort is absolutely ubiquitous in Java programming -- many would consider it one of the most power features of the language. With reflection we can, for example, delay decisions about which specific classes to use for particular functions until runtime. Of course, compiling to a native executable is all about making compilation decisions in advance -- it is inimical to reflection.

Consequently, if we compile this class in the same way we compiled HelloWorld earlier, we will run into a problem at runtime, if the program even compiles:

Exception in thread "main" java.lang.InstantiationException: Type
`java.lang.String` can not be instantiated reflectively as it does not have a
no-parameter constructor or the no-parameter constructor has not been added
explicitly to the native image.

What's happened here is that, as the class String was loaded by name only, and never used directly in the program, no code was compiled for it. The native compiler is smart enough to recognize the problem in this case, because it has built-in logic for handling Class.forName(); so we get a somewhat helpful message, rather than a core dump. Still, the onus is on the developer to configure the build to add classes that are only loaded reflectively. There is some information on doing this on a GitHub page.

Essentially, we must create a JSON file that lists the various classes and methods that must be included, and pass it to the native-image command line using -H:ReflectionConfigurationFiles=.... In the present case, it's reasonably clear what needs to be added -- a constructor for the String class. A suitable file is this:

[
  {
    "name" : "java.lang.String",
    "methods" : [
      {
        "name" : "<init>", "parameterTypes" : []
      }
    ]
  }
]

Despite the documentation, it's not always clear how to figure out how to specify the reflection properties, and I find that I need a certain amount of trial-and-error. In fact, some popular libraries, like Log4J2, use reflection so extensively that it's difficut -- perhaps impossible -- to get reflection to work correctly with native-image.

Notes

Command line parameters. The binary produced by native-image will tacitly process a number of traditional JVM parameters. In particular, it will set system properties if the command line has -Dname=value, and you can adjust the heap size using the familiar -Xmx... switch. You don't need to take account of these switches in your code if you don't want to -- they are silently removed from the command line, leaving all the unrecognized parameters in the args[] argument to main. What this means is that the compiled program will take whatever command-line arguments the application handles (if any), in addition to some of the common java command-line switches.

Thread/heap dumps. There's no obvious way to get a traditional Java thread or heap dump from a compiled program. You can get native thread and heap using pstack and gcore, but relating these to Java code is not at all straightforward. For serviceability, an application probably needs to generate a lot more of its own diagnostics than would be the case than when running under a traditional JVM.

Although I haven't demonstrated it in this article, one of the potential strengths of native compilation is that it can run static initializers at compile time, and store just the results in the image. This could be very effective for applications that do a lot of one-time initialization, but there are side-effects that developers need to be careful about.

Summary

Using native-image is straightforward, and clearly effective, with some kinds of Java program. At present, configuration can be a bit hit-and-miss, although this might improve in time. The biggest problem seems to be the widespread use of reflection in Java. It's easy enough to accomodate this when you're compiling your own code, but it's a much bigger problem if it's a library, with unfamiliar internal operation.