Spring

Spring Native provides experimental support of building native images for Spring projects.

This page is based on Spring Native 0.12.0.

warning

Spring Native is still an experimental project. Use with caution.

Getting Started

When creating a new Spring Boot project, the easiest way to enable Spring Native is using Spring initializr. When adding dependencies, make sure Spring Native is selected.

Enable Spring Native

For an existing project, you need to add Spring Native configurations manually. This can be done by comparing a newly created Spring Native project with your existing project. You may only need to update Maven or Gradle build configurations to get it working.

A simple Maven project is used as an example. Full source of this project can be found at GitHub.

Spring Native provides two approaches to build native images, using Buildpacks or Native Build Tools. The difference is that Buildpacks requires Docker to build container images, but Native Build Tools requires local GraalVM to build native executables.

Buildpacks

When using Buildpacks, the following command can be used to build a container image.

./mvnw spring-boot:build-image

The native image buildpack is used to build a container image with native images. The actual builder used is paketobuildpacks/builder:tiny. The BP_NATIVE_IMAGE environment variable enables this buildpack. Extra options can be passed to native-image using the BP_NATIVE_IMAGE_BUILD_ARGUMENTS environment variable.

Spring Boot Maven plugin
<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <classifier>${repackage.classifier}</classifier>
    <image>
      <builder>paketobuildpacks/builder:tiny</builder>
      <env>
        <BP_NATIVE_IMAGE>true</BP_NATIVE_IMAGE>
      </env>
    </image>
  </configuration>
</plugin>

The build result is a container image with the native image of the current Spring project.

Run the container image

docker run --rm -p 8080:8080 grpc:1.0.0-SNAPSHOT

Native Build Tools

When using Native Build Tools, the following command can be used to build a native image.

./mvnw -Pnative package

Maven or Gradle plugin provided by GraalVM is used to invoke native-image tool to build a native image. For Maven projects, the native profile contains the configurations of Native Build Tools Maven plugin.

Profile native
<profile>
  <id>native</id>
  <properties>
    <repackage.classifier>exec</repackage.classifier>
    <native-buildtools.version>0.9.9</native-buildtools.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.platform</groupId>
      <artifactId>junit-platform-launcher</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.graalvm.buildtools</groupId>
        <artifactId>native-maven-plugin</artifactId>
        <version>${native-buildtools.version}</version>
        <extensions>true</extensions>
        <executions>
          <execution>
            <id>test-native</id>
            <phase>test</phase>
            <goals>
              <goal>test</goal>
            </goals>
          </execution>
          <execution>
            <id>build-native</id>
            <phase>package</phase>
            <goals>
              <goal>build</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

The build result is a native executable in the target directory.

Native Hints

If an application requires specific configurations related to native image generation, it can add hints for Spring Native to update the configurations used by native image builder.

The easiest way to provide native hints is using annotations defined in the org.springframework.nativex.hint package. These annotations are usually added to the Spring Boot application class.

The @NativeHint annotation provides hints. The table below lists attributed related to Native Image configurations. These attributes are used to generate build configurations for native-image. Values of these attributes are other annotation types to provide configuration details.

Attribute	Type	Description
`options`	`String[]`	Options passed to `native-image`
`types`	`TypeHint[]`	Types that should be accessible
`resources`	`ResourceHint[]`	Resources to be included
`initialization`	`InitializationHint[]`	Class initialization configurations
`jdkProxies`	`JdkProxyHint[]`	JDK dynamic proxies
`serializables`	`SerializationHint[]`	Serialization configurations
`aotProxies`	`AotProxyHint[]`	Class based proxies that should be created at image build time

Options

Options are passed to the native-image command. These options will be added to the native-image.properties file.

Options
@NativeHint(
        options = {
                "-H:+ReportExceptionStackTraces"
        }
)