ktc-to-gradle

ktc-to-gradle converts a Kotlin Toolchain 0.12 project into a Gradle Kotlin DSL build in place. It finds project.yaml or module.yaml, resolves modules and templates, and generates a build pinned to Gradle 9.7.1.

Intent

This project exists to make trying Kotlin Toolchain a low-risk, reversible decision. A team should be able to start a real project with the simpler declarative Toolchain model, evaluate it in practice, and keep using it when it fits. If Toolchain does not yet cover the project's requirements, ktc-to-gradle provides an escape hatch to a conventional Gradle Kotlin DSL build instead of forcing the team to rewrite its build from scratch.

The goal is not to move projects away from Kotlin Toolchain. The Gradle converter is a safety net intended to reduce fear of lock-in, so more developers feel comfortable adopting and testing Kotlin Toolchain today.

For AI-assisted work with module.yaml, project.yaml, templates, dependencies, platforms, and the kotlin CLI, see the version-aware Kotlin Toolchain skill in Heapy/kortex. The kortex plugin packages this skill for Codex, Claude Code, and Junie.

The converter and its integration-test harness are built by Kotlin Toolchain. Gradle is invoked only as the system under test: each fixture is converted and then built with the generated Gradle 9.7.1 wrapper.

Getting Started

Run the latest GitHub Release binary directly. The bootstrap script detects the current OS and architecture, downloads the archive and its SHA-256 checksum, verifies it, caches the executable, and forwards all arguments:

curl -fsSL https://raw.githubusercontent.com/Heapy/ktc-to-gradle/main/run.sh | bash -s -- /path/to/toolchain-project

To download, verify, and install the native binary in ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/Heapy/ktc-to-gradle/main/install.sh | sh
ktc-to-gradle /path/to/toolchain-project

Windows PowerShell:

irm https://raw.githubusercontent.com/Heapy/ktc-to-gradle/main/install.ps1 | iex
ktc-to-gradle C:\path\to\toolchain-project

Set KTC_TO_GRADLE_VERSION=0.12.0 to pin a release or KTC_TO_GRADLE_REPOSITORY=owner/repository when using a fork. Native release binaries are published for macOS arm64, Linux x64/arm64, and Windows x64. Kotlin Toolchain 0.12 no longer supports macOS Intel native app products.

Use --dry-run to validate without writing. Existing Gradle files that were not generated by this tool are protected; pass --force only after reviewing them.

The converter generates gradlew and gradlew.bat in the converted project. These thin wrappers download Gradle 9.7.1 into the user's Gradle cache, so no manual Gradle installation is required.

Conversion coverage

• single-module projects and project.yaml multi-module projects, including one-component globs;
• nested module templates with Toolchain precedence;
• amper and maven-like JVM layouts;
• jvm/app, jvm/lib, android/app, kmp/lib, JS, Wasm, and native app products;
• root-relative and relative local module dependencies;
• Maven coordinates, BOMs, dependency scopes, exported dependencies, repositories, and libs.versions.toml catalogs;
• Kotlin/JVM compiler settings, JDK/release settings, JUnit 4/5, test process settings, Kotlin serialization, and the Ktor BOM;
• platform-qualified KMP source, resource, test, and dependency sections.

The converter stops with an explanation for Toolchain build plugins, Maven plugins, ios/app, Android targets nested in kmp/lib, and built-in technologies whose Gradle behavior cannot yet be reproduced safely. Original YAML and source files are never removed.

Build and test

The code uses the io.heapy.ktctogradle package and kotaml for YAML 1.2 parsing. The checked-in Kotlin Toolchain 0.12 wrapper provisions everything needed by the application build:

./kotlin test -m core -p jvm
./kotlin build -m macos -p macosArm64 -v release  # choose the host module/platform

Run the Kotlin Toolchain integration-test module separately:

./kotlin test -m integration-tests -p jvm

The suite copies three real Toolchain fixtures, converts them, and executes build on every generated Gradle 9.7.1 project. GitHub Actions also smoke-tests run.sh and install.sh on Linux/macOS and install.ps1 on Windows, including checksum-failure paths. Native archives with SHA-256 checksum files are published for v* tags.