Skip to content

Commit

Permalink
Add Kotlin DSL examples to Gradle Plugin's documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
jnizet authored and wilkinsona committed Oct 5, 2018
1 parent f8f6b47 commit 5ed6c0d
Show file tree
Hide file tree
Showing 52 changed files with 1,188 additions and 115 deletions.
3 changes: 2 additions & 1 deletion spring-boot-project/spring-boot-parent/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
<maven.version>3.5.4</maven.version>
<maven-resolver.version>1.1.1</maven-resolver.version>
<spock.version>1.0-groovy-2.4</spock.version>
<dependency-management-plugin.version>1.0.6.RELEASE</dependency-management-plugin.version>
</properties>
<scm>
<url>http://github.com/spring-projects/spring-boot</url>
Expand Down Expand Up @@ -108,7 +109,7 @@
<dependency>
<groupId>io.spring.gradle</groupId>
<artifactId>dependency-management-plugin</artifactId>
<version>1.0.6.RELEASE</version>
<version>${dependency-management-plugin.version}</version>
</dependency>
<dependency>
<groupId>jline</groupId>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,13 @@
</plugin>
</plugins>
</build>
<pluginRepositories>
<pluginRepository>
<id>springio</id>
<name>Spring IO releases repository</name>
<url>https://repo.spring.io/release</url>
</pluginRepository>
</pluginRepositories>
<profiles>
<profile>
<id>windows</id>
Expand Down Expand Up @@ -275,6 +282,7 @@
<github-tag>${github-tag}</github-tag>
<version-type>${version-type}</version-type>
<version>${project.version}</version>
<dependency-management-plugin-version>${dependency-management-plugin.version}</dependency-management-plugin-version>
</attributes>
</configuration>
<dependencies>
Expand All @@ -283,6 +291,11 @@
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
<dependency>
<groupId>io.spring.asciidoctor</groupId>
<artifactId>spring-asciidoctor-extensions</artifactId>
<version>0.1.3.RELEASE</version>
</dependency>
</dependencies>
</plugin>
<plugin>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,91 @@ To get started with the plugin it needs to be applied to your project.
ifeval::["{version-type}" == "RELEASE"]
The plugin is https://plugins.gradle.org/plugin/org.springframework.boot[published to
Gradle's plugin portal] and can be applied using the `plugins` block:
[source,groovy,indent=0,subs="verbatim,attributes"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/apply-plugin-release.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
----
endif::[]
ifeval::["{version-type}" == "MILESTONE"]
The plugin is published to the Spring milestones repository.

For Gradle versions less than 4.10, you must apply the plugin imperatively:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
include::../gradle/getting-started/apply-plugin-milestone.gradle[]
----

For Gradle 4.10 and above, it can be applied using the `plugins` block:
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/apply-plugin-release.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
----

provided you add the following lines in the `settings.gradle` file (or `settings.gradle.kts` in Kotlin):

[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/milestone-settings.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/milestone-settings.gradle.kts[]
----
endif::[]
ifeval::["{version-type}" == "SNAPSHOT"]
The plugin is published to the Spring snapshots repository.

For Gradle versions less than 4.10, you must apply the plugin imperatively:

[source,groovy,indent=0,subs="verbatim,attributes"]
----
include::../gradle/getting-started/apply-plugin-snapshot.gradle[]
----

For Gradle 4.10 and above, it can be applied using the `plugins` block:
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/apply-plugin-release.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/apply-plugin-release.gradle.kts[]
----

provided you add the following lines in the `settings.gradle` file (or `settings.gradle.kts` in Kotlin):

[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/snapshot-settings.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/snapshot-settings.gradle.kts[]
----
endif::[]

Applied in isolation the plugin makes few changes to a project. Instead, the plugin
Expand All @@ -34,10 +103,18 @@ A typical Spring Boot project will apply the {groovy-plugin}[`groovy`],
plugin and the {dependency-management-plugin}[`io.spring.dependency-management`] plugin as
a minimum. For example:

[source,groovy,indent=0,subs="verbatim,attributes"]

[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/getting-started/typical-plugins.gradle[tags=apply]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/getting-started/typical-plugins.gradle.kts[tags=apply]
----

To learn more about how the Spring Boot plugin behaves when other plugins are applied
please see the section on <<reacting-to-other-plugins, reacting to other plugins>>.
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ Andy Wilkinson
The Spring Boot Gradle Plugin provides Spring Boot support in https://gradle.org[Gradle],
allowing you to package executable jar or war archives, run Spring Boot applications, and
use the dependency management provided by `spring-boot-dependencies`. Spring Boot's
Gradle plugin requires Gradle 4.4 or later.
Gradle plugin requires Gradle 4.4 or later. If you choose to use the newer Kotlin DSL,
it requires Gradle 4.10 or later.

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

Expand All @@ -47,4 +48,4 @@ include::packaging.adoc[]
include::publishing.adoc[]
include::running.adoc[]
include::integrating-with-actuator.adoc[]
include::reacting.adoc[]
include::reacting.adoc[]
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,19 @@ build in the presence of a `META-INF/build-info.properties` file. A
{build-info-javadoc}[`BuildInfo`] task is provided to generate this file. The easiest way
to use the task is via the plugin's DSL:

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

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/integrating-with-actuator/build-info-basic.gradle.kts[tags=build-info]
----


This will configure a {build-info-javadoc}[`BuildInfo`] task named `bootBuildInfo` and, if
it exists, make the Java plugin's `classes` task depend upon it. The task's destination
directory will be `META-INF` in the output directory of the main source set's resources
Expand Down Expand Up @@ -45,11 +53,19 @@ By default, the generated build information is derived from the project:

The properties can be customized using the DSL:

[source,groovy,indent=0,subs="verbatim"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/integrating-with-actuator/build-info-custom-values.gradle[tags=custom-values]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/integrating-with-actuator/build-info-custom-values.gradle.kts[tags=custom-values]
----


The default value for `build.time` is the instant at which the project is being built. A
side-effect of this is that the task will never be up-to-date. As a result, builds will
take longer as more tasks, including the project's tests, will have to be executed.
Expand All @@ -59,7 +75,15 @@ than the accuracy of the `build.time` property, set `time` to `null` or a fixed

Additional properties can also be added to the build information:

[source,groovy,indent=0,subs="verbatim"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/integrating-with-actuator/build-info-additional.gradle[tags=additional]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/integrating-with-actuator/build-info-additional.gradle.kts[tags=additional]
----

Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,17 @@ Maven users. For example, it allows you to omit version numbers when declaring
dependencies that are managed in the bom. To make use of this functionality, simply
declare dependencies in the usual way but omit the version number:

[source,groovy,indent=0,subs="verbatim"]
[source,groovy,indent=0,subs="verbatim",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/dependencies.gradle[tags=dependencies]
----

[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependencies]
----


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

[source,groovy,indent=0,subs="verbatim"]
[source,groovy,indent=0,subs="verbatim",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/custom-version.gradle[tags=custom-version]
----

[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/custom-version.gradle.kts[tags=custom-version]
----


WARNING: Each Spring Boot release is designed and tested against a specific set of
third-party dependencies. Overriding versions may cause compatibility issues and should
be done with care.
Expand All @@ -50,21 +64,41 @@ artifact ID, or version.
First, configure the project to depend on the Spring Boot plugin but do not apply it:

ifeval::["{version-type}" == "RELEASE"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle[]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
----
endif::[]
ifeval::["{version-type}" == "MILESTONE"]
[source,groovy,indent=0,subs="verbatim,attributes"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/depend-on-plugin-milestone.gradle[]
----
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
----
endif::[]
ifeval::["{version-type}" == "SNAPSHOT"]
[source,groovy,indent=0,subs="verbatim,attributes"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/depend-on-plugin-snapshot.gradle[]
----
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/depend-on-plugin-release.gradle.kts[]
----
endif::[]

The Spring Boot plugin's dependency on the dependency management plugin means that you
Expand All @@ -74,11 +108,31 @@ management plugin as Spring Boot uses.

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

[source,groovy,indent=0,subs="verbatim,attributes"]
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/managing-dependencies/configure-bom.gradle[tags=configure-bom]
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/managing-dependencies/configure-bom.gradle.kts[tags=configure-bom]
----


The Kotlin code above is a bit awkward. That's because we're using the imperative way of applying
the dependency management plugin.

We can make the code less awkward by applying the plugin from
the root parent project, or by using the `plugins` block as we're doing for the spring boot plugin.
The downside of this method, though, is that it forces us to specify the version of the
dependency management plugin, even though it's a dependency of the spring boot plugin:

[source,kotlin,indent=0,subs="verbatim,attributes"]
----
include::../gradle/managing-dependencies/configure-bom-with-plugins.gradle.kts[tags=configure-bom]
----


[[managing-dependencies-learning-more]]
Expand Down
Loading

0 comments on commit 5ed6c0d

Please sign in to comment.