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, 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.
2. 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.
3. 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 "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.
4. 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.

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".

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:

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.
2. GitHub code search on the plugin marker rather than the tool name: "product: jvm/amper-plugin", path:plugin.yaml "@TaskAction", "jvm/amper-plugin" jib.
3. 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.

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.
2. Write project.yaml with all plugin module paths.
3. Per plugin: search GitHub first (Phase 2 "Scope"), then vendor or author it under plugins/<name>/, running ./kotlin show modules after each to confirm the model still loads.
4. 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.
5. 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.
6. Validate each plugin in isolation: ./kotlin task :<module>:<task>@<plugin> or ./kotlin do <command>.
7. Rewrite CI (Phase 4).
8. Delete build.gradle.kts, gradlew, gradlew.bat, gradle/wrapper/ — but keep gradle/libs.versions.toml.
9. Sweep the catalog: drop the whole [plugins] block, any [versions] keys that only fed it, and [bundles] once every consumer applies a template.
10. 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.

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.