Version Catalogs in Gradle 7.0
Currently, there are multiple ways to share dependency versions between projects in multi-project builds. For example, users can declare versions or dependency coordinates directly in build scripts (in the
ext block), external files (e.g
In version 7.0 Gradle has introduced an incubating feature to centrally manage dependencies in your Gradle project that tries to combine the advantages of both approaches.
Version Catalog enables build authors to centralize the dependency coordinates (group, artifact, version) of their third-party dependencies in a conventional configuration file and declare the actual dependencies in a type-safe way. Declaring dependencies this way allows easy reuse of dependency coordinates in all modules, provides content assistance in the IDEs, and reduces the risk of typos. More importantly, it also provides a single location to change versions when upgrading a library.
How to use the version catalog feature?
Version Catalog is an experimental feature hence opt-in is required.
Enable version catalog
To enable the feature to add the below line in your project’s
Update: Version Catalog is stable in Gradle version 7.4, enabling feature is not required when using version 7.4 or above.
Creating a version catalog
A version catalog can be created in a couple of ways
- Declaring a catalog in the
- Declaring dependencies in a
Declaring a catalog in the
The catalog can be created using the
dependencyResolutionManagent API as shown below in the
Declaring dependencies in a
In addition to the settings API above, Gradle offers a conventional file to declare a catalog. If
libs.versions.toml is found in the
gradle subdirectory of the root build, then a catalog will be automatically declared with the contents of this file.
gradle/libs.versions.toml file from the root of your project as shown below
The version catalog TOML file format
The TOML file consists of 3 major sections:
[versions]section is used to declare versions which can be referenced by dependencies
[libraries]section is used to declare the aliases to coordinates
[bundles]section is used to declare dependency bundles
Declaring dependencies in the
Declaring dependency in the
build.gralde does not change much, instead of mentioning the dependency name and version in the dependency block
libs.bundles.<bundleName> is used.
Bundles is a list of dependency which needs is added to the application.
Advantages of using a version catalog
Version catalog has a number of advantages over declaring dependencies directly in the build script.
- For each catalog, Gradle generates type-safe accessors so that you can easily add dependencies with autocompletion in the IDE.
- Each catalog is visible to all projects of a build. It is a central place to declare a version of a dependency and to make sure that a change to that version applies to every subproject.
- Catalogs can declare dependency bundles, which are “groups of dependencies” that are commonly used together.
- Catalogs can separate the group and name of a dependency from its actual version and use version references instead, making it possible to share a version declaration between multiple dependencies.
Version Catalogs have a few advantages even above
buildSrc approach or
- Version catalogs can be shared across teams or projects, as catalog files can be imported into a project using version catalog builder API.
- Version catalogs can be published using the
maven-publishplugin making it easier to share across teams or in some cases outside the organisations.
Refer to official documentation to know more about Version Catalogs.