Add buildpack option for image building

This commit adds configuration to the Maven and Gradle plugins to
allow a list of buildpacks to be provided to the image building
goal and task.

Fixes gh-21722

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

@@ -130,6 +130,18 @@ Acceptable values are `ALWAYS`, `NEVER`, and `IF_NOT_PRESENT`.
 | Environment variables that should be passed to the builder.
 |
 
+| `buildpacks`
+|
+a|Buildpacks that the builder should use when building the image.
+Only the specified buildpacks will be used, overriding the default buildpacks included in the builder.
+Buildpack references must be in one of the following forms:
+
+* Buildpack in the builder - [urn:cnb:builder:]<buildpack id>[@<version>]
+* Buildpack in a directory on the file system - [file://]<path>
+* Buildpack in a gzipped tar (.tgz) file on the file system - [file://]<path>/<file name>
+* Buildpack in an OCI image - [docker://]<host>/<repo>[:<tag>][@<digest>]
+| None, indicating the builder should use the buildpacks included in it.
+
 | `cleanCache`
 | `--cleanCache`
 | Whether to clean the cache before building.
@@ -249,6 +261,58 @@ The image name can be specified on the command line as well, as shown in this ex
 	$ gradle bootBuildImage --imageName=example.com/library/my-app:v1
 ----
 
+
+
+[[build-image-example-buildpacks]]
+==== Buildpacks
+By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order.
+An alternative set of buildpacks can be provided to apply buildpacks that are not included in the builder, or to change the order of included buildpacks.
+When one or more buildpacks are provided, only the specified buildpacks will be applied.
+
+The following example instructs the builder to use a custom buildpack packaged in a `.tgz` file, followed by a buildpack included in the builder.
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-buildpacks.gradle[tags=buildpacks]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-buildpacks.gradle.kts[tags=buildpacks]
+----
+
+Buildpacks can be specified in any of the forms shown below.
+
+A buildpack located in a CNB Builder (version may be omitted if there is only one buildpack in the builder matching the `buildpack-id`):
+
+* `urn:cnb:builder:buildpack-id`
+* `urn:cnb:builder:buildpack-id@0.0.1`
+* `buildpack-id`
+* `buildpack-id@0.0.1`
+
+A path to a directory containing buildpack content (not supported on Windows):
+
+* `\file:///path/to/buildpack/`
+* `/path/to/buildpack/`BootBuildImageIntegrationTests
+
+A path to a gzipped tar file containing buildpack content:
+
+* `\file:///path/to/buildpack.tgz`
+* `/path/to/buildpack.tgz`
+
+An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/[packaged buildpack]:
+
+* `docker://example/buildpack`
+* `docker:///example/buildpack:latest`
+* `docker:///example/buildpack@sha256:45b23dee08...`
+* `example/buildpack`
+* `example/buildpack:latest`
+* `example/buildpack@sha256:45b23dee08...`
+
+
+
 [[build-image-example-publish]]
 ==== Image Publishing
 The generated image can be published to a Docker registry by enabling a `publish` option and configuring authentication for the registry using `docker.publishRegistry` properties.
@@ -272,6 +336,8 @@ 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-example-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:

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

@@ -0,0 +1,16 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{gradle-project-version}'
+}
+
+// tag::buildpacks[]
+bootBuildImage {
+	buildpacks = ["file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"]
+}
+// end::buildpacks[]
+
+task bootBuildImageBuildpacks {
+	doFirst {
+		bootBuildImage.buildpacks.each { reference -> println "$reference" }
+	}
+}

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

@@ -0,0 +1,20 @@
+import org.springframework.boot.gradle.tasks.bundling.BootBuildImage
+
+plugins {
+	java
+	id("org.springframework.boot") version "{gradle-project-version}"
+}
+
+// tag::buildpacks[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+    buildpacks = listOf("file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java")
+}
+// end::buildpacks[]
+
+tasks.register("bootBuildImageBuildpacks") {
+    doFirst {
+        for((reference) in tasks.getByName<BootBuildImage>("bootBuildImage").buildpacks) {
+            print(reference)
+        }
+    }
+}