Introduction

In modern software development, managing dependencies efficiently is crucial for maintaining scalable and maintainable projects. Gradle, a powerful build tool used predominantly in Java environments, has introduced an innovative approach to manage project dependencies through the Version Catalog TOML file format. This guide provides a step-by-step approach to using this format, specifically tailored for experienced Java developers looking to streamline their builds.

Prerequisites

Before diving into the details of the Version Catalog TOML file format, ensure that you meet the following prerequisites:

Proficient understanding of Java and Gradle build processes.
Basic familiarity with TOML (Tom's Obvious, Minimal Language) format.
Gradle 7.0 or higher installed on your development machine.

Preparation

To begin using the Version Catalog in your project, you first need to set up your environment to support this new feature:

Update Gradle: Ensure your project is using Gradle version 7.4.2 or later. You can download the latest version from the Gradle Official Releases.

1.1 Otherwise you have to Enable The Feature Preview: In your settings.gradle file, enable the feature preview by adding the following line:

enableFeaturePreview('VERSION_CATALOGS')

Create TOML File: Create a new file named libs.versions.toml in the gradle directory of your project.

Step-by-Step Guide

Step 1: Defining Dependencies

Start by defining your project dependencies in the libs.versions.toml file. Here is an example structure:

[versions]
junit = "5.7.1"

[libraries]
junitApi = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }
junitEngine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit" }

Versions Block: Declare the versions of your libraries in a central location.
Libraries Block: Map a logical name to each dependency, associating it with the module and version.

Step 2: Accessing Dependencies

In your Gradle build scripts (build.gradle), you can now refer to the dependencies by their logical names:

    testImplementation libs.junitApi
    testRuntimeOnly libs.junitEngine

Step 3: Managing Versions

Updating library versions becomes simpler with the Version Catalog. To upgrade a library, update the version in the libs.versions.toml file, and all references will automatically use the new version.

Step 4: Adding Plugins

You can also manage Gradle plugins using the TOML format. Define your plugins in the same TOML file:

[versions]
lombok-plugin="8.6"

[plugins]
lombok-plugin = { id = "io.freefair.lombok", version.ref = "lombok-plugin"}

And apply them in your settings.gradle:

plugins {
    alias(libs.plugins.myplugin)
}

Introduction to Bundles

Bundles are a powerful feature in the Gradle Version Catalog that allows developers to group related dependencies together. This functionality is especially useful for including multiple libraries that are commonly used together in projects, thereby simplifying dependency declarations in your Gradle build scripts.

How to Define Bundles

To make use of bundles in your libs.versions.toml file, you'll need to follow a structured approach to defining grouped dependencies. Here’s how you can set up a bundle:

Identify Common Libraries: Determine which libraries are often used together in your projects. For instance, if you are working on a web application, you might frequently use a set of Spring Boot libraries.
Define the Bundle in TOML: Add a [bundles] section in your TOML file where each bundle is a collection of library aliases defined under [libraries]. Here's an example:

[versions]
springBootStarter = "2.4.1"

[libraries]
springBootStarterWeb = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "springBootStarter" } 
springBootStarterSecurity = { module = "org.springframework.boot:spring-boot-starter-security", version.ref = "springBootStarter" } 

[bundles]
springBootStarter = ["springBootStarterWeb", "springBootStarterSecurity"]

Utilizing Bundles in Build Scripts

Once you have defined your bundles, you can reference them directly in your build.gradle files, which keeps your dependency declarations clean and organized:

dependencies {
    implementation libs.bundles.springBootStarter
}

Benefits of Using Bundles

Simplified Management: Bundles allow you to manage and update groups of dependencies more efficiently.
Consistency Across Projects: Ensures that the same group of dependencies is used across multiple projects or modules, enhancing consistency and compatibility.
Ease of Upgrades: When library versions need to be updated, you only need to update them in the TOML file, and all associated bundles will automatically use the updated versions.
Logical Grouping: Only group libraries that are logically related and used together to avoid unnecessary coupling of unrelated dependencies.
Documentation: Document the purpose of each bundle within the TOML file to make it clear to other developers why certain libraries are grouped.
Regular Reviews: Regularly review your bundles to ensure they are up to date with the latest versions of dependencies and adjust them as your project requirements evolve.

Best Practices

Keep your TOML file organized: Maintain a well-organized TOML file with grouped related dependencies and clearly commented sections.
Regularly review and update dependencies: This ensures you leverage the most up-to-date and secure versions of libraries.
Use version ranges cautiously: Specifying version ranges can lead to unpredictable builds. Prefer specific versions for stability.

Conclusion

Gradle's Version Catalog and Bundles features represent a significant leap forward in dependency management, offering a clean, efficient, and robust framework for handling Java project dependencies. By embracing these tools, Java developers can significantly reduce build complexity and improve project maintainability.

This comprehensive guide should serve as your foundation for integrating the TOML format into your Java projects, enabling a smoother, more streamlined development process.

Version Catalog with TOML in Gradle