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.
- 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 validateskmp.targetsbefore any project is configured and gives settings scriptskmpTargetEnabled(...)andkmpTargetSelection().
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
andriodnever 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:
iosoff macOS, and runninglinuxX64Testoff Linux x86_64.linuxX64compiles and links on every host. allmeans every target this host can build. It logs each target it drops (iOS off macOS,linuxX64Testoff Linux x86_64) and never includesandroid, which needs an SDK: nameandroidto get it.- The command line wins over
systemProp.kmp.targetsingradle.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.
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.
- 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.).
For each BOM, two TOML version catalogs are published:
- Versioned Catalog: Contains both the dependencies and their versions.
- BOM Catalog: Contains only the dependencies, to be used with the BOM.
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
}
}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
}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
}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
}To publish the artifacts to Maven Central:
- Set up your Sonatype credentials in
~/.gradle/gradle.properties:
ossrhUsername=your-username
ossrhPassword=your-password
signing.gnupg.keyName=your-key-id- Run the publish task:
./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepositoryFor snapshots:
./gradlew publishToSonatypeThis project is licensed under the Apache 2.0 License - see the LICENSE file for details.