Gradle

https://docs.gradle.org/current/userguide/
Admin
Gradle is a fast, dependable, and adaptable open-source build automation tool with an elegant...
Tokens:1,252,638
Snippets:9,514
Trust Score:10
Update:2 days ago
Show doc for...
Tokens:
Raw
### Example project path

Source: https://docs.gradle.org/current/userguide/multi_project_builds_intermediate.html

Shows the pattern of a project path, starting with a colon for the root project.

```text
:sub-project-1
```

--------------------------------

### Run hello task and output (first example)

Source: https://docs.gradle.org/current/userguide/implementing_gradle_plugins_binary.html

Command to run the hello task and its expected output for the first example.

```bash
$ ./gradlew -q hello
```

```text
Hi from Gradle
```

--------------------------------

### Verbose VFS logging output example

Source: https://docs.gradle.org/current/userguide/file_system_watching.html

This example shows the command to run a build with verbose VFS logging and the output produced at the start and end of the build, including the number of file system events and the state of the virtual file system.

```bash
$ ./gradlew assemble --watch-fs -Dorg.gradle.vfs.verbose=true
```

```text
Received 3 file system events since last build while watching 1 locations
Virtual file system retained information about 2 files, 2 directories and 0 missing files since last build
> Task :compileJava NO-SOURCE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :assemble UP-TO-DATE

BUILD SUCCESSFUL in 58ms
1 actionable task: 1 up-to-date
Received 5 file system events during the current build while watching 1 locations
Virtual file system retains information about 3 files, 2 directories and 2 missing files until next build
```

--------------------------------

### Example settings.gradle.kts file

Source: https://docs.gradle.org/current/userguide/part4_settings_file.html

A complete Kotlin settings file example with plugin declaration, root project name, and project includes.

```kotlin
plugins {                                                                   (1)
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"  (2)
}

rootProject.name = "authoring-tutorial"                                     (3)

include("app")                                                              (4)
include("lib")

includeBuild("gradle/license-plugin")                                       (5)
```

--------------------------------

### Example settings.gradle file

Source: https://docs.gradle.org/current/userguide/part4_settings_file.html

A complete Groovy settings file example with plugin declaration, root project name, and project includes.

```groovy
plugins {                                                                   (1)
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'   (2)
}

rootProject.name = 'running-tutorial-groovy'                                (3)

include('app')                                                              (4)
include('lib')

includeBuild('gradle/license-plugin')                                       (5)
```

--------------------------------

### Project structure for convention plugin example

Source: https://docs.gradle.org/current/userguide/plugins.html

Shows the directory layout of the example build with buildSrc, data-model, database-logic, and app subprojects.

```text
.
├── buildSrc
│   ├── src
│   │   └──...
│   └── build.gradle.kts
├── data-model
│   ├── src
│   │   └──...
│   └── build.gradle.kts
├── database-logic
│   ├── src
│   │   └──...
│   └── build.gradle.kts
├── app
│   ├── src
│   │   └──...
│   └── build.gradle.kts
└── settings.gradle.kts
```

--------------------------------

### Run gradle to test installation

Source: https://docs.gradle.org/current/userguide/part1_gradle_init.html

Run 'gradle' from the command line to verify the installation. If Gradle is not installed, refer to the installation section.

```bash
$ gradle
```

--------------------------------

### Example verbose build output showing task states

Source: https://docs.gradle.org/current/userguide/gradle_optimizations.html

Example output from running the verbose command, showing tasks marked UP-TO-DATE or NO-SOURCE.

```text
> Task :buildSrc:generateExternalPluginSpecBuilders UP-TO-DATE
> Task :buildSrc:extractPrecompiledScriptPluginPlugins UP-TO-DATE
> Task :buildSrc:compilePluginsBlocks UP-TO-DATE
> Task :buildSrc:generatePrecompiledScriptPluginAccessors UP-TO-DATE
> Task :buildSrc:generateScriptPluginAdapters UP-TO-DATE
> Task :buildSrc:compileKotlin UP-TO-DATE
> Task :buildSrc:compileJava NO-SOURCE
> Task :buildSrc:compileGroovy NO-SOURCE
> Task :buildSrc:pluginDescriptors UP-TO-DATE
> Task :buildSrc:processResources UP-TO-DATE
> Task :buildSrc:classes UP-TO-DATE
> Task :buildSrc:jar UP-TO-DATE
> Task :list:compileJava UP-TO-DATE
> Task :utilities:compileJava UP-TO-DATE
> Task :app:compileJava UP-TO-DATE

BUILD SUCCESSFUL in 374ms
12 actionable tasks: 12 up-to-date
```

