Skip to content

About

Gradle build support plugins and dependency catalogs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Gradle Build Support

This project provides a set of Gradle plugins, BOMs (Bill of Materials), and TOML version catalogs to help standardize and simplify Gradle builds for Kotlin projects. It is used internally in Sphereon to ensure a consistent build environment and versioning for all our software. Although targeting Sphereon, we encourage others to re-(use) part of our build support.

Components

Plugins

  • ConventionsPlugin (com.sphereon.gradle.plugin.conventions): Applies standard conventions for Kotlin Multiplatform projects.
  • DependencyAnalysisConventionPlugin (com.sphereon.gradle.plugin.dependency-analysis): Makes Autonomous Apps dependency analysis permanently available from the Kotlin plugin classloader. The top-level build applies it to the projects being analyzed so composite included builds do not load conflicting analyzer copies.
  • IntegrationTestPlugin (com.sphereon.gradle.plugin.integration-tests): Adds support for integration tests.
  • ProjectPublicationPlugin (com.sphereon.gradle.plugin.project-publication): Configures Maven publication with consistent POM metadata and signing.
  • TomlCatalogPlugin (com.sphereon.gradle.toml-catalog): Generates TOML version catalogs from BOMs.
  • NpmPublicationPlugin (com.sphereon.gradle.plugin.npm-publication): Derives each npm package version from its component build and assembles JS packages for publication.
  • KmpTargetsSettingsPlugin (com.sphereon.gradle.plugin.kmp-targets): A settings plugin that validates kmp.targets before any project is configured and gives settings scripts kmpTargetEnabled(...) and kmpTargetSelection().

Kotlin targets (kmp.targets)

The conventions declare Kotlin targets from the kmp.targets system property: a comma-separated, case-insensitive list of jvm, js, wasmJs (alias wasm), native (alias linuxX64), android, ios and all.

  • No property means jvm. A property that is set but empty fails the build.
  • An unknown value fails the build with the allowed values, so a typo such as andriod never produces a green JVM-only build.
  • The JVM target is always declared; the other values add targets next to it.
  • A named target the host cannot build fails the build and names the host: ios off macOS, and running linuxX64Test off Linux x86_64. linuxX64 compiles and links on every host.
  • all means every target this host can build. It logs each target it drops (iOS off macOS, linuxX64Test off Linux x86_64) and never includes android, which needs an SDK: name android to get it.
  • The command line wins over systemProp.kmp.targets in gradle.properties: ./gradlew build -Dkmp.targets=jvm,wasmJs.

The value is read once per build through Gradle's providers, so the configuration cache tracks it. Build scripts call kmpTargetEnabled("js"), androidTargetEnabled() and configureAndroidLibraryTargetIfEnabled(...); settings scripts apply the settings plugin and call the same names, for example to include an Android application only when android is named:

import com.sphereon.gradle.plugin.kmpTargetEnabled

plugins {
    id("com.sphereon.gradle.plugin.kmp-targets") version "<gbs version>"
}

if (kmpTargetEnabled("android")) include(":app-android")

The npm publication plugin follows the targets a module really declares, not the requested ones: a module without js or wasmJs gets no npm tasks.

Npm component build versions

The npm plugin uses the consuming module's Gradle version as its compatibility version. Releases keep that value. For a snapshot, generateNpmBuildVersion derives a SHA-256 component build identity from the JS production output, bundled dependencies, declarations, resources, npm dependency metadata, build files and the publication plugin implementation. Plugin archive timestamps and checkout paths do not change its build identity. The package version is <base>-SNAPSHOT.build.b<identity>. Git HEAD, branch names, timestamps and CI run counters do not determine the version. Unchanged component builds retain the same version; changed code or dependency bytes change it. Snapshot publication checks the registry for that exact component version and reuses it when already published. Missing versions are published with the snapshot tag; authentication or registry errors fail the check. Release and explicit dry-run publication behavior is unchanged.

This task runs in the product repository through ordinary Gradle, using the published plugin. CI requires no parent repository, workspace launcher or local Maven-overlay receipt. The version is written to <module>/build/npm-build-version/version.txt before package assembly. JVM-only builds do not register npm preparation tasks.

A build system that already has a target-specific SHA-256 component build version can supply it using npmPublication { buildVersion.set("<64-character identity>") } or -PbuildVersion.<module-name>=<identity>. Supply the JS component identity; a JVM producer receipt does not establish the identity of a JS build.

BOMs (Bill of Materials)

  • common-bom: Core dependencies for Kotlin projects (Kotlin, KotlinX, testing libraries).
  • library-bom: Common libraries for Kotlin projects (cryptography, serialization, etc.).
  • gradle-plugin-bom: Gradle plugins for Kotlin projects (Kotlin, Android, KSP, etc.).

TOML Version Catalogs

For each BOM, two TOML version catalogs are published:

  1. Versioned Catalog: Contains both the dependencies and their versions.
  2. BOM Catalog: Contains only the dependencies, to be used with the BOM.

Using in Your Project

Setting Up the Repository

Add the repository to your settings.gradle.kts file:

pluginManagement {
    repositories {
        mavenCentral()
        // Add other repositories as needed
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        // Add other repositories as needed
    }
}

Using the Plugins

Add the plugin to your build.gradle.kts file:

plugins {
    id("com.sphereon.gradle.plugin.conventions") version "0.0.3"
    // Add other plugins as needed
}

Using the BOMs

Add the BOM to your build.gradle.kts file:

dependencies {
    implementation(platform("com.sphereon.gradle:common-bom:0.0.3"))
    implementation(platform("com.sphereon.gradle:library-bom:0.0.3"))
    // Add other dependencies as needed
}

Using the TOML Version Catalogs

Add the TOML version catalog to your settings.gradle.kts file:

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from("com.sphereon.gradle:common-bom-versioned-catalog:0.0.3")
        }
    }
}

Or, if you're using the BOM:

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from("com.sphereon.gradle:common-bom-bom-catalog:0.0.3")
        }
    }
}

Then, in your build.gradle.kts file:

dependencies {
    implementation(platform("com.sphereon.gradle:common-bom:0.0.3"))
    implementation(libs.kotlin.stdlib)
    implementation(libs.kotlinx.coroutines.core)
    // Add other dependencies as needed
}

Publishing

To publish the artifacts to Maven Central:

  1. Set up your Sonatype credentials in ~/.gradle/gradle.properties:
ossrhUsername=your-username
ossrhPassword=your-password
signing.gnupg.keyName=your-key-id
  1. Run the publish task:
./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

For snapshots:

./gradlew publishToSonatype

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

About

Gradle build support plugins and dependency catalogs

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages