Skip to content

Commit bb568c5

Browse files
scottfrederickscottfrederick
committed
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
1 parent c119dd2 commit bb568c5

File tree

12 files changed

+183
-374
lines changed

12 files changed

+183
-374
lines changed

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
:spring-boot-current-docs: https://docs.spring.io/spring-boot/docs/current/reference/
3131
:spring-boot-actuator-restapi: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/actuator-api/
3232
:spring-boot-maven-plugin-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/reference/html/
33-
: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
33+
: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
3434
:spring-boot-maven-plugin-api: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/maven-plugin/api/
3535
:spring-boot-gradle-plugin-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/gradle-plugin/reference/html/
3636
: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

Lines changed: 0 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -20,146 +20,6 @@ Please refer to the plugin's documentation to learn more:
2020
* {spring-boot-maven-plugin-api}[API]
2121

2222

23-
24-
[[build-tool-plugins-include-maven-plugin]]
25-
=== Including the Plugin
26-
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:
27-
28-
[source,xml,indent=0,subs="verbatim,attributes"]
29-
----
30-
<?xml version="1.0" encoding="UTF-8"?>
31-
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
32-
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
33-
<modelVersion>4.0.0</modelVersion>
34-
<!-- ... -->
35-
<build>
36-
<plugins>
37-
<plugin>
38-
<groupId>org.springframework.boot</groupId>
39-
<artifactId>spring-boot-maven-plugin</artifactId>
40-
<version>{spring-boot-version}</version>
41-
<executions>
42-
<execution>
43-
<goals>
44-
<goal>repackage</goal>
45-
</goals>
46-
</execution>
47-
</executions>
48-
</plugin>
49-
</plugins>
50-
</build>
51-
</project>
52-
----
53-
54-
The preceding configuration repackages a jar or war that is built during the `package` phase of the Maven lifecycle.
55-
The following example shows both the repackaged jar as well as the original jar in the `target` directory:
56-
57-
[indent=0]
58-
----
59-
$ mvn package
60-
$ ls target/*.jar
61-
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
62-
----
63-
64-
65-
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:
66-
67-
[indent=0]
68-
----
69-
$ mvn package spring-boot:repackage
70-
$ ls target/*.jar
71-
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
72-
----
73-
74-
If you use a milestone or snapshot release, you also need to add the appropriate `pluginRepository` elements, as shown in the following listing:
75-
76-
[source,xml,indent=0,subs="verbatim,attributes"]
77-
----
78-
<pluginRepositories>
79-
<pluginRepository>
80-
<id>spring-snapshots</id>
81-
<url>https://repo.spring.io/snapshot</url>
82-
</pluginRepository>
83-
<pluginRepository>
84-
<id>spring-milestones</id>
85-
<url>https://repo.spring.io/milestone</url>
86-
</pluginRepository>
87-
</pluginRepositories>
88-
----
89-
90-
91-
92-
[[build-tool-plugins-maven-packaging]]
93-
=== Packaging Executable Jar and War Files
94-
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.
95-
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:
96-
97-
[source,xml,indent=0,subs="verbatim,attributes"]
98-
----
99-
<?xml version="1.0" encoding="UTF-8"?>
100-
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
101-
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
102-
<!-- ... -->
103-
<packaging>jar</packaging>
104-
<!-- ... -->
105-
</project>
106-
----
107-
108-
Your existing archive is enhanced by Spring Boot during the `package` phase.
109-
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.
110-
If you do not specify a main class, the plugin searches for a class with a `public static void main(String[] args)` method.
111-
112-
[source,xml,indent=0,subs="verbatim,attributes"]
113-
----
114-
<plugin>
115-
<groupId>org.springframework.boot</groupId>
116-
<artifactId>spring-boot-maven-plugin</artifactId>
117-
<configuration>
118-
<mainClass>com.example.app.Main</mainClass>
119-
</configuration>
120-
</plugin>
121-
----
122-
123-
124-
To build and run a project artifact, you can type the following:
125-
126-
[indent=0]
127-
----
128-
$ mvn package
129-
$ java -jar target/mymodule-0.0.1-SNAPSHOT.jar
130-
----
131-
132-
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:
133-
134-
[source,xml,indent=0,subs="verbatim,attributes"]
135-
----
136-
<?xml version="1.0" encoding="UTF-8"?>
137-
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
138-
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
139-
<!-- ... -->
140-
<packaging>war</packaging>
141-
<!-- ... -->
142-
<dependencies>
143-
<dependency>
144-
<groupId>org.springframework.boot</groupId>
145-
<artifactId>spring-boot-starter-web</artifactId>
146-
</dependency>
147-
<dependency>
148-
<groupId>org.springframework.boot</groupId>
149-
<artifactId>spring-boot-starter-tomcat</artifactId>
150-
<scope>provided</scope>
151-
</dependency>
152-
<!-- ... -->
153-
</dependencies>
154-
</project>
155-
----
156-
157-
TIP: See the "`<<howto.adoc#howto-create-a-deployable-war-file>>`" section for more details on how to create a deployable war file.
158-
159-
Advanced configuration options and examples are available in the {spring-boot-maven-plugin-docs}[plugin info page].
160-
161-
162-
16323
[[build-tool-plugins-gradle-plugin]]
16424
== Spring Boot Gradle Plugin
16525
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

Lines changed: 1 addition & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -108,88 +108,7 @@ Spring Boot dependencies use the `org.springframework.boot` `groupId`.
108108
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`">>.
109109
Spring Boot also provides an optional <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> to create executable jars.
110110

111-
The following listing shows a typical `pom.xml` file:
112-
113-
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
114-
----
115-
<?xml version="1.0" encoding="UTF-8"?>
116-
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
117-
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
118-
<modelVersion>4.0.0</modelVersion>
119-
120-
<groupId>com.example</groupId>
121-
<artifactId>myproject</artifactId>
122-
<version>0.0.1-SNAPSHOT</version>
123-
124-
<!-- Inherit defaults from Spring Boot -->
125-
<parent>
126-
<groupId>org.springframework.boot</groupId>
127-
<artifactId>spring-boot-starter-parent</artifactId>
128-
<version>{spring-boot-version}</version>
129-
</parent>
130-
131-
<!-- Override inherited settings -->
132-
<description/>
133-
<developers>
134-
<developer/>
135-
</developers>
136-
<licenses>
137-
<license/>
138-
</licenses>
139-
<scm>
140-
<url/>
141-
</scm>
142-
<url/>
143-
144-
<!-- Add typical dependencies for a web application -->
145-
<dependencies>
146-
<dependency>
147-
<groupId>org.springframework.boot</groupId>
148-
<artifactId>spring-boot-starter-web</artifactId>
149-
</dependency>
150-
</dependencies>
151-
152-
<!-- Package as an executable jar -->
153-
<build>
154-
<plugins>
155-
<plugin>
156-
<groupId>org.springframework.boot</groupId>
157-
<artifactId>spring-boot-maven-plugin</artifactId>
158-
</plugin>
159-
</plugins>
160-
</build>
161-
162-
ifeval::["{spring-boot-artifactory-repo}" != "release"]
163-
<!-- Add Spring repositories -->
164-
<!-- (you don't need this if you are using a .RELEASE version) -->
165-
<repositories>
166-
<repository>
167-
<id>spring-snapshots</id>
168-
<url>https://repo.spring.io/snapshot</url>
169-
<snapshots><enabled>true</enabled></snapshots>
170-
</repository>
171-
<repository>
172-
<id>spring-milestones</id>
173-
<url>https://repo.spring.io/milestone</url>
174-
</repository>
175-
</repositories>
176-
<pluginRepositories>
177-
<pluginRepository>
178-
<id>spring-snapshots</id>
179-
<url>https://repo.spring.io/snapshot</url>
180-
</pluginRepository>
181-
<pluginRepository>
182-
<id>spring-milestones</id>
183-
<url>https://repo.spring.io/milestone</url>
184-
</pluginRepository>
185-
</pluginRepositories>
186-
endif::[]
187-
</project>
188-
----
189-
190-
TIP: The `spring-boot-starter-parent` is a great way to use Spring Boot, but it might not be suitable all of the time.
191-
Sometimes you may need to inherit from a different parent POM, or you might not like our default settings.
192-
In those cases, see <<using-spring-boot.adoc#using-boot-maven-without-a-parent>> for an alternative solution that uses an `import` scope.
111+
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.
193112

194113

195114

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2440,23 +2440,14 @@ Using this format lets the time be parsed into a `Date` and its format, when ser
24402440

24412441
[[howto-customize-dependency-versions]]
24422442
=== Customize Dependency Versions
2443-
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.
2444-
Browse the <<appendix-dependency-versions.adoc#dependency-versions-properties, `Version properties`>> for a complete list of version properties.
2445-
For example, to pick a different `slf4j` version, you would add the following property:
2446-
2447-
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
2448-
----
2449-
<properties>
2450-
<slf4j.version>1.7.5<slf4j.version>
2451-
</properties>
2452-
----
2453-
2454-
NOTE: Doing so only works if your Maven project inherits (directly or indirectly) from `spring-boot-dependencies`.
2455-
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.
2443+
The `spring-boot-dependencies` POM manages the versions of common dependencies.
2444+
The Spring Boot plugins for Maven and Gradle allow these managed dependency versions to be customized using build properties.
24562445

24572446
WARNING: Each Spring Boot release is designed and tested against this specific set of third-party dependencies.
24582447
Overriding versions may cause compatibility issues.
24592448

2449+
To override dependency versions with Maven, see {spring-boot-maven-plugin-docs}/#using[this section] of the Maven plugin's documentation.
2450+
24602451
To override dependency versions in Gradle, see {spring-boot-gradle-plugin-docs}/#managing-dependencies-customizing[this section] of the Gradle plugin's documentation.
24612452

24622453

@@ -2501,7 +2492,7 @@ However, you must additionally add an `<executions>` section, as follows:
25012492
</build>
25022493
----
25032494

2504-
See the {spring-boot-maven-plugin-docs}#getting-started[plugin documentation] for full usage details.
2495+
See the {spring-boot-maven-plugin-docs}#repackage[plugin documentation] for full usage details.
25052496

25062497

25072498

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.htmladoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[spring-boot-reference-documentation]]
22
= Spring Boot Reference Documentation
3-
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
3+
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
44
:docinfo: shared
55

66
The reference documentation consists of the following sections:

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.htmlsingleadoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[spring-boot-reference-documentation]]
22
= Spring Boot Reference Documentation
3-
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
3+
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
44
:docinfo: shared
55
include::attributes.adoc[]
66

0 commit comments

Comments
 (0)