Skip to content

Commit 35bb5ab

Browse files
wilkinsonawilkinsona
committed
Merge pull request #14585 from JB Nizet
* gh-14585: Polish "Add Kotlin DSL examples to Gradle Plugin's documentation" Add Kotlin DSL examples to Gradle Plugin's documentation
2 parents f8f6b47 + a3d2f3f commit 35bb5ab

File tree

52 files changed

+1174
-106
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+1174
-106
lines changed

‎spring-boot-project/spring-boot-parent/pom.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
<maven.version>3.5.4</maven.version>
2727
<maven-resolver.version>1.1.1</maven-resolver.version>
2828
<spock.version>1.0-groovy-2.4</spock.version>
29+
<dependency-management-plugin.version>1.0.6.RELEASE</dependency-management-plugin.version>
2930
</properties>
3031
<scm>
3132
<url>https://github.com/spring-projects/spring-boot</url>
@@ -108,7 +109,7 @@
108109
<dependency>
109110
<groupId>io.spring.gradle</groupId>
110111
<artifactId>dependency-management-plugin</artifactId>
111-
<version>1.0.6.RELEASE</version>
112+
<version>${dependency-management-plugin.version}</version>
112113
</dependency>
113114
<dependency>
114115
<groupId>jline</groupId>

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/pom.xml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,13 @@
128128
</plugin>
129129
</plugins>
130130
</build>
131+
<pluginRepositories>
132+
<pluginRepository>
133+
<id>springio</id>
134+
<name>Spring IO releases repository</name>
135+
<url>https://repo.spring.io/release</url>
136+
</pluginRepository>
137+
</pluginRepositories>
131138
<profiles>
132139
<profile>
133140
<id>windows</id>
@@ -275,6 +282,7 @@
275282
<github-tag>${github-tag}</github-tag>
276283
<version-type>${version-type}</version-type>
277284
<version>${project.version}</version>
285+
<dependency-management-plugin-version>${dependency-management-plugin.version}</dependency-management-plugin-version>
278286
</attributes>
279287
</configuration>
280288
<dependencies>
@@ -283,6 +291,11 @@
283291
<artifactId>asciidoctorj-pdf</artifactId>
284292
<version>1.5.0-alpha.11</version>
285293
</dependency>
294+
<dependency>
295+
<groupId>io.spring.asciidoctor</groupId>
296+
<artifactId>spring-asciidoctor-extensions</artifactId>
297+
<version>0.1.3.RELEASE</version>
298+
</dependency>
286299
</dependencies>
287300
</plugin>
288301
<plugin>

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/asciidoc/getting-started.adoc‎

Lines changed: 86 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,96 @@ To get started with the plugin it needs to be applied to your project.
66
ifeval::["{version-type}" == "RELEASE"]
77
The plugin is https://plugins.gradle.org/plugin/org.springframework.boot[published to
88
Gradle's plugin portal] and can be applied using the `plugins` block:
9-
[source,groovy,indent=0,subs="verbatim,attributes"]
9+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
10+
.Groovy
1011
----
1112
include::../gradle/getting-started/apply-plugin-release.gradle[]
1213
----
14+
15+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
16+
.Kotlin
17+
----
18+
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
19+
----
1320
endif::[]
1421
ifeval::["{version-type}" == "MILESTONE"]
22+
The plugin is published to the Spring milestones repository. For Gradle versions less
23+
than 4.10, this means that you must apply the plugin imperatively:
24+
1525
[source,groovy,indent=0,subs="verbatim,attributes"]
1626
----
1727
include::../gradle/getting-started/apply-plugin-milestone.gradle[]
1828
----
29+
30+
For Gradle 4.10 and above, Gradle can be configured to use the milestones repository
31+
and it can be applied using the `plugins` block. To configure Gradle to use the milestones
32+
repository, add the following to your `settings.gradle` (Groovy) or `settings.gradle.kts`
33+
(Kotlin):
34+
35+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
36+
.Groovy
37+
----
38+
include::../gradle/getting-started/milestone-settings.gradle[]
39+
----
40+
41+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
42+
.Kotlin
43+
----
44+
include::../gradle/getting-started/milestone-settings.gradle.kts[]
45+
----
46+
47+
The plugin can then be applied using the `plugins` block:
48+
49+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
50+
.Groovy
51+
----
52+
include::../gradle/getting-started/apply-plugin-release.gradle[]
53+
----
54+
55+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
56+
.Kotlin
57+
----
58+
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
59+
----
1960
endif::[]
2061
ifeval::["{version-type}" == "SNAPSHOT"]
62+
The plugin is published to the Spring snapshots repository. For Gradle versions less
63+
than 4.10, this means that you must apply the plugin imperatively:
64+
2165
[source,groovy,indent=0,subs="verbatim,attributes"]
2266
----
23-
include::../gradle/getting-started/apply-plugin-snapshot.gradle[]
67+
include::../gradle/getting-started/apply-plugin-milestone.gradle[]
68+
----
69+
70+
For Gradle 4.10 and above, Gradle can be configured to use the snapshots repository
71+
and it can be applied using the `plugins` block. To configure Gradle to use the snapshots
72+
repository, add the following to your `settings.gradle` (Groovy) or `settings.gradle.kts`
73+
(Kotlin):
74+
75+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
76+
.Groovy
77+
----
78+
include::../gradle/getting-started/snapshot-settings.gradle[]
79+
----
80+
81+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
82+
.Kotlin
83+
----
84+
include::../gradle/getting-started/snapshot-settings.gradle.kts[]
85+
----
86+
87+
The plugin can then be applied using the `plugins` block:
88+
89+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
90+
.Groovy
91+
----
92+
include::../gradle/getting-started/apply-plugin-release.gradle[]
93+
----
94+
95+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
96+
.Kotlin
97+
----
98+
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
2499
----
25100
endif::[]
26101

