Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Testing and Native Images

GraalVM Native Image Basics

Compile a Micronaut app to a native executable with GraalVM: what native image does, nativeCompile, Docker builds, startup and memory gains, trade-offs. Runnable stand-ins.

A normal Java application needs a JVM: it loads class files, interprets them and compiles hot paths to machine code while running. That is flexible, but it makes startup take a second or more and keeps memory use high. GraalVM Native Image compiles your application ahead of time into a single standalone executable. It starts in tens of milliseconds and uses a fraction of the memory. That matters for serverless functions, command-line tools and containers that scale up and down all day.

Micronaut was built for this. Because it does its dependency injection and AOP work at compile time (see Ahead-of-Time Compilation), it needs very little reflection, which is the main obstacle for native builds. The native tooling is not available on this site, so the build commands are read-only; the TryIt examples are stand-ins that illustrate how the compiler decides what to include.

Creating a native-ready project

The Micronaut launcher adds the GraalVM feature when you ask for it:

Terminal
mn create-app com.example.notes --features=graalvm --build=gradle --lang=java

This adds the io.micronaut.graalvm Gradle plugin (or the native Maven profile). You need a GraalVM JDK (use SDKMAN: sdk install java 25-graal) and a C toolchain for your platform. Then:

Terminal
./gradlew nativeCompile          # produces build/native/nativeCompile/notes
./build/native/nativeCompile/notes

A build takes from about a minute to several minutes and uses a lot of memory, so do it in CI or in Docker rather than on every code change. For daily work, run on the JVM; build native for release.

To build without installing GraalVM, use the Docker integration:

Terminal
./gradlew dockerBuildNative      # builds an image containing the native executable

and run native tests (your normal tests, executed against the native build) with ./gradlew nativeTest.

JVM or native?

JVM Fast build, dynamic features, great peak speed.
Native Starts in milliseconds, small memory use.

Develop on the JVM, ship native when startup and memory matter.

1 / 2

How native image works

The compiler performs points-to analysis starting from your main method (the entry points). It follows every method call and every class that might be instantiated, and includes only what is reachable. Everything else (unused classes, unused methods, unused library code) is removed. This is called the closed-world assumption: all code that can ever run must be known at build time.

Consequences:

  • Dead code is deleted, so executables are small and contain no JIT compiler.
  • Reflection, dynamic proxies, resource loading and JNI are invisible to the analysis unless you declare them in configuration, because the compiler cannot see which class a string name refers to.
  • Class initialization can happen at build time. Static state computed during the build is stored in the image heap.

Micronaut helps by generating the metadata automatically: bean definitions, introspection data and the reflection configuration for what it knows about. For your own special cases you annotate types (@ReflectiveAccess, @Introspected) or add a reflect-config.json. The next lesson, Native Image Pitfalls, covers these.

Try it: reachability analysis

This stand-in does a graph search from the entry point. Methods that cannot be reached are "removed", which is why a native executable is small, and why a class used only through a string name would be removed by mistake.

Java What the compiler keeps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Try it: startup work at build time or at run time

Native image can run static initializers while building and freeze the result. This stand-in compares doing the expensive setup at startup with doing it once at build time.

Java Build-time initialization

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What you give up

  • Peak throughput: the JVM's JIT can optimize long-running code using runtime profile data and often wins on sustained heavy load. Native can close the gap with profile-guided optimization (PGO).
  • Build time and memory: minutes and several gigabytes.
  • Dynamic features: runtime class loading, agents, many Java debugging tools and some libraries do not work or need extra configuration.
  • Platform-specific binaries: build per operating system and CPU architecture.

For a typical REST service the JVM is perfectly fine. Choose native when you measure that cold start or memory cost matters.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the closed-world assumption?

    Native image analyses reachable code at build time and includes only that.
  2. 2. Why does Micronaut suit native image well?

    Compile-time processing gives the compiler visible code and little reflection to configure.
  3. 3. What is a typical benefit of a native executable?

    Startup and memory improve a lot, while build time grows and the binary is platform-specific.
  4. 4. Which Gradle task creates the native executable?

    nativeCompile runs the GraalVM native-image tool on your application.

Summary

  • GraalVM Native Image compiles Java ahead of time into a standalone executable with fast startup and small memory use.
  • It keeps only reachable code (closed-world assumption), so reflection and dynamic features need declarations.
  • Micronaut's compile-time approach produces most of the metadata for you.
  • Develop on the JVM; build native in CI or Docker for release, and run nativeTest against it.

Next: Native Image Pitfalls