--------------------------------

### Example output of help --task libs

Source: https://docs.gradle.org/current/userguide/command_line_interface.html

Example output from the `help --task libs` command, showing detailed task information for the 'libs' task.

```text
Detailed task information for libs

Paths
     :api:libs (registered in build file 'api/build.gradle')
     :webapp:libs (registered in build file 'webapp/build.gradle')

Type
     Task (org.gradle.api.Task)

Options
     --rerun     Causes the task to be re-run even if up-to-date.

Description
     Builds the JAR

Group
     build
```

--------------------------------

### Create and enter the plugin-tutorial directory

Source: https://docs.gradle.org/current/userguide/part1_gradle_init_plugin.html

Creates a new directory named `plugin-tutorial` and navigates into it. This is the first step before running `gradle init`.

```bash
$ mkdir plugin-tutorial
$ cd plugin-tutorial
```

--------------------------------

### Create tutorial directory

Source: https://docs.gradle.org/current/userguide/part1_gradle_init.html

Creates a new directory named 'tutorial'.

```bash
$ mkdir tutorial
```

--------------------------------

### Groovy property syntax examples

Source: https://docs.gradle.org/current/userguide/groovy_build_script_primer.html

Shows the general syntax for getting and setting properties, and embedding property values in strings.

```groovy
<obj>.<name>                // Get a property value
<obj>.<name> = <value>      // Set a property to a new value
"$<name>"                   // Embed a property value in a string
"${<obj>.<name>}"           // Same as previous (embedded value)
```

--------------------------------

### Groovy: Find all environment variables starting with JDK_

Source: https://docs.gradle.org/current/userguide/configuration_cache_requirements.html

This example uses System.getenv().findAll with a predicate to find environment variables whose names start with "JDK_". The predicate is opaque to the Configuration Cache, so all environment variables are considered inputs.

```groovy
def jdkLocations = System.getenv().findAll {
    key, _ -> key.startsWith("JDK_")
}
```

--------------------------------

### Create a new directory for the tutorial

Source: https://docs.gradle.org/current/userguide/part1_gradle_init_project.html

Creates a new directory named `authoring-tutorial` for the project.

```bash
$ mkdir authoring-tutorial
```

--------------------------------

### my-app/app/build.gradle - applying included plugin

Source: https://docs.gradle.org/current/userguide/composite_builds.html

Groovy DSL build script that applies the 'com.example.hello' plugin from the included build.

```groovy
plugins {
    id 'application'
    id('com.example.hello') // from the Included Build in pluginManagement
}
```

--------------------------------

### List tasks from a specific group with --group

Source: https://docs.gradle.org/current/userguide/command_line_interface.html

Use the `--group` option to display only tasks from a specific task group, for example 'build setup'.

```bash
$ ./gradlew tasks --group="build setup"
```

--------------------------------

### Check JAVA_HOME on Windows with echo %JAVA_HOME%

Source: https://docs.gradle.org/current/userguide/installation.html

Use this command on Windows to display the JAVA_HOME environment variable. The example output shows a JDK 17 installation directory.

```shell
$ echo %JAVA_HOME%
```

```text
C:\Program Files\Java\jdk17.0_6
```

--------------------------------

### Check JAVA_HOME on Unix with echo $JAVA_HOME

Source: https://docs.gradle.org/current/userguide/installation.html

Use this command on Unix-like systems to display the JAVA_HOME environment variable. The example output shows a JDK 17 installation directory.

```bash
$ echo $JAVA_HOME
```

```text
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
```

--------------------------------

### Groovy DSL: hello-a/build.gradle

Source: https://docs.gradle.org/current/userguide/plugins_intermediate.html

Applies the 'com.example.hello' plugin in the hello-a subproject.

```groovy
plugins {
    id 'com.example.hello'
}
```

--------------------------------

### Inject BuildInvocationDetails in Groovy DSL

Source: https://docs.gradle.org/current/userguide/service_injection.html

Groovy DSL example for a task that injects BuildInvocationDetails via constructor and prints the build start time. The service is only available via @Inject.

