Setting Up a Clean Gradle Multi-Project Structure from Scratch

Posted on Edited on

This article will guide you through setting up a clean Gradle multi-project structure from scratch.

Project Structure Overview

A typical Gradle multi-project structure looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
my-multi-project/
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── projectA/
│   ├── build.gradle
│   └── src/
├── projectB/
│   ├── build.gradle
│   └── src/
├── build.gradle
├── gradlew
├── gradlew.bat
└── settings.gradle

Root Directory Setup

1. Creating settings.gradle

This is the core configuration file for multi-project structures:

1
2
3
4
rootProject.name = 'my-multi-project'

// Include subprojects
include 'projectA', 'projectB'

2. Gradle Wrapper Setup

Ensure your project includes these essential files:

  • gradlew (Unix) and gradlew.bat (Windows) - Gradle Wrapper executables
  • gradle/wrapper/gradle-wrapper.jar - Wrapper JAR file
  • gradle/wrapper/gradle-wrapper.properties - Wrapper configuration

Initialize the wrapper using:

1
gradle wrapper

3. Root build.gradle (Optional)

If you need to manage common settings for all subprojects, create a root build.gradle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.9.0' apply false
}

// Common settings for all subprojects
subprojects {
    repositories {
        mavenCentral()
    }
    
    // Additional common configurations
    tasks.withType(JavaCompile) {
        sourceCompatibility = '21'
        targetCompatibility = '21'
    }
}

Subproject Configuration

Subproject Independence

For independent subproject operation, create a settings.gradle in the subproject directory:

1
rootProject.name = 'projectA'

Subproject build.gradle

Each subproject needs its own build script:

1
2
3
4
5
6
7
8
plugins {
    id 'org.jetbrains.kotlin.jvm'
}

dependencies {
    implementation 'org.example:library:1.0.0'
    // Project-specific dependencies
}

Common Commands

View Project Structure

1
./gradlew projects

Example output:

1
2
3
Root project 'my-multi-project'
+--- Project ':projectA'
+--- Project ':projectB'

Build Commands

Build all projects:

1
./gradlew build

Build specific project:

1
./gradlew :projectA:build

Running Specific Projects

Run from root directory:

1
./gradlew :projectA:run

Or from subproject directory:

1
2
cd projectA
../gradlew run

Best Practices

  1. Keep root directory clean with only necessary configuration files
  2. Place common configurations in root build.gradle
  3. Maintain modular subprojects, avoid excessive dependencies
  4. Utilize buildSrc directory for custom build logic
  5. Use version catalogs for unified dependency management

Alternative: Using Kotlin DSL

Gradle also supports Kotlin DSL for build scripts. Here’s how the previous examples would look using Kotlin DSL:

Root settings.gradle.kts

1
2
3
rootProject.name = "my-multi-project"

include("projectA", "projectB")

Root build.gradle.kts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
plugins {
    kotlin("jvm") version "1.9.0" apply false
}

subprojects {
    repositories {
        mavenCentral()
    }
    
    tasks.withType<JavaCompile> {
        sourceCompatibility = "21"
        targetCompatibility = "21"
    }
}

Subproject build.gradle.kts

1
2
3
4
5
6
7
plugins {
    kotlin("jvm")
}

dependencies {
    implementation("org.example:library:1.0.0")
}

Advantages of Kotlin DSL

  • Better IDE support with auto-completion
  • Strong type checking
  • Better refactoring support
  • Better Kotlin project integration

However, Kotlin DSL might have:

  • Steeper learning curve
  • Slightly slower build times
  • More verbose syntax in some cases

Important Notes When Using Kotlin DSL

  • File names must end with .gradle.kts
  • String literals use double quotes instead of single quotes
  • Different syntax for applying plugins and configuring tasks
  • Cannot mix Groovy and Kotlin DSL in the same project

Conclusion

This multi-project structure enables:

  • Better organization of large projects
  • Reuse of common configurations
  • Independent module management
  • Improved build efficiency

This architecture is ideal for modular large-scale projects, facilitating team collaboration and code management.