Merge pull request #30916 from geoand/#30821

Add AppCDS documentation

docs/src/main/asciidoc/appcds.adoc

@@ -0,0 +1,95 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= AppCDS
+include::_attributes.adoc[]
+:categories: core, cloud
+:summary: This reference guide explains how to enable AppCDS with Quarkus.
+
+This reference guide explains how to enable Application Class Data Sharing in your Quarkus applications.
+
+== What is Application Class Data Sharing (AppCDS)?
+
+link:https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#application-class-data-sharing[Application Class Data Sharing] is a JVM feature that helps reduce the startup time and memory footprint of a JVM application.
+This is achieved by having the JVM create a pre-processed shared archived of classes that are loaded at startup time. As these classes
+are loaded every time the application starts, AppCDS is a conceptually simple way of improving the application startup time,
+without the application itself having to be coded or configured in a specific way. How much of an improvement depends on many factors, such as the number of classes loaded, the underlying hardware etc.
+
+== Vanilla AppCDS generation
+
+The main downside of creating AppCDS manually for an application is that their generation requires launching the application with special flags and obtaining the archive in a step before the application is deployed to production.
+
+NOTE: The exact process depends on the JVM version being used as newer JVM have incrementally made the process easier.
+
+This fact makes the use of AppCDS difficult to use for real world deployments where a CI pipeline is responsible for building and deploying applications.
+
+== AppCDS in Quarkus
+
+=== Creating the archive
+
+Quarkus makes AppCDS generation as simple as setting the `quarkus.package.create-appcds` configuration property to `true`.
+For an example Quarkus application using Maven (assuming it is located in `/tmp/code-with-quarkus`), the AppCDS archive can be generated by simply building the application like so:
+
+[source,bash]
+----
+./mvnw package -Dquarkus.package.create-appcds=true
+----
+
+When the build completes, the output will contain (among other things) the following:
+
+[source]
+----
+[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] Launching AppCDS creation process.
+[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] AppCDS successfully created at: '/tmp/code-with-quarkus/target/quarkus-app/app-cds.jsa'.
+[INFO] [io.quarkus.deployment.pkg.steps.AppCDSBuildStep] To ensure they are loaded properly, run the application jar from its directory and also add the '-XX:SharedArchiveFile=app-cds.jsa' JVM flag.
+Moreover, make sure to use the exact same Java version (x.y.z) to run the application as was used to build it.
+----
+
+If we take a look at `/tmp/code-with-quarkus/target/quarkus-app`, among the other files, we see `app-cds.jsa`, which is the generated AppCDS archive.
+
+=== Using the archive
+
+Using the archive is done by using the `-XX:SharedArchiveFile` flag. However, a few caveats apply:
+
+* The paths to the Quarkus jar file and the AppCDS archive need to be exactly the same as those Quarkus used to build the archive
+* The version of the JVM used to run the application must be **exactly** the same as the one used to build the Quarkus application.
+
+Assuming we are using the same JVM to run the application as we used to build the application, we can launch the application like so:
+
+[source,bash]
+----
+cd target/quarkus-app
+java -XX:SharedArchiveFile=app-cds.jsa -jar quarkus-run.jar
+----
+
+[TIP]
+====
+The JVM is resilient. Faced with a situation where the archive file is not usable (for whatever reason) it will simply disable the AppCDS feature.
+
+If it is desirable to simply halt the execution when the archive is not usable, the following command line invocation can be used:
+
+[source,bash]
+----
+java -Xshare:on -XX:SharedArchiveFile=app-cds.jsa -jar quarkus-run.jar
+----
+====
+
+[NOTE]
+====
+Given what was mentioned above about how the application needs to be launched in order for the archive to be built, the question arises of how Quarkus deals with this situation.
+
+The answer is that at application build time, right after the application archive is built, Quarkus launches the application, but only the parts of the launch process that are safe are run.
+More specifically, the application is run up until the steps that actually open sockets or run application logic.
+
+This results in an archive generation process that on one hand is completely safe, but on the other hand is unable to archive every single class that the application might need at boot time.
+As a result, users are expected to get a slightly more effective archive if they manually go through the hoops of generating the AppCDS archive.
+====
+
+=== Usage in containers
+
+When building container images using the `quarkus-container-image-jib` extension, Quarkus automatically takes care of all the steps needed to generate the archive
+and make it usable at runtime in the container.
+
+This way, by simply setting `quarkus.package.create-appcds` to `true` the generated container can benefit from a slight reduction in startup time and memory usage.

docs/src/main/asciidoc/container-image.adoc

@@ -99,6 +99,11 @@ To enable this feature, the property `quarkus.bootstrap.workspace-discovery` nee
 when invoking the build tool, either as a build tool property. Setting this property in `application.properties` will **not** work because
 this property needs to be known very early on in the build process.
 
+==== AppCDS
+
+Quarkus supports generating and including an link:https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#application-class-data-sharing[Application Class Data Sharing] archive when generating a container image using Jib.
+See the xref:appcds.adoc[AppCDS documentation] for more details.
+
 [#docker]
 === Docker