Mastering the Build: A Deep Dive into Gradle

20 min readJun 12, 2026

For many developers, moving from Maven to Gradle feels like graduating from a rigid configuration file to a full-fledged programming language. While Maven provides a structured “Convention over Configuration” approach, Gradle provides the power of code to define your build process.

In this post, we will dissect why Gradle has become the de facto standard for modern JVM projects, explore its “Build Script” philosophy, and clarify how it handles performance through smart caching.

The Philosophy: Build as Code

Maven’s pom.xml is a declarative document. You define what the project is, and Maven executes its rigid lifecycle. Gradle, conversely, uses a Domain Specific Language (DSL)—traditionally Groovy, but increasingly Kotlin—to define how the project is built. This means your build script is essentially a program. If you need to manipulate a file, query a database before compiling, or execute a conditional task based on the environment, you don't need a plugin; you can simply write the logic

This shift allows for:
1. Dynamic Logic: Unlike XML, you can use if-else blocks, loops, and external API calls directly within your build file.
2. Conciseness: The ability to define complex logic in a few lines of code significantly reduces the “boilerplate” common in large Maven POMs.

The Heart of Gradle: The Task & The Project

Tasks

In Maven, you have a rigid lifecycle (compile -> test -> package -> install). In Gradle, you have Tasks.

Everything in Gradle is a task. A task in Gradle is the fundamental unit of work in a Gradle build — the smallest executable step that Gradle can run. The official Gradle documentation defines a task as “an independent unit of work that a build performs”, such as compiling code, running tests, packaging artifacts, or generating documentation. A build is essentially a collection of tasks connected by dependencies.

A Gradle task represents one specific action your build needs to perform. Examples include:
1. compileJava — compiles Java source code
2. test — runs unit tests
3. jar — packages compiled classes into a JAR
4. copy — copies files

You can build your custom task as well

Each task can have:
1. Inputs (files, properties)
2. Outputs (generated files)
3. Actions (code executed during the task)

Tasks rarely run alone. They can depend on other tasks, and Gradle automatically determines the correct execution order.

Example: Running ./gradlew build triggers:
compileJava
processResources
classes
jar
assemble
check
build

Gradle skips tasks whose outputs are already up‑to‑date.

Gradle analyzes your task dependencies to create a DAG. It calculates exactly which tasks need to be executed to reach your goal. eg If you run ./gradlew build, Gradle knows test depends on classes, which depends on compileJava. It executes only what is necessary in the optimal order.

Projects

A Project in Gradle is the top‑level unit of organization in a Gradle build. Everything you build — a library, an application, a microservice, or even a documentation module — is represented as a Project. A Gradle Project is a logical unit of work in a build, defined by a build.gradle file, and it contains tasks, plugins, configurations, and dependencies.

A project is basically the context in which tasks run. If you’re coming from Maven, think of a Gradle Project ≈ Maven Module, but more flexible.

A Gradle Project typically includes:
1. A build script ( typically named build.gradle)
2. Tasks (compile, test, jar, custom tasks)
3. Plugins (java, application, spring-boot, etc.)
4. Dependencies (external libraries, other projects)
4. Configurations (compileClasspath, runtimeClasspath)
5. Source sets (main, test)
6. Properties (project.name, project.version)
7. Artifacts (JAR, WAR, ZIP, etc.)

A Project is a container. A Task is a unit of work inside that container.

Project: my-app
 ├── Task: compileJava
 ├── Task: test
 ├── Task: jar
 └── Task: customTask

Plugins

A plugin in Gradle is a reusable extension that adds new capabilities to a Gradle project — such as new tasks, conventions, configurations, or integrations with frameworks and languages. If a task is a unit of work, then a plugin is what teaches your project new kinds of work.

Without plugins, every project would need to manually define: how to compile Java, how to run tests, how to package a JAR, how to publish artifacts, etc. Plugins solve this by packaging all that logic once and letting you reuse it.

There are different types of plugins:

Core Plugins (built into Gradle)

These come with Gradle itself. eg: java (adds Java compilation, testing, JAR tasks), application (adds run task for Java apps), java-library (adds API/implementation separation), maven-publish (publishing to Maven repos), idea/eclipse (IDE integration)

Usage example:

plugins {
    id 'java'
}

Community Plugins (from Gradle Plugin Portal)

