The Graal team changed their versioning scheme. It used to be based on the year and quarter, but it now simply matches the JDK version.

We used to have, for example a v22.3.2 release for each supported JDK. We now have, for example GraalVM v17.0.8 and GraalVM v20.0.2.

This version change does make it awkward to refer to past versions of GraalVM. For the old version scheme we’ll prefix the version with legacy like so GraalVM legacy v22.

We now have 2 free flavours of GraalVM:

• GraalVM Community Edition

• Oracle GraalVM

Oracle GraalVM is has more features but has a different license. Choose the flavour that makes sense for your project.

Tips should be generic to both flavours, but we’ll refer to Oracle GraalVM if/when appropriate.

Make sure you put (set! *warn-on-reflection* true) at the top of every namespace in your project. This tells the Clojure compiler to report cases where Clojure is using reflection.

If we recompile our Clojure source, we’ll see a warning:

Let’s add a ^String type hint to avoid usage of Clojure reflection:

If we recompile our updated source:

We no longer see our reflection warning and our native image now works just fine:

Enable or disable the warn-on-reflection depending on the alias, the following methods are available for each tool.

• leiningen: Use :global-vars in project.clj

• tools.deps: Use alter-var-root in user.clj

dev/user.clj

deps.edn

When you cannot add type hints, you can specify a GraalVM config for classes that are reflected at runtime.

If we go back to our original src/refl/main.clj that is absent of any type hints:

And we create GraalVM reflect-config.json with:

Then recompile specifying our reflection config:

We have success:

See the GraalVM docs on reflection for details on the reflection config format.

