Common Gradle Build Patterns & Conventions

A collection of idiomatic patterns for common Gradle build scenarios, including multi-project setups, convention plugins, and task registration.

1. Multi-Project Build Structure

Standard project structure with a root project and multiple subprojects.

Directory Structure

root/
├── build.gradle.kts
├── settings.gradle.kts
├── libs.versions.toml
├── app/
│   └── build.gradle.kts
├── core/
│   └── build.gradle.kts
└── build-logic/
    ├── build.gradle.kts
    └── settings.gradle.kts

`settings.gradle.kts`

pluginManagement {
    includeBuild("build-logic")
}

rootProject.name = "my-project"
include(":app", ":core")

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
    repositories {
        mavenCentral()
    }
}

2. Convention Plugins (The `build-logic` Pattern)

Move common project configuration logic into separate plugins to reduce duplication in build.gradle.kts files.

`build-logic/build.gradle.kts`

plugins {
    `kotlin-dsl`
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0")
}

`build-logic/src/main/kotlin/my-convention.gradle.kts`

plugins {
    kotlin("jvm")
}

repositories {
    mavenCentral()
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

Usage in Subprojects

plugins {
    id("my-convention")
}

3. Registering Custom Tasks

Use lazy task registration and configure properties with the Property and Provider APIs.

abstract class MyCustomTask : DefaultTask() {
    @get:Input
    abstract val message: Property<String>

    @TaskAction
    fun action() {
        println("Message: ${message.get()}")
    }
}

tasks.register<MyCustomTask>("myTask") {
    message.set("Hello from custom task!")
}

4. Configuring Standard Plugins

Java/Kotlin Library

plugins {
    `java-library`
    kotlin("jvm")
}

dependencies {
    api("com.example:some-api:1.0")
    implementation("com.example:some-impl:1.0")
    testImplementation(kotlin("test"))
}

Application Plugin

plugins {
    application
}

application {
    mainClass.set("com.example.Main")
}

2.8 KiB Raw Blame History

Common Gradle Build Patterns & Conventions

1. Multi-Project Build Structure

Directory Structure

settings.gradle.kts

2. Convention Plugins (The build-logic Pattern)

build-logic/build.gradle.kts

build-logic/src/main/kotlin/my-convention.gradle.kts