Created by the community or companies. e.g: org.springframework.boot (Spring Boot support), com.github.johnrengelman.shadow ( fat/uber jar), io.freefair.lombok (Lombok integration)

Usage example:

plugins {
    id 'org.springframework.boot' version '3.2.0'
}

Custom Plugins (you write them)

You can write your own plugin as well. Some typical use cases can be to enforce company conventions, to add custom tasks or to automate repetitive custom build logic

Example:

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.tasks.register("hello") {
            doLast { println "Hello from plugin!" }
        }
    }
}

When applied, a plugin can:
1. Add tasks (e.g., compileJava, test, bootRun)
2. Add configurations (e.g., implementation, runtimeOnly)
3. Add conventions (eg default directory layout, default Java version)
4. Add extensions (e.g., springBoot)
5. Add dependencies (e.g., Spring Boot plugin adds BOMs)

For example, when you apply:

plugins {
    id 'java'
}

Gradle automatically adds tasks like: compileJava, processResources, test, jar, javadoc etc. This is why plugins are so powerful — they configure your project for you.

Configurations (Dependency Scopes)

n Gradle, configurations are the core mechanism for managing dependencies. You can think of them as named groups of dependencies that serve specific purposes in your build lifecycle, such as compiling your code, running tests, or packaging your application. Each configuration defines how a set of files (dependencies) is retrieved, used, and exposed to other parts of the build.

Key concepts:

Grouping: Configurations allow you to categorize dependencies based on their function (e.g., compile-time vs. runtime).
Inheritance: Configurations can extend other configurations, allowing you to build complex dependency structures easily.
Resolution: When you build your project, Gradle “resolves” the configuration, meaning it looks at the dependencies listed, finds the correct versions, and downloads them.

If you are using the java plugin, Gradle provides several standard configurations out of the box:

implementation: Dependencies required to compile and run your code, but not exposed to consumers of your library. This is the recommended default.
api: Dependencies required to compile and run your code, and are also exposed to consumers of your library (used in java-library).
compileOnly: Dependencies needed only at compile time (e.g., annotations that aren’t needed at runtime).
runtimeOnly: Dependencies not needed for compilation but required to run the application.
testImplementation: Dependencies required to compile and run your tests.

in build.gradlein your dependencies block, you assign dependencies to specific configurations:

dependencies {
    // Used for the main application code
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    
    // Only needed during compilation, not included in the final artifact
    compileOnly 'org.projectlombok:lombok:1.18.24'
    
    // Only needed for running tests
    testImplementation 'org.junit.jupiter:junit-jupiter:5.8.2'
}

Advantages:
1. Optimization: By using specific configurations like compileOnly, you prevent unnecessary files from being included in your final JAR or WAR file, making your application smaller and faster.
2. API Encapsulation: By using implementation instead of api (where appropriate), you prevent "dependency leaking," which speeds up build times for other projects that depend on yours.
3. Clarity: They provide a standardized way for developers to understand exactly what a dependency is doing within the project.

Dependencies

Gradle handles dependencies through a declarative, layered dependency management system that resolves libraries from repositories, builds a dependency graph, applies conflict resolution, and ensures reproducible builds. It’s one of the reasons Gradle is so much more flexible than Maven.

Unlike Maven’s limited scope (compile, test, provided), Gradle uses Configurations to group dependencies. Dependencies live inside configurations such as implementation, api, compileOnly, runtimeOnly etc

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
}

Each configuration represents a classpath.

Gradle resolves dependencies from repositories you define:

repositories {
    mavenCentral()
    mavenLocal()
    google()
}

You can also add private repos:

maven {
    url "https://company.jfrog.io/artifactory/libs-release"
}

When you run a task like build, Gradle:
1. Reads your dependency declarations
2. Fetches metadata (POM files)
3. Builds a dependency graph
4. Downloads required JARs
5. Applies conflict resolution
6. Produces the final classpath

Conflict Resolution (Gradle’s Secret Weapon)
If two libraries bring different versions of the same dependency:

A → Guava 30.0
B → Guava 31.1

Gradle uses newest‑version‑wins by default. You can override it:

configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:30.0-jre'
    }
}

You can even reject certain versions:

rejectVersionIf {
    it.candidate.version.endsWith('-beta')
}

By default, Gradle automatically pulls in transitive dependencies (dependencies of your dependencies).

implementation 'org.springframework.boot:spring-boot-starter-web'

This single line brings in: Spring MVC, Jackson, Tomcat etc. You can explicitly disable transitivity as well :

