quarkus.package.jar.tree-shake option to eliminate unused classes from runtime dependencies

Author: aloubyansky

core/deployment/src/main/java/io/quarkus/deployment/pkg/PackageConfig.java

@@ -182,6 +182,11 @@ interface JarConfig {
         @WithDefault("true")
         boolean addRunnerSuffix();
 
+        /**
+         * Tree-shaking configuration.
+         */
+        TreeShakeConfig treeShake();
+
         /**
          * Indicates a list of dependency for which the jar will use artifactId.type filename scheme
          * Each dependency needs to be expressed in the following format:

core/deployment/src/main/java/io/quarkus/deployment/pkg/TreeShakeConfig.java

@@ -0,0 +1,51 @@
+package io.quarkus.deployment.pkg;
+
+import java.util.Optional;
+import java.util.Set;
+
+import io.quarkus.runtime.annotations.ConfigGroup;
+import io.smallrye.config.WithDefault;
+
+/**
+ * Tree-shaking configuration.
+ */
+@ConfigGroup
+public interface TreeShakeConfig {
+
+    /**
+     * Whether to perform class reachability analysis and exclude non-reachable classes
+     * from the produced JAR.
+     * <ul>
+     * <li>{@code none} - No analysis or exclusion is performed.</li>
+     * <li>{@code classes} - Exclude non-reachable classes from dependencies.</li>
+     * </ul>
+     */
+    @WithDefault("classes")
+    TreeShakeMode mode();
+
+    /**
+     * Dependency artifacts to exclude from tree-shaking. All classes from excluded
+     * artifacts are preserved regardless of reachability analysis.
+     * <p>
+     * This is useful for libraries that perform self-integrity checks (e.g., BouncyCastle FIPS)
+     * or that load classes in ways the tree-shaker cannot detect.
+     * <p>
+     * Each dependency is expressed as {@code groupId:artifactId[:[classifier][:[type]]]}.
+     * The classifier and type are optional. If the type is missing, {@code jar} is assumed.
+     */
+    Optional<Set<String>> excludedArtifacts();
+
+    /**
+     * Tree shaking mode.
+     */
+    enum TreeShakeMode {
+        /**
+         * No analysis or exclusion is performed.
+         */
+        NONE,
+        /**
+         * Exclude non-reachable classes from dependencies.
+         */
+        CLASSES;
+    }
+}

core/deployment/src/main/java/io/quarkus/deployment/pkg/builditem/JarTreeShakeBuildItem.java

@@ -0,0 +1,67 @@
+package io.quarkus.deployment.pkg.builditem;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import io.quarkus.builder.item.SimpleBuildItem;
+import io.quarkus.maven.dependency.ArtifactKey;
+
+/**
+ * Build item that holds the results of dependency usage analysis for tree shaking.
+ * Contains whether class-level tree shaking was performed, the set of reachable class names (dot-separated),
+ * and the sorted list of removed class resource paths per dependency.
+ */
+public final class JarTreeShakeBuildItem extends SimpleBuildItem {
+
+    private final boolean classesShaken;
+    private final Set<String> reachableClassNames;
+    private final Map<ArtifactKey, List<String>> removedClasses;
+
+    public JarTreeShakeBuildItem(boolean classesShaken, Set<String> reachableClassNames,
+            Map<ArtifactKey, List<String>> removedClasses) {
+        this.classesShaken = classesShaken;
+        this.reachableClassNames = reachableClassNames;
+        this.removedClasses = removedClasses;
+    }
+
+    public boolean isClassesShaken() {
+        return classesShaken;
+    }
+
+    /**
+     * @return dot-separated class names of all reachable classes
+     */
+    public Set<String> getReachableClassNames() {
+        return reachableClassNames;
+    }
+
+    /**
+     * @return sorted list of removed class resource paths (e.g. "com/example/Foo.class") per dependency
+     */
+    public Map<ArtifactKey, List<String>> getRemovedClasses() {
+        return removedClasses;
+    }
+
+    /**
+     * Computes a pedigree string for the given dependency describing what was removed.
+     *
+     * @return pedigree text or {@code null} if nothing was removed
+     */
+    public String computePedigree(ArtifactKey depKey) {
+        if (!classesShaken) {
+            return null;
+        }
+        List<String> removed = removedClasses.getOrDefault(depKey, Collections.emptyList());
+        if (removed.isEmpty()) {
+            return null;
+        }
+        var sb = new StringBuilder("Removed ");
+        sb.append(removed.get(0));
+        for (int i = 1; i < removed.size(); ++i) {
+            sb.append(",").append(removed.get(i));
+        }
+        return sb.toString();
+    }
+}

core/deployment/src/main/java/io/quarkus/deployment/pkg/builditem/JarTreeShakeExcludedArtifactBuildItem.java

@@ -0,0 +1,25 @@
+package io.quarkus.deployment.pkg.builditem;
+
+import io.quarkus.builder.item.MultiBuildItem;
+import io.quarkus.maven.dependency.ArtifactKey;
+
+/**
+ * Excludes an entire dependency artifact from jar tree-shake class removal.
+ * All classes from excluded artifacts are treated as reachable and will never
+ * be removed by the tree-shaker.
+ * <p>
+ * This is needed for libraries like BouncyCastle FIPS that perform self-integrity
+ * checks (checksums over their own classes) and break if any classes are removed.
+ */
+public final class JarTreeShakeExcludedArtifactBuildItem extends MultiBuildItem {
+
+    private final ArtifactKey artifactKey;
+
+    public JarTreeShakeExcludedArtifactBuildItem(ArtifactKey artifactKey) {
+        this.artifactKey = artifactKey;
+    }
+
+    public ArtifactKey getArtifactKey() {
+        return artifactKey;
+    }
+}

core/deployment/src/main/java/io/quarkus/deployment/pkg/builditem/JarTreeShakeRootClassBuildItem.java

@@ -0,0 +1,24 @@
+package io.quarkus.deployment.pkg.builditem;
+
+import io.quarkus.builder.item.MultiBuildItem;
+
+/**
+ * This build item is meant to be internal to {@link io.quarkus.deployment.pkg.steps.JarTreeShakeProcessor},
+ * in a sense it's produced and consumed by it.
+ * <p>
+ * Declares a class that must be treated as a root for jar tree-shake reachability analysis.
+ * Any class registered through this build item will not be removed by the tree-shaker,
+ * and all classes reachable from it will also be preserved.
+ */
+public final class JarTreeShakeRootClassBuildItem extends MultiBuildItem {
+
+    private final String className;
+
+    public JarTreeShakeRootClassBuildItem(String className) {
+        this.className = className;
+    }
+
+    public String getClassName() {
+        return className;
+    }
+}

core/deployment/src/main/java/io/quarkus/deployment/pkg/jar/AbstractFastJarBuilder.java

@@ -52,6 +52,7 @@
 import io.quarkus.deployment.pkg.PackageConfig;
 import io.quarkus.deployment.pkg.builditem.CurateOutcomeBuildItem;
 import io.quarkus.deployment.pkg.builditem.JarBuildItem;
+import io.quarkus.deployment.pkg.builditem.JarTreeShakeBuildItem;
 import io.quarkus.deployment.pkg.builditem.OutputTargetBuildItem;
 import io.quarkus.deployment.util.FileUtil;
 import io.quarkus.maven.dependency.ArtifactKey;
@@ -66,6 +67,7 @@ abstract class AbstractFastJarBuilder extends AbstractJarBuilder<JarBuildItem> {
 
     private final List<AdditionalApplicationArchiveBuildItem> additionalApplicationArchives;
     private final Set<ArtifactKey> parentFirstArtifactKeys;
+    private final JarTreeShakeBuildItem treeShakeResult;
 
     AbstractFastJarBuilder(CurateOutcomeBuildItem curateOutcome,
             OutputTargetBuildItem outputTarget,
@@ -80,11 +82,13 @@ abstract class AbstractFastJarBuilder extends AbstractJarBuilder<JarBuildItem> {
             Set<ArtifactKey> parentFirstArtifactKeys,
             Set<ArtifactKey> removedArtifactKeys,
             ExecutorService executorService,
-            ResolvedJVMRequirements jvmRequirements) {
+            ResolvedJVMRequirements jvmRequirements,
+            JarTreeShakeBuildItem treeShakeResult) {
         super(curateOutcome, outputTarget, applicationInfo, packageConfig, mainClass, applicationArchives, transformedClasses,
                 generatedClasses, generatedResources, removedArtifactKeys, executorService, jvmRequirements);
         this.additionalApplicationArchives = additionalApplicationArchives;
         this.parentFirstArtifactKeys = parentFirstArtifactKeys;
+        this.treeShakeResult = treeShakeResult;
     }
 
     public JarBuildItem build() throws IOException {
@@ -232,7 +236,7 @@ public JarBuildItem build() throws IOException {
                 copyDependency(parentFirstArtifactKeys, outputTarget, copiedArtifacts, mainLib, baseLib,
                         fastJarJarsBuilder::addDependency, fastJarJarsBuilder::addParentFirstDependency, true,
                         appDep, transformedClasses, removedArtifactKeys, packageConfig, manifestConfig,
-                        executorService);
+                        executorService, treeShakeResult);
             } else if (includeAppDependency(appDep, outputTarget.getIncludedOptionalDependencies(), removedArtifactKeys)) {
                 appDep.getResolvedPaths().forEach(fastJarJarsBuilder::addDependency);
             }
@@ -311,7 +315,7 @@ public JarBuildItem build() throws IOException {
                     copyDependency(parentFirstArtifactKeys, outputTarget, copiedArtifacts, deploymentLib, baseLib, p -> {
                     }, p -> {
                     }, false, appDep, new TransformedClassesBuildItem(Map.of()), removedArtifactKeys, packageConfig,
-                            manifestConfig, executorService); //we don't care about transformation here, so just pass in an empty item
+                            manifestConfig, executorService, null); //we don't care about transformation or tree shaking here
                 }
                 Map<ArtifactKey, List<String>> relativePaths = new HashMap<>();
                 for (Entry<ArtifactKey, List<Path>> e : copiedArtifacts.entrySet()) {
@@ -398,7 +402,8 @@ private static void copyDependency(Set<ArtifactKey> parentFirstArtifacts, Output
             Map<ArtifactKey, List<Path>> runtimeArtifacts, Path libDir, Path baseLib, Consumer<Path> dependenciesConsumer,
             Consumer<Path> parentFirstDependenciesConsumer, boolean allowParentFirst, ResolvedDependency appDep,
             TransformedClassesBuildItem transformedClasses, Set<ArtifactKey> removedDeps,
-            PackageConfig packageConfig, ApplicationManifestConfig.Builder manifestConfig, ExecutorService executorService)
+            PackageConfig packageConfig, ApplicationManifestConfig.Builder manifestConfig, ExecutorService executorService,
+            JarTreeShakeBuildItem treeShakeResult)
             throws IOException {
 
         // Exclude files that are not jars (typically, we can have XML files here, see https://github.com/quarkusio/quarkus/issues/2852)
@@ -450,6 +455,40 @@ private static void copyDependency(Set<ArtifactKey> parentFirstArtifacts, Output
                         }
                     }
                 }
+                // When tree shake level is CLASSES, add non-reachable classes to removal set.
+                // Use walkRaw to handle multi-release JARs: we need to add both base and
+                // versioned entry paths to the removal set for unreachable classes.
+                if (treeShakeResult != null
+                        && treeShakeResult.isClassesShaken()) {
+                    try (var pathTree = appDep.getContentTree().open()) {
+                        pathTree.walkRaw(visit -> {
+                            String rel = visit.getRelativePath("/");
+                            String classRel = rel;
+                            // For multi-release entries, extract the actual class path
+                            if (rel.startsWith("META-INF/versions/")) {
+                                String afterVersions = rel.substring("META-INF/versions/".length());
+                                int slash = afterVersions.indexOf('/');
+                                if (slash > 0) {
+                                    classRel = afterVersions.substring(slash + 1);
+                                } else {
+                                    return;
+                                }
+                            }
+                            if (classRel.endsWith(".class") && !classRel.equals("module-info.class")) {
+                                String className = classRel.substring(0, classRel.length() - 6).replace('/', '.');
+                                if (!treeShakeResult.getReachableClassNames().contains(className)) {
+                                    int dollarIdx = className.indexOf('$');
+                                    if (dollarIdx < 0
+                                            || !treeShakeResult.getReachableClassNames()
+                                                    .contains(className.substring(0, dollarIdx))) {
+                                        // Add the raw path (base or META-INF/versions/N/...) to removal set
+                                        removedFromThisArchive.add(rel);
+                                    }
+                                }
+                            }
+                        });
+                    }
+                }
                 var appComponent = ApplicationComponent.builder()
                         .setPath(targetPath)
                         .setResolvedDependency(appDep);
@@ -461,14 +500,10 @@ private static void copyDependency(Set<ArtifactKey> parentFirstArtifacts, Output
                     // we copy jars for which we remove entries to the same directory
                     // which seems a bit odd to me
                     JarUnsigner.unsignJar(resolvedDep, targetPath, Predicate.not(removedFromThisArchive::contains));
-
-                    var list = new ArrayList<>(removedFromThisArchive);
-                    Collections.sort(list);
-                    var sb = new StringBuilder("Removed ").append(list.get(0));
-                    for (int i = 1; i < list.size(); ++i) {
-                        sb.append(",").append(list.get(i));
-                    }
-                    appComponent.setPedigree(sb.toString());
+                }
+                String pedigree = treeShakeResult != null ? treeShakeResult.computePedigree(appDep.getKey()) : null;
+                if (pedigree != null) {
+                    appComponent.setPedigree(pedigree);
                 }
                 manifestConfig.addComponent(appComponent);
             }