@@ -34,10 +109,18 @@ A typical Spring Boot project will apply the {groovy-plugin}[`groovy`],
34109
plugin and the {dependency-management-plugin}[`io.spring.dependency-management`] plugin as
35110
a minimum. For example:
36111

37-
[source,groovy,indent=0,subs="verbatim,attributes"]
112+
113+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
114+
.Groovy
38115
----
39116
include::../gradle/getting-started/typical-plugins.gradle[tags=apply]
40117
----
41118

119+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
120+
.Kotlin
121+
----
122+
include::../gradle/getting-started/typical-plugins.gradle.kts[tags=apply]
123+
----
124+
42125
To learn more about how the Spring Boot plugin behaves when other plugins are applied
43126
please see the section on <<reacting-to-other-plugins, reacting to other plugins>>.

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/asciidoc/index.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ Andy Wilkinson
3737
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle],
3838
allowing you to package executable jar or war archives, run Spring Boot applications, and
3939
use the dependency management provided by `spring-boot-dependencies`. Spring Boot's
40-
Gradle plugin requires Gradle 4.4 or later.
40+
Gradle plugin requires Gradle 4.4 or later. If you choose to use the newer Kotlin DSL,
41+
it requires Gradle 4.10 or later.
4142

4243
In addition to this user guide, {api-documentation}[API documentation] is also available.
4344

@@ -47,4 +48,4 @@ include::packaging.adoc[]
4748
include::publishing.adoc[]
4849
include::running.adoc[]
4950
include::integrating-with-actuator.adoc[]
50-
include::reacting.adoc[]
51+
include::reacting.adoc[]

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/asciidoc/integrating-with-actuator.adoc‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,19 @@ build in the presence of a `META-INF/build-info.properties` file. A
1010
{build-info-javadoc}[`BuildInfo`] task is provided to generate this file. The easiest way
1111
to use the task is via the plugin's DSL:
1212

13-
[source,groovy,indent=0,subs="verbatim"]
13+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
14+
.Groovy
1415
----
1516
include::../gradle/integrating-with-actuator/build-info-basic.gradle[tags=build-info]
1617
----
1718

19+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
20+
.Kotlin
21+
----
22+
include::../gradle/integrating-with-actuator/build-info-basic.gradle.kts[tags=build-info]
23+
----
24+
25+
1826
This will configure a {build-info-javadoc}[`BuildInfo`] task named `bootBuildInfo` and, if
1927
it exists, make the Java plugin's `classes` task depend upon it. The task's destination
2028
directory will be `META-INF` in the output directory of the main source set's resources
@@ -45,11 +53,19 @@ By default, the generated build information is derived from the project:
4553

4654
The properties can be customized using the DSL:
4755

48-
[source,groovy,indent=0,subs="verbatim"]
56+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
57+
.Groovy
4958
----
5059
include::../gradle/integrating-with-actuator/build-info-custom-values.gradle[tags=custom-values]
5160
----
5261

62+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
63+
.Kotlin
64+
----
65+
include::../gradle/integrating-with-actuator/build-info-custom-values.gradle.kts[tags=custom-values]
66+
----
67+
68+
5369
The default value for `build.time` is the instant at which the project is being built. A
5470
side-effect of this is that the task will never be up-to-date. As a result, builds will
5571
take longer as more tasks, including the project's tests, will have to be executed.
@@ -59,7 +75,15 @@ than the accuracy of the `build.time` property, set `time` to `null` or a fixed
5975

