Skip to content

S
spring-boot
Commit bb568c5b authored by Scott Frederick's avatar Scott Frederick
Browse files
Options

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
parent c119dd24
Hide whitespace changes
Inline Side-by-side
Showing with 183 additions and 374 deletions
spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc
View file @ bb568c5b
...@@ -30,7 +30,7 @@ ...@@ -30,7 +30,7 @@
:spring-boot-current-docs: https://docs.spring.io/spring-boot/docs/current/reference/ :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-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-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-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-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 :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
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/build-tool-plugins.adoc
View file @ bb568c5b
...@@ -20,146 +20,6 @@ Please refer to the plugin's documentation to learn more: ...@@ -20,146 +20,6 @@ Please refer to the plugin's documentation to learn more:
* {spring-boot-maven-plugin-api}[API] * {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]] [[build-tool-plugins-gradle-plugin]]
== Spring Boot 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`. 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`.
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started.adoc
View file @ bb568c5b
...@@ -108,88 +108,7 @@ Spring Boot dependencies use the `org.springframework.boot` `groupId`. ...@@ -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`">>. 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. 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: 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.
[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.
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc
View file @ bb568c5b
...@@ -2440,23 +2440,14 @@ Using this format lets the time be parsed into a `Date` and its format, when ser ...@@ -2440,23 +2440,14 @@ Using this format lets the time be parsed into a `Date` and its format, when ser
[[howto-customize-dependency-versions]] [[howto-customize-dependency-versions]]
=== 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. The `spring-boot-dependencies` POM manages the versions of common dependencies.
Browse the <<appendix-dependency-versions.adoc#dependency-versions-properties, `Version properties`>> for a complete list of version properties. The Spring Boot plugins for Maven and Gradle allow these managed dependency versions to be customized using build 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.
WARNING: Each Spring Boot release is designed and tested against this specific set of third-party dependencies. WARNING: Each Spring Boot release is designed and tested against this specific set of third-party dependencies.
Overriding versions may cause compatibility issues. 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. 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: ...@@ -2501,7 +2492,7 @@ However, you must additionally add an `<executions>` section, as follows:
</build> </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.
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.htmladoc
View file @ bb568c5b
[[spring-boot-reference-documentation]] [[spring-boot-reference-documentation]]
= 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 :docinfo: shared
The reference documentation consists of the following sections: The reference documentation consists of the following sections:
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.htmlsingleadoc
View file @ bb568c5b
[[spring-boot-reference-documentation]] [[spring-boot-reference-documentation]]
= 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 :docinfo: shared
include::attributes.adoc[] include::attributes.adoc[]
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc
View file @ bb568c5b
...@@ -27,8 +27,8 @@ When you upgrade Spring Boot itself, these dependencies are upgraded as well in ...@@ -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. 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 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 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. 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. We **highly** recommend that you not specify its version.
...@@ -37,127 +37,10 @@ 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]] [[using-boot-maven]]
=== Maven === Maven
Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible defaults. To learn about using Spring Boot with Maven, please refer to the documentation for Spring Boot's Maven plugin:
The parent project provides the following features:
* Java 1.8 as the default compiler level. * Reference ({spring-boot-maven-plugin-docs}[HTML] and {spring-boot-maven-plugin-pdfdocs}[PDF])
* UTF-8 source encoding. * {spring-boot-maven-plugin-api}[API]
* 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.
......
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc
View file @ bb568c5b
[[getting-started]] [[getting-started]]
== 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>
----
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc 0 → 100644
View file @ bb568c5b
[[goals]]
== Goals
The Spring Boot Plugin has the following goals:
include::goals/overview.adoc[]
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc
View file @ bb568c5b
...@@ -10,7 +10,11 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick ...@@ -10,7 +10,11 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
:docinfo: shared,private :docinfo: shared,private
:buildpacks-reference: https://buildpacks.io/docs :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]]
== Introduction == Introduction
...@@ -19,6 +23,8 @@ The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[A ...@@ -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. 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::getting-started.adoc[]
include::using.adoc[]
include::goals.adoc[]
include::packaging.adoc[] include::packaging.adoc[]
include::packaging-oci-image.adoc[] include::packaging-oci-image.adoc[]
include::running.adoc[] include::running.adoc[]
......
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc
View file @ bb568c5b
...@@ -25,20 +25,21 @@ Packaging an executable archive is performed by the `repackage` goal, as shown i ...@@ -25,20 +25,21 @@ Packaging an executable archive is performed by the `repackage` goal, as shown i
</build> </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. 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. 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. 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). 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. 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.
If the defaults don't work you have to configure the values in the Spring Boot plugin, not in the jar plugin.
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 controlled by the `layout` property of the Spring Boot plugin, as shown in the following example:
The "Main-Class" in the manifest is actually controlled by the "layout" property of the Spring Boot plugin, as shown in the following example:
[source,xml,indent=0,subs="verbatim,attributes"] [source,xml,indent=0,subs="verbatim,attributes"]
---- ----
...@@ -64,7 +65,7 @@ The "Main-Class" in the manifest is actually controlled by the "layout" property ...@@ -64,7 +65,7 @@ The "Main-Class" in the manifest is actually controlled by the "layout" property
</build> </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. * `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. * `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 ...@@ -152,7 +153,7 @@ The following example shows how the default ordering described above can be defi
<application> <application>
<into layer="spring-boot-loader"> <into layer="spring-boot-loader">
<include>org/springframework/boot/loader/**</include> <include>org/springframework/boot/loader/**</include>
</into> </into>
<into layer="application" /> <into layer="application" />
</application> </application>
<dependencies> <dependencies>
...@@ -572,7 +573,7 @@ The following `layers.xml` configuration shown one such setup: ...@@ -572,7 +573,7 @@ The following `layers.xml` configuration shown one such setup:
<application> <application>
<into layer="spring-boot-loader"> <into layer="spring-boot-loader">
<include>org/springframework/boot/loader/**</include> <include>org/springframework/boot/loader/**</include>
</into> </into>
<into layer="application" /> <into layer="application" />
</application> </application>
<dependencies> <dependencies>
......
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc 0 → 100644
View file @ bb568c5b
[[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>
----
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