Consolidate Maven plugin documentation in plugin reference
This commit moves Maven plugin content from several sections in the main Spring Boot reference documentation to the plugin-specific documentation. Fixes gh-19165
This commit is contained in:
Scott Frederick
@@ -30,7 +30,7 @@
|
||||
:spring-boot-current-docs: https://docs.spring.io/spring-boot/docs/current/reference/
|
||||
:spring-boot-actuator-restapi: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/actuator-api/
|
||||
:spring-boot-maven-plugin-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/reference/html/
|
||||
:spring-boot-maven-plugin-pdfdocs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/reference/pdf/spring-boot-gradle-plugin-reference.pdf
|
||||
:spring-boot-maven-plugin-pdfdocs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/reference/pdf/spring-boot-maven-plugin-reference.pdf
|
||||
:spring-boot-maven-plugin-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/api/
|
||||
:spring-boot-gradle-plugin-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/reference/html/
|
||||
:spring-boot-gradle-plugin-pdfdocs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/reference/pdf/spring-boot-gradle-plugin-reference.pdf
|
||||
|
||||
@@ -20,146 +20,6 @@ Please refer to the plugin's documentation to learn more:
|
||||
* {spring-boot-maven-plugin-api}[API]
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins-include-maven-plugin]]
|
||||
=== Including the Plugin
|
||||
To use the Spring Boot Maven Plugin, include the appropriate XML in the `plugins` section of your `pom.xml`, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<!-- ... -->
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<version>{spring-boot-version}</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>repackage</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
----
|
||||
|
||||
The preceding configuration repackages a jar or war that is built during the `package` phase of the Maven lifecycle.
|
||||
The following example shows both the repackaged jar as well as the original jar in the `target` directory:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ mvn package
|
||||
$ ls target/*.jar
|
||||
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
|
||||
----
|
||||
|
||||
|
||||
If you do not include the `<execution/>` configuration, as shown in the prior example, you can run the plugin on its own (but only if the package goal is used as well), as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ mvn package spring-boot:repackage
|
||||
$ ls target/*.jar
|
||||
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
|
||||
----
|
||||
|
||||
If you use a milestone or snapshot release, you also need to add the appropriate `pluginRepository` elements, as shown in the following listing:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>spring-snapshots</id>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-milestones</id>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins-maven-packaging]]
|
||||
=== Packaging Executable Jar and War Files
|
||||
Once `spring-boot-maven-plugin` has been included in your `pom.xml`, it automatically tries to rewrite archives to make them executable by using the `spring-boot:repackage` goal.
|
||||
You should configure your project to build a jar or war (as appropriate) by using the usual `packaging` element, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<!-- ... -->
|
||||
<packaging>jar</packaging>
|
||||
<!-- ... -->
|
||||
</project>
|
||||
----
|
||||
|
||||
Your existing archive is enhanced by Spring Boot during the `package` phase.
|
||||
The main class that you want to launch can be specified either by using a configuration option, as shown below, or by adding a `Main-Class` attribute to the manifest.
|
||||
If you do not specify a main class, the plugin searches for a class with a `public static void main(String[] args)` method.
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<configuration>
|
||||
<mainClass>com.example.app.Main</mainClass>
|
||||
</configuration>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
|
||||
To build and run a project artifact, you can type the following:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ mvn package
|
||||
$ java -jar target/mymodule-0.0.1-SNAPSHOT.jar
|
||||
----
|
||||
|
||||
To build a war file that is both executable and deployable into an external container, you need to mark the embedded container dependencies as "`provided`", as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<!-- ... -->
|
||||
<packaging>war</packaging>
|
||||
<!-- ... -->
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
<!-- ... -->
|
||||
</dependencies>
|
||||
</project>
|
||||
----
|
||||
|
||||
TIP: See the "`<<howto.adoc#howto-create-a-deployable-war-file>>`" section for more details on how to create a deployable war file.
|
||||
|
||||
Advanced configuration options and examples are available in the {spring-boot-maven-plugin-docs}[plugin info page].
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins-gradle-plugin]]
|
||||
== Spring Boot Gradle Plugin
|
||||
The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, letting you package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by `spring-boot-dependencies`.
|
||||
|
||||
@@ -108,88 +108,7 @@ Spring Boot dependencies use the `org.springframework.boot` `groupId`.
|
||||
Typically, your Maven POM file inherits from the `spring-boot-starter-parent` project and declares dependencies to one or more <<using-spring-boot.adoc#using-boot-starter,"`Starters`">>.
|
||||
Spring Boot also provides an optional <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> to create executable jars.
|
||||
|
||||
The following listing shows a typical `pom.xml` file:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<groupId>com.example</groupId>
|
||||
<artifactId>myproject</artifactId>
|
||||
<version>0.0.1-SNAPSHOT</version>
|
||||
|
||||
<!-- Inherit defaults from Spring Boot -->
|
||||
<parent>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-parent</artifactId>
|
||||
<version>{spring-boot-version}</version>
|
||||
</parent>
|
||||
|
||||
<!-- Override inherited settings -->
|
||||
<description/>
|
||||
<developers>
|
||||
<developer/>
|
||||
</developers>
|
||||
<licenses>
|
||||
<license/>
|
||||
</licenses>
|
||||
<scm>
|
||||
<url/>
|
||||
</scm>
|
||||
<url/>
|
||||
|
||||
<!-- Add typical dependencies for a web application -->
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<!-- Package as an executable jar -->
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
|
||||
ifeval::["{spring-boot-artifactory-repo}" != "release"]
|
||||
<!-- Add Spring repositories -->
|
||||
<!-- (you don't need this if you are using a .RELEASE version) -->
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>spring-snapshots</id>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
<snapshots><enabled>true</enabled></snapshots>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>spring-milestones</id>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>spring-snapshots</id>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-milestones</id>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
endif::[]
|
||||
</project>
|
||||
----
|
||||
|
||||
TIP: The `spring-boot-starter-parent` is a great way to use Spring Boot, but it might not be suitable all of the time.
|
||||
Sometimes you may need to inherit from a different parent POM, or you might not like our default settings.
|
||||
In those cases, see <<using-spring-boot.adoc#using-boot-maven-without-a-parent>> for an alternative solution that uses an `import` scope.
|
||||
More details on getting started with Spring Boot and Maven can be found in the {spring-boot-maven-plugin-docs}/#getting-started[Getting Started section] of the Maven plugin's reference guide.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -2440,23 +2440,14 @@ Using this format lets the time be parsed into a `Date` and its format, when ser
|
||||
|
||||
[[howto-customize-dependency-versions]]
|
||||
=== Customize Dependency Versions
|
||||
If you use a Maven build that inherits directly or indirectly from `spring-boot-dependencies` (for instance, `spring-boot-starter-parent`) but you want to override a specific third-party dependency, you can add appropriate `<properties>` elements.
|
||||
Browse the <<appendix-dependency-versions.adoc#dependency-versions-properties, `Version properties`>> for a complete list of version properties.
|
||||
For example, to pick a different `slf4j` version, you would add the following property:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<slf4j.version>1.7.5<slf4j.version>
|
||||
</properties>
|
||||
----
|
||||
|
||||
NOTE: Doing so only works if your Maven project inherits (directly or indirectly) from `spring-boot-dependencies`.
|
||||
If you have added `spring-boot-dependencies` in your own `dependencyManagement` section with `<scope>import</scope>`, you have to redefine the artifact yourself instead of overriding the property.
|
||||
The `spring-boot-dependencies` POM manages the versions of common dependencies.
|
||||
The Spring Boot plugins for Maven and Gradle allow these managed dependency versions to be customized using build properties.
|
||||
|
||||
WARNING: Each Spring Boot release is designed and tested against this specific set of third-party dependencies.
|
||||
Overriding versions may cause compatibility issues.
|
||||
|
||||
To override dependency versions with Maven, see {spring-boot-maven-plugin-docs}/#using[this section] of the Maven plugin's documentation.
|
||||
|
||||
To override dependency versions in Gradle, see {spring-boot-gradle-plugin-docs}/#managing-dependencies-customizing[this section] of the Gradle plugin's documentation.
|
||||
|
||||
|
||||
@@ -2501,7 +2492,7 @@ However, you must additionally add an `<executions>` section, as follows:
|
||||
</build>
|
||||
----
|
||||
|
||||
See the {spring-boot-maven-plugin-docs}#getting-started[plugin documentation] for full usage details.
|
||||
See the {spring-boot-maven-plugin-docs}#repackage[plugin documentation] for full usage details.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[[spring-boot-reference-documentation]]
|
||||
= Spring Boot Reference Documentation
|
||||
Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave, Eddú Meléndez
|
||||
Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave, Eddú Meléndez, Scott Frederick
|
||||
:docinfo: shared
|
||||
|
||||
The reference documentation consists of the following sections:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[[spring-boot-reference-documentation]]
|
||||
= Spring Boot Reference Documentation
|
||||
Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave
|
||||
Phillip Webb, Dave Syer, Josh Long, Stéphane Nicoll, Rob Winch, Andy Wilkinson, Marcel Overdijk, Christian Dupuis, Sébastien Deleuze, Michael Simons, Vedran Pavić, Jay Bryant, Madhura Bhave, Eddú Meléndez, Scott Frederick
|
||||
:docinfo: shared
|
||||
include::attributes.adoc[]
|
||||
|
||||
|
||||
@@ -27,8 +27,8 @@ When you upgrade Spring Boot itself, these dependencies are upgraded as well in
|
||||
|
||||
NOTE: You can still specify a version and override Spring Boot's recommendations if you need to do so.
|
||||
|
||||
The curated list contains all the spring modules that you can use with Spring Boot as well as a refined list of third party libraries.
|
||||
The list is available as a standard <<using-boot-maven-without-a-parent,Bills of Materials (`spring-boot-dependencies`)>> that can be used with both <<using-boot-maven-parent-pom,Maven>> and <<using-boot-gradle,Gradle>>.
|
||||
The curated list contains all the Spring modules that you can use with Spring Boot as well as a refined list of third party libraries.
|
||||
The list is available as a standard Bills of Materials (`spring-boot-dependencies`) that can be used with both <<using-boot-maven,Maven>> and <<using-boot-gradle,Gradle>>.
|
||||
|
||||
WARNING: Each release of Spring Boot is associated with a base version of the Spring Framework.
|
||||
We **highly** recommend that you not specify its version.
|
||||
@@ -37,127 +37,10 @@ We **highly** recommend that you not specify its version.
|
||||
|
||||
[[using-boot-maven]]
|
||||
=== Maven
|
||||
Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible defaults.
|
||||
The parent project provides the following features:
|
||||
To learn about using Spring Boot with Maven, please refer to the documentation for Spring Boot's Maven plugin:
|
||||
|
||||
* Java 1.8 as the default compiler level.
|
||||
* UTF-8 source encoding.
|
||||
* A <<using-boot-dependency-management,Dependency Management section>>, inherited from the spring-boot-dependencies pom, that manages the versions of common dependencies.
|
||||
This dependency management lets you omit <version> tags for those dependencies when used in your own pom.
|
||||
* An execution of the {spring-boot-maven-plugin-docs}#goals-repackage[`repackage` goal] with a `repackage` execution id.
|
||||
* Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering].
|
||||
* Sensible plugin configuration (https://www.mojohaus.org/exec-maven-plugin/[exec plugin], https://github.com/ktoso/maven-git-commit-id-plugin[Git commit ID], and https://maven.apache.org/plugins/maven-shade-plugin/[shade]).
|
||||
* Sensible resource filtering for `application.properties` and `application.yml` including profile-specific files (for example, `application-dev.properties` and `application-dev.yml`)
|
||||
|
||||
Note that, since the `application.properties` and `application.yml` files accept Spring style placeholders (`${...}`), the Maven filtering is changed to use `@..@` placeholders.
|
||||
(You can override that by setting a Maven property called `resource.delimiter`.)
|
||||
|
||||
|
||||
|
||||
[[using-boot-maven-parent-pom]]
|
||||
==== Inheriting the Starter Parent
|
||||
To configure your project to inherit from the `spring-boot-starter-parent`, set the `parent` as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<!-- Inherit defaults from Spring Boot -->
|
||||
<parent>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-parent</artifactId>
|
||||
<version>{spring-boot-version}</version>
|
||||
</parent>
|
||||
----
|
||||
|
||||
NOTE: You should need to specify only the Spring Boot version number on this dependency.
|
||||
If you import additional starters, you can safely omit the version number.
|
||||
|
||||
With that setup, you can also override individual dependencies by overriding a property in your own project.
|
||||
For instance, to upgrade to another Spring Data release train, you would add the following to your `pom.xml`:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<spring-data-releasetrain.version>Fowler-SR2</spring-data-releasetrain.version>
|
||||
</properties>
|
||||
----
|
||||
|
||||
TIP: Check out the <<howto.adoc#howto-customize-dependency-versions, Customize Dependency Versions "`How-to`">> for more information.
|
||||
|
||||
|
||||
|
||||
[[using-boot-maven-without-a-parent]]
|
||||
==== Using Spring Boot without the Parent POM
|
||||
Not everyone likes inheriting from the `spring-boot-starter-parent` POM.
|
||||
You may have your own corporate standard parent that you need to use or you may prefer to explicitly declare all your Maven configuration.
|
||||
|
||||
If you do not want to use the `spring-boot-starter-parent`, you can still keep the benefit of the dependency management (but not the plugin management) by using a `scope=import` dependency, as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<!-- Import dependency management from Spring Boot -->
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>{spring-boot-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
The preceding sample setup does not let you override individual dependencies by using a property, as explained above.
|
||||
To achieve the same result, you need to add an entry in the `dependencyManagement` of your project **before** the `spring-boot-dependencies` entry.
|
||||
For instance, to upgrade to another Spring Data release train, you could add the following element to your `pom.xml`:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- Override Spring Data release train provided by Spring Boot -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.data</groupId>
|
||||
<artifactId>spring-data-releasetrain</artifactId>
|
||||
<version>Fowler-SR2</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>{spring-boot-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
NOTE: In the preceding example, we specify a _BOM_, but any dependency type can be overridden in the same way.
|
||||
|
||||
|
||||
|
||||
[[using-boot-maven-plugin]]
|
||||
==== Using the Spring Boot Maven Plugin
|
||||
Spring Boot includes a <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> that can package the project as an executable jar.
|
||||
Add the plugin to your `<plugins>` section if you want to use it, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
----
|
||||
|
||||
NOTE: If you use the Spring Boot starter parent pom, you need to add only the plugin.
|
||||
There is no need to configure it unless you want to change the settings defined in the parent.
|
||||
* Reference ({spring-boot-maven-plugin-docs}[HTML] and {spring-boot-maven-plugin-pdfdocs}[PDF])
|
||||
* {spring-boot-maven-plugin-api}[API]
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,41 @@
|
||||
[[getting-started]]
|
||||
== Getting started
|
||||
The Spring Boot Plugin has the following goals:
|
||||
|
||||
include::goals/overview.adoc[]
|
||||
To use the Spring Boot Maven Plugin, include the appropriate XML in the `plugins` section of your `pom.xml`, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<!-- ... -->
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<version>{gradle-project-version}</version>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
----
|
||||
|
||||
If you use a milestone or snapshot release, you also need to add the appropriate `pluginRepository` elements, as shown in the following listing:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>spring-snapshots</id>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-milestones</id>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
----
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
[[goals]]
|
||||
== Goals
|
||||
The Spring Boot Plugin has the following goals:
|
||||
|
||||
include::goals/overview.adoc[]
|
||||
|
||||
@@ -10,7 +10,11 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
|
||||
:docinfo: shared,private
|
||||
|
||||
:buildpacks-reference: https://buildpacks.io/docs
|
||||
:spring-boot-api: https://docs.spring.io/spring-boot/docs/{gradle-project-version}/api/org/springframework/boot
|
||||
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version}
|
||||
:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
|
||||
:spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
|
||||
:version-properties-appendix: {spring-boot-reference}/#dependency-versions-properties
|
||||
|
||||
|
||||
[[introduction]]
|
||||
== Introduction
|
||||
@@ -19,6 +23,8 @@ The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[A
|
||||
It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests.
|
||||
|
||||
include::getting-started.adoc[]
|
||||
include::using.adoc[]
|
||||
include::goals.adoc[]
|
||||
include::packaging.adoc[]
|
||||
include::packaging-oci-image.adoc[]
|
||||
include::running.adoc[]
|
||||
|
||||
@@ -25,20 +25,21 @@ Packaging an executable archive is performed by the `repackage` goal, as shown i
|
||||
</build>
|
||||
----
|
||||
|
||||
TIP: If you are using `spring-boot-starter-parent`, such execution is already pre-configured with a `repackage` execution id so that only the plugin definition should be added.
|
||||
TIP: If you are using `spring-boot-starter-parent`, such execution is already pre-configured with a `repackage` execution ID so that only the plugin definition should be added.
|
||||
|
||||
The example above repackages a jar or war that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
|
||||
If some of these dependencies need to be excluded, you can use one of the exclude options, see the <<repackage-example-exclude-dependency,dependency exclusion>> for more details.
|
||||
The example above repackages a `jar` or `war` archive that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
|
||||
If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<repackage-example-exclude-dependency,dependency exclusion>> for more details.
|
||||
|
||||
The original (i.e. non-executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
|
||||
|
||||
NOTE: The `outputFileNameMapping` feature of the `maven-war-plugin` is currently not supported.
|
||||
|
||||
Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
|
||||
In order to make that work with `war` packaging, the `spring-boot-devtools` dependency must be set as `optional` or with the `provided` scope.
|
||||
|
||||
The original (i.e. non executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
|
||||
|
||||
The plugin rewrites your manifest, and in particular it manages the "Main-Class" and "Start-Class" entries, so if the defaults don't work you have to configure those there (not in the jar plugin).
|
||||
The "Main-Class" in the manifest is actually controlled by the "layout" property of the Spring Boot plugin, as shown in the following example:
|
||||
The plugin rewrites your manifest, and in particular it manages the `Main-Class` and `Start-Class` entries.
|
||||
If the defaults don't work you have to configure the values in the Spring Boot plugin, not in the jar plugin.
|
||||
The `Main-Class` in the manifest is controlled by the `layout` property of the Spring Boot plugin, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes"]
|
||||
----
|
||||
@@ -64,7 +65,7 @@ The "Main-Class" in the manifest is actually controlled by the "layout" property
|
||||
</build>
|
||||
----
|
||||
|
||||
The `layout` property defaults to a guess based on the archive type (`jar` or `war`). The following layouts are available:
|
||||
The `layout` property defaults to a value determined by the archive type (`jar` or `war`). The following layouts are available:
|
||||
|
||||
* `JAR`: regular executable JAR layout.
|
||||
* `WAR`: executable WAR layout. `provided` dependencies are placed in `WEB-INF/lib-provided` to avoid any clash when the `war` is deployed in a servlet container.
|
||||
@@ -152,7 +153,7 @@ The following example shows how the default ordering described above can be defi
|
||||
<application>
|
||||
<into layer="spring-boot-loader">
|
||||
<include>org/springframework/boot/loader/**</include>
|
||||
</into>
|
||||
</into>
|
||||
<into layer="application" />
|
||||
</application>
|
||||
<dependencies>
|
||||
@@ -572,7 +573,7 @@ The following `layers.xml` configuration shown one such setup:
|
||||
<application>
|
||||
<into layer="spring-boot-loader">
|
||||
<include>org/springframework/boot/loader/**</include>
|
||||
</into>
|
||||
</into>
|
||||
<into layer="application" />
|
||||
</application>
|
||||
<dependencies>
|
||||
|
||||
@@ -0,0 +1,108 @@
|
||||
[[using]]
|
||||
== Using the plugin
|
||||
Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible defaults.
|
||||
The parent project provides the following features:
|
||||
|
||||
* Java 1.8 as the default compiler level.
|
||||
* UTF-8 source encoding.
|
||||
* A dependency management section, inherited from the `spring-boot-dependencies` POM, that manages the versions of common dependencies.
|
||||
This dependency management lets you omit `<version>` tags for those dependencies when used in your own POM.
|
||||
* An execution of the <<goals.adoc#goals-repackage, `repackage` goal>> with a `repackage` execution id.
|
||||
* Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering].
|
||||
* Sensible plugin configuration (https://www.mojohaus.org/exec-maven-plugin/[exec plugin], https://github.com/ktoso/maven-git-commit-id-plugin[Git commit ID], and https://maven.apache.org/plugins/maven-shade-plugin/[shade]).
|
||||
* Sensible resource filtering for `application.properties` and `application.yml` including profile-specific files (for example, `application-dev.properties` and `application-dev.yml`)
|
||||
|
||||
Note that, since the `application.properties` and `application.yml` files accept Spring style placeholders (`${...}`), the Maven filtering is changed to use `@..@` placeholders.
|
||||
(You can override that by setting a Maven property called `resource.delimiter`.)
|
||||
|
||||
|
||||
|
||||
[[using-parent-pom]]
|
||||
=== Inheriting the Starter Parent POM
|
||||
To configure your project to inherit from the `spring-boot-starter-parent`, set the `parent` as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<!-- Inherit defaults from Spring Boot -->
|
||||
<parent>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-parent</artifactId>
|
||||
<version>{gradle-project-version}</version>
|
||||
</parent>
|
||||
----
|
||||
|
||||
NOTE: You should need to specify only the Spring Boot version number on this dependency.
|
||||
If you import additional starters, you can safely omit the version number.
|
||||
|
||||
With that setup, you can also override individual dependencies by overriding a property in your own project.
|
||||
For instance, to use a different version of the SLF4J library and the Spring Data release train, you would add the following to your `pom.xml`:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<properties>
|
||||
<slf4j.version>1.7.30</slf4j.version>
|
||||
<spring-data-releasetrain.version>Moore-SR6</spring-data-releasetrain.version>
|
||||
</properties>
|
||||
----
|
||||
|
||||
Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of dependency version properties.
|
||||
|
||||
|
||||
|
||||
[[using-import]]
|
||||
=== Using Spring Boot without the Parent POM
|
||||
There may be reasons for you not to inherit from the `spring-boot-starter-parent` POM.
|
||||
You may have your own corporate standard parent that you need to use or you may prefer to explicitly declare all your Maven configuration.
|
||||
|
||||
If you do not want to use the `spring-boot-starter-parent`, you can still keep the benefit of the dependency management (but not the plugin management) by using an `import` scoped dependency, as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<!-- Import dependency management from Spring Boot -->
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>{gradle-project-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
The preceding sample setup does not let you override individual dependencies by using properties, as explained above.
|
||||
To achieve the same result, you need to add entries in the `dependencyManagement` section of your project **before** the `spring-boot-dependencies` entry.
|
||||
For instance, to use a different version of the SLF4J library and the Spring Data release train, you could add the following elements to your `pom.xml`:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<!-- Override SLF4J provided by Spring Boot -->
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-api</artifactId>
|
||||
<version>1.7.30</version>
|
||||
</dependency>
|
||||
<!-- Override Spring Data release train provided by Spring Boot -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.data</groupId>
|
||||
<artifactId>spring-data-releasetrain</artifactId>
|
||||
<version>Moore-SR6</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>{gradle-project-version}</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
|
||||
Reference in New Issue
Block a user