diff --git a/subprojects/docs/src/docs/release/notes.md b/subprojects/docs/src/docs/release/notes.md index fdfd035c8f3b3..44af99a6d6d6d 100644 --- a/subprojects/docs/src/docs/release/notes.md +++ b/subprojects/docs/src/docs/release/notes.md @@ -122,6 +122,7 @@ We would like to thank the following community members for making contributions - [Ben McCann](https://github.com/benmccann) - Remove Play 2.2 support (gradle/gradle#3353) - [Björn Kautler](https://github.com/Vampire) - No Deprecated Configurations in Build Init (gradle/gradle#6208) - [Georg Friedrich](https://github.com/GFriedrich) - Base Java Library Distribution Plugin on Java Library Plugin (gradle/gradle#5695) +- [Stefan M.](https://github.com/StefMa) — Include Kotlin DSL samples in Gradle wrapper user manual chapter (gradle/gradle#5923) We love getting contributions from the Gradle community. For information on contributing, please see [gradle.org/contribute](https://gradle.org/contribute). diff --git a/subprojects/docs/src/docs/userguide/gradle_wrapper.adoc b/subprojects/docs/src/docs/userguide/gradle_wrapper.adoc index 028cb96a339ca..fbf475eccfd90 100644 --- a/subprojects/docs/src/docs/userguide/gradle_wrapper.adoc +++ b/subprojects/docs/src/docs/userguide/gradle_wrapper.adoc @@ -40,11 +40,9 @@ Generating the Wrapper files requires an installed version of the Gradle runtime Every vanilla Gradle build comes with a built-in task called `wrapper`. You’ll be able to find the task listed under the group "Build Setup tasks" when <>. Executing the `wrapper` task generates the necessary Wrapper files in the project directory. -=== Example: Running the Wrapper task - -.Output of **`gradle wrapper`** +.Running the Wrapper task ---- -> gradle wrapper +$ gradle wrapper include::{samplesPath}/userguide/wrapper/simple/wrapperCommandLine.out[] ---- @@ -64,7 +62,7 @@ The generated Wrapper properties file, `gradle/wrapper/gradle-wrapper.properties [source,properties] .`gradle/wrapper/gradle-wrapper.properties` ---- -distributionUrl=https\://services.gradle.org/distributions/gradle-4.3.1-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-bin.zip ---- All of those aspects are configurable at the time of generating the Wrapper files with the help of the following command line options. @@ -81,13 +79,11 @@ The full URL pointing to Gradle distribution ZIP file. Using this option makes ` `--gradle-distribution-sha256-sum`:: The SHA256 hash sum used for <<#sec:verification,verifying the downloaded Gradle distribution>>. -Let’s assume the following use case to illustrate the use of the command line options. You would like to generate the Wrapper with version 4.0 and use the `-all` distribution to enable your IDE to enable code-completion and being able to navigate to the Gradle source code. Those requirements are captured by the following command line execution: - -=== Example: Providing options to Wrapper task +Let’s assume the following use case to illustrate the use of the command line options. You would like to generate the Wrapper with version {gradleVersion} and use the `-all` distribution to enable your IDE to enable code-completion and being able to navigate to the Gradle source code. Those requirements are captured by the following command line execution: -.Output of **`gradle wrapper --gradle-version 4.0 --distribution-type all`** +.Providing options to Wrapper task ---- -> gradle wrapper --gradle-version 4.0 --distribution-type all +$ gradle wrapper --gradle-version {gradleVersion} --distribution-type all include::{samplesPath}/userguide/wrapper/simple/wrapperCommandLine.out[] ---- @@ -97,7 +93,7 @@ As a result you can find the desired information in the Wrapper properties file. [source,properties] .`gradle/wrapper/gradle-wrapper.properties` ---- -distributionUrl=https\://services.gradle.org/distributions/gradle-4.0-all.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-all.zip ---- Let’s have a look at the following project layout to illustrate the expected Wrapper files: @@ -133,12 +129,9 @@ You can go ahead and <<#sec:using_wrapper,execute the build with the Wrapper>> w It is recommended to always execute a build with the Wrapper to ensure a reliable, controlled and standardized execution of the build. Using the Wrapper looks almost exactly like running the build with a Gradle installation. Depending on the operating system you either run `gradlew` or `gradlew.bat` instead of the `gradle` command. The following console output demonstrate the use of the Wrapper on a Windows machine for a Java-based project. -=== Example: Executing the build with the Wrapper batch file - -[listing] -.Output of `gradlew.bat build` +.Executing the build with the Wrapper batch file ---- -> gradlew.bat build +$ gradlew.bat build include::{samplesPath}/userguide/wrapper/wrapperBatchFileExecution.out[] ---- @@ -156,21 +149,15 @@ Projects will typically want to keep up with the times and upgrade their Gradle Use the Gradle `wrapper` task to generate the wrapper, specifying a version. The default is the current version, which you can check by executing `./gradlew --version`. -=== Example: Upgrading the Wrapper version - -[listing] -.Output of `./gradlew wrapper --gradle-version 4.2.1` +.Example: Upgrading the Wrapper version ---- -> ./gradlew wrapper --gradle-version 4.2.1 +$ ./gradlew wrapper --gradle-version {gradleVersion} include::{samplesPath}/userguide/wrapper/wrapperGradleVersionUpgrade.out[] ---- -=== Example: Checking the Wrapper version after upgrading - -[listing] -.Output of `./gradlew -v` +.Checking the Wrapper version after upgrading ---- -> ./gradlew -v +$ ./gradlew -v include::{samplesPath}/userguide/wrapper/wrapperGradleVersionAfterUpgrade.out[] ---- @@ -181,21 +168,19 @@ Most users of Gradle are happy with the default runtime behavior of the Wrapper. Let’s assume you grew tired of defining the `-all` distribution type on the command line every time you upgrade the Wrapper. You can save yourself some keyboard strokes by re-configuring the `wrapper` task. -=== Example: Customizing the Wrapper task - -[source.multi-language-sample,groovy] -.build.gradle ----- -include::{samplesPath}/userguide/wrapper/customized-task/build.gradle[tag=customized-wrapper-task] ----- +.Example: Customizing the Wrapper task +==== +include::sample[dir="userguide/wrapper/customized-task/groovy",files="build.gradle[tag=customized-wrapper-task]"] +include::sample[dir="userguide/wrapper/customized-task/kotlin",files="build.gradle.kts[tag=customized-wrapper-task]"] +==== -With the configuration in place running `./gradlew wrapper --gradle-version 4.1` is enough to produce a `distributionUrl` value in the Wrapper properties file that will request the `-all` distribution. +With the configuration in place running `./gradlew wrapper --gradle-version {gradleVersion}` is enough to produce a `distributionUrl` value in the Wrapper properties file that will request the `-all` distribution. .The generated distribution URL [listing] .`gradle/wrapper/gradle-wrapper.properties` ---- -distributionUrl=https\://services.gradle.org/distributions/gradle-4.1-all.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-{gradleVersion}-all.zip ---- Check out the API documentation for more detail descriptions of the available configuration options. You can also find various samples for configuring the Wrapper in the Gradle distribution. diff --git a/subprojects/docs/src/samples/userguide/wrapper/customized-task/build.gradle b/subprojects/docs/src/samples/userguide/wrapper/customized-task/groovy/build.gradle similarity index 100% rename from subprojects/docs/src/samples/userguide/wrapper/customized-task/build.gradle rename to subprojects/docs/src/samples/userguide/wrapper/customized-task/groovy/build.gradle diff --git a/subprojects/docs/src/samples/userguide/wrapper/customized-task/settings.gradle b/subprojects/docs/src/samples/userguide/wrapper/customized-task/groovy/settings.gradle similarity index 100% rename from subprojects/docs/src/samples/userguide/wrapper/customized-task/settings.gradle rename to subprojects/docs/src/samples/userguide/wrapper/customized-task/groovy/settings.gradle diff --git a/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/build.gradle.kts b/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/build.gradle.kts new file mode 100644 index 0000000000000..da28dee88a24b --- /dev/null +++ b/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/build.gradle.kts @@ -0,0 +1,5 @@ +// tag::customized-wrapper-task[] +tasks.getByName("wrapper") { + distributionType = Wrapper.DistributionType.ALL +} +// end::customized-wrapper-task[] diff --git a/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/settings.gradle.kts b/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/settings.gradle.kts new file mode 100644 index 0000000000000..93ca22e8a37ce --- /dev/null +++ b/subprojects/docs/src/samples/userguide/wrapper/customized-task/kotlin/settings.gradle.kts @@ -0,0 +1 @@ +rootProject.name = "customized-task" diff --git a/subprojects/docs/src/samples/userguide/wrapper/customized-task/wrapperCustomized.sample.conf b/subprojects/docs/src/samples/userguide/wrapper/customized-task/wrapperCustomized.sample.conf index 3aaf111dd8a83..f6303d66b6186 100644 --- a/subprojects/docs/src/samples/userguide/wrapper/customized-task/wrapperCustomized.sample.conf +++ b/subprojects/docs/src/samples/userguide/wrapper/customized-task/wrapperCustomized.sample.conf @@ -1,2 +1,10 @@ -executable: gradle -args: tasks +commands: [{ + execution-subdirectory: groovy + executable: gradle + args: tasks +},{ + execution-subdirectory: kotlin + executable: gradle + args: tasks +}] +