```groovy
abstract class ReportBuildStartTask extends DefaultTask {
    private BuildInvocationDetails invocationDetails

    @Inject //@javax.inject.Inject
    ReportBuildStartTask(BuildInvocationDetails invocationDetails) {
        this.invocationDetails = invocationDetails
    }

    @TaskAction
    void report() {
        def started = new Date(invocationDetails.buildStartedTime)
        println("Build started at $started")
    }
}

tasks.register("reportBuildStart", ReportBuildStartTask) {}
```

--------------------------------

### Kotlin DSL: hello-a/build.gradle.kts

Source: https://docs.gradle.org/current/userguide/plugins_intermediate.html

Applies the 'com.example.hello' plugin in the hello-a subproject.

```kotlin
plugins {
    id("com.example.hello")
}
```

--------------------------------

### Inject BuildInvocationDetails in Kotlin DSL

Source: https://docs.gradle.org/current/userguide/service_injection.html

Kotlin DSL example for a task that injects BuildInvocationDetails via constructor and prints the build start time. The service is only available via @Inject.

```kotlin
abstract class ReportBuildStartTask
@Inject constructor(private var invocationDetails: BuildInvocationDetails) : DefaultTask() {

    @TaskAction
    fun report() {
        val started = Date(invocationDetails.buildStartedTime)
        println("Build started at $started")
    }
}

tasks.register("reportBuildStart", ReportBuildStartTask::class) {}
```

--------------------------------

### Set JAVA_HOME and verify it

Source: https://docs.gradle.org/current/userguide/troubleshooting.html

Use these commands to set the JAVA_HOME environment variable to the location of your Java installation and then echo it to verify the value. The example uses a Corretto JDK path on macOS.

```bash
$ export JAVA_HOME=/Users/user/Library/Java/JavaVirtualMachines/corretto-22.0.1/Contents/Home
$ echo $JAVA_HOME

```

--------------------------------

### build.gradle.kts - Configuration and Execution Phase Example

Source: https://docs.gradle.org/current/userguide/build_lifecycle_intermediate.html

This build file demonstrates the configuration and execution phases. It registers tasks 'configured', 'test', and 'testBoth', with print statements showing when each part runs. The 'configured' task is not executed because it is not requested.

```kotlin
// Configuration Phase
println("This is executed during the configuration phase.")

tasks.register("configured") {
    println("This is also executed during the configuration phase.")
}

// Execution Phase
tasks.register("test") {
    doLast {
        println("This is executed during the execution phase.")
    }
}

// Configurations AND Execution Phase
tasks.register("testBoth") {
    println("This is executed during the configuration phase as well.")
    doFirst {
        println("This is executed first during the execution phase.")
    }
    doLast {
        println("This is executed last during the execution phase.")
    }
}
```

--------------------------------

### Resolve path relative to settings directory using layout.settingsDirectory (Groovy)

Source: https://docs.gradle.org/current/userguide/working_with_files.html

Groovy equivalent of the Kotlin example. Use layout.settingsDirectory.file("shared/config.xml").asFile to get a File relative to the settings directory.

```groovy
File configFile = layout.settingsDirectory.file("shared/config.xml").asFile
```

--------------------------------

### Full build script example (Kotlin DSL)

Source: https://docs.gradle.org/current/userguide/writing_build_scripts_intermediate.html

Complete build.gradle.kts example showing plugins, repositories, dependencies, application configuration, and task configuration. Includes numbered comments (1)-(5) that correspond to the breakdown sections.

```kotlin
plugins {   (1)
    id("application")
}

repositories {  (2)
    mavenCentral()
}

dependencies {  (3)
    testImplementation("org.junit.jupiter:junit-jupiter-engine:5.9.3")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    implementation("com.google.guava:guava:32.1.1-jre")
}

application {   (4)
    mainClass = "com.example.Main"
}

tasks.named<Test>("test") { (5)
    useJUnitPlatform()
}

tasks.named<Javadoc>("javadoc").configure {
    exclude("app/Internal*.java")
    exclude("app/internal/*")
}

tasks.register<Zip>("zip-reports") {
    from("Reports/")
    include("*")
    archiveFileName.set("Reports.zip")
    destinationDirectory.set(file("/dir"))
}
```

--------------------------------

### Use the<T>() for one-line extension configuration in build.gradle.kts

Source: https://docs.gradle.org/current/userguide/kotlin_dsl.html

Use the<T>() function to get a reference to an extension without configuring it, or for one-line configuration. This example configures the 'main' source set's Java source directory.

```kotlin
the<SourceSetContainer>()["main"].java.srcDir("src/main/java")
```

--------------------------------

### build.gradle - Configuration and Execution Phase Example (Groovy)

Source: https://docs.gradle.org/current/userguide/build_lifecycle_intermediate.html

This build file demonstrates the configuration and execution phases in Groovy DSL. It registers tasks 'configured', 'test', and 'testBoth', with print statements showing when each part runs.

```groovy
// Configuration Phase
println 'This is executed during the configuration phase.'

tasks.register('configured') {
    println 'This is also executed during the configuration phase.'
}

// Execution Phase
tasks.register('test') {
    doLast {
        println 'This is executed during the execution phase.'
    }
}

// Configurations AND Execution Phase
tasks.register('testBoth') {
    println 'This is executed during the configuration phase as well.'
    doFirst {
	  println 'This is executed first during the execution phase.'
	}
	doLast {
	  println 'This is executed last during the execution phase.'
	}
}
```

--------------------------------

### Command Line: Set JDK Home with -Dorg.gradle.java.home

Source: https://docs.gradle.org/current/userguide/build_environment.html

Use this command to specify the JDK installation directory via the command line. This has the highest precedence among configuration methods. The example includes the --scan flag.

```text
$ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan
```

--------------------------------

### Full build script example (Groovy DSL)

Source: https://docs.gradle.org/current/userguide/writing_build_scripts_intermediate.html

Complete build.gradle example showing plugins, repositories, dependencies, application configuration, and task configuration. Includes numbered comments (1)-(5) that correspond to the breakdown sections.

```groovy
plugins {   (1)
    id 'application'
}

repositories {  (2)
    mavenCentral()
}

dependencies {  (3)
    testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.9.3'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation 'com.google.guava:guava:32.1.1-jre'
}

application {   (4)
    mainClass = 'com.example.Main'
}

tasks.named('test', Test) { (5)
    useJUnitPlatform()
}

tasks.named('javadoc', Javadoc).configure {
    exclude 'app/Internal*.java'
    exclude 'app/internal/*'
}

tasks.register('zip-reports', Zip) {
    from 'Reports/'
    include '*'
    archiveFileName = 'Reports.zip'
    destinationDirectory = file('/dir')
}
```

--------------------------------

### AWS S3 IAM policy for publishing artifacts

Source: https://docs.gradle.org/current/userguide/upgrading_version_4.html

IAM policy example that grants the necessary permissions for publishing to an S3 bucket. Requires s3:PutObjectAcl and s3:PutObjectVersionAcl (if versioning is enabled) starting with Gradle 4.10.

```json
{
    "Version":"2012-10-17",
    "Statement":[
        // ...
        {
            "Effect":"Allow",
            "Action":[
                "s3:PutObject", // necessary for uploading objects
                "s3:PutObjectAcl", // required starting with this release
                "s3:PutObjectVersionAcl" // if S3 bucket versioning is enabled
            ],
            "Resource":"arn:aws:s3:::myCompanyBucket/*"
        }
    ]
}
```

--------------------------------

### beforeSettings callback in Kotlin init script

Source: https://docs.gradle.org/current/userguide/build_lifecycle.html

Use in an init script to tweak start parameters or log early info before settings are loaded. The example checks the CI environment variable and enables or disables parallel project execution accordingly.

```kotlin
// 1. beforeSettings: tweak start parameters / log early info
// before the build settings have been loaded and evaluated.
gradle.beforeSettings {
    println("[beforeSettings] gradleUserHome = ${gradle.gradleUserHomeDir}")

    // Example: default to --parallel if an env var is set
    if (System.getenv("CI") == "true") {
        println("[beforeSettings] Enabling parallel execution on CI")
        gradle.startParameter.isParallelProjectExecutionEnabled = true
    } else {
        println("[beforeSettings] Disabling parallel execution, not on CI")
        gradle.startParameter.isParallelProjectExecutionEnabled = false
    }
}
```

--------------------------------

### settings.gradle - Initialization Phase Example (Groovy)

Source: https://docs.gradle.org/current/userguide/build_lifecycle_intermediate.html

This settings file sets the root project name and prints a message during the initialization phase. It is the Groovy DSL equivalent of the Kotlin example.

```groovy
rootProject.name = 'basic'
println 'This is executed during the initialization phase.'
```

--------------------------------

### Include GitLab Gradle template

Source: https://docs.gradle.org/current/userguide/gitlab-ci.html

Include the official GitLab Gradle CI template to get a starting pipeline with build, test, and deploy stages. The template uses the gradle:alpine image and configures a .gradle/ cache keyed by branch.

```yaml
include:
  - template: Gradle.gitlab-ci.yml
```

--------------------------------

### Change into the tutorial directory

Source: https://docs.gradle.org/current/userguide/part1_gradle_init_project.html

Changes the current directory to `authoring-tutorial`.

```bash
$ cd authoring-tutorial
```

--------------------------------

### Change into tutorial directory

Source: https://docs.gradle.org/current/userguide/part1_gradle_init.html

Changes the current directory to 'tutorial'.

```bash
$ cd tutorial
```

--------------------------------

### my-app/app/build.gradle.kts - applying included plugin

Source: https://docs.gradle.org/current/userguide/composite_builds.html

Kotlin DSL build script that applies the 'com.example.hello' plugin from the included build.

```kotlin
plugins {
    id("application")
    id("com.example.hello") // from the Included Build in pluginManagement
}
```

--------------------------------

### Kotlin custom task with lazy Property input

Source: https://docs.gradle.org/current/userguide/implementing_custom_tasks.html

Kotlin DSL example of a custom task class using an abstract val Property<String> for lazy configuration. Avoids Java Bean properties and uses @get:Input. The task action prints the lazy property value and warns against using the eager property.

```kotlin
abstract class MyTask : DefaultTask() {
    // Avoid Java Bean properties
    @Input
    var myEagerProperty: String = "default value"

    // Use Gradle managed properties instead
    @get:Input
    abstract val myLazyProperty: Property<String>

    @TaskAction
    fun myAction() {
        println("Use ${myLazyProperty.get()} and do NOT use $myEagerProperty")
    }
}
```

--------------------------------

### Run multiple tasks sequentially

Source: https://docs.gradle.org/current/userguide/command_line_interface_basics.html

Example of running 'clean' first, then 'build'.

```text
gradle clean build
```

--------------------------------

### Install Gradle with SDKMAN!

Source: https://docs.gradle.org/current/userguide/installation.html

Use SDKMAN! to install Gradle on Unix-like systems. The command downloads and installs the latest version of Gradle.

```bash
$ sdk install gradle
```

--------------------------------

### Install Gradle with MacPorts

Source: https://docs.gradle.org/current/userguide/installation.html

Use MacPorts to install Gradle on macOS.

```bash
$ sudo port install gradle
```

--------------------------------

### Enable Configuration Cache and run help

Source: https://docs.gradle.org/current/userguide/configuration_cache_adoption.html

Run the help task with the --configuration-cache flag to test configuration-phase compatibility. The flag toggles CC per invocation without changing files.

```bash
$ ./gradlew help --configuration-cache
```

--------------------------------

### Install Gradle with Homebrew

Source: https://docs.gradle.org/current/userguide/installation.html

Use Homebrew to install Gradle on macOS.

```bash
$ brew install gradle
```

--------------------------------

### Create license-plugin directory and navigate into it

Source: https://docs.gradle.org/current/userguide/part3_multi_project_builds.html

Commands to create a new directory 'license-plugin' in the 'gradle' directory and navigate into it.

```bash
$ cd gradle

```

```bash
$ mkdir license-plugin

```

```bash
$ cd license-plugin

```

--------------------------------

### finalizedBy example in Groovy DSL

Source: https://docs.gradle.org/current/userguide/controlling_task_execution.html

Groovy version of the finalizedBy example.

```groovy
def taskX = tasks.register('taskX') {
    doLast {
        println 'taskX'
    }
}
def taskY = tasks.register('taskY') {
    doLast {
        println 'taskY'
    }
}

taskX.configure { finalizedBy taskY }
```

--------------------------------

### Plugin DSL syntax examples

Source: https://docs.gradle.org/current/userguide/plugins_intermediate.html

Shows the general syntax of the plugins{} block, including applying by name and by id with optional version.

```text
plugins {
    application                                     // by name
    java                                            // by name
    id("java")                                      // by id - recommended
    id("org.jetbrains.kotlin.jvm") version "1.9.0"  // by id - recommended
}
```

--------------------------------

### Run a single task

Source: https://docs.gradle.org/current/userguide/command_line_interface_basics.html

Example of running a task named 'build'.

```text
gradle build
```
Tokens:
Raw