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

---
name: kotlin-tooling-gradle-to-kotlin-toolchain-project
description: >
  Load when migrating or converting an entire Gradle Kotlin project
  (build.gradle(.kts), wrapper, libs.versions.toml, buildSrc) to the Kotlin
  Toolchain, including rewriting CI and replacing Gradle plugins that have no
  native Toolchain equivalent. Skip for porting one Gradle plugin or general
  Toolchain work once Gradle is gone.
license: Apache-2.0
metadata:
  author: github:@singleton11
  version: "0.1.0"
---

# 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.
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](#no-buildsrc--convention-plugins--shared-config-goes-in-templates).
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](#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.
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](#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/`](https://github.com/JetBrains/kotlin-toolchain/tree/main/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](#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](https://github.com/JetBrains/kotlin-toolchain)) 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](#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.
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](#phase-4--rewrite-ci)).
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:

```sh
./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

```yaml
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:

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

```yaml
# 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
```

```yaml
# 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>") }`:

```kotlin
// 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)
}
```

```yaml
# 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:

```xml
<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/>