To configure reflection config for an array of Java objects, you need to specify [Lfully.qualified.class. For example a Statement[] would be specified as "[Ljava.sql.Statement".

You can discover this name by calling (.getClass instance) in a REPL. A contrived example:

To automatically discover reflection, you can use the tracing agent.

To prevent false positives in the generated config, you can use a caller based filter. An example filter.json:

To invoke the agent, you run your program wth the GraalVM JVM and add the -agentlib:native-image-agent argument.

Let’s recompile our original reflection example app and then run it from GraalVM JVM with the tracing agent:

This will output reflect-config.json:

The entry for java.lang.reflect.Method is expected, see clojure.lang.Reflector.

You then feed this generated reflection config to native-image just like you would for a hand-coded one.

If you are suffering NoSuchMethodError: java.lang.reflect.AccessibleObject.canAccess exceptions, GraalVM needs a little help. Include the following to your reflect-config.json file:

See also: Automatically Discovering Reflection Config

Use GraalVM’s native-image -H:+PrintAnalysisCallTree to to learn what packages, classes and methods are being analyzed. These details are written under ./reports.

Note that this option will greatly slow down compilation so it’s better to turn it off in production builds.

To visualize what is in your native image, you can use -H:+DashboardAll and upload the .bgv file to the GraalVM Dashboard, here’s an example screenshot:

GraalVM’s native-image can sometimes consume more RAM than is available on free tiers of services such as CircleCI. To limit how much RAM native-image uses set max heap usage via the "-J-Xmx" option (for example "-J-Xmx3g" limits the heap to 3 gigabytes).

If you are suffering out of memory errors, experiment on your development computer with higher -J-Xmx values.

Refer to native-image output for Peak RSS for RAM usage.

Actual memory usage is an ideal. Once you have a successful build, you can experiment with lowering -J-Xmx below the ideal. The cost will be longer build times, and when -J-Xmx is too low, out of memory errors.

You can shorten the time it takes to compile a native image, and sometimes dramatically reduce the amount of RAM required, by using direct linking when compiling your Clojure code to JVM bytecode.

This is done by setting the Java system property clojure.compiler.direct-linking to true.

The most convenient place for you to set that system property will vary depending on what tool you’re using to compile your Clojure code:

• If you’re using Leiningen, add :jvm-opts ["-Dclojure.compiler.direct-linking=true"] to the profile you’re using for compilation (the same one that includes :aot :all)

• If you’re using tools.deps via the Clojure CLI tools, add :jvm-opts ["-Dclojure.compiler.direct-linking=true"] to the alias you’re using for compilation

  • You can alternatively specify this property at the command line when invoking clojure: clojure -J-Dclojure.compiler.direct-linking=true -M -e "(compile 'my.ns)"

If you happen to need a DNS lookup in your program, you need to avoid statically linked images (at least on Linux). If you are building a minimal docker image, it is sufficient to add the linked libraries (like libnss*) to the resulting image. But be sure that those libraries have the same version as the ones used in the linking phase.

One way to achieve that is to compile within the docker image then scraping the intermediate files using the FROM scratch directive and COPY the executable and shared libraries linked to it into the target image.

See oracle/graal#571

Using musl for static builds is recommended by the official GraalVM docs. Usage of --static without specifying --libc=musl will use glibc instead. However, while this may look like a fully statically binary, this will still load some libraries (using dlopen) at runtime. This may result in some segmentation fault errors related to glibc version mismatches. See this section in official glibc documentation for more information on why glibc "static" builds are not really static.

With --static --libc=musl, you will have truly static binaries equivalent to Go’s with CGO_ENABLED=0 or Rust compiled with musl. This can be deployed almost anywhere and is also smaller than the glibc equivalent. However, keep in mind that musl builds still have some limitations:

• Only works with Linux AMD64

• You will need to either use a distro that already have musl and zlib statically compiled in the repositories or compile it yourself.

  • See babashka/babashka#828 for an example of using musl-tools from Debian

  • See https://gist.github.com/sify21/2eec007e4b05d448c85192fc279232c6 for an example of compiling musl from source

• There is a known issue with stack sizes in musl being really small by default and main thread not respecting stack size settings. This may cause some stack overflow errors during runtime

  • See oracle/graal#3398 for details about this issue

  • See babashka/babashka#831 for a workaround

If supporting non-glibc distros are not an issue for you, there is also an option of building a mostly static native image that should work in any glibc distro. Those binaries are very similar to Go binaries without CGO_ENABLED=0 and Rust images build with glibc (the default).

static boolean inImageBuildtimeCode()
Returns true if (at the time of the call) code is executing in the context of image building (e.g. in a static initializer of class that will be contained in the image).

static boolean inImageCode()
Returns true if (at the time of the call) code is executing in the context of image building or during image runtime, else false.

static boolean inImageRuntimeCode()
Returns true if (at the time of the call) code is executing at image runtime.

static boolean isExecutable()
Returns true if the image is build as an executable.

static boolean isSharedLibrary()
Returns true if the image is build as a shared library.

There have historically been bugs (example) in the GraalVM implementations of some JNI functions. If you encounter bugs with these API calls, you might try the latest development versions of GraalVM. If bugs persist please https://github.com/oracle/graal/issues [raise them with with the Graal project].

For interfacing with native libraries you can use JNI.

• An example of a native Clojure program calling a Rust library.

• Spire is a real life project that combines GraalVM-compiled Clojure and C in a native binary.

To interface with C code using JNI:

1. Write a java file is defining a class. This class contains public static native methods defining the C functions you would like, their arguments and the return types. An example .java file from Spire.

2. Generate a C .h header file from this java file:

   • Java 11+ bundles this tool into javac. Run javac on your .java source file and specify a directory to store the header file: javac -h destination_dir Library.java

3. Write a .c implementation file with function definitions that match the prototypes created in your generated .h file. You will need to #include your generated .h header file. An example .c file from Spire.

4. Compile the C code into a shared library as follows (we assume JAVA_HOME is setup as per GraalVM installation instructions):

   • On linux:

     cc -I$JAVA_HOME/include -I$JAVA_HOME/include/linux -shared Library.c -o liblibrary.so -fPIC

   • On MacOS:

     cc -I$JAVA_HOME/Contents/Home/include -I$JAVA_HOME/Contents/Home/include/darwin -dynamiclib -undefined suppress -flat_namespace Library.c -o liblibrary.dylib -fPIC

5. Load the generated library at runtime from clojure via (clojure.lang.RT/loadLibrary "library")

6. The JVM will need to be able to find the library on the standard library path. This can be set via LD_LIBRARY_PATH environment variable or via the ld linker config file (/etc/ld.so.conf on linux). Alternately you can set the library path by passing -Djava.library.path="my_lib_dir" to the java command line or by setting it at runtime with (System/setProperty "java.library.path" "my_lib_dir")

7. Functions may be called via standard Java interop in clojure via the interface specified in your Library.java file (from step 1): (Library/method args)

@borkdude noticed slower startup times for babashka on macOS when using GraalVM legacy v20. He elaborated in the @graalvm channel on Clojurians Slack:

The issue only happens with specific usages of certain classes that are somehow related to security, urls and whatnot. So not all projects will hit this issue.

Maybe it’s also related to enabling the SSL stuff. Likely, but I haven’t tested that hypothesis.

The Graal team closed the issue with the following absolutely reasonable rationales:

• I don’t think we can do much on this issue. The problem is the inefficiency of the Apple dynamic linker/loader.

• Yes, startup time is important, but correctness can of course never be compromised. You are correct that a more precise static analysis could detect that, but our current context insensitive analysis it too limited.

Apple may fix this issue in macOS someday, who knows? If you:

• have measured a slowdown in startup time of your native-image produced app after moving to Graal legacy v20

• want to restore startup app to what it was on macOS prior legacy v20 of Graal

• are comfortable with a "caveat emptor" hack from the Graal team

then you may want to try incorporating this Java code with @borkdude’s tweaks into your project.

Here’s how borkdude applied the fix to babashka.

On macOS, GraalVM’s native-image makes use of XCode command line tools. XCode creates native binaries that specify the minimum macOS version required for execution. This minimum version can change with each new release of XCode.

To explicitly tell XCode what minimum version is required for your native binary, you can set the MACOSX_DEPLOYMENT_TARGET environment variable.

Here’s an example @borkdude setting MACOSX_DEPLOYMENT_TARGET on CircleCI when building babashka.

Bonus tip: to check the the minimum macOS version required for a native binary, you can use otool. Example for babashka native binary at the time of this writing: