Commit 1702c9fc authored by Phillip Webb's avatar Phillip Webb

Rework title anchors for gradle docs

Closes gh-26618
parent f692b0e9
...@@ -23,6 +23,8 @@ repositories { ...@@ -23,6 +23,8 @@ repositories {
} }
dependencies { dependencies {
asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-section-ids")
implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-buildpack-platform")) implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-buildpack-platform"))
implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-loader-tools")) implementation(project(":spring-boot-project:spring-boot-tools:spring-boot-loader-tools"))
implementation("io.spring.gradle:dependency-management-plugin") implementation("io.spring.gradle:dependency-management-plugin")
...@@ -78,7 +80,6 @@ asciidoctor { ...@@ -78,7 +80,6 @@ asciidoctor {
sources { sources {
include "index.adoc" include "index.adoc"
} }
attributes "stylesheet": "css/style.css"
} }
task asciidoctorPdf(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) { task asciidoctorPdf(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) {
......
integrating-with-actuator=integrating-with-actuator
integrating-with-actuator-build-info=integrating-with-actuator.build-info
managing-dependencies=managing-dependencies
managing-dependencies-dependency-management-plugin=managing-dependencies.dependency-management-plugin
managing-dependencies-dependency-management-plugin-customizing=managing-dependencies.dependency-management-plugin.customizing
managing-dependencies-dependency-management-plugin-using-in-isolation=managing-dependencies.dependency-management-plugin.using-in-isolation
managing-dependencies-dependency-management-plugin-learning-more=managing-dependencies.dependency-management-plugin.learning-more
managing-dependencies-gradle-bom-support=managing-dependencies.gradle-bom-support
managing-dependencies-gradle-bom-support-customizing=managing-dependencies.gradle-bom-support.customizing
build-image=build-image
build-image-docker-daemon=build-image.docker-daemon
build-image-docker-registry=build-image.docker-registry
build-image-customization=build-image.customization
build-image-examples=build-image.examples
build-image-example-custom-image-builder=build-image.examples.custom-image-builder
build-image-example-builder-configuration=build-image.examples.builder-configuration
build-image-example-runtime-jvm-configuration=build-image.examples.runtime-jvm-configuration
build-image-example-custom-image-name=build-image.examples.custom-image-name
build-image-example-buildpacks=build-image.examples.buildpacks
build-image-example-publish=build-image.examples.publish
build-image-example-docker=build-image.examples.docker
packaging-executable=packaging-executable
packaging-executable-jars=packaging-executable.jars
packaging-executable-wars=packaging-executable.wars
packaging-executable-wars-deployable=packaging-executable.wars.deployable
packaging-executable-and-plain=packaging-executable.and-plain-archives
packaging-executable-configuring=packaging-executable.configuring
packaging-executable-configuring-main-class=packaging-executable.configuring.main-class
packaging-executable-configuring-including-development-only-dependencies=packaging-executable.configuring.including-development-only-dependencies
packaging-executable-configuring-unpacking=packaging-executable.configuring.unpacking
packaging-executable-configuring-launch-script=packaging-executable.configuring.launch-script
packaging-executable-configuring-properties-launcher=packaging-executable.configuring.properties-launcher
packaging-layered-archives=packaging-executable.configuring.layered-archives
packaging-layers-configuration=packaging-executable.configuring.layered-archives.configuration
publishing-your-application=publishing-your-application
publishing-your-application-maven-publish=publishing-your-application.maven-publish
publishing-your-application-maven=publishing-your-application.maven
publishing-your-application-distribution=publishing-your-application.distribution
reacting-to-other-plugins=reacting-to-other-plugins
reacting-to-other-plugins-java=reacting-to-other-plugins.java
reacting-to-other-plugins-kotlin=reacting-to-other-plugins.kotlin
reacting-to-other-plugins-war=reacting-to-other-plugins.war
reacting-to-other-plugins-dependency-management=reacting-to-other-plugins.dependency-management
reacting-to-other-plugins-application=reacting-to-other-plugins.application
running-your-application=running-your-application
running-your-application-passing-arguments=running-your-application.passing-arguments
running-your-application-passing-system-properties=running-your-application.passing-system-properties
running-your-application-reloading-resources=running-your-application.reloading-resources
[[getting-started]] [[getting-started]]
== Getting Started = Getting Started
To get started with the plugin it needs to be applied to your project. To get started with the plugin it needs to be applied to your project.
ifeval::["{spring-boot-artifactory-repo}" == "release"] ifeval::["{spring-boot-artifactory-repo}" == "release"]
......
...@@ -40,26 +40,20 @@ Andy Wilkinson, Scott Frederick ...@@ -40,26 +40,20 @@ Andy Wilkinson, Scott Frederick
[[introduction]] include::introduction.adoc[leveloffset=+1]
== Introduction
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
In addition to this user guide, {api-documentation}[API documentation] is also available. include::getting-started.adoc[leveloffset=+1]
include::getting-started.adoc[] include::managing-dependencies.adoc[leveloffset=+1]
include::managing-dependencies.adoc[] include::packaging.adoc[leveloffset=+1]
include::packaging.adoc[] include::packaging-oci-image.adoc[leveloffset=+1]
include::packaging-oci-image.adoc[] include::publishing.adoc[leveloffset=+1]
include::publishing.adoc[] include::running.adoc[leveloffset=+1]
include::running.adoc[] include::integrating-with-actuator.adoc[leveloffset=+1]
include::integrating-with-actuator.adoc[] include::reacting.adoc[leveloffset=+1]
include::reacting.adoc[]
[[integrating-with-actuator]] [[integrating-with-actuator]]
== Integrating with Actuator = Integrating with Actuator
[[integrating-with-actuator-build-info]] [[integrating-with-actuator.build-info]]
=== Generating Build Information == Generating Build Information
Spring Boot Actuator's `info` endpoint automatically publishes information about your build in the presence of a `META-INF/build-info.properties` file. Spring Boot Actuator's `info` endpoint automatically publishes information about your build in the presence of a `META-INF/build-info.properties` file.
A {build-info-javadoc}[`BuildInfo`] task is provided to generate this file. A {build-info-javadoc}[`BuildInfo`] task is provided to generate this file.
The easiest way to use the task is via the plugin's DSL: The easiest way to use the task is via the plugin's DSL:
......
[[introduction]]
= Introduction
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle].
It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
Spring Boot's Gradle plugin requires Gradle 6.8, 6.9, or 7.x and can be used with Gradle's {gradle-userguide}/configuration_cache.html[configuration cache].
In addition to this user guide, {api-documentation}[API documentation] is also available.
[[managing-dependencies]] [[managing-dependencies]]
== Managing Dependencies = Managing Dependencies
To manage dependencies in your Spring Boot application, you can either apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin or use Gradle's native bom support. To manage dependencies in your Spring Boot application, you can either apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin or use Gradle's native bom support.
The primary benefit of the former is that it offers property-based customization of managed versions, while using the latter will likely result in faster builds. The primary benefit of the former is that it offers property-based customization of managed versions, while using the latter will likely result in faster builds.
[[managing-dependencies-dependency-management-plugin]] [[managing-dependencies.dependency-management-plugin]]
=== Managing Dependencies with the Dependency Management Plugin == Managing Dependencies with the Dependency Management Plugin
When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins-dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using. When you apply the {dependency-management-plugin}[`io.spring.dependency-management`] plugin, Spring Boot's plugin will automatically <<reacting-to-other-plugins.dependency-management,import the `spring-boot-dependencies` bom>> from the version of Spring Boot that you are using.
This provides a similar dependency management experience to the one that's enjoyed by Maven users. This provides a similar dependency management experience to the one that's enjoyed by Maven users.
For example, it allows you to omit version numbers when declaring dependencies that are managed in the bom. For example, it allows you to omit version numbers when declaring dependencies that are managed in the bom.
To make use of this functionality, declare dependencies in the usual way but omit the version number: To make use of this functionality, declare dependencies in the usual way but omit the version number:
...@@ -26,8 +26,8 @@ include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependenci ...@@ -26,8 +26,8 @@ include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependenci
[[managing-dependencies-dependency-management-plugin-customizing]] [[managing-dependencies.dependency-management-plugin.customizing]]
==== Customizing Managed Versions === Customizing Managed Versions
The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages. The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages.
Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of these properties. Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of these properties.
...@@ -51,8 +51,8 @@ Overriding versions may cause compatibility issues and should be done with care. ...@@ -51,8 +51,8 @@ Overriding versions may cause compatibility issues and should be done with care.
[[managing-dependencies-dependency-management-plugin-using-in-isolation]] [[managing-dependencies.dependency-management-plugin.using-in-isolation]]
==== Using Spring Boot's Dependency Management in Isolation === Using Spring Boot's Dependency Management in Isolation
Spring Boot's dependency management can be used in a project without applying Spring Boot's plugin to that project. Spring Boot's dependency management can be used in a project without applying Spring Boot's plugin to that project.
The `SpringBootPlugin` class provides a `BOM_COORDINATES` constant that can be used to import the bom without having to know its group ID, artifact ID, or version. The `SpringBootPlugin` class provides a `BOM_COORDINATES` constant that can be used to import the bom without having to know its group ID, artifact ID, or version.
...@@ -126,14 +126,14 @@ include::../gradle/managing-dependencies/configure-bom-with-plugins.gradle.kts[t ...@@ -126,14 +126,14 @@ include::../gradle/managing-dependencies/configure-bom-with-plugins.gradle.kts[t
[[managing-dependencies-dependency-management-plugin-learning-more]] [[managing-dependencies.dependency-management-plugin.learning-more]]
==== Learning More === Learning More
To learn more about the capabilities of the dependency management plugin, please refer to its {dependency-management-plugin-documentation}[documentation]. To learn more about the capabilities of the dependency management plugin, please refer to its {dependency-management-plugin-documentation}[documentation].
[[managing-dependencies-gradle-bom-support]] [[managing-dependencies.gradle-bom-support]]
=== Managing Dependencies with Gradle's Bom Support == Managing Dependencies with Gradle's Bom Support
Gradle allows a bom to be used to manage a project's versions by declaring it as a `platform` or `enforcedPlatform` dependency. Gradle allows a bom to be used to manage a project's versions by declaring it as a `platform` or `enforcedPlatform` dependency.
A `platform` dependency treats the versions in the bom as recommendations and other versions and constraints in the dependency graph may cause a version of a dependency other than that declared in the bom to be used. A `platform` dependency treats the versions in the bom as recommendations and other versions and constraints in the dependency graph may cause a version of a dependency other than that declared in the bom to be used.
An `enforcedPlatform` dependency treats the versions in the bom as requirements and they will override any other version found in the dependency graph. An `enforcedPlatform` dependency treats the versions in the bom as requirements and they will override any other version found in the dependency graph.
...@@ -157,8 +157,8 @@ As a result, in may be necessary to declare the same dependency in more than one ...@@ -157,8 +157,8 @@ As a result, in may be necessary to declare the same dependency in more than one
[[managing-dependencies-gradle-bom-support-customizing]] [[managing-dependencies.gradle-bom-support.customizing]]
==== Customizing Managed Versions === Customizing Managed Versions
When using Gradle's bom support, you cannot use the properties from `spring-boot-dependencies` to control the versions of the dependencies that it manages. When using Gradle's bom support, you cannot use the properties from `spring-boot-dependencies` to control the versions of the dependencies that it manages.
Instead, you must use one of the mechanisms that Gradle provides. Instead, you must use one of the mechanisms that Gradle provides.
One such mechanism is a resolution strategy. One such mechanism is a resolution strategy.
......
[[build-image]] [[build-image]]
== Packaging OCI Images = Packaging OCI Images
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io[Cloud Native Buildpacks] (CNB). The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io[Cloud Native Buildpacks] (CNB).
Images can be built using the `bootBuildImage` task. Images can be built using the `bootBuildImage` task.
...@@ -8,13 +8,13 @@ See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specificat ...@@ -8,13 +8,13 @@ See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specificat
The task is automatically created when the `java` or `war` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`]. The task is automatically created when the `java` or `war` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable-configuring-launch-script, fully executable Spring Boot archive>> that includes a launch script. NOTE: The `bootBuildImage` task can not be used with a <<packaging-executable.configuring.launch-script, fully executable Spring Boot archive>> that includes a launch script.
Disable launch script configuration in the `bootJar` task when building a jar file that is intended to be used with `bootBuildImage`. Disable launch script configuration in the `bootJar` task when building a jar file that is intended to be used with `bootBuildImage`.
[[build-image-docker-daemon]] [[build-image.docker-daemon]]
=== Docker Daemon == Docker Daemon
The `bootBuildImage` task requires access to a Docker daemon. The `bootBuildImage` task requires access to a Docker daemon.
By default, it will communicate with a Docker daemon over a local connection. By default, it will communicate with a Docker daemon over a local connection.
This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration. This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration.
...@@ -53,12 +53,12 @@ The following table summarizes the available properties: ...@@ -53,12 +53,12 @@ The following table summarizes the available properties:
| Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise) | Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise)
|=== |===
For more details, see also <<build-image-example-docker,examples>>. For more details, see also <<build-image.examples.docker,examples>>.
[[build-image-docker-registry]] [[build-image.docker-registry]]
=== Docker Registry == Docker Registry
If the Docker images specified by the `builder` or `runImage` properties are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` properties. If the Docker images specified by the `builder` or `runImage` properties are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` properties.
If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` properties. If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` properties.
...@@ -87,12 +87,12 @@ The following table summarizes the available properties for `docker.builderRegis ...@@ -87,12 +87,12 @@ The following table summarizes the available properties for `docker.builderRegis
| Identity token for the Docker image registry user. Required for token authentication. | Identity token for the Docker image registry user. Required for token authentication.
|=== |===
For more details, see also <<build-image-example-docker,examples>>. For more details, see also <<build-image.examples.docker,examples>>.
[[build-image-customization]] [[build-image.customization]]
=== Image Customizations == Image Customizations
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image. 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. 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. By default, the plugin chooses a builder image.
...@@ -176,17 +176,17 @@ Where `<options>` can contain: ...@@ -176,17 +176,17 @@ Where `<options>` can contain:
NOTE: The plugin detects the target Java compatibility of the project using the JavaPlugin's `targetCompatibility` property. NOTE: The plugin detects the target Java compatibility of the project using the JavaPlugin's `targetCompatibility` property.
When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version. When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version.
You can override this behaviour as shown in the <<build-image-example-builder-configuration,builder configuration>> examples. You can override this behaviour as shown in the <<build-image.examples.builder-configuration,builder configuration>> examples.
[[build-image-examples]] [[build-image.examples]]
=== Examples == Examples
[[build-image-example-custom-image-builder]] [[build-image.examples.custom-image-builder]]
==== Custom Image Builder and Run Image === Custom Image Builder and Run Image
If you need to customize the builder used to create the image or the run image used to launch the built image, configure the task as shown in the following example: If you need to customize the builder used to create the image or the run image used to launch the built image, configure the task as shown in the following example:
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
...@@ -212,8 +212,8 @@ The builder and run image can be specified on the command line as well, as shown ...@@ -212,8 +212,8 @@ The builder and run image can be specified on the command line as well, as shown
[[build-image-example-builder-configuration]] [[build-image.examples.builder-configuration]]
==== Builder Configuration === Builder Configuration
If the builder exposes configuration options, those can be set using the `environment` property. If the builder exposes configuration options, those can be set using the `environment` property.
The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time: The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time:
...@@ -247,8 +247,8 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env] ...@@ -247,8 +247,8 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env]
[[build-image-example-runtime-jvm-configuration]] [[build-image.examples.runtime-jvm-configuration]]
==== Runtime JVM Configuration === Runtime JVM Configuration
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable. Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container. The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
...@@ -268,8 +268,8 @@ include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-ru ...@@ -268,8 +268,8 @@ include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-ru
[[build-image-example-custom-image-name]] [[build-image.examples.custom-image-name]]
==== Custom Image Name === Custom Image Name
By default, the image name is inferred from the `name` and the `version` of the project, something like `docker.io/library/${project.name}:${project.version}`. By default, the image name is inferred from the `name` and the `version` of the project, something like `docker.io/library/${project.name}:${project.version}`.
You can take control over the name by setting task properties, as shown in the following example: You can take control over the name by setting task properties, as shown in the following example:
...@@ -297,8 +297,8 @@ The image name can be specified on the command line as well, as shown in this ex ...@@ -297,8 +297,8 @@ The image name can be specified on the command line as well, as shown in this ex
[[build-image-example-buildpacks]] [[build-image.examples.buildpacks]]
==== Buildpacks === Buildpacks
By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order. 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. 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. When one or more buildpacks are provided, only the specified buildpacks will be applied.
...@@ -347,8 +347,8 @@ An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/pack ...@@ -347,8 +347,8 @@ An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/pack
[[build-image-example-publish]] [[build-image.examples.publish]]
==== Image Publishing === 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. 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.
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
...@@ -372,8 +372,8 @@ The publish option can be specified on the command line as well, as shown in thi ...@@ -372,8 +372,8 @@ The publish option can be specified on the command line as well, as shown in thi
[[build-image-example-docker]] [[build-image.examples.docker]]
==== Docker Configuration === 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: 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"] [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
......
[[packaging-executable]] [[packaging-executable]]
== Packaging Executable Archives = Packaging Executable Archives
The plugin can create executable archives (jar files and war files) that contain all of an application's dependencies and can then be run with `java -jar`. The plugin can create executable archives (jar files and war files) that contain all of an application's dependencies and can then be run with `java -jar`.
[[packaging-executable-jars]] [[packaging-executable.jars]]
=== Packaging Executable Jars == Packaging Executable Jars
Executable jars can be built using the `bootJar` task. Executable jars can be built using the `bootJar` task.
The task is automatically created when the `java` plugin is applied and is an instance of {boot-jar-javadoc}[`BootJar`]. The task is automatically created when the `java` plugin is applied and is an instance of {boot-jar-javadoc}[`BootJar`].
The `assemble` task is automatically configured to depend upon the `bootJar` task so running `assemble` (or `build`) will also run the `bootJar` task. The `assemble` task is automatically configured to depend upon the `bootJar` task so running `assemble` (or `build`) will also run the `bootJar` task.
[[packaging-executable-wars]] [[packaging-executable.wars]]
=== Packaging Executable Wars == Packaging Executable Wars
Executable wars can be built using the `bootWar` task. Executable wars can be built using the `bootWar` task.
The task is automatically created when the `war` plugin is applied and is an instance of {boot-war-javadoc}[`BootWar`]. The task is automatically created when the `war` plugin is applied and is an instance of {boot-war-javadoc}[`BootWar`].
The `assemble` task is automatically configured to depend upon the `bootWar` task so running `assemble` (or `build`) will also run the `bootWar` task. The `assemble` task is automatically configured to depend upon the `bootWar` task so running `assemble` (or `build`) will also run the `bootWar` task.
[[packaging-executable-wars-deployable]] [[packaging-executable.wars.deployable]]
==== Packaging Executable and Deployable Wars === Packaging Executable and Deployable Wars
A war file can be packaged such that it can be executed using `java -jar` and deployed to an external container. A war file can be packaged such that it can be executed using `java -jar` and deployed to an external container.
To do so, the embedded servlet container dependencies should be added to the `providedRuntime` configuration, for example: To do so, the embedded servlet container dependencies should be added to the `providedRuntime` configuration, for example:
...@@ -43,8 +43,8 @@ NOTE: `providedRuntime` is preferred to Gradle's `compileOnly` configuration as, ...@@ -43,8 +43,8 @@ NOTE: `providedRuntime` is preferred to Gradle's `compileOnly` configuration as,
[[packaging-executable-and-plain]] [[packaging-executable.and-plain-archives]]
=== Packaging Executable and Plain Archives == Packaging Executable and Plain Archives
By default, when the `bootJar` or `bootWar` tasks are configured, the `jar` or `war` tasks are configured to use `plain` as the convention for their archive classifier. By default, when the `bootJar` or `bootWar` tasks are configured, the `jar` or `war` tasks are configured to use `plain` as the convention for their archive classifier.
This ensures that `bootJar` and `jar` or `bootWar` and `war` have different output locations, allowing both the executable archive and the plain archive to be built at the same time. This ensures that `bootJar` and `jar` or `bootWar` and `war` have different output locations, allowing both the executable archive and the plain archive to be built at the same time.
...@@ -78,16 +78,16 @@ include::../gradle/packaging/only-boot-jar.gradle.kts[tags=disable-jar] ...@@ -78,16 +78,16 @@ include::../gradle/packaging/only-boot-jar.gradle.kts[tags=disable-jar]
[[packaging-executable-configuring]] [[packaging-executable.configuring]]
=== Configuring Executable Archive Packaging == Configuring Executable Archive Packaging
The {boot-jar-javadoc}[`BootJar`] and {boot-war-javadoc}[`BootWar`] tasks are subclasses of Gradle's `Jar` and `War` tasks respectively. The {boot-jar-javadoc}[`BootJar`] and {boot-war-javadoc}[`BootWar`] tasks are subclasses of Gradle's `Jar` and `War` tasks respectively.
As a result, all of the standard configuration options that are available when packaging a jar or war are also available when packaging an executable jar or war. As a result, all of the standard configuration options that are available when packaging a jar or war are also available when packaging an executable jar or war.
A number of configuration options that are specific to executable jars and wars are also provided. A number of configuration options that are specific to executable jars and wars are also provided.
[[packaging-executable-configuring-main-class]] [[packaging-executable.configuring.main-class]]
==== Configuring the Main Class === Configuring the Main Class
By default, the executable archive's main class will be configured automatically by looking for a class with a `public static void main(String[])` method in directories on the task's classpath. By default, the executable archive's main class will be configured automatically by looking for a class with a `public static void main(String[])` method in directories on the task's classpath.
The main class can also be configured explicitly using the task's `mainClass` property: The main class can also be configured explicitly using the task's `mainClass` property:
...@@ -153,8 +153,8 @@ If another name is defined using `@JvmName` then that name should be used. ...@@ -153,8 +153,8 @@ If another name is defined using `@JvmName` then that name should be used.
[[packaging-executable-configuring-including-development-only-dependencies]] [[packaging-executable.configuring.including-development-only-dependencies]]
==== Including Development-only Dependencies === Including Development-only Dependencies
By default all dependencies declared in the `developmentOnly` configuration will be excluded from an executable jar or war. By default all dependencies declared in the `developmentOnly` configuration will be excluded from an executable jar or war.
If you want to include dependencies declared in the `developmentOnly` configuration in your archive, configure the classpath of its task to include the configuration, as shown in the following example for the `bootWar` task: If you want to include dependencies declared in the `developmentOnly` configuration in your archive, configure the classpath of its task to include the configuration, as shown in the following example for the `bootWar` task:
...@@ -173,8 +173,8 @@ include::../gradle/packaging/boot-war-include-devtools.gradle.kts[tags=include-d ...@@ -173,8 +173,8 @@ include::../gradle/packaging/boot-war-include-devtools.gradle.kts[tags=include-d
[[packaging-executable-configuring-unpacking]] [[packaging-executable.configuring.unpacking]]
==== Configuring Libraries that Require Unpacking === Configuring Libraries that Require Unpacking
Most libraries can be used directly when nested in an executable archive, however certain libraries can have problems. Most libraries can be used directly when nested in an executable archive, however certain libraries can have problems.
For example, JRuby includes its own nested jar support which assumes that `jruby-complete.jar` is always directly available on the file system. For example, JRuby includes its own nested jar support which assumes that `jruby-complete.jar` is always directly available on the file system.
...@@ -198,8 +198,8 @@ The closure is passed a `FileTreeElement` and should return a `boolean` indicati ...@@ -198,8 +198,8 @@ The closure is passed a `FileTreeElement` and should return a `boolean` indicati
[[packaging-executable-configuring-launch-script]] [[packaging-executable.configuring.launch-script]]
==== Making an Archive Fully Executable === Making an Archive Fully Executable
Spring Boot provides support for fully executable archives. Spring Boot provides support for fully executable archives.
An archive is made fully executable by prepending a shell script that knows how to launch the application. An archive is made fully executable by prepending a shell script that knows how to launch the application.
On Unix-like platforms, this launch script allows the archive to be run directly like any other executable or to be installed as a service. On Unix-like platforms, this launch script allows the archive to be run directly like any other executable or to be installed as a service.
...@@ -254,8 +254,8 @@ include::../gradle/packaging/boot-jar-custom-launch-script.gradle.kts[tags=custo ...@@ -254,8 +254,8 @@ include::../gradle/packaging/boot-jar-custom-launch-script.gradle.kts[tags=custo
[[packaging-executable-configuring-properties-launcher]] [[packaging-executable.configuring.properties-launcher]]
==== Using the PropertiesLauncher === Using the PropertiesLauncher
To use the `PropertiesLauncher` to launch an executable jar or war, configure the task's manifest to set the `Main-Class` attribute: To use the `PropertiesLauncher` to launch an executable jar or war, configure the task's manifest to set the `Main-Class` attribute:
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
...@@ -272,8 +272,8 @@ include::../gradle/packaging/boot-war-properties-launcher.gradle.kts[tags=proper ...@@ -272,8 +272,8 @@ include::../gradle/packaging/boot-war-properties-launcher.gradle.kts[tags=proper
[[packaging-layered-archives]] [[packaging-executable.configuring.layered-archives]]
==== Packaging Layered Jar or War === Packaging Layered Jar or War
By default, the `bootJar` task builds an archive that contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively. By default, the `bootJar` task builds an archive that contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively.
Similarly, `bootWar` builds an archive that contains the application's classes in `WEB-INF/classes` and dependencies in `WEB-INF/lib` and `WEB-INF/lib-provided`. Similarly, `bootWar` builds an archive that contains the application's classes in `WEB-INF/classes` and dependencies in `WEB-INF/lib` and `WEB-INF/lib-provided`.
For cases where a docker image needs to be built from the contents of the jar, it's useful to be able to separate these directories further so that they can be written into distinct layers. For cases where a docker image needs to be built from the contents of the jar, it's useful to be able to separate these directories further so that they can be written into distinct layers.
...@@ -323,8 +323,8 @@ include::../gradle/packaging/boot-jar-layered-exclude-tools.gradle.kts[tags=laye ...@@ -323,8 +323,8 @@ include::../gradle/packaging/boot-jar-layered-exclude-tools.gradle.kts[tags=laye
[[packaging-layers-configuration]] [[packaging-executable.configuring.layered-archives.configuration]]
===== Custom Layers Configuration ==== Custom Layers Configuration
Depending on your application, you may want to tune how layers are created and add new ones. Depending on your application, you may want to tune how layers are created and add new ones.
This can be done using configuration that describes how the jar or war can be separated into layers, and the order of those layers. This can be done using configuration that describes how the jar or war can be separated into layers, and the order of those layers.
......
[[publishing-your-application]] [[publishing-your-application]]
== Publishing your Application = Publishing your Application
[[publishing-your-application-maven-publish]] [[publishing-your-application.maven-publish]]
=== Publishing with the Maven-publish Plugin == Publishing with the Maven-publish Plugin
To publish your Spring Boot jar or war, add it to the publication using the `artifact` method on `MavenPublication`. To publish your Spring Boot jar or war, add it to the publication using the `artifact` method on `MavenPublication`.
Pass the task that produces that artifact that you wish to publish to the `artifact` method. Pass the task that produces that artifact that you wish to publish to the `artifact` method.
For example, to publish the artifact produced by the default `bootJar` task: For example, to publish the artifact produced by the default `bootJar` task:
...@@ -23,8 +23,8 @@ include::../gradle/publishing/maven-publish.gradle.kts[tags=publishing] ...@@ -23,8 +23,8 @@ include::../gradle/publishing/maven-publish.gradle.kts[tags=publishing]
[[publishing-your-application-maven]] [[publishing-your-application.maven]]
=== Publishing with the Maven Plugin == Publishing with the Maven Plugin
WARNING: Due to its deprecation in Gradle 6, this plugin's support for publishing with Gradle's `maven` plugin is deprecated and will be removed in a future release. WARNING: Due to its deprecation in Gradle 6, this plugin's support for publishing with Gradle's `maven` plugin is deprecated and will be removed in a future release.
Please use the `maven-publish` plugin instead. Please use the `maven-publish` plugin instead.
...@@ -46,8 +46,8 @@ include::../gradle/publishing/maven.gradle.kts[tags=upload] ...@@ -46,8 +46,8 @@ include::../gradle/publishing/maven.gradle.kts[tags=upload]
[[publishing-your-application-distribution]] [[publishing-your-application.distribution]]
=== Distributing with the Application Plugin == Distributing with the Application Plugin
When the {application-plugin}[`application` plugin] is applied a distribution named `boot` is created. When the {application-plugin}[`application` plugin] is applied a distribution named `boot` is created.
This distribution contains the archive produced by the `bootJar` or `bootWar` task and scripts to launch it on Unix-like platforms and Windows. This distribution contains the archive produced by the `bootJar` or `bootWar` task and scripts to launch it on Unix-like platforms and Windows.
Zip and tar distributions can be built by the `bootDistZip` and `bootDistTar` tasks respectively. Zip and tar distributions can be built by the `bootDistZip` and `bootDistTar` tasks respectively.
......
[[reacting-to-other-plugins]] [[reacting-to-other-plugins]]
== Reacting to Other Plugins = Reacting to Other Plugins
When another plugin is applied the Spring Boot plugin reacts by making various changes to the project's configuration. When another plugin is applied the Spring Boot plugin reacts by making various changes to the project's configuration.
This section describes those changes. This section describes those changes.
[[reacting-to-other-plugins-java]] [[reacting-to-other-plugins.java]]
=== Reacting to the Java Plugin == Reacting to the Java Plugin
When Gradle's {java-plugin}[`java` plugin] is applied to a project, the Spring Boot plugin: When Gradle's {java-plugin}[`java` plugin] is applied to a project, the Spring Boot plugin:
1. Creates a {boot-jar-javadoc}[`BootJar`] task named `bootJar` that will create an executable, fat jar for the project. 1. Creates a {boot-jar-javadoc}[`BootJar`] task named `bootJar` that will create an executable, fat jar for the project.
...@@ -22,8 +22,8 @@ When Gradle's {java-plugin}[`java` plugin] is applied to a project, the Spring B ...@@ -22,8 +22,8 @@ When Gradle's {java-plugin}[`java` plugin] is applied to a project, the Spring B
[[reacting-to-other-plugins-kotlin]] [[reacting-to-other-plugins.kotlin]]
=== Reacting to the Kotlin Plugin == Reacting to the Kotlin Plugin
When {kotlin-plugin}[Kotlin's Gradle plugin] is applied to a project, the Spring Boot plugin: When {kotlin-plugin}[Kotlin's Gradle plugin] is applied to a project, the Spring Boot plugin:
1. Aligns the Kotlin version used in Spring Boot's dependency management with the version of the plugin. 1. Aligns the Kotlin version used in Spring Boot's dependency management with the version of the plugin.
...@@ -32,8 +32,8 @@ When {kotlin-plugin}[Kotlin's Gradle plugin] is applied to a project, the Spring ...@@ -32,8 +32,8 @@ When {kotlin-plugin}[Kotlin's Gradle plugin] is applied to a project, the Spring
[[reacting-to-other-plugins-war]] [[reacting-to-other-plugins.war]]
=== Reacting to the War Plugin == Reacting to the War Plugin
When Gradle's {war-plugin}[`war` plugin] is applied to a project, the Spring Boot plugin: When Gradle's {war-plugin}[`war` plugin] is applied to a project, the Spring Boot plugin:
1. Creates a {boot-war-javadoc}[`BootWar`] task named `bootWar` that will create an executable, fat war for the project. 1. Creates a {boot-war-javadoc}[`BootWar`] task named `bootWar` that will create an executable, fat war for the project.
...@@ -44,14 +44,14 @@ When Gradle's {war-plugin}[`war` plugin] is applied to a project, the Spring Boo ...@@ -44,14 +44,14 @@ When Gradle's {war-plugin}[`war` plugin] is applied to a project, the Spring Boo
[[reacting-to-other-plugins-dependency-management]] [[reacting-to-other-plugins.dependency-management]]
=== Reacting to the Dependency Management Plugin == Reacting to the Dependency Management Plugin
When the {dependency-management-plugin}[`io.spring.dependency-management` plugin] is applied to a project, the Spring Boot plugin will automatically import the `spring-boot-dependencies` bom. When the {dependency-management-plugin}[`io.spring.dependency-management` plugin] is applied to a project, the Spring Boot plugin will automatically import the `spring-boot-dependencies` bom.
[[reacting-to-other-plugins-application]] [[reacting-to-other-plugins.application]]
=== Reacting to the Application Plugin == Reacting to the Application Plugin
When Gradle's {application-plugin}[`application` plugin] is applied to a project, the Spring Boot plugin: When Gradle's {application-plugin}[`application` plugin] is applied to a project, the Spring Boot plugin:
1. Creates a `CreateStartScripts` task named `bootStartScripts` that will create scripts that launch the artifact in the `bootArchives` configuration using `java -jar`. 1. Creates a `CreateStartScripts` task named `bootStartScripts` that will create scripts that launch the artifact in the `bootArchives` configuration using `java -jar`.
...@@ -65,7 +65,7 @@ When Gradle's {application-plugin}[`application` plugin] is applied to a project ...@@ -65,7 +65,7 @@ When Gradle's {application-plugin}[`application` plugin] is applied to a project
[[reacting-to-other-plugins-maven]] [[reacting-to-other-plugins-maven]]
=== Reacting to the Maven plugin =Í= Reacting to the Maven plugin
WARNING: Support for reacting to Gradle's `maven` plugin is deprecated and will be removed in a future release. WARNING: Support for reacting to Gradle's `maven` plugin is deprecated and will be removed in a future release.
Please use the `maven-publish` plugin instead. Please use the `maven-publish` plugin instead.
......
[[running-your-application]] [[running-your-application]]
== Running your Application with Gradle = Running your Application with Gradle
To run your application without first building an archive use the `bootRun` task: To run your application without first building an archive use the `bootRun` task:
[source,bash,indent=0,subs="verbatim"] [source,bash,indent=0,subs="verbatim"]
...@@ -72,8 +72,8 @@ include::../gradle/running/application-plugin-main-class-name.gradle.kts[tags=ma ...@@ -72,8 +72,8 @@ include::../gradle/running/application-plugin-main-class-name.gradle.kts[tags=ma
[[running-your-application-passing-arguments]] [[running-your-application.passing-arguments]]
=== Passing Arguments to your Application == Passing Arguments to your Application
Like all `JavaExec` tasks, arguments can be passed into `bootRun` from the command line using `--args='<arguments>'` when using Gradle 4.9 or later. Like all `JavaExec` tasks, arguments can be passed into `bootRun` from the command line using `--args='<arguments>'` when using Gradle 4.9 or later.
For example, to run your application with a profile named `dev` active the following command can be used: For example, to run your application with a profile named `dev` active the following command can be used:
...@@ -86,8 +86,8 @@ See {gradle-api}/org/gradle/api/tasks/JavaExec.html#setArgsString-java.lang.Stri ...@@ -86,8 +86,8 @@ See {gradle-api}/org/gradle/api/tasks/JavaExec.html#setArgsString-java.lang.Stri
[[running-your-application-passing-system-properties]] [[running-your-application.passing-system-properties]]
=== Passing System properties to your application == Passing System properties to your application
Since `bootRun` is a standard `JavaExec` task, system properties can be passed to the application's JVM by specifying them in the build script. Since `bootRun` is a standard `JavaExec` task, system properties can be passed to the application's JVM by specifying them in the build script.
To make that value of a system property to be configurable set its value using a {gradle-dsl}/org.gradle.api.Project.html#N14FE1[project property]. To make that value of a system property to be configurable set its value using a {gradle-dsl}/org.gradle.api.Project.html#N14FE1[project property].
To allow a project property to be optional, reference it using `findProperty`. To allow a project property to be optional, reference it using `findProperty`.
...@@ -120,8 +120,8 @@ The preceding example sets the value of the `example` project property to `custo ...@@ -120,8 +120,8 @@ The preceding example sets the value of the `example` project property to `custo
[[running-your-application-reloading-resources]] [[running-your-application.reloading-resources]]
=== Reloading Resources == Reloading Resources
If devtools has been added to your project it will automatically monitor your application for changes. If devtools has been added to your project it will automatically monitor your application for changes.
Alternatively, you can configure `bootRun` such that your application's static resources are loaded from their source location: Alternatively, you can configure `bootRun` such that your application's static resources are loaded from their source location:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment