0
# GraalVM Native Image SDK
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.graalvm.sdk:nativeimage
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
  <groupId>org.graalvm.sdk</groupId>
14
  <artifactId>nativeimage</artifactId>
15
  <version>24.2.1</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import org.graalvm.nativeimage.*;
23
import org.graalvm.nativeimage.hosted.*;
24
import org.graalvm.nativeimage.c.*;
25
import org.graalvm.nativeimage.c.function.*;
26
import org.graalvm.nativeimage.c.struct.*;
27
import org.graalvm.nativeimage.c.type.*;
28
```
29

30
## Basic Usage
31

32
```java
33
// Check execution context
34
if (ImageInfo.inImageBuildtimeCode()) {
35
    // This code runs during native image generation
36
    System.out.println("Building native image...");
37
} else if (ImageInfo.inImageRuntimeCode()) {
38
    // This code runs in the native executable
39
    System.out.println("Running in native image");
40
}
41

42
// Platform-specific code
43
if (Platform.includedIn(Platform.LINUX.class)) {
44
    // Linux-specific implementation
45
}
46

47
// Memory management
48
try (PinnedObject pinnedArray = PinnedObject.create(byteArray)) {
49
    CCharPointer pointer = pinnedArray.addressOfArrayElement(0);
50
    // Use pointer for native operations
51
}
52

53
// Isolate management
54
IsolateThread currentThread = CurrentIsolate.getCurrentThread();
55
Isolate isolate = CurrentIsolate.getIsolate();
56
```
57

58
## Architecture
59

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

62
### **Runtime Architecture**
63
- **Isolate Model**: Multi-isolate support with independent memory spaces and thread management
64
- **Memory Management**: Stack allocation, unmanaged memory, and pinned objects for GC-safe native access
65
- **Threading System**: Per-isolate thread handling with callback support
66
- **Object Handles**: Cross-isolate communication via opaque object references
67

68
### **Build-time Architecture**
69
- **Feature System**: Comprehensive lifecycle hooks for customizing native image generation
70
- **Registration APIs**: Reflection, JNI, serialization, and resource configuration
71
- **Conditional Configuration**: Platform and condition-based setup
72
- **Transformation Pipeline**: Field value transformation during image building
73

74
### **C Interoperability Architecture**
75
- **Type-Safe Interop**: Word types for safe pointer arithmetic and memory access
76
- **Annotation-Driven Mapping**: Comprehensive annotation system for C structure and function mapping
77
- **Direct Function Calls**: Bypass JNI overhead with direct C function invocation
78
- **Memory Model**: Interface-based C struct representation with type safety
79

80
### **Platform Abstraction**
81
- **Multi-Architecture Support**: AMD64, AARCH64, RISCV64
82
- **Multi-OS Support**: Linux, Windows, macOS, iOS, Android
83
- **Conditional Compilation**: `@Platforms` annotation for platform-specific code
84

85
## Capabilities
86

87
### Runtime Core APIs
88

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

91
```java { .api }
92
// Context and Information
93
class ImageInfo {
94
    static boolean inImageBuildtimeCode();
95
    static boolean inImageRuntimeCode();
96
    static boolean inImageCode();
97
    static boolean isExecutable();
98
    static boolean isSharedLibrary();
99
}
100

101
// Platform Support
102
interface Platform {}
103
@interface Platforms {
104
    Class<? extends Platform>[] value();
105
}
106

107
// Isolate Management
108
interface Isolate extends PointerBase {}
109
interface IsolateThread extends PointerBase {}
110
class CurrentIsolate {
111
    static IsolateThread getCurrentThread();
112
    static Isolate getIsolate();
113
}
114
```
115

116
[Runtime Core APIs](./runtime-core.md)
117

118
### C Interoperability
119

120
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.
121

122
```java { .api }
123
// Function Interop
124
@interface CFunction {
125
    String value() default "";
126
}
127

128
@interface CEntryPoint {
129
    String name() default "";
130
}
131

132
// Struct Mapping
133
@interface CStruct {
134
    String value() default "";
135
}
136

137
@interface CField {
138
    String value() default "";
139
}
140

141
// Type System
142
interface VoidPointer extends PointerBase {}
143
interface CCharPointer extends PointerBase {}
144
interface WordPointer extends PointerBase {}
145
```
146

147
[C Interoperability](./c-interop.md)
148

149
### Build-time Configuration
150

151
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.
152

153
```java { .api }
154
// Feature System
155
interface Feature {
156
    boolean isInConfiguration(IsInConfigurationAccess access);
157
    void beforeAnalysis(BeforeAnalysisAccess access);
158
    void duringAnalysis(DuringAnalysisAccess access);
159
    void afterAnalysis(AfterAnalysisAccess access);
160
    void beforeCompilation(BeforeCompilationAccess access);
161
    void afterHeapLayout(AfterHeapLayoutAccess access);
162
}
163

164
// Configuration APIs
165
class RuntimeReflection {
166
    static void register(Class<?>... classes);
167
    static void register(Method... methods);
168
    static void register(Field... fields);
169
}
170

171
class RuntimeJNIAccess {
172
    static void register(Class<?>... classes);
173
    static void register(Method... methods);
174
}
175
```
176

177
[Build-time Configuration](./build-time.md)
178

179
## Key Design Patterns
180

181
### **Singleton Registry Pattern**
182
Uses `ImageSingletons` for compile-time constant lookup and configuration sharing.
183

184
### **Annotation-Driven Configuration**
185
Extensive use of annotations (`@CFunction`, `@CStruct`, `@Platforms`) for declarative configuration.
186

187
### **Interface-Based APIs**
188
Most APIs use interfaces for flexibility and extensibility.
189

190
### **Lifecycle Hook Pattern**
191
Feature system provides comprehensive build-time control through well-defined phases.
192

193
### **Type Safety Through Word Types**
194
Word types and pointer abstractions ensure memory safety while maintaining performance.
195

196
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.