GraalVM Native Image SDK

The GraalVM SDK Native Image API enables customization of native image generation - the ahead-of-time compilation of Java code to standalone executables. It provides comprehensive control over the compilation process, C interoperability, memory management, and runtime behavior customization.

Package Information

• Package Name: org.graalvm.sdk:nativeimage
• Package Type: maven
• Language: Java
• Installation: Add to Maven pom.xml:

<dependency>
  <groupId>org.graalvm.sdk</groupId>
  <artifactId>nativeimage</artifactId>
  <version>24.2.1</version>
</dependency>

Core Imports

import org.graalvm.nativeimage.*;
import org.graalvm.nativeimage.hosted.*;
import org.graalvm.nativeimage.c.*;
import org.graalvm.nativeimage.c.function.*;
import org.graalvm.nativeimage.c.struct.*;
import org.graalvm.nativeimage.c.type.*;

Basic Usage

// Check execution context
if (ImageInfo.inImageBuildtimeCode()) {
    // This code runs during native image generation
    System.out.println("Building native image...");
} else if (ImageInfo.inImageRuntimeCode()) {
    // This code runs in the native executable
    System.out.println("Running in native image");
}

// Platform-specific code
if (Platform.includedIn(Platform.LINUX.class)) {
    // Linux-specific implementation
}

// Memory management
try (PinnedObject pinnedArray = PinnedObject.create(byteArray)) {
    CCharPointer pointer = pinnedArray.addressOfArrayElement(0);
    // Use pointer for native operations
}

// Isolate management
IsolateThread currentThread = CurrentIsolate.getCurrentThread();
Isolate isolate = CurrentIsolate.getIsolate();

Architecture

The GraalVM Native Image SDK is organized into several key architectural components:

Runtime Architecture

• Isolate Model: Multi-isolate support with independent memory spaces and thread management
• Memory Management: Stack allocation, unmanaged memory, and pinned objects for GC-safe native access
• Threading System: Per-isolate thread handling with callback support
• Object Handles: Cross-isolate communication via opaque object references

Build-time Architecture

• Feature System: Comprehensive lifecycle hooks for customizing native image generation
• Registration APIs: Reflection, JNI, serialization, and resource configuration
• Conditional Configuration: Platform and condition-based setup
• Transformation Pipeline: Field value transformation during image building

C Interoperability Architecture

• Type-Safe Interop: Word types for safe pointer arithmetic and memory access
• Annotation-Driven Mapping: Comprehensive annotation system for C structure and function mapping
• Direct Function Calls: Bypass JNI overhead with direct C function invocation
• Memory Model: Interface-based C struct representation with type safety

Platform Abstraction

• Multi-Architecture Support: AMD64, AARCH64, RISCV64
• Multi-OS Support: Linux, Windows, macOS, iOS, Android
• Conditional Compilation: @Platforms annotation for platform-specific code

Capabilities

Runtime Core APIs

Core runtime functionality including isolate management, memory allocation, threading support, and platform abstraction. Essential for native image execution and runtime behavior.

// Context and Information
class ImageInfo {
    static boolean inImageBuildtimeCode();
    static boolean inImageRuntimeCode();
    static boolean inImageCode();
    static boolean isExecutable();
    static boolean isSharedLibrary();
}

// Platform Support
interface Platform {}
@interface Platforms {
    Class<? extends Platform>[] value();
}

// Isolate Management
interface Isolate extends PointerBase {}
interface IsolateThread extends PointerBase {}
class CurrentIsolate {
    static IsolateThread getCurrentThread();
    static Isolate getIsolate();
}

Runtime Core APIs

C Interoperability

Comprehensive C interoperability framework providing type-safe integration between Java and C code. Enables direct function calls, struct mapping, and memory operations without JNI overhead.

// Function Interop
@interface CFunction {
    String value() default "";
}

@interface CEntryPoint {
    String name() default "";
}

// Struct Mapping
@interface CStruct {
    String value() default "";
}

@interface CField {
    String value() default "";
}

// Type System
interface VoidPointer extends PointerBase {}
interface CCharPointer extends PointerBase {}
interface WordPointer extends PointerBase {}

C Interoperability

Build-time Configuration

Build-time APIs for customizing native image generation, including feature registration, reflection configuration, and lifecycle management. Used during the compilation phase to control what gets included in the final executable.

// Feature System
interface Feature {
    boolean isInConfiguration(IsInConfigurationAccess access);
    void beforeAnalysis(BeforeAnalysisAccess access);
    void duringAnalysis(DuringAnalysisAccess access);
    void afterAnalysis(AfterAnalysisAccess access);
    void beforeCompilation(BeforeCompilationAccess access);
    void afterHeapLayout(AfterHeapLayoutAccess access);
}

// Configuration APIs
class RuntimeReflection {
    static void register(Class<?>... classes);
    static void register(Method... methods);
    static void register(Field... fields);
}

class RuntimeJNIAccess {
    static void register(Class<?>... classes);
    static void register(Method... methods);
}

Build-time Configuration

Key Design Patterns

Singleton Registry Pattern

Uses ImageSingletons for compile-time constant lookup and configuration sharing.

Annotation-Driven Configuration

Extensive use of annotations (@CFunction, @CStruct, @Platforms) for declarative configuration.

Interface-Based APIs

Most APIs use interfaces for flexibility and extensibility.

Lifecycle Hook Pattern

Feature system provides comprehensive build-time control through well-defined phases.

Type Safety Through Word Types

Word types and pointer abstractions ensure memory safety while maintaining performance.

This API enables developers to create high-performance native executables from Java applications with full control over compilation, memory management, and platform integration while maintaining Java's type safety and development experience.