6076
Additional properties can also be added to the build information:
6177

62-
[source,groovy,indent=0,subs="verbatim"]
78+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
79+
.Groovy
6380
----
6481
include::../gradle/integrating-with-actuator/build-info-additional.gradle[tags=additional]
6582
----
83+
84+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
85+
.Kotlin
86+
----
87+
include::../gradle/integrating-with-actuator/build-info-additional.gradle.kts[tags=additional]
88+
----
89+

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/asciidoc/managing-dependencies.adoc‎

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,17 @@ Maven users. For example, it allows you to omit version numbers when declaring
1010
dependencies that are managed in the bom. To make use of this functionality, simply
1111
declare dependencies in the usual way but omit the version number:
1212

13-
[source,groovy,indent=0,subs="verbatim"]
13+
[source,groovy,indent=0,subs="verbatim",role="primary"]
14+
.Groovy
1415
----
1516
include::../gradle/managing-dependencies/dependencies.gradle[tags=dependencies]
1617
----
1718

19+
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
20+
.Kotlin
21+
----
22+
include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependencies]
23+
----
1824

1925

2026
[[managing-dependencies-customizing]]
@@ -28,11 +34,19 @@ for a complete list of these properties.
2834
To customize a managed version you set its corresponding property. For example, to
2935
customize the version of SLF4J which is controlled by the `slf4j.version` property:
3036

31-
[source,groovy,indent=0,subs="verbatim"]
37+
[source,groovy,indent=0,subs="verbatim",role="primary"]
38+
.Groovy
3239
----
3340
include::../gradle/managing-dependencies/custom-version.gradle[tags=custom-version]
3441
----
3542

43+
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
44+
.Kotlin
45+
----
46+
include::../gradle/managing-dependencies/custom-version.gradle.kts[tags=custom-version]
47+
----
48+
49+
3650
WARNING: Each Spring Boot release is designed and tested against a specific set of
3751
third-party dependencies. Overriding versions may cause compatibility issues and should
3852
be done with care.
@@ -50,21 +64,41 @@ artifact ID, or version.
5064
First, configure the project to depend on the Spring Boot plugin but do not apply it:
5165

5266
ifeval::["{version-type}" == "RELEASE"]
67+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
68+
.Groovy
5369
----
5470
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle[]
5571
----
72+
73+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
74+
.Kotlin
75+
----
76+
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
77+
----
5678
endif::[]
5779
ifeval::["{version-type}" == "MILESTONE"]
58-
[source,groovy,indent=0,subs="verbatim,attributes"]
80+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
81+
.Groovy
5982
----
6083
include::../gradle/managing-dependencies/depend-on-plugin-milestone.gradle[]
6184
----
85+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
86+
.Kotlin
87+
----
88+
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
89+
----
6290
endif::[]
6391
ifeval::["{version-type}" == "SNAPSHOT"]
64-
[source,groovy,indent=0,subs="verbatim,attributes"]
92+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
93+
.Groovy
6594
----
6695
include::../gradle/managing-dependencies/depend-on-plugin-snapshot.gradle[]
6796
----
97+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
98+
.Kotlin
99+
----
100+
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
101+
----
68102
endif::[]
69103

70104
The Spring Boot plugin's dependency on the dependency management plugin means that you
@@ -74,11 +108,30 @@ management plugin as Spring Boot uses.
74108

75109
Apply the dependency management plugin and then configure it to import Spring Boot's bom:
76110

77-
[source,groovy,indent=0,subs="verbatim,attributes"]
111+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
112+
.Groovy
78113
----
79114
include::../gradle/managing-dependencies/configure-bom.gradle[tags=configure-bom]
80115
----
81116

117+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
118+
.Kotlin
119+
----
120+
include::../gradle/managing-dependencies/configure-bom.gradle.kts[tags=configure-bom]
121+
----
122+
123+
124+
The Kotlin code above is a bit awkward. That's because we're using the imperative way of
125+
applying the dependency management plugin.
126+
127+
We can make the code less awkward by applying the plugin from the root parent project, or
128+
by using the `plugins` block as we're doing for the Spring Boot plugin. A downside of this
129+
method is that it forces us to specify the version of the dependency management plugin:
130+
131+
[source,kotlin,indent=0,subs="verbatim,attributes"]
132+
----
133+
include::../gradle/managing-dependencies/configure-bom-with-plugins.gradle.kts[tags=configure-bom]
134+
----
82135

83136

84137
[[managing-dependencies-learning-more]]

0 commit comments

Comments
 (0)