Build Configuration

native-image has a lot of options to configure a native image build process. These build configurations are specific for different libraries and applications. Java applications typically use third-party dependencies. When building native images for Java applications, it's hard for application developers to figure out the correct building configurations for all the external libraries.

The recommended way to provide image build configuration is to embed a native-image.properties file in the JAR file. These configuration files will be picked up by the Native Image builder to construct the options.

The native-image.properties file can be put anywhere below the resource location META-INF/native-image/. It's recommended to use project-specific subdirectories within META-INF/native-image. A common choice is using project's Maven group id and artifact id as the directory. For example, if the module has group id com.example and artifact id myapp, then the path of native-image.properties file can be META-INF/native-image/com.example/myapp/native-image.properties.

info

Spring Native uses this approach to add image build configurations. See Spring.

Libraries are expected to improve their support for native images. For example, Netty already embeds native image configurations in its JAR files.

Configuration File Format

A native-image.properties file is a regular Java properties file. This file may contain the following properties.

Args

This property specifies command line options passed to native-image.

If some options need to reference files, the placeholder ${.} can expand to the resource location that contains this configuration file. For example, if a proxy config resource proxy-config.json is in the config sub-directory of the current directory of native-image.properties file, then this config resource can be referenced as ${.}/config/proxy-config.json.

JavaArgs

This property specifies command line options passed to the JVM that runs the native image builder.

ImageName

This property specifies name of the image.

Configuration Files

Configuration files can also be placed in the same directory as native-image.properties file. These files will be picked up by native-image automatically.

File	Description	JSON Schema	Reference
jni-config.json	JNI	JNI config
predefined-classes-config.json	Predefined classes
proxy-config.json	Dynamic proxy	Proxy config	Proxy
reflect-config.json	Reflection	Reflection config	Reflection
resource-config.json	Resources	Resource config	Resources
serialization-config.json	Serialization	Serialization config