kotlin-tooling-gradle-to-kotlin-toolchain-project

Gradle → Kotlin Toolchain Project Migration

Two jobs at once: a mechanical translation of dependencies and configuration, plus a replacement for every

Gradle plugin the Toolchain has no native answer for. Templates to adapt are in

[references/examples.md](references/examples.md), drawn from one real migration.

Lean on the companion skills for the plugin-shaped subproblems: kotlin-tooling-kotlin-toolchain for syntax,

kotlin-tooling-gradle-to-kotlin-toolchain-plugin for the per-plugin port workflow (you will run it once per Gradle plugin

without a native equivalent), kotlin-tooling-kotlin-toolchain-plugin-authoring for plugins written from scratch.

Principles

1. Preserve source code. If the migration forces edits to business logic, a local plugin can probably

fill the gap instead. Code reading release.properties off the classpath should keep working — publish

that exact file, don't rewrite the consumer.

1. Every third-party Gradle plugin is drop, native, or reimplement — never "keep the Gradle plugin".

Your own convention plugins are different: buildSrc / build-logic precompiled scripts are shared

configuration, so they become module templates, not local plugins — see

[No buildSrc / convention plugins](#no-buildsrc--convention-plugins--shared-config-goes-in-templates).

1. Search GitHub before authoring a local plugin. Someone has probably already written it; vendoring a

working implementation beats a from-scratch port every time. Where to look and what to search for:

[Phase 2](#phase-2--decide-layout-plugin-set-and-scope) "Scope". Author only after the search comes up empty. Read what you vendor end to end before wiring it

in — it runs at build time with full filesystem and network access.

1. All dependencies should reside in version catalog. gradle/libs.versions.toml survives as the built-in $libs.*

catalog. Every coordinate in every module/plugin YAML must end up as a $libs.* reference. [bundles] has no

Toolchain equivalent and becomes a module template — see [No version-catalog bundles](#no-version-catalog-bundles).

Workflow

Phase 1 — Inventory the Gradle build

Write the inventory down (e.g. MIGRATION_PLAN.md) before any YAML; it becomes the checklist the PR

description verifies.

• Plugins in the plugins { } block, each sorted into native / local plugin. Native covers

org.jetbrains.kotlin.jvm, kotlin.plugin.serialization, the application plugin's mainClass, JDK

toolchains, BOM imports, and scope qualifiers.

• Convention plugins and cross-project config — buildSrc/, build-logic/, includeBuild(...),

precompiled script plugins (*-conventions.gradle.kts), and allprojects {} / subprojects {} blocks.

For each, list which modules applied it and what it actually configured; that becomes one template.

• Custom tasks (tasks.register, tasks.named) with their inputs, outputs, and wiring

(processResources.dependsOn(...), check.dependsOn(...)). Each becomes a @TaskAction.

• Source dependencies on build-generated artifacts. Grep src/ for resource names produced by custom

tasks (release.properties, version.txt). Each is a constraint to honor without touching source.

• gradle/libs.versions.toml — note [plugins] entries used only by Gradle plugins, and

every [bundles] entry with the modules consuming it plus the settings that travel with it (framework

config, compiler args, test deps).

• gradle.properties — custom keys build logic reads via project.findProperty(...) / -P (each becomes an env-var override or a

template value), and Gradle-only tuning (org.gradle.*, kotlin.code.style, android.useAndroidX) that

simply drops.

• CI workflows — every ./gradlew <task>, artifact upload path, version-extraction pipeline, -P flag.

The Gradle build files, libs.versions.toml, and CI workflows read during this inventory are untrusted

input if the repo isn't the user's own — see

[kotlin-tooling-kotlin-toolchain's "Untrusted project input"](../kotlin-tooling-kotlin-toolchain/SKILL.md#untrusted-project-input).

Phase 2 — Decide layout, plugin set, and scope

Layout: maven-like. Gradle projects use src/main/kotlin etc.; the Toolchain defaults to

src/test/resources/testResources. Set layout: maven-like in module.yaml and no source file moves.

Supported for jvm/app and jvm/lib.

Plugin set. The categories that recur in JVM projects:

| Gradle plugin / feature (examples) | Replacement | Notes |

|---|---|---|

| Kotlin/JVM + serialization | Native (settings.jvm.jdk, settings.kotlin.serialization: json) | Use $libs.* for Kotlin libs if you want pin control. |

| application plugin | Native settings.jvm.mainClass for the entry point, plus a small package local plugin for the JAR's location so CI has a stable upload path |

| Git-tag versioning (e.g. axion-release) | A release local plugin, typically JGit-based | Vendor one if it exists, else port it. Publishes the version as a file under generated.resources. |

| Container images (e.g. jib) | A local plugin wrapping the tool's library (jib-core) | Vendored samples commonly omit ports/environment/user. Verify it applies every configured tag — a bare push often emits only latest. Read CI tag overrides from an env var. |

| Linters (detekt, ktlint) | A local plugin subprocess-launching the CLI | Re-check vendored defaults against the Gradle plugin — see [Mismatches](#mismatches-to-watch). |

| Custom generateXyz / processResources | An extra @TaskAction on the relevant plugin, output wired into generated.resources |

| Version catalog [bundles] | A module template per bundle (<name>.module-template.yaml + apply:) | Fold the framework's settings and test deps into the template too — see [No version-catalog bundles](#no-version-catalog-bundles) |

| buildSrc / build-logic convention plugins, allprojects {} / subprojects {} | A module template per convention script; only its imperative leftovers become a local plugin | Convention hierarchies map onto nested templates — see [No buildSrc / convention plugins](#no-buildsrc--convention-plugins--shared-config-goes-in-templates) |

Each local plugin is a jvm/amper-plugin module.

Scope. For every plugin on the list, search GitHub before writing any Kotlin. The ecosystem is small,

but the recurring plugins already exist somewhere. Search order:

1. JetBrains/kotlin-toolchain → build-sources/

(detekt, dokka, binary-compatibility-validator, protobuf, generate-build-properties,

project-commands) — the local plugins the Toolchain builds itself with, i.e. de facto reference

implementations. Also plugin-samples/ and docs/ in the same repo.

1. GitHub code search on the plugin marker rather than the tool name:

"product: jvm/amper-plugin", path:plugin.yaml "@TaskAction", "jvm/amper-plugin" jib.

1. The tool's own repo — most linters/packagers ship a -cli or -core artifact, which is all a thin wrapper

plugin needs, so "no plugin exists" often still means "a 50-line wrapper exists".

Then pick per plugin: vendor (copy a hit as-is; keep its license header and add a comment with the source

URL + commit so it can be re-synced), extend (vendor + extra Settings fields), or author (nothing

found, or the need is bespoke). Sensible default for one PR: vendor what exists, author the small bespoke ones

(a package plugin, a thin linter wrapper), defer the rest. Always diff a vendored plugin's behavior against

the Gradle plugin it replaces before trusting it — see

[A vendored linter plugin can be stricter than the Gradle plugin](#a-vendored-linter-plugin-can-be-stricter-than-the-gradle-plugin).

Phase 3 — Implement

1. Copy kotlin / kotlin.bat from a reference Toolchain project (for example this one) or kotlin init in a scratch dir. Pin

kotlintoolchain=<version> in .sdkmanrc to match the wrapper.

1. Write project.yaml with all plugin module paths.
2. Per plugin: search GitHub first ([Phase 2](#phase-2--decide-layout-plugin-set-and-scope) "Scope"), then vendor or author it under plugins/<name>/,

running ./kotlin show modules after each to confirm the model still loads.

1. Write the templates at the project root: one <name>.module-template.yaml per convention script and per

[bundles] entry with two or more consumers (dependencies plus the settings, test deps, and repositories

that travel with them), nested the way the Gradle conventions were.

1. Write the root module.yaml: product: jvm/app, layout: maven-like, $libs.* dependencies, an

apply: list for the templates, and a plugins: block enabling each local plugin with its non-default

settings.

1. Validate each plugin in isolation: ./kotlin task :<module>:<task>@<plugin> or ./kotlin do <command>.
2. Rewrite CI ([Phase 4](#phase-4--rewrite-ci)).
3. Delete build.gradle.kts, gradlew, gradlew.bat, gradle/wrapper/ — but keep

gradle/libs.versions.toml.

1. Sweep the catalog: drop the whole [plugins] block, any [versions] keys that only fed it, and

[bundles] once every consumer applies a template.

1. Sweep every module.yaml / plugin.yaml for literal Maven coordinates and replace them with

$libs.<key>.

Phase 4 — Rewrite CI

• Set KOTLIN_CLI_NO_WELCOME_BANNER: "1".
• ./gradlew build && ./gradlew check → ./kotlin build && ./kotlin check (which runs every plugin's

checks: registrations plus tests).

• ./gradlew jib -Djib.to.tags=… → ./kotlin do jib, with tags passed through an env var the plugin reads.

Vendored jib-style plugins usually lack that hook — add it while vendoring.

• Artifact upload path changes: Gradle's build/libs/<name>.jar is gone and jarJvm writes to a

Toolchain-internal path. Author a package plugin staging the JAR at

${module.rootDir}/build/libs/${module.name}.jar so uploading artifacts stays simple.

Phase 5 — Validate end-to-end

Run each user-facing command locally and record the output in the PR's test plan:

./kotlin show modules            # project model loads, all expected modules listed
./kotlin clean && ./kotlin build
./kotlin test
./kotlin check                   # linters + tests; expect zero violations after Phase 3
./kotlin do currentVersion       # if applicable
./kotlin do jib                  # or jibBuildTar to avoid pushing locally (if applicable)
./kotlin do package              # verify build/libs/<name>.jar and its Main-Class manifest (if applicable)
./kotlin do ktlintFormat         # if applicable

Mismatches to watch

No ${...} interpolation in module.yaml

configFile: ${module.rootDir}/detekt.yml is taken literally. Use a module-relative path

(configFile: detekt.yml). Interpolation works only in plugin.yaml.

Module name comes from the directory name

There is no name: field. actions/checkout clones into a directory named after the GitHub repo, while a

local worktree may resolve ${module.name} to something else. Never hardcode the module name into a plugin

task's output path — use ${module.name}.

Plugin settings without enabled: true are ignored

plugins:
  release: enabled         # shorthand — only valid with no other settings
  jib:                     # long form — required as soon as any setting is present
    enabled: true
    container:
      mainClass: com.example.App

Settings without enabled: true produce only a warning ("Plugin X is not enabled, but has some explicit

configuration") and the plugin is skipped.

A vendored linter plugin can be stricter than the Gradle plugin

Diff the flags the vendored plugin passes against the Gradle plugin's default task, and gate anything

stricter behind an opt-in setting so the default matches the old behaviour.

The canonical case: the upstream detekt plugin (amper/build-sources/detekt/) always passes --classpath to

detekt-cli, enabling type resolution, which Gradle's default detekt task does not. Used as-is it surfaces

violations Gradle never reported (notably UnreachableCode on elvis-with-return). Fix: add

useTypeResolution: Boolean get() = false to the plugin's Settings and gate the flag on it — patch in

[references/examples.md](references/examples.md).

No version-catalog bundles

Only [libraries] keys resolve ($libs.<key>). $libs.bundles.<name> does not exist and [bundles] in the

catalog is dead config the Toolchain never reads. The official answer (KTC-4759) is a module template per

bundle, applied wherever the bundle was used:

# gradle/libs.versions.toml — before
[bundles]
ktor-server = ["ktor-server-core", "ktor-server-netty", "ktor-server-content-negotiation"]

# ktor-server.module-template.yaml — at the project root; templates cannot declare product:
dependencies:
  - $libs.ktor.server.core
  - $libs.ktor.server.netty
  - $libs.ktor.server.content.negotiation

settings:
  kotlin:
    serialization: json

test-dependencies:
  - $libs.ktor.server.test.host

# module.yaml
product: jvm/app

apply:
  - //ktor-server.module-template.yaml

Templates are the better target, not just a workaround: a bundle carries coordinates only, while the

framework it enables usually also needs settings (kotlin.serialization, springBoot, freeCompilerArgs),

test-dependencies, and sometimes repositories. Put all of it in the template so one apply: line yields a

working framework instead of a bare classpath.

Rules that might bite:

• Path notation is //<name>.module-template.yaml, relative to the project root (where project.yaml is).
• No product: in a template. Templates may apply: other templates; each is applied once even if reached

through two paths, so list dependencies appear once.

• Merge semantics: lists append, scalars are overridden, and module.yaml always wins regardless of where

apply: sits in the file.

• Two sibling templates setting the same scalar (e.g. settings.jvm.release) is a hard error

("Conflicting values for property"). Resolve by setting the value in the consuming module.yaml, or in a

third template that applies both.

• Don't convert a single-consumer bundle. Templates pay off from the second module; below that, inline the

$libs.* list.

• Templates express the union of platform-qualified sections too (dependencies@jvm, settings@android), so

a KMP bundle split across source sets still fits one template.

No buildSrc / convention plugins — shared config goes in templates

buildSrc/, build-logic/, and includeBuild(...) have no counterpart, and project.yaml carries only

modules: and plugins: — there is no root-project inheritance and nowhere to put imperative shared build

logic. A local plugin is also the wrong target: plugins contribute tasks, they don't inject module

configuration. A precompiled script plugin is mostly declarative, so it translates to one

<name>.module-template.yaml, applied by the modules that used plugins { id("<name>") }:

// buildSrc/src/main/kotlin/service-conventions.gradle.kts
plugins {
    kotlin("jvm")
    kotlin("plugin.serialization")
}
kotlin { jvmToolchain(21) }
repositories { maven("https://jitpack.io") }
dependencies {
    implementation(libs.ktor.server.core)
    testImplementation(libs.kotest.runner.junit5)
}

# service-conventions.module-template.yaml
settings:
  jvm:
    jdk:
      version: 21
  kotlin:
    serialization: json

repositories:
  - id: jitpack
    url: https://jitpack.io

dependencies:
  - $libs.ktor.server.core

test-dependencies:
  - $libs.kotest.runner.junit5

| Convention script construct | Template counterpart |

|---|---|

| plugins { kotlin("jvm"), kotlin("plugin.serialization"), id("org.springframework.boot") } | native settings: (settings.kotlin.*, settings.springBoot, …) |

| kotlin { jvmToolchain(21) }, java { targetCompatibility } | settings.jvm.jdk.version, settings.jvm.release |

| dependencies { implementation / api / testImplementation } | dependencies: (: exported for api) and test-dependencies: |

| repositories { } | repositories: |

| tasks.withType<Test> { useJUnitPlatform() } | built-in / settings.junit |

| a convention script applying another convention script | nested templates (apply: inside the template) |

| allprojects {} / subprojects {} in the root script | one template that every module.yaml applies |

| tasks.register(…), doLast { }, anything imperative | the residue — a local plugin, one per behavior |

Also:

• Delete buildSrc/ outright. Its libs catalog accessors are replaced by $libs.* used directly in the

templates.

• Splitting one fat convention script into several small templates (jvm, ktor-server, testing) is

usually the better shape, and bundle templates fold into the same hierarchy — see

[No version-catalog bundles](#no-version-catalog-bundles) for the merge/conflict rules, which apply

identically here.

• Local-plugin enablement inside a template (a plugins: block in a *.module-template.yaml) is unverified.

If a convention script enabled a plugin you reimplemented, keep the plugins: block in each module.yaml

until you have confirmed the template form loads (./kotlin show modules plus an actual task run).

No dependency exclusions

There is no equivalent of Gradle's exclude(group, module). Any transitive exclusion silently disappears and

the library lands on the runtime classpath. Note the trade-off in the PR (usually a few hundred unused KB).

No plugin-to-plugin dependencies

Plugins are isolated. If two plugins logically belong together, put both task actions in the same plugin

module or extract the library.

No -P / -D CLI overrides

Read ephemeral overrides (force-version, skip-checks, dynamic image tags) from environment variables inside

the @TaskAction; don't count on a --setting flag either (the pinned CLI may reject it). Pattern in the

[kotlin-tooling-gradle-to-kotlin-toolchain-plugin skill](../kotlin-tooling-gradle-to-kotlin-toolchain-plugin/SKILL.md#no--p-properties).

Capturing a command's output value

println from a @TaskAction is not a machine-readable channel. The Toolchain wraps it as

<ts> INFO :<module>:<task>@<plugin> <value> and appends a <task> successful banner, so

./kotlin do currentVersion | tail -n1 yields the banner — and lowering --log-level to error/off drops

the value line entirely, since it is emitted at INFO. Instead:

• Have the task write the value to a file named by an env var and cat it. Moreover, other tasks can reuse this value down the line
• Or read the git state the command produced: git describe --tags --exact-match HEAD.
• If you must parse stdout, match the task coordinate: awk '/<task>@<plugin>/ { v = $NF } END { print v }'.

Test resources shadow generated.resources

When a plugin emits release.properties and src/test/resources/release.properties exists, classpath

ordering puts the test fixture first. It usually does the right thing but is brittle — if a test asserts a

specific value, inject a stub service instead of relying on precedence.

Dependabot needs a stub build.gradle.kts

Dependabot's gradle file fetcher requires a build.gradle(.kts) in the configured directory before it scans

gradle/libs.versions.toml; without one, package-ecosystem: "gradle" silently no-ops. Keep an empty

build.gradle.kts at the root with a comment explaining why. The Toolchain ignores it.

amd64-only container images on Apple Silicon

Images like mongo:3.2 crash under Rosetta/QEMU on M-series Macs

(runtime: failed to create new OS thread (have 2 already; errno=22)). Unchanged by the migration — the same

image fails under ./gradlew check. Flag it as pre-existing; CI on ubuntu-latest is unaffected.

iOS (KMP): a migrated Info.plist loses its CFBundle* keys

A Gradle/KMP iOS app keeps bundle metadata in the hand-maintained iosApp.xcodeproj

(GENERATE_INFOPLIST_FILE = YES), so Xcode synthesizes CFBundle* keys and the checked-in Info.plist is

intentionally partial. The Toolchain ignores that .xcodeproj, generates its own, and uses your plist

verbatim — nothing synthesizes the keys, and the .app has no bundle id:

Simulator device failed to install the application. Missing bundle ID.

Fix: make the plist self-contained, keeping your app-specific keys alongside these:

<key>CFBundleDevelopmentRegion</key><string>$(DEVELOPMENT_LANGUAGE)</string>
<key>CFBundleExecutable</key><string>$(EXECUTABLE_NAME)</string>
<key>CFBundleIdentifier</key><string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
<key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
<key>CFBundleName</key><string>$(PRODUCT_NAME)</string>
<key>CFBundlePackageType</key><string>APPL</string>
<key>CFBundleShortVersionString</key><string>1.0</string>
<key>CFBundleVersion</key><string>1</string>

PRODUCT_BUNDLE_IDENTIFIER is set on the generated target. Underlying behaviour: the

[kotlin-tooling-kotlin-toolchain skill's "iOS apps" section](../kotlin-tooling-kotlin-toolchain/SKILL.md#ios-apps).

KMP: carry over every source set's dependencies

Translate each Gradle source set (commonMain, jvmMain, androidMain, iosMain, commonTest, jvmTest,

…) into its Amper counterpart — dependencies, dependencies@jvm/@android/@ios, test-dependencies,

test-dependencies@<platform>. Don't cherry-pick the obvious library deps:

• A *Main dependency is also on that target's test classpath (jvmTest extends jvmMain), so dropping one

can break tests with no compile error.

• A dependency can look like it belongs to another module and still be load-bearing. Canonical case:

jvmMain { implementation(compose.desktop.currentOs) } in a shared library reads like a desktop-app dep,

but it supplies the Skiko native runtime (skiko-awt-runtime-<os> with libskiko-<os>.dylib + .sha256)

that the module's own JVM Compose UI tests (compose.uiTest / runComposeUiTest) load at runtime.

compose.ui:ui-test pulls only Skiko's classes, never the natives. Dropping it compiles fine, then fails

with:

  org.jetbrains.skiko.LibraryLoadException: Cannot find libskiko-macos-arm64.dylib.sha256, proper native dependency missing.

Not a Toolchain bug: Gradle fails identically without it. Restore under dependencies@jvm, or scope it to

test-dependencies@jvm to keep Skiko natives off consumers' classpaths.

Guard against drops: diff each Gradle source set's dependency list against its Kotlin Toolchain section (names and

count), then run ./kotlin show dependencies -m <module> and compare with the Gradle build.

Common pitfalls

• No package plugin. CI ends up uploading build/artifacts/CompiledJvmArtifact/ (an internal class-file

tree) instead of a JAR. Add the plugin before swapping the upload path.

• Committing build/. Add it to .gitignore early; drop the old .gradle/ entry.
• String interpolation inside Maven coordinates. com.example:foo:${pluginSettings.version} in

plugin.yaml fails with "Value of type 'ShadowDependency' doesn't support string interpolation". Use $libs.foo.

Kotlin Toolchain docs: <https://kotlin-toolchain.org/dev/>