Add native image reference documentation

Update reference documentation with a new "native image" section.

This commit includes some work derived from the "Spring Native"
project documentation written by Andy Clement, Sébastien Deleuze,
Filip Hanik, Dave Syer, Esteban Ginez, Jay Bryant, Brian Clozel,
Stéphane Nicoll, and Josh Long.

Closes gh-32582

Co-authored-by: Moritz Halbritter <[email protected]>

Author: philwebb

spring-boot-project/spring-boot-docs/build.gradle

@@ -317,6 +317,7 @@ tasks.withType(org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask) {
 					"spring-integration-version": versionConstraints["org.springframework.integration:spring-integration-core"],
 					"spring-kafka-version": versionConstraints["org.springframework.kafka:spring-kafka"],
 					"spring-security-version": securityVersion,
+					"native-build-tools-version": nativeBuildToolsVersion,
 					"spring-webservices-version": versionConstraints["org.springframework.ws:spring-ws-core"],
 					"remote-spring-application-output": runRemoteSpringApplicationExample.outputs.files.singleFile,
 					"spring-application-output": runSpringApplicationExample.outputs.files.singleFile,

spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc

@@ -110,3 +110,6 @@
 :micrometer-concepts-docs: {micrometer-docs}/concepts
 :micrometer-registry-docs: {micrometer-docs}/registry
 :tomcat-docs: https://tomcat.apache.org/tomcat-9.0-doc
+:graal-version: 22.2
+:graal-native-image-docs: https://www.graalvm.org/{graal-version}/reference-manual/native-image
+:liberica-nik-download: https://bell-sw.com/pages/downloads/native-image-kit/

spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment/whats-next.adoc

@@ -4,4 +4,4 @@ See the https://www.cloudfoundry.org/[Cloud Foundry], https://www.heroku.com/[He
 These are just four of the most popular Java PaaS providers.
 Since Spring Boot is so amenable to cloud-based deployment, you can freely consider other providers as well.
 
-The next section goes on to cover the _<<cli#cli, Spring Boot CLI>>_, or you can jump ahead to read about _<<build-tool-plugins#build-tool-plugins, build tool plugins>>_.
+The next section goes on to cover the _<<native-image#native-image, GraalVM Native Images>>_, or you can jump ahead to read about the _<<cli#cli, Spring Boot CLI>>_ or our _<<build-tool-plugins#build-tool-plugins, build tool plugins>>_.

spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc

@@ -32,4 +32,6 @@ include::documentation/io.adoc[]
 
 include::documentation/container-images.adoc[]
 
+include::documentation/native-images.adoc[]
+
 include::documentation/advanced.adoc[]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/native-images.adoc

@@ -0,0 +1,9 @@
+[[documentation.native-images]]
+== GraalVM Native Images
+Spring Boot applications can be converted into native executables using GraalVM.
+You can read more about our native image support here:
+
+* *GraalVM Native Images:* <<native-image#native-image.introducing-graalvm-native-images, Introduction>> | <<native-image#native-image.introducing-graalvm-native-images.key-differences-with-jvm-deployments, Key Differences with the JVM>> | <<native-image#native-image.introducing-graalvm-native-images.understanding-aot-processing, Ahead-of-Time Processing>>
+* *Getting Started:* <<native-image#native-image.developing-your-first-application.buildpacks, Buildpacks>> | <<native-image#native-image.developing-your-first-application.native-build-tools, Native Build Tools>>
+* *Testing:* <<native-image#native-image.testing.with-the-jvm, JVM>> | <<native-image#native-image.testing.with-native-build-tools, Native Build Tools>>
+* *Advanced Topics:* <<native-image#native-image.advanced.nested-configuration-properties, Nested Configuration Properties>> | <<native-image#native-image.advanced.converting-executable-jars, Converting JARs>> | <<native-image#native-image.advanced.known-limitations, Known Limitations>>

spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started/system-requirements.adoc

@@ -35,3 +35,24 @@ Spring Boot supports the following embedded servlet containers:
 |===
 
 You can also deploy Spring Boot applications to any servlet 5.0+ compatible container.
+
+
+
+[[getting-started.system-requirements.graal]]
+=== GraalVM Native Images
+Spring Boot applications can be <<native-image#native-image.introducing-graalvm-native-images,converted into a Native Image>> using using Graal {graal-version} or above.
+
+Images can be created using the https://github.com/graalvm/native-build-tools[native build tools] Gradle/Maven plugins or `native-image` tool provided by GraalVM.
+You can also create native images using the the https://github.com/paketo-buildpacks/native-image[native-image Paketo buildpack].
+
+The following versions are supported:
+
+|===
+| Name | Version
+
+| GraalVM Community
+| {graal-version}
+
+| Native Build Tools
+| {native-build-tools-version}
+|===

spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc

@@ -23,6 +23,7 @@ The reference documentation consists of the following sections:
 <<container-images#container-images,Container Images>> :: Efficient container images and Building container images with Dockerfiles and Cloud Native Buildpacks.
 <<actuator#actuator,Production-ready Features>> :: Monitoring, Metrics, Auditing, and more.
 <<deployment#deployment,Deploying Spring Boot Applications>> :: Deploying to the Cloud, and Installing as a Unix application.
+<<native-image#native-image,Graal Native Image Support>> :: Create a native executable from your application using GraalVM
 <<cli#cli,Spring Boot CLI>> :: Installing the CLI, Using the CLI, Configuring the CLI, and more.
 <<build-tool-plugins#build-tool-plugins,Build Tool Plugins>> :: Maven Plugin, Gradle Plugin, Antlib, and more.
 <<howto#howto,"`How-to`" Guides>> :: Application Development, Configuration, Embedded Servers, Data Access, and many more.

spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc

@@ -39,6 +39,8 @@ include::actuator.adoc[leveloffset=+1]
 
 include::deployment.adoc[leveloffset=+1]
 
+include::native-image.adoc[leveloffset=+1]
+
 include::cli.adoc[leveloffset=+1]
 
 include::build-tool-plugins.adoc[leveloffset=+1]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/native-image.adoc

@@ -0,0 +1,16 @@
+[[native-image]]
+= GraalVM Native Image Support
+include::attributes.adoc[]
+
+https://www.graalvm.org/native-image/[GraalVM Native Images] are standalone executables that can be generated by processing compiled Java applications ahead-of-time.
+Native Images generally have a smaller memory footprint and start faster than their JVM counterparts.
+
+include::native-image/introducing-graalvm-native-images.adoc[]
+
+include::native-image/developing-your-first-application.adoc[]
+
+include::native-image/testing-native-applications.adoc[]
+
+include::native-image/advanced-topics.adoc[]
+
+include::native-image/whats-next.adoc[]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/native-image/advanced-topics.adoc

@@ -0,0 +1,166 @@
+[[native-image.advanced]]
+== Advanced Native Images Topics
+
+
+
+[[native-image.advanced.nested-configuration-properties]]
+=== Nested Configuration Properties
+Reflection hints are automatically created for configuration properties by Spring's ahead-of-time engine.
+Nested configuration properties, however, *must* be annotated with `@NestedConfigurationProperty`, otherwise they won't be detected and will not be bindable.
+
+include::code:MyProperties[]
+
+The example above produces configuration properties for `my.properties.name` and `my.properties.nested.number`.
+Without the `@NestedConfigurationProperty` annotation on the `nested` field, the `my.properties.nested.number` property would not be bindable in a native image.
+
+NOTE: Please use public getters / setters, otherwise the properties won't be bindable.
+
+
+
+[[native-image.advanced.converting-executable-jars]]
+=== Converting a Spring Boot Executable JAR
+It is possible to convert a Spring Boot <<executable-jar#appendix.executable-jar, executable JAR>> into a native image as long at the jar contains the AOT generated assets.
+This can be useful for a number of reasons, including:
+
+* You can keeping your regular JVM pipeline and turn the JVM application into a native image on your CI/CD platform.
+* As `native-image` https://github.com/oracle/graal/issues/407[does not support cross-compilation], you can keep an OS neutral deployment artifact which you convert later to different OS architectures.
+
+You can convert a Spring Boot executable jar into a native image using buildpacks, or the `native-image` tool that is shipped with GraalVM.
+
+NOTE: Your executable JAR must include AOT generated assets such as generated classes and JSON hint files.
+
+
+
+[[native-image.advanced.converting-executable-jars.buildpacks]]
+==== Using Buildpacks
+Spring Boot applications usually use Buildpacks via the Maven (`mvn spring-boot:build-image`), or Gradle (`gradle bootBuildImage`) integrations.
+You can, however, also use https://buildpacks.io//docs/tools/pack/[`pack`] to turn an AOT processed Spring Boot executable JAR into a native container image.
+
+
+First, make sure that a Docker daemon is available (see https://docs.docker.com/installation/#installation[Get Docker] for more details).
+https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user[Configure it to allow non-root user] if you are on Linux.
+
+You also need to install `pack` by following https://buildpacks.io//docs/tools/pack/#install[the installation guide on buildpacks.io].
+
+Assuming an AOT processed Spring Boot executable JAR built as `myproject-0.0.1-SNAPSHOT.jar` is in the `target` directory, run:
+
+[source,shell,indent=0,subs="verbatim"]
+----
+	$ pack build --builder paketobuildpacks/builder:tiny \
+	    --path target/myproject-0.0.1-SNAPSHOT.jar \
+	    --env 'BP_NATIVE_IMAGE=true' \
+	    my-application:0.0.1-SNAPSHOT
+----
+
+NOTE: You do not need to have a local GraalVM installation to generate an image in this way.
+
+Once `pack` has finished, you can launch the application using `docker run`:
+
+[source,shell,indent=0,subs="verbatim"]
+----
+	$ docker run --rm -p 8080:8080 docker.io/library/myproject:0.0.1-SNAPSHOT
+----
+
+
+
+[[native-image.advanced.converting-executable-jars.native-image]]
+==== Using GraalVM native-image
+Another option to turn an AOT processed Spring Boot executable JAR into a native executable is to use the GraalVM `native-image` tool.
+For this to work, you'll need a GraalVM distribution on your machine.
+You can either download it manually on the {liberica-nik-download}[Liberica Native Image Kit page] or you can use a download manager like SDKMAN!.
+
+Assuming an AOT processed Spring Boot executable JAR built as `myproject-0.0.1-SNAPSHOT.jar` is in the `target` directory, run:
+
+[source,shell,indent=0,subs="verbatim"]
+----
+	$ rm -rf target/native
+	$ mkdir -p target/native
+	$ cd target/native
+	$ jar -xvf ../myproject-0.0.1-SNAPSHOT.jar
+	$ native-image -H:Name=myproject @META-INF/native-image/argfile -cp .:BOOT-INF/classes:`find BOOT-INF/lib | tr '\n' ':'`
+	$ mv myproject ../
+----
+
+NOTE: These commands work on Linux or MacOS machines, you will need to adapt them for Windows.
+
+TIP: The `@META-INF/native-image/argfile` might not be packaged in your jar.
+It is only included when reachability metadata overrides are needed.
+
+WARNING: The `native-image` `-cp` flag does not not accept wildcards.
+You need to ensure that all jars are listed (the command above uses `find` and `tr` to do this).
+
+
+
+[[native-image.advanced.using-the-tracing-agent]]
+=== Using the Tracing Agent
+The GraalVM native image https://www.graalvm.org/reference-manual/native-image/Agent/[tracing agent] allows you to intercept reflection, resources or proxy usage on the JVM in order to generate the related hints.
+Spring should generate most of these hints automatically, but the tracing agent can be used to quickly identify the missing entries.
+
+When using the agent to generate hints for a native image, there are a couple of approaches:
+
+* Launch the application directly and exercise it.
+* Run application tests to exercise the application.
+
+The first option is interesting for identifying the missing hints when a library or a pattern is not recognized by Spring.
+
+The second option sounds more appealing for a repeatable setup, but by default the generated hints will include anything required by the test infrastructure.
+Some of these will be unnecessary when the application runs for real.
+To address this problem the agent supports an access-filter file that will cause certain data to be excluded from the generated output.
+
+
+
+[[native-image.advanced.using-the-tracing-agent.launch]]
+==== Launch the Application Directly
+Use the following command to launch the application with the native image tracing agent attached:
+
+[source,shell,indent=0,subs="verbatim,attributes"]
+----
+	$ java -Dspring.aot.enabled=true \
+	    -agentlib:native-image-agent=config-output-dir=/path/to/config-dir/ \
+	    -jar target/myproject-0.0.1-SNAPSHOT.jar
+----
+
+Now you can exercise the code paths you want to have hints for and then stop the application with `ctrl-c`.
+
+On application shutdown the native image tracing agent will write the hint files to the given config output directory.
+You can either manually inspect these files, or use them as input to the native image build process.
+To use them as input, copy them into the `src/main/resources/META-INF/native-image/` directory.
+The next time you build the native image, GraalVM will take these files into consideration.
+
+There are more advanced options which can be set on the native image tracing agent, for example filtering the recorded hints by caller classes, etc.
+For further reading, please see https://www.graalvm.org/reference-manual/native-image/Agent/[the official documentation].
+
+
+
+[[native-image.advanced.custom-hints]]
+=== Custom Hints
+If you need to provide your own hints for reflection, resources, serialization, proxy usage etc. you can use the `RuntimeHintsRegistrar` API.
+Create a class that implements the `RuntimeHintsRegistrar` interface, then make appropriate calls to the provided `RuntimeHints` instance:
+
+include::code:MyRuntimeHints[]
+
+You can then use `@ImportRuntimeHints` on any `@Configuration` class (for example your `@SpringBootApplication` annotated application class) to activate those hints.
+
+
+
+[[native-image.advanced.custom-hints.testing]]
+==== Testing custom hints
+The `RuntimeHintsPredicates` API can be used to test your hints.
+The API provides methods that build a `Predicate` that can be used to test a `RuntimeHints` instance.
+
+If you're using AssertJ, your test would look like this:
+
+include::code:MyRuntimeHintsTests[]
+
+
+
+[[native-image.advanced.known-limitations]]
+=== Known Limitations
+GraalVM native images are an evolving technology and not all libraries provide support.
+The GraalVM community is helping by providing https://github.com/oracle/graalvm-reachability-metadata[reachability metadata] for projects that don't yet ship their own.
+Spring itself doesn't contain hints for 3rd party libraries and instead relies on the reachability metadata project.
+
+If you encounter problems when generating native images for Spring Boot applications, please check the {github-wiki}/Known-GraalVM-Native-Image-Limitations[Known GraalVM Native Image Limitations] page of the Spring Boot wiki.
+You can also contribute issues to the https://github.com/spring-projects/spring-aot-smoke-tests[spring-aot-smoke-tests] project on GitHub which is used to confirm that common application types are working as expected.
+
+If you find a library which doesn't work with GraalVM, please raise an issue on the https://github.com/oracle/graalvm-reachability-metadata[reachability metadata project].