Migrating from Maven to Gradle: A Complete Guide

Migrating from Maven to Gradle can streamline your build process and allow you to take advantage of Gradle's powerful features. This guide provides a step-by-step process for transitioning a Java project from Maven to Gradle using the latest versions of all dependencies.

Step 1: Install Gradle

Before starting the migration, ensure that Gradle is installed on your system.

On Windows

1. Download Gradle: Download the latest Gradle distribution from Gradle's official website.
2. Extract the Download: Extract the downloaded ZIP file to a directory of your choice.
3. Set Environment Variables:
   • Open the System Properties window (Win + Pause).
   • Click on "Advanced system settings" and then "Environment Variables".
   • Add a new GRADLE_HOME variable pointing to the extracted Gradle directory.
   • Add %GRADLE_HOME%\bin to the PATH variable.

On Mac

1. Using Homebrew:

   brew install gradle
   

On Linux

1. Using SDKMAN:

   sdk install gradle
   

Verify the installation by running:

gradle -v

Step 2: Initialize a Gradle Project

Navigate to your Maven project's root directory and initialize a new Gradle project:

gradle init --type java-library

This command will create a build.gradle file and other necessary Gradle files in your project directory.

Step 3: Convert the POM Dependencies to Gradle

Open your pom.xml file and translate the dependencies into the build.gradle file.

Sample pom.xml:

<dependencies>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.12.0</version>
    </dependency>
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>31.1-jre</version>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Converted build.gradle:

plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    implementation 'com.google.guava:guava:31.1-jre'
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
}

application {
    mainClass = 'com.example.App'
}

test {
    useJUnitPlatform()
}

Step 4: Update the Project Structure

Gradle uses a different project structure compared to Maven. Ensure your project follows this structure:

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── example/
│   │           └── App.java
│   └── resources/
└── test/
    ├── java/
    │   └── com/
    │       └── example/
    │           └── AppTest.java
    └── resources/

Move your source files to match this structure if necessary.

Step 5: Configure Plugins and Tasks

Add necessary plugins and configure tasks to match your build requirements.

Example: Adding the JAR Plugin

plugins {
    id 'java'
    id 'application'
}

application {
    mainClassName = 'com.example.App'
}

jar {
    manifest {
        attributes 'Main-Class': 'com.example.App'
    }
}

Example: Adding the JUnit 5 Plugin

test {
    useJUnitPlatform()
}

Step 6: Verify the Migration

Run the following commands to verify your Gradle build:

Compile the Code

gradle compileJava

Run the Tests

gradle test

Build the JAR File

gradle jar

Run the Application

gradle run

Conclusion

Migrating from Maven to Gradle involves converting your pom.xml dependencies to build.gradle, updating the project structure, and configuring plugins and tasks. Gradle offers powerful features and improved build performance, making it a valuable tool for modern Java projects.

By following this guide, you can smoothly transition from Maven to Gradle and take advantage of its advanced capabilities. For more information, refer to the Gradle User Guide.