Add 'postAppImageStep' to modify the app image before packaging

Creating a JEP 514 AOT cache requires running the packaged launcher once and
storing the result inside the app image, which has to happen after jpackage
assembled the image but before the OS-specific packages are derived from it.
The new option runs an Action on the app image directory at exactly that point;
it is rejected together with 'singleStepPackaging', where no intermediate image
exists.

Closes #135

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnKVoy56BKWZAkVtvSqNgg

Author: koppor

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Java Module Packaging Gradle Plugin - Changelog
 
+## Unreleased
+* [Added] [#135](https://github.com/gradlex-org/java-module-packaging/issues/135) - `postAppImageStep` option to modify the app image before the packages are built from it
+
 ## Version 1.3
 - [#122](https://github.com/gradlex-org/java-module-packaging/issues/122) - 'fatModueJar' tasks to re-package module Jars into one Jar with launcher
 - [#102](https://github.com/gradlex-org/java-module-packaging/issues/102) - Configure all targets via 'allTargets' notation

README.md

@@ -280,6 +280,26 @@ javaModulePackaging {
 
 You can tell the plugin to perform packaging in one step by setting the `singleStepPackaging = true` option on a target.
 
+### How can I modify the app image before the packages are built from it?
+
+Configure a `postAppImageStep` on a target. It receives the app image directory after all resources have been copied
+into it and runs before the OS-specific packages are built from that image, so modifications end up in all packages.
+
+```kotlin
+javaModulePackaging {
+  allTargets {
+    postAppImageStep = Action<Directory> {
+      // 'this' is the app image directory, e.g. run the packaged launcher once to train a
+      // JEP 514 AOT cache and store it in the image
+    }
+  }
+}
+```
+
+The step is not a task input. If its result depends on state outside the app image, register that state as an
+additional input of the `jpackage<Target>` task. The option cannot be combined with `singleStepPackaging`, because
+single-step packaging builds the packages without an intermediate app image.
+
 ### How does a `fatModuleJar` work?
 
 The structure of the Jar follows the structure defined by the [Jenesis Launcher](https://github.com/raphw/jenesis-launcher).

src/main/java/org/gradlex/javamodule/packaging/JavaModulePackagingExtension.java

@@ -337,6 +337,7 @@ private void registerTargetSpecificTasks(
             t.getAppImageOptions().convention(target.getAppImageOptions());
             t.getPackageTypes().convention(target.getPackageTypes());
             t.getSingleStepPackaging().convention(target.getSingleStepPackaging());
+            t.getPostAppImageStep().convention(target.getPostAppImageStep());
             t.getResources().from(getResources());
             t.getTargetResources().from(target.getTargetResources());
             t.getVerbose().convention(getVerbose());

src/main/java/org/gradlex/javamodule/packaging/model/Target.java

@@ -2,7 +2,9 @@
 package org.gradlex.javamodule.packaging.model;
 
 import javax.inject.Inject;
+import org.gradle.api.Action;
 import org.gradle.api.file.ConfigurableFileCollection;
+import org.gradle.api.file.Directory;
 import org.gradle.api.provider.ListProperty;
 import org.gradle.api.provider.Property;
 import org.jspecify.annotations.NullMarked;
@@ -26,6 +28,12 @@ public abstract class Target {
 
     public abstract Property<Boolean> getSingleStepPackaging();
 
+    /**
+     * An optional step to run on the created app image, after all resources have been copied into it and before
+     * the OS-specific packages are built from that image. Not supported together with 'singleStepPackaging'.
+     */
+    public abstract Property<Action<Directory>> getPostAppImageStep();
+
     @Inject
     public Target(String name) {
         this.name = name;

src/main/java/org/gradlex/javamodule/packaging/tasks/Jpackage.java

@@ -16,7 +16,9 @@
 import java.util.List;
 import java.util.stream.Collectors;
 import javax.inject.Inject;
+import org.gradle.api.Action;
 import org.gradle.api.DefaultTask;
+import org.gradle.api.InvalidUserDataException;
 import org.gradle.api.file.ConfigurableFileCollection;
 import org.gradle.api.file.Directory;
 import org.gradle.api.file.DirectoryProperty;
@@ -112,6 +114,17 @@ public abstract class Jpackage extends DefaultTask {
     @Input
     public abstract Property<Boolean> getVerbose();
 
+    /**
+     * An optional step to run on the created app image, after all resources have been copied into it and before
+     * the OS-specific packages are built from that image. Not supported together with 'singleStepPackaging',
+     * as there is no intermediate app image in that case.
+     *
+     * <p>The step is not an input of this task. If its result depends on state outside the app image, register
+     * that state as an additional task input.
+     */
+    @Internal
+    public abstract Property<Action<Directory>> getPostAppImageStep();
+
     @OutputDirectory
     public abstract DirectoryProperty getDestination();
 
@@ -138,6 +151,12 @@ public void runJpackage() throws Exception {
 
         validateHostSystem(arch, os);
 
+        boolean packagesRequested = getPackageTypes().get().stream().anyMatch(t -> !"app-image".equals(t));
+        if (getPostAppImageStep().isPresent() && getSingleStepPackaging().get() && packagesRequested) {
+            throw new InvalidUserDataException("'postAppImageStep' cannot be combined with 'singleStepPackaging', "
+                    + "because single-step packaging builds the packages without an intermediate app image");
+        }
+
         Directory resourcesDir = getTempDirectory().get().dir("jpackage-resources");
         //noinspection ResultOfMethodCallIgnored
         resourcesDir.getAsFile().mkdirs();
@@ -171,6 +190,9 @@ public void runJpackage() throws Exception {
                 appRootFolder = new File(appImageFolder, "lib");
             }
             copyAdditionalRessourcesToImageFolder(appRootFolder);
+            if (getPostAppImageStep().isPresent()) {
+                getPostAppImageStep().get().execute(getDestination().get().dir(appImageFolder.getName()));
+            }
         }
 
         if (getSingleStepPackaging().get()) {

src/test/java/org/gradlex/javamodule/packaging/test/JavaModulePackagingOptionsTest.java

@@ -221,4 +221,37 @@ void works_if_module_path_contains_spaces() {
 
         build.build(":app:jpackage");
     }
+
+    @Test
+    void can_run_a_post_app_image_step() {
+        build.appBuildFile.appendText("""
+            javaModulePackaging {
+                allTargets {
+                    postAppImageStep.set(Action<Directory> {
+                        file("marker.txt").asFile.writeText("touched")
+                    })
+                }
+            }
+        """);
+
+        build.build(":app:jpackage");
+
+        assertThat(build.appImageFolder().getAsPath()).isDirectoryRecursivelyContaining("glob:**/marker.txt");
+    }
+
+    @Test
+    void cannot_combine_post_app_image_step_with_single_step_packaging() {
+        build.appBuildFile.appendText("""
+            javaModulePackaging {
+                allTargets {
+                    singleStepPackaging.set(true)
+                    postAppImageStep.set(Action<Directory> { })
+                }
+            }
+        """);
+
+        var result = build.fail(":app:jpackage");
+
+        assertThat(result.getOutput()).contains("'postAppImageStep' cannot be combined with 'singleStepPackaging'");
+    }
 }