Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Consolidate Maven plugin documentation in plugin reference

Browse Source 
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
2020-04-02 14:18:59 -05:00
parent c119dd2450
commit bb568c5bff
12 changed files with 183 additions and 374 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc
View File

@@ -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>
----

6
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[goals]]
== Goals
The Spring Boot Plugin has the following goals:
include::goals/overview.adoc[]

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

@@ -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[]

21
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc
View File

@@ -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>

108
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc Normal file
View File

@@ -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>
----