implementation('com.example:lib') {
    transitive = false
}

Gradle caches downloaded JARs, metadata, resolved dependency graphs etc. This makes subsequent builds extremely fast

Version Catalogs

Gradle 7+ introduced version catalogs for centralized dependency management, providing a type-safe, scalable way to manage your project’s dependencies and plugin versions. Instead of hardcoding versions directly in your build.gradle files, you define them in a single place, making updates and maintenance significantly easier.

Why Use Version Catalogs?

Single Source of Truth: You define a version once and reference it across multiple modules. If you need to upgrade a library, you change it in one location.
Type-Safety and Auto-completion: Since they generate type-safe accessors, your IDE can provide autocomplete suggestions when you are defining dependencies.
Reduced Duplication: They prevent “version drift,” where different sub-projects might accidentally use different versions of the same library.
Sharing across Builds: They can be shared across multiple independent projects, allowing you to standardize your stack across an entire organization.

By default, Gradle looks for a file located at gradle/libs.versions.toml. This is a TOML file organized into four main sections:

# gradle/libs.versions.toml

[versions]
# Define versions here
retrofit = "2.9.0"
junit = "5.9.2"

[libraries]
# Contains the coordinates (group, name, version) for your external dependencies.
retrofit-core = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
junit-jupiter = { group = "org.junit.jupiter", name = "junit-jupiter", version.ref = "junit" }

[bundles]
# Creates a logical grouping of dependencies. If you always use some libraries, you can bundle them so that adding one line in your build.gradle adds all of them.
common-tests = ["junit-jupiter"]

[plugins]
# Simplifies plugin management by keeping the ID and version separate from the logic.
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version = "1.8.0" }

Once defined, you can reference these in your build scripts using a human-readable syntax that the IDEs and build tools understand:

dependencies {
    // Accessing the catalog via the 'libs' accessor
    implementation libs.retrofit.core
    testImplementation libs.bundles.common.tests
}

plugins {
    alias(libs.plugins.kotlin.jvm)
}

This is now the recommended approach for large codebases. You should move to Version Catalogs as soon as your project grows beyond a single module or if you find yourself managing more than a handful of dependencies.

Source Sets

In Gradle, Source Sets are a way to group your project’s source files — such as Java or Kotlin code and resources — into distinct collections that are treated as a single unit for compilation and execution. Think of a Source Set as a logical partition of your project. Each partition has its own source directory, resources directory, and compilation settings.

By default, the java plugin creates two primary source sets for your project:
1. main: Contains the code that will be packaged into your final application or library (the production code).
2. test: Contains the code used to verify the main source set (your unit and integration tests).

Each source set has its own associated configuration and directory structure. When you define a source set, you typically point to these elements:

Source Directory: Where the .java or .kt files live.
Resources Directory: Where non-code assets live (e.g., icons, text files, properties).
Compile Classpath: The dependencies required to compile this specific set of files.
Runtime Classpath: The dependencies required to execute this specific set of files.

You can create your own source sets in your build.gradle if you have specific testing requirements, such as a separate set for integration tests:

sourceSets {
    // Create a new source set named 'intTest'
    intTest {
        java {
            srcDir 'src/intTest/java'
        }
        resources {
            srcDir 'src/intTest/resources'
        }
    }
}

// Ensure the integration test code can access your main code
dependencies {
    intTestImplementation sourceSets.main.output
    intTestImplementation configurations.testImplementation
}

Gradle automatically creates the main and test source sets for you, following the standard directory structure (src/main/java, src/test/java, etc.). You only need to define custom ones if your project structure is non-standard.

When you add a source set, Gradle automatically creates tasks to compile, process resources, and test that specific source set (e.g., compileIntTestJava, processIntTestResources). Each source set is linked to specific configurations (e.g., testImplementation is tied specifically to the test source set), ensuring that only the necessary dependencies are present during compilation and runtime.

Properties

In Gradle, Properties are the mechanism used to pass configuration, environment settings, or project-specific variables into your build. They allow you to parameterize your build process without hardcoding values directly into your build.gradle files.

Think of them as key-value pairs that your build scripts can read at runtime to change how they behave.

Gradle looks for properties in several places, following a specific hierarchy (the first one found wins):
1. Command Line: Passed via -P flag (e.g., -PmyProp=value).
2. System Environment Variables: Defined in your OS (e.g., ORG_GRADLE_PROJECT_myProp=value).
3. gradle.properties (Project level): Located in the root of your project directory.
4. gradle.properties (Global): Located in your ~/.gradle/ directory.

