# The Version Catalog Plugin

version 9.8.0-milestone-2

The Version Catalog Plugin (plugin id: `version-catalog`) lets you publish a version catalog as a Maven or Ivy artifact, so it can be consumed like any other dependency by independent Gradle builds. It works with both an existing `libs.versions.toml` file and programmatic catalog declarations.

For an introduction to version catalogs themselves — the TOML format, aliases, bundles, and how to consume them — see Version Catalogs.

## Usage

To use the Version Catalog Plugin, include the following in your build script:

build.gradle.kts

    plugins {
        `version-catalog`
        `maven-publish`
    }

build.gradle

    plugins {
        id 'version-catalog'
        id 'maven-publish'
    }

Applying the plugin adds a `catalog` extension, a `generateCatalogAsToml` task, and registers a `versionCatalog` software component for publishing.

## Tasks

`generateCatalogAsToml` (type `TomlFileGenerator`)

  Generates the version catalog TOML file from the configured catalog. The default output location is `layout.buildDirectory.file("version-catalog/libs.versions.toml")`. When the Base Plugin is applied — for example, transitively by a publishing plugin — this task is wired into the `assemble` lifecycle task.

## Dependency management

The Version Catalog Plugin adds the following dependency configurations:

`versionCatalog`

  Declarable. Used to declare the platforms and dependencies whose coordinates and versions make up the generated catalog.

`versionCatalogElements`

  Consumable. Exposes the generated TOML catalog as an artifact for publishing and consumption, with the `org.gradle.category=platform` and `org.gradle.usage=version-catalog` attributes. This configuration backs the `versionCatalog` component.

## Contributed extension

The plugin adds the `catalog` extension to the project. Configure the catalog contents through its nested `versionCatalog { }` block, which exposes a VersionCatalogBuilder.

If you already have a `gradle/libs.versions.toml` file, you can publish it directly by importing it — keeping the TOML file as the single source of truth:

build.gradle.kts

    plugins {
        `version-catalog`
        `maven-publish`
    }

    catalog {
        versionCatalog {
            from(files("gradle/libs.versions.toml"))
        }
    }

    group = "com.mycompany"
    version = "1.0"

    publishing {
        publications {
            create<MavenPublication>("maven") {
                from(components["versionCatalog"])
            }
        }
    }

build.gradle

    plugins {
        id 'version-catalog'
        id 'maven-publish'
    }

    catalog {
        versionCatalog {
            from(files("gradle/libs.versions.toml"))
        }
    }

    group = 'com.mycompany'
    version = '1.0'

    publishing {
        publications {
            maven(MavenPublication) {
                from components.versionCatalog
            }
        }
    }

Alternatively, declare the catalog entries programmatically:

build.gradle.kts

    catalog {
        // declare the aliases, bundles and versions in this block
        versionCatalog {
            library("my-lib", "com.mycompany:mylib:1.2")
        }
    }

build.gradle

    catalog {
        // declare the aliases, bundles and versions in this block
        versionCatalog {
            library('my-lib', 'com.mycompany:mylib:1.2')
        }
    }

## Publishing

The plugin registers a `versionCatalog` software component. Attach it to a Maven or Ivy publication to publish the catalog:

build.gradle.kts

    publishing {
        publications {
            create<MavenPublication>("maven") {
                from(components["versionCatalog"])
            }
        }
    }

build.gradle

    publishing {
        publications {
            maven(MavenPublication) {
                from components.versionCatalog
            }
        }
    }

Running `./gradlew publish` uploads the catalog as an artifact (with the `.toml` extension). Consumers then import it in their `settings.gradle(.kts)` file using standard dependency notation.