Add documentation for gradle bootBuildImage task

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc

@@ -1,5 +1,5 @@
 = Spring Boot Gradle Plugin Reference Guide
-Andy Wilkinson
+Andy Wilkinson, Scott Frederick
 :doctype: book
 :toc: left
 :toclevels: 4
@@ -25,6 +25,7 @@ Andy Wilkinson
 :spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version}
 :api-documentation: {spring-boot-docs}/gradle-plugin/api
 :spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
+:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
 :version-properties-appendix: {spring-boot-reference}/#dependency-versions-coordinates
 :build-info-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/buildinfo/BuildInfo.html
 :boot-build-image-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.html
@@ -32,7 +33,7 @@ Andy Wilkinson
 :boot-war-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootWar.html
 :boot-run-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/run/BootRun.html
 :github-code: https://github.com/spring-projects/spring-boot/tree/{github-tag}
-
+:buildpacks-reference: https://buildpacks.io/docs
 
 
 [[introduction]]
@@ -47,6 +48,7 @@ In addition to this user guide, {api-documentation}[API documentation] is also a
 include::getting-started.adoc[]
 include::managing-dependencies.adoc[]
 include::packaging.adoc[]
+include::packaging-oci-image.adoc[]
 include::publishing.adoc[]
 include::running.adoc[]
 include::integrating-with-actuator.adoc[]

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

@@ -0,0 +1,99 @@
+[[build-image]]
+== Packaging OCI images
+
+The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from executable jars using https://buildpacks.io[Cloud Native Buildpacks].
+Images can be built using the `bootBuildImage` task and a local Docker installation.
+The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
+
+[[build-image-customization]]
+=== Image Customizations
+The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
+The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
+By default, the plugin chooses a builder image.
+The name of the generated image is deduced from project properties.
+
+Task properties can be used to configure how the builder should operate on the project.
+The following table summarizes the available properties and their default values:
+
+|===
+| Property | Description | Default value
+
+| `builder`
+| Name of the Builder image to use.
+| `cloudfoundry/cnb:0.0.43-bionic`
+
+| `imageName`
+| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
+| `docker.io/library/${project.artifactId}:${project.version}`
+
+| `environment`
+| Environment variables that should be passed to the builder.
+|
+
+| `cleanCache`
+| Whether to clean the cache before building.
+| `false`
+
+| `verboseLogging`
+| Enables verbose logging of builder operations.
+| `false`
+
+|===
+
+[[build-image-examples]]
+=== Examples
+
+[[build-image-example-custom-image-builder]]
+==== Custom Image Builder
+If you need to customize the builder used to create the image, configure the task as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-builder.gradle[tags=builder]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-builder.gradle.kts[tags=builder]
+----
+
+This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
+
+If the builder exposes configuration options, those can be set using the `environment` property, as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env]
+----
+
+The example above assumes that the builder defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use).
+
+
+[[build-image-example-custom-image-name]]
+==== Custom Image Name
+By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.
+You can take control over the name by setting task properties, as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-name.gradle[tags=image-name]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-name.gradle.kts[tags=image-name]
+----
+
+Note that this configuration does not provide an explicit tag so `latest` is used.
+It is possible to specify a tag as well, either using `${project.version}`, any property available in the build or a hardcoded version.

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

@@ -299,11 +299,3 @@ The jar will then be split into layer folders which may include:
 * `snapshots-dependencies`
 * `dependencies`
 
-
-
-[[packaging-oci-images]]
-== Packaging OCI images
-
-The plugin can create OCI images from executable jars using a https://buildpacks.io[buildpack].
-Images can be built using the `bootBuildImage` task and a local Docker installation.
-The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].

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

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::builder[]
+bootBuildImage {
+	builder = "mine/java-cnb-builder"
+}
+// end::builder[]

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

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::builder[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	builder = "mine/java-cnb-builder"
+}
+// end::builder[]

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

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::env[]
+bootBuildImage {
+	environment = ["BP_JAVA_VERSION" : "13.0.1"]
+}
+// end::env[]

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

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::env[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	environment = ["BP_JAVA_VERSION" : "13.0.1"]
+}
+// end::env[]

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

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::image-name[]
+bootBuildImage {
+	imageName = "example.com/library/${project.artifactId}"
+}
+// end::image-name[]

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

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::image-name[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	imageName = "example.com/library/${project.artifactId}"
+}
+// end::image-name[]

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc

@@ -1,5 +1,5 @@
 = Spring Boot Maven Plugin Documentation
-Stephane Nicoll, Andy Wilkinson
+Stephane Nicoll, Andy Wilkinson, Scott Frederick
 :doctype: book
 :toc: left
 :toclevels: 4

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

@@ -1,7 +1,7 @@
 [[build-image]]
 == Packaging OCI Images
 
-The plugin can create https://github.com/opencontainers/image-spec[OCI images] using a https://buildpacks.io/[buildpack].
+The plugin can create an https://github.com/opencontainers/image-spec[OCI image] using https://buildpacks.io/[Cloud Native Buildpacks].
 Images can be built using the `build-image` goal and a local Docker installation.
 
 The easiest way to get started is to to invoke `mvn spring-boot:build-image` on a project.
@@ -14,7 +14,7 @@ It is possible to automate the creation of an image whenever the `package` phase
 			<plugin>
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-maven-plugin</artifactId>
-				<version>{version}</version>
+				<version>{gradle-project-version}</version>
 				<executions>
 					<execution>
 						<goals>
@@ -32,7 +32,11 @@ When the `build-image` repackages the application, it applies the same settings
 
 [[build-image-customization]]
 === Image Customizations
-By default, the image is built using the `cloudfoundry/cnb:0.0.43-bionic` builder and its name is deduced from the `artifactId` of the project.
+The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
+The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
+By default, the plugin chooses a builder image.
+The name of the generated image is deduced from project properties.
+
 The `image` parameter allows to configure how the builder should operate on the project.
 The following table summarizes the available properties and their default values:
 
@@ -40,15 +44,15 @@ The following table summarizes the available properties and their default values
 | Property | Description | Default value
 
 | `builder`
-| {buildpacks-reference}/concepts/components/builder/[Builder image] name to use.
+| Name of the Builder image to use.
 | `cloudfoundry/cnb:0.0.43-bionic`
 
 | `name`
-| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name].
+| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
 | `docker.io/library/${project.artifactId}:${project.version}`
 
 | `env`
-| Environment properties that should be passed to the builder.
+| Environment variables that should be passed to the builder.
 |
 
 | `cleanCache`
@@ -56,7 +60,7 @@ The following table summarizes the available properties and their default values
 | `false`
 
 | `verboseLogging`
-| Whether verbose logging is required.
+| Enables verbose logging of builder operations.
 | `false`
 
 |===
@@ -81,7 +85,7 @@ If you need to customize the builder used to create the image, configure yours a
 				<plugin>
 					<groupId>org.springframework.boot</groupId>
 					<artifactId>spring-boot-maven-plugin</artifactId>
-					<version>{version}</version>
+					<version>{gradle-project-version}</version>
 					<configuration>
 						<image>
 							<builder>mine/java-cnb-builder</builder>
@@ -93,7 +97,7 @@ If you need to customize the builder used to create the image, configure yours a
 	</project>
 ----
 
-This configuration will use the `latest` version of the `mine/java-cnb-builder` builder.
+This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
 
 If the builder exposes configuration options, those can be set using the `env` attributes, as shown in the following example:
 
@@ -105,7 +109,7 @@ If the builder exposes configuration options, those can be set using the `env` a
 				<plugin>
 					<groupId>org.springframework.boot</groupId>
 					<artifactId>spring-boot-maven-plugin</artifactId>
-					<version>{version}</version>
+					<version>{gradle-project-version}</version>
 					<configuration>
 						<image>
 							<builder>mine/java-cnb-builder</builder>
@@ -126,7 +130,7 @@ The example above assumes that `mine/java-cnb-builder` defines a `BP_JAVA_VERSIO
 
 [[build-image-example-custom-image-name]]
 ==== Custom Image Name
-By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:{project.version}`.
+By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.
 You can take control over the name, as shown in the following example:
 
 [source,xml,indent=0,subs="verbatim,attributes"]
@@ -137,7 +141,7 @@ You can take control over the name, as shown in the following example:
 				<plugin>
 					<groupId>org.springframework.boot</groupId>
 					<artifactId>spring-boot-maven-plugin</artifactId>
-					<version>{version}</version>
+					<version>{gradle-project-version}</version>
 					<configuration>
 						<image>
 							<name>example.com/library/${project.artifactId}</name>
@@ -149,5 +153,5 @@ You can take control over the name, as shown in the following example:
 	</project>
 ----
 
-Note that this configuration does not provide an explicit version so `latest` is used.
-It is possible to specify a version as well, either using `${project.version}`, any property available in the build or an hardcoded version.
+Note that this configuration does not provide an explicit tag so `latest` is used.
+It is possible to specify a tag as well, either using `${project.version}`, any property available in the build or a hardcoded version.