The most common way to define project properties is in the gradle.properties file:

# gradle/gradle.properties
# Global project settings
minSdkVersion=24
versionCode=1
isRelease=false

Gradle automatically makes these properties available as dynamic properties on your Project object. You can access them directly by name:

android {
    defaultConfig {
        minSdkVersion project.minSdkVersion // Accessing the property
        versionCode project.versionCode.toInteger()
    }
}

You can override properties at runtime, which is highly useful for CI/CD pipelines (e.g., switching between debug and release builds):

# This overrides the 'isRelease' property for just this execution
./gradlew build -PisRelease=true

Best Practices:
1. Avoid Sensitive Data in Code: Never commit secrets (API keys, passwords) to your gradle.properties file if it is in version control. Instead, use local environment variables or the ~/.gradle/gradle.properties file (which is outside the project folder).
2. Use Descriptive Names: Since properties become part of the Project namespace, use clear, specific names to avoid conflicts with existing Gradle methods or properties.
3. Type Casting: Remember that properties read from gradle.properties are treated as Strings by default. You will often need to call .toInteger() or .toBoolean() when using them in build logic.

Artifacts

In the context of Gradle, Artifacts are the tangible output files produced by your build process. When you run a build, Gradle compiles your source code and resources and packages them into a format that can be consumed by other projects or deployed to a server. Common examples include .jar (Java Archive), .war (Web Archive), .aar (Android Archive), or even documentation like Javadoc. Artifacts are the result of the build lifecycle

Gradle uses the ArtifactHandler to define and publish these outputs. While the standard plugins (like java or java-library) automatically handle the creation of standard JARs, you can define custom artifacts in your build.gradle file.

Example: defining a custom artifact: If you want to package a specialized report or a specific set of configuration files as an artifact, you can do so like this:

// Define a custom task that creates a zip file
tasks.register('customDist', Zip) {
    from 'src/dist'
    archiveClassifier = 'custom'
}

// Add this file as an artifact to the 'archives' configuration
artifacts {
    archives customDist
}

Artifacts are tied to configurations. When you define an artifact, you assign it to a configuration (like archives or runtimeElements) to tell Gradle who needs this file and when it should be produced.

To make your artifacts available to others, you use the maven-publish or ivy-publish plugins. These plugins take the artifacts you've defined and upload them to a repository server.

When you publish an artifact, you usually publish a .pom or .module file with it. This file tells downstream consumers exactly what dependencies they need to include to run your artifact successfully.

Common built-in tasks in the Java plugin

compileJava

Compiles all Java files under src/main/java using the JDK compiler.

to invoke:

./gradlew compileJava

Customizing it:

tasks.compileJava {
    options.encoding = 'UTF-8'
    options.release = 17
}

processResources

Copies everything under src/main/resources into the build output directory (optionally performing filtering, token replacement, renaming, or excluding files)

to invoke:

./gradlew processResources

Here are some common customizations:

Replace placeholders inside resource files (token filtering)

tasks.processResources {
    filesMatching("**/application.properties") {
        expand(version: project.version)
    }
}

Copy only specific files (include patterns)

tasks.processResources {
    include("**/*.yaml", "**/*.json")
}

Exclude unwanted files

tasks.processResources {
    exclude("**/*.tmp", "**/*.bak")
}

Rename files during processing

tasks.processResources {
    rename { fileName ->
        fileName.replace(".template", "")
    }
}

Add additional resource directories

sourceSets {
    main {
        resources {
            srcDir "src/common/resources"
        }
    }
}

Copy resources with custom destination logic

tasks.processResources {
    from("src/main/resources") {
        into("config")
    }
}

Use filtering (e.g., replace variables inside files)

tasks.processResources {
    filter(org.apache.tools.ant.filters.ReplaceTokens, tokens: [
        env: "production",
        apiUrl: "https://api.example.com"
    ])
}

You can also use a combination of customizations like this:

tasks.processResources {
    // Replace tokens in .properties files
    filesMatching("**/*.properties") {
        expand(
            version: project.version,
            buildTime: new Date().toString()
        )
    }

    // Exclude unnecessary files
    exclude("**/*.bak", "**/*.tmp")

    // Rename template files
    rename { name ->
        name.endsWith(".template") ? name.replace(".template", "") : name
    }
}

classes

Essentially an aggregator for compileJava and processResources

Get Kaustubh Saha’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

To invoke

./gradlew classes

compileTestJava

Compiles everything under src/test/java.

To invoke:

./gradlew compileTestJava

Example:

tasks.compileTestJava {
    options.release = 17
    options.compilerArgs += ['-parameters']
}

processTestResources

Copies files from src/test/resources

To invoke:

./gradlew processTestResources

Example:

tasks.processTestResources {
    duplicatesStrategy = DuplicatesStrategy.INCLUDE
}

testClasses

Aggregator for compileTestJava + processTestResources

To invoke:

./gradlew testClasses

test

Runs JUnit/TestNG tests.

To invoke:

./gradlew test

Example:

tasks.test {
    useJUnitPlatform()
    testLogging {
        events "passed", "skipped", "failed"
        showStandardStreams = true
    }
    maxParallelForks = Runtime.runtime.availableProcessors()
}

jar

Creates build/libs/<project>-<version>.jar.

To invoke:

./gradlew jar

Example:

tasks.jar {
    archiveBaseName = "myapp"
    archiveVersion = "1.2.3"

    manifest {
        attributes(
            'Main-Class': 'com.example.Main'
        )
    }

    from("LICENSE") {
        into("META-INF")
    }
}

javadoc

Runs the Javadoc tool and generates API documentation

To invoke:

./gradlew javadoc

Example:

tasks.javadoc {
    options.memberLevel = JavadocMemberLevel.PRIVATE
    options.addStringOption('Xdoclint:none', '-quiet')
}

A few other common built-in tasks and plugins

shadow plugin/shadowJar task

This is the industry‑standard way for creating fat jar/uber jar. It automatically handles dependency merging, avoiding duplicate classes, minimizing jar size, etc

Apply the plugin

plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '8.1.1'
}

Customize the fat JAR

shadowJar {
    archiveBaseName.set('myapp')
    archiveClassifier.set('fat')
    archiveVersion.set('1.0.0')

    mergeServiceFiles()   // handles META-INF/services
    minimize()            // removes unused classes
}

Build the fat JAR

./gradlew shadowJar

OSpackage plugin/buildRpm task

Apply the plugin

plugins {
    id 'java'
    id 'nebula.ospackage' version '11.4.0'
}

Configure the RPM

ospackage {
    packageName = 'myapp'
    version = '1.0.0'
    release = '1'
    arch = 'x86_64'
    os = 'LINUX'

    summary = 'My Java Application'
    description = 'This is a sample RPM built using Gradle.'

    // Where the app will be installed
    into '/opt/myapp'

    // Include your fat jar or normal jar
    from('build/libs') {
        include 'myapp.jar'
        into 'lib'
    }

    // Include config files
    from('config/') {
        into 'config'
    }

    // Add scripts
    preInstall file('scripts/preinstall.sh')
    postInstall file('scripts/postinstall.sh')
}

Build the RPM

./gradlew buildRpm

jacocoTestReport

For generating test coverage report

Add the Jacoco plugin

plugins {
    id "jacoco"
}

Configure the jacoco plugin

tasks.jacocoTestReport {
    dependsOn test
    reports {
        xml.required = true
        html.required = true
    }
}

Generate coverage report

./gradlew test jacocoTestReport

sonar

Add the SonarQube plugin in your build.gradle

plugins {
    id "java"
    id "org.sonarqube" version "4.4.1.3373"
}

Configure SonarQube Connection:

sonar {
    properties {
        property "sonar.projectKey", "myapp"
        property "sonar.projectName", "My Application"
        property "sonar.host.url", "http://localhost:9000"
        property "sonar.login", "admin"
        property "sonar.password", "admin"
        property "sonar.java.coveragePlugin", "jacoco"
        property "sonar.jacoco.reportPaths", "build/jacoco/test.exec"
        property "sonar.coverage.jacoco.xmlReportPaths", "build/reports/jacoco/test/jacocoTestReport.xml"
    }
}

Run the analysis

./gradlew clean build sonar

dependencies

This is the Gradle equivalent of mvn dependency:tree.

To invoke:

./gradlew dependencies

To show only the Resolved Dependency Graph (No Versions Conflicts):

./gradlew dependencyInsight --dependency <name>

Example:

./gradlew dependencyInsight --dependency guava

Standard Files and Directories associated with Gradle

In a mature Gradle project, these are the standard files and directories you will encounter.

The core build files

These are the files that define how your build behaves and how your project structure is organized.

build.gradle (or build.gradle.kts): The primary build script for a specific project. If you are using Kotlin DSL, the extension is .kts. This file is where you define plugins, dependencies, and task logic.
settings.gradle (or settings.gradle.kts): The "root" configuration file. It tells Gradle which projects are part of the build (in a multi-module setup) and defines global settings. It is executed before any build.gradle files.
gradle.properties: A key-value pair file used to define build properties, such as JVM arguments, proxy settings, or project-wide version variables.
gradlew & gradlew.bat: The Gradle Wrapper scripts. You should never run a locally installed version of Gradle; always use the wrapper. These ensure that every developer on the team uses the exact same version of Gradle, regardless of what is installed on their system
gradle-wrapper.jar: The code that downloads and runs the actual Gradle distribution.
gradle-wrapper.properties: Defines the specific Gradle version to be used and where to download it from.

Version Catalogs

As discussed already, in newer projects, you should centralize your dependencies using the Version Catalog feature.

gradle/libs.versions.toml: This is the standard file for declaring all your library versions, dependency bundles, and plugin versions in one place. It eliminates the "version spread" issue common in Maven.

Standard Directory Structure

Gradle adheres to the Maven conventions by default, but it allows you to override these easily in your build.gradle.

root-project/
├── build.gradle
├── settings.gradle
├── gradle.properties
├── gradlew
├── gradle/
│   ├── wrapper/
│   └── libs.versions.toml
├── src/
│   ├── main/
│   │   ├── java/         # Production Java code
│   │   ├── resources/    # Configs, properties, templates
│   └── test/
│       ├── java/         # Test code
│       └── resources/
└── build/                # Generated artifacts (equivalent to Maven's 'target')

Hidden/Generated Files

.gradle/: This directory is generated by the build. It contains internal state, cached task results, and checksums used for incremental builds. Do not commit this to version control.
.gradle-cache/: Your local global cache, typically located in your home directory (~/.gradle/caches), which holds downloaded dependencies and cached build outputs.

Let's take a basic Maven pom and convert it to equivalent Gradle files. Here’s an example pom:

<project>
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.example.finance</groupId>
    <artifactId>market-data-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    
    <properties>
        <java.version>21</java.version>
        <junit.version>5.10.0</junit.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

build.gradle

This translates your pom.xml directly. Note how the plugin configuration replaces the verbose Maven <plugin> block.

plugins {
    id 'java'
}

group = 'com.example.finance'
version = '1.0.0-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(libs.versions.java.get())
    }
}

dependencies {
    testImplementation libs.junit.jupiter.api
}

tasks.named('test') {
    useJUnitPlatform()
}

libs.versions.toml

This decouples your versions from the build logic, mirroring how Maven <properties> work but in a centralized, type-safe way.

[versions]
java = "21"
junit = "5.10.0"

[libraries]
junit-jupiter-api = { group = "org.junit.jupiter", name = "junit-jupiter-api", version.ref = "junit" }

Key Differences

Java Versioning: In Maven, you set the maven-compiler-plugin source/target properties. In Gradle, we use the java { toolchain { ... } } block. This is superior because it allows Gradle to automatically provision the JDK if it's missing on the build machine.
Test Framework: Maven requires the maven-surefire-plugin for JUnit. In Gradle, simply adding useJUnitPlatform() to the test task is sufficient to bridge the execution.
Scope: Maven’s test scope maps directly to Gradle's testImplementation configuration.

Multi-Module Gradle Projects

A multi‑module Gradle project lets you organize a large codebase into smaller, reusable modules (like core, service, api, etc.). Gradle treats each module as a subproject, all managed by a single root project.

Directory structure:

my-parent-project/
├── settings.gradle
├── build.gradle        <-- root build
├── core/
│   └── build.gradle    <-- subproject 1
├── service/
│   └── build.gradle    <-- subproject 2
└── api/
    └── build.gradle    <-- subproject 3

Each folder with a build.gradle is a module.

The settings.gradle file defines the modules

rootProject.name = 'my-parent-project'

include 'core'
include 'service'
include 'api'

You can also nest modules:

include 'services:payment'
include 'services:auth'

The parent build.gradle file is the shared configuration — this is where you put common settings for all modules. This avoids duplication across modules.

plugins {
    id 'java'
}

subprojects {
    apply plugin: 'java'

    group = 'com.mycompany'
    version = '1.0.0'

    repositories {
        mavenCentral()
    }

    dependencies {
        testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
    }

    tasks.test {
        useJUnitPlatform()
    }
}

Each module has its own dependencies and tasks.

eg: Module 1: core/build.gradle

dependencies {
    implementation 'com.google.guava:guava:32.0.0'
}

Module 2: api/build.gradle

dependencies {
    implementation project(':core')   // depends on core module
}

Module 3: service/build.gradle

dependencies {
    implementation project(':core')
    implementation project(':api')
}

This is how modules declare dependencies on each other.

If service depends on api, and api depends on core, Gradle takes that into account and builds them in the correct order: core → api → service

Gradle Wrapper

A Gradle Wrapper is a small set of files that allows anyone to build your project using the exact same Gradle version, without requiring Gradle to be installed on their machine. It is one of Gradle’s smartest features — and every serious project uses it. The Gradle Wrapper is a script + config that downloads and uses a specific Gradle version automatically, ensuring consistent, reproducible builds.

Without the wrapper:
Every developer must install Gradle manually
Different Gradle versions = inconsistent builds
CI/CD machines need Gradle installed
Onboarding becomes painful

With the wrapper:
No installation needed
CI/CD works out of the box
Everyone uses the same Gradle version
Builds are reproducible and stable

How to create the wrapper ?

If your project doesn’t have it yet:

gradle wrapper

Or you can even explicitly specify a version

gradle wrapper --gradle-version 8.7

This generates the wrapper files.

gradlew               <-- Unix shell script
gradlew.bat           <-- Windows batch script
gradle/wrapper/
    gradle-wrapper.jar
    gradle-wrapper.properties

These files:
1. Download the correct Gradle version
2. cache it
3. run your build using that version

Instead of running: gradle build, you now run ./gradlew build ( or gradlew.bat build on Windows). This ensures the build uses the exact Gradle version defined in gradle/wrapper/gradle-wrapper.properties

How does Gradle outpace Maven ?

Gradle’s ability to “outpace” Maven is not accidental; it is the result of architectural choices made to avoid redundant work. While Maven is built on a fixed, linear lifecycle, Gradle was engineered as a task-based engine designed to maximize efficiency through three main performance pillars.

Incremental Builds

The most significant difference is how they handle the build process.

Maven historically treats a build as a linear sequence of phases. Even if only one file changes, Maven often re-executes goals across the entire project lifecycle
Gradle analyzes the inputs and outputs of every single task. It creates a “snapshot” of the state of your project. If the source files, dependencies, and environment variables for a specific task have not changed since the last run, Gradle marks that task as UP-TO-DATE and skips it entirely. It refuses to perform work that has already been done

The Gradle Daemon

Starting a JVM for every build command is expensive in terms of time and resources. The Gradle Daemon is a long-lived, background Java process that stays active after your build finishes. It keeps project information, plugin classes, and build logic “hot” in memory. When you run a subsequent build, the Daemon is ready to execute immediately, sidestepping the overhead of bootstrapping the JVM and loading build scripts. This makes incremental builds feel near-instant.

Build Caching

Gradle’s caching mechanism is more sophisticated than simply keeping a local repository of dependencies.

Task Output Caching: Gradle can cache the outputs of tasks. If you build a project, then switch branches and build again, Gradle can often reuse the compiled classes or test results from the previous branch if the inputs match the cached key.
Remote Build Cache: In a team environment, this is a force multiplier. If your CI server builds a module and uploads the result to a remote cache, your local machine can download those pre-compiled binaries instead of running the compiler itself.

It is worth noting that the gap has narrowed recently. Maven users can now utilize the Maven Daemon (mvnd) to gain some of the performance benefits of a long-lived process, and modern Maven extensions allow for build caching. However, Gradle’s incremental build intelligence remains its most fundamental architectural advantage for complex, multi-module projects.

So, is there still a use case for Maven?

Ultimately, Maven is optimized for predictability and standardization, while Gradle is optimized for performance and flexibility. Maven is deliberately restrictive. Because it uses a declarative XML model, it is extremely difficult for a developer to write a “clever” or “hacky” build script that breaks the project for everyone else. Gradle is much more flexible.

Maven’s dependency resolution (the “nearest-definition” rule) is deterministic and simple. While this can lead to version conflicts that require manual intervention (via <dependencyManagement>), it is predictable. Gradle’s resolution engine is far more powerful, using sophisticated selection rules and dynamic conflict resolution. However, this power can sometimes lead to “magic” where dependencies are resolved in ways that aren’t immediately obvious to a developer. In highly regulated financial systems where you need to explicitly audit every binary that ends up in production, Maven’s transparency is a feature, not a bug.

Maven has been the industry standard for two decades. Most enterprise-grade plugins, security scanning tools (like Black Duck, Snyk, or SonarQube), and CI/CD pipeline templates were built “Maven-first. You are significantly less likely to run into breaking API changes in Maven plugins than in Gradle plugins. Upgrading a Gradle version often requires significant refactoring of your build scripts; upgrading Maven versions is usually a non-event.

Mastering the Build: A Deep Dive into Gradle

The Philosophy: Build as Code

The Heart of Gradle: The Task & The Project

Tasks

Projects

Plugins

Configurations (Dependency Scopes)

Dependencies

Version Catalogs

Why Use Version Catalogs?

Source Sets

Properties

Artifacts

Common built-in tasks in the Java plugin

compileJava

processResources

classes

Get Kaustubh Saha’s stories in your inbox

compileTestJava

processTestResources

testClasses

test

jar

javadoc

A few other common built-in tasks and plugins

shadow plugin/shadowJar task

OSpackage plugin/buildRpm task

jacocoTestReport

sonar

dependencies

Standard Files and Directories associated with Gradle

The core build files

Version Catalogs

Standard Directory Structure

Hidden/Generated Files

Key Differences

Multi-Module Gradle Projects

Gradle Wrapper

How to create the wrapper ?

How does Gradle outpace Maven ?

Incremental Builds

The Gradle Daemon

Build Caching

So, is there still a use case for Maven?

Written by Kaustubh Saha

No responses yet

More from Kaustubh Saha

A comprehensive guide to Autosys

In the bustling world of IT infrastructure, where thousands of scripts, commands, and data transfers must happen at precisely the right…

Comparison between G1 GC, Z GC and Shenandoah GC

G1 GC

Unlocking the Black Box: A beginner’s guide to Java Flight Recorder (JFR)

Performance tuning often feels like detective work. You know the application is slow, but finding the “smoking gun” — whether it’s a memory…

Building Low-Latency Java Applications: A Beginner’s Guide to OpenHFT

In the world of high-frequency trading (HFT) and other performance-critical systems, microseconds matter. Standard Java applications can…

Recommended from Medium

Senior Android Interview Questions & Answers (2026 Edition)

Modern Android interviews in 2026 are much less focused on “What is an Activity?” and much more focused on architecture, scalability…

Java Spring Boot Microservices: The 2026 Backend Engineer Roadmap

If you want to become a strong backend engineer in 2026, learning Java syntax is not enough.

10 Spring Boot Performance Optimization Techniques That Actually Make a Difference

1. Fix N+1 Queries Before Optimizing Java Code

Android CLI: Getting Started with Installation, Initialization, and Your First Workflow

Install Android CLI, prepare your Android environment, connect a device, and run your first agent-ready Android development workflow.

The CocoaPods Clock Is Ticking: What Happens to Flutter on December 2nd?

Native iOS developers moved to Swift Package Manager years ago. For Flutter developers, our reckoning is happening right now.

📈 E_DEPRECATED Got Louder in PHP 8.4. Here Is How to Keep Symfony Quiet

E_STRICT is gone. Deprecations are everywhere. Symfony’s ErrorHandler has strong opinions about both.

No responses yet

More from Kaustubh Saha

A comprehensive guide to Autosys

In the bustling world of IT infrastructure, where thousands of scripts, commands, and data transfers must happen at precisely the right…

Comparison between G1 GC, Z GC and Shenandoah GC

G1 GC

Unlocking the Black Box: A beginner’s guide to Java Flight Recorder (JFR)

Performance tuning often feels like detective work. You know the application is slow, but finding the “smoking gun” — whether it’s a memory…

Building Low-Latency Java Applications: A Beginner’s Guide to OpenHFT

In the world of high-frequency trading (HFT) and other performance-critical systems, microseconds matter. Standard Java applications can…

Recommended from Medium

Senior Android Interview Questions & Answers (2026 Edition)