Polish "Add option to customize cache volume names when building an image"

See gh-28292

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc

@@ -181,10 +181,15 @@ The value supplied will be passed unvalidated to Docker when creating the builde
 | A list of one or more additional tags to apply to the generated image.
 |
 
-| `cacheVolumeNames`
+| `buildCache`
 |
-| Cache volume names that should be used by the builder instead of generating random names.
+| A cache containing layers created by buildpacks and used by the image building process.
+| A named volume in the Docker daemon, with a name derived from the image name.
+
+| `launchCache`
 |
+| A cache containing layers created by buildpacks and used by the image launching process.
+| A named volume in the Docker daemon, with a name derived from the image name.
 
 |===
 
@@ -384,10 +389,30 @@ The publish option can be specified on the command line as well, as shown in thi
 	$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage
 ----
 
+[[build-image.examples.caches]]
+=== Builder Cache Configuration
 
+The CNB builder caches layers that are used when building and launching an image.
+By default, these caches are stored as named volumes in the Docker daemon with names that are derived from the full name of the target image.
+If the image name changes frequently, for example when the project version is used as a tag in the image name, then the caches can be invalidated frequently.
+
+The cache volumes can be configured to use alternative names to give more control over cache lifecycle as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-caches.gradle[tags=caches]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-caches.gradle.kts[tags=caches]
+----
 
 [[build-image.examples.docker]]
 === Docker Configuration
+
 If you need the plugin to communicate with the Docker daemon using a remote connection instead of the default local connection, the connection details can be provided using `docker` properties as shown in the following example:
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-cacheVolumeNames.gradle

@@ -1,23 +0,0 @@
-plugins {
-	id 'java'
-	id 'org.springframework.boot' version '{gradle-project-version}'
-}
-
-bootJar {
-	mainClass = 'com.example.ExampleApplication'
-}
-
-// tag::cacheVolumeNames[]
-bootBuildImage {
-    cacheVolumeNames = [
-        "build": "example-build-cachevol",
-        "launch": "example-launch-cachevol"
-    ]
-}
-// end::cacheVolumeNames[]
-
-task bootBuildImageCacheVolumeNames {
-	doFirst {
-		bootBuildImage.cacheVolumeNames.each { type, name -> println "$type=$name" }
-	}
-}

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-cacheVolumeNames.gradle.kts

@@ -1,21 +0,0 @@
-import org.springframework.boot.gradle.tasks.bundling.BootBuildImage
-
-plugins {
-	java
-	id("org.springframework.boot") version "{gradle-project-version}"
-}
-
-// tag::cacheVolumeNames[]
-tasks.getByName<BootBuildImage>("bootBuildImage") {
-	cacheVolumeNames = mapOf("build" to "example-build-cachevol",
-						"launch" to "example-launch-cachevol")
-}
-// end::cacheVolumeNames[]
-
-tasks.register("bootBuildImageEnvironment") {
-	doFirst {
-		for((type, name) in tasks.getByName<BootBuildImage>("bootBuildImage").cacheVolumeNames) {
-			print(type + "=" + name)
-		}
-	}
-}

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-caches.gradle

@@ -0,0 +1,30 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{gradle-project-version}'
+}
+
+bootJar {
+	mainClass = 'com.example.ExampleApplication'
+}
+
+// tag::caches[]
+bootBuildImage {
+	buildCache {
+		volume {
+			name = "cache-${rootProject.name}.build"
+		}
+	}
+	launchCache {
+		volume {
+			name = "cache-${rootProject.name}.launch"
+		}
+	}
+}
+// end::caches[]
+
+task bootBuildImageCaches {
+	doFirst {
+		bootBuildImage.buildCache.asCache().with { println "buildCache=$name" }
+		bootBuildImage.launchCache.asCache().with { println "launchCache=$name" }
+	}
+}

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-caches.gradle.kts

@@ -0,0 +1,28 @@
+import org.springframework.boot.gradle.tasks.bundling.BootBuildImage
+
+plugins {
+	java
+	id("org.springframework.boot") version "{gradle-project-version}"
+}
+
+// tag::caches[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	buildCache {
+		volume {
+			name = "cache-${rootProject.name}.build"
+		}
+	}
+	launchCache {
+		volume {
+			name = "cache-${rootProject.name}.launch"
+		}
+	}
+}
+// end::caches[]
+
+tasks.register("bootBuildImageCaches") {
+	doFirst {
+		println("buildCache=" + tasks.getByName<BootBuildImage>("bootBuildImage").buildCache.asCache().volume.name)
+		println("launchCache=" + tasks.getByName<BootBuildImage>("bootBuildImage").launchCache.asCache().volume.name)
+	}
+}