Skip to content

JVM AOT cache: a training task, a Jib image, and a Dagger pipeline - #73

Open
rocketraman wants to merge 4 commits into
masterfrom
rg/aot-cache
Open

rocketraman wants to merge 4 commits into
masterfrom
rg/aot-cache

Conversation

@rocketraman

@rocketraman rocketraman commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Makes JVM AOT caches (JEP 483/514, JDK 24+) easy for Bootable apps, three ways: a Gradle task, a Jib image, and a Dagger pipeline.

What's here

  • bootable.aot-cache (new build-logic included build, AotCache.kt): it adds an aotCache task to any application project. The task runs the installed distribution by its start script, on the project's Java toolchain, with -XX:AOTCacheOutput. It waits for Bootable's => Running line, sends any configured training requests (request(method, url, body), rounds), stops the app with SIGTERM, and checks that the cache was written. The app's output goes to build/aot/<name>.aot.log.

  • Vanilla server-ktor-db trains with a small PUT/GET/DELETE/metrics workload.

  • examples/server-ktor-db/jib: an image with the cache in it, trained inside the image itself. jibBuildTar builds the image without a cache, then it is loaded. aotCache runs it in a container with -XX:AOTCacheOutput and a mounted directory. jibDockerBuild/jib then add the cache as an extra layer, with -XX:AOTCache in jvmFlags.

  • The server-ktor-db Dagger module (dagger.toml, dagger.lock, .dagger/modules/server-ktor-db/main.dang): a Dagger module in Dang, on Dagger v1.0.0-beta.28. .mise.toml provides the stable CLI and sets DAGGER_X_RELEASE, and DAGGER_NO_NAG to hide the Dagger Cloud signup hint. Bootable sends no traces to Dagger Cloud unless the user provides their own DAGGER_CLOUD_TOKEN or runs dagger login.

    • installed runs Gradle installDist in eclipse-temurin:25-jdk, with the build cache in the Gradle-home cache volume;
    • runtime installs the app into eclipse-temurin:25-jre;
    • aot-cache trains in a container of that runtime;
    • image is that same runtime plus the cache, so the JDK build and the jar mtimes match by construction;
    • verify fails unless at least 90% of the start's classes come from the cache, and check (@check) runs it;
    • dev (@up) runs the image for dagger start.

    dagger.lock pins both images by digest. The image is exported (image export --path=…), never pushed.

  • README: a "Faster Start: the JVM AOT Cache" section, including when to use each of the three, plus notes in the example's README.

Where the task lives, and why

It is a binary plugin in an included build-logic build, not root-build subprojects {} logic or a script plugin:

  • examples opt in with id("bootable.aot-cache");
  • the task type is reusable on its own (the Jib example uses AotCacheTraining directly with a podman run command);
  • it is one self-contained file with only Gradle API dependencies, so a downstream app can copy AotCache.kt into its own buildSrc.

Things found on the way

  • Modification times matter. The JVM checks each jar's size and mtime against the cache.
    • The installed directory can be moved (cp -a) and still use the cache.
    • A plain copy, or a rerun of installDist, gives "This file is not the one used while building the AOT cache", and the app runs without the cache.
    • So the plugin adds the installed files' mtimes as a task input.
  • Read the output from a file, not a pipe. When the task read the app's output through a pipe, the shutdown's output was lost and the child JVM that assembles the cache never finished. With output redirected to a file, it works.
  • Jib needs two things:
    • containerizingMode = "packaged", because the JVM won't use a cache with a non-empty directory like /app/classes on the class path;
    • an overridden training entrypoint, because -XX:AOTCache and -XX:AOTCacheOutput can't be combined.
  • Retraining in the Jib flow. The training image's layer directory is emptied first, so its tar is stable and aotCache stays UP-TO-DATE. Jib's dockerClient.executable must be an absolute path, so the build resolves -PcontainerCli=podman on PATH.
  • Dagger and OpenTelemetry. Dagger sets OTEL_EXPORTER_OTLP_* in every exec, and forwards that telemetry to Dagger Cloud when logged in. The training, verify and dev unset those variables, so the app exports nothing. Without that, the cache also picked up about 1,200 OTLP-exporter classes the app doesn't load in production.
  • Dang treats ${…} inside """ strings as its own interpolation, so the module's shell scripts avoid shell brace expansions.
  • JDK mismatch gives "created by a different version or build of HotSpot", and the app runs without the cache. -XX:AOTMode=on turns that into a startup failure.

Measurements (median of 7, JDK 25)

without with cache
vanilla, launch → => Running 721 ms 307 ms
vanilla, boot → => Running 690 ms 229 ms
vanilla, boot → services starting 485 ms 160 ms
vanilla, first PUT /entries/x 44 ms 12 ms
Jib container (Temurin 25.0.5), launch → => Running 819 ms 390 ms
Dagger image (Temurin 25.0.5), launch → => Running 860 ms 385 ms
Dagger image, boot → => Running 762 ms 248 ms
  • Vanilla: the cache is 66 MB, or 60 MB from a start-only training run. 8,217 of 8,368 loaded classes came from it. A start-only cache starts the app just as fast, but leaves the first PUT at 47 ms.
  • Jib: the cache layer is 64 MB. 8,259 of 8,403 classes came from it.
  • Dagger: the cache layer is 64 MB. verify reports 8,253 of 8,400 classes from it, and -Xlog:aot in podman run showed "Opened AOT cache /app/aot/vanilla.aot".
  • The vanilla and Jib numbers were measured before rebasing onto master's boot-stage tracing (Startup telemetry: a Clock, the boot's stages as spans, an always-sampled start; Kotlin API 2.3 #72). The Dagger numbers were measured on beta.28 before the same rebase.

Testing

  • ./gradlew build passes, after rebasing onto master.
  • :examples:server-ktor-db:vanilla:aotCache and :examples:server-ktor-db:jib:jibDockerBuild -PcontainerCli=podman were run locally with rootless Podman.
  • dagger check, dagger api call server-ktor-db verify and image export were run with Dagger v1.0.0-beta.28 on rootless Podman, with no Dagger Cloud login. The exported image was timed with podman run.
  • Nothing was pushed to a registry. CI doesn't run the training, the image builds or the Dagger module.

@claude

claude Bot commented Nov 17, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

The bootable.aot-cache plugin, in a new build-logic included build,
adds an aotCache task to an application: it runs the installed
distribution once, by its start script, on the project's toolchain,
with -XX:AOTCacheOutput, waits for Bootable's "=> Running" line,
sends the requests given to it, and stops it with SIGTERM, so the
JVM writes the cache as it exits.

- AotCacheTraining runs any command, so a container's training can
  use it too.
- The task reruns when the installed jars' modification times
  change, as the JVM checks them against the cache.
- The vanilla server-ktor-db example trains with a few requests, so
  the cache covers the request path too.
The cache is trained in a container of the image itself, so it matches
the image's JDK build and class path: jibBuildTar builds the image
without a cache, the container runtime loads it, aotCache runs it with
-XX:AOTCacheOutput and the cache's directory mounted, and
jibDockerBuild (or jib) builds the final image with the cache as one
more layer and -XX:AOTCache in its JVM flags.

- Jib's images are reproducible, so the final image's jars match the
  training's, modification times included.
- containerizingMode is packaged: the JVM won't use a cache with a
  non-empty directory on the class path.
- -PcontainerCli=podman runs it with Podman.
How to produce the cache and run with it, what has to match for the
JVM to use it, the measured start times with and without it, and how
the Jib example trains it in its own image.
@rocketraman rocketraman changed the title JVM AOT cache: a training task, a Jib image with the cache, and a Dagger example JVM AOT cache: a training task, a Jib image, and a Dagger pipeline Nov 18, 2026
A Dagger module, in Dang, that builds the vanilla app with Gradle in a
JDK 25 container, installs it into a JRE container, trains the AOT
cache in a container of that runtime, and adds the cache to the same
runtime as the image, so the JDK build and the jars' modification
times match by construction. check runs verify, which fails unless
the image loads most of its classes from the cache; the image is
exported, never pushed.

- It follows the Dagger 1.0 beta layout: dagger.toml, dagger.lock, and
  the module in .dagger/modules. .mise.toml provides the stable CLI,
  and DAGGER_X_RELEASE has it run v1.0.0-beta.28.
- dagger.lock pins the JDK and JRE images by digest.
- The build uses Gradle's build cache, in the Gradle user home's cache
  volume, without turning it on for every build.
- The training sends its requests through bash's /dev/tcp, as the JRE
  image has no curl, and unsets the OTEL_* variables Dagger sets, so
  the app exports nothing to Dagger's collector, and trains as it runs
  in production.
- The README says when to use it rather than the aotCache task or Jib.
@claude

claude Bot commented Nov 18, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant