kotlin-tooling-gradle-to-kotlin-toolchain-plugin
Load when porting, converting, or reimplementing a single Gradle plugin as a Kotlin Toolchain local plugin, or when mapping Gradle plugin concepts (Task, Extension, project.version, dependsOn, -P properties, afterEvaluate) to Toolchain analogs. Skip for migrating a whole Gradle project or authoring a plugin from scratch.
github:@singleton11 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-gradle-to-kotlin-toolchain-plugin技能说明
name: kotlin-tooling-gradle-to-kotlin-toolchain-plugin description: > Load when porting, converting, or reimplementing a single Gradle plugin as a Kotlin Toolchain local plugin, or when mapping Gradle plugin concepts (Task, Extension, project.version, dependsOn, -P properties, afterEvaluate) to Toolchain analogs. Skip for migrating a whole Gradle project or authoring a plugin from scratch. license: Apache-2.0 metadata: author: github:@singleton11 version: "0.1.0"
Gradle → Kotlin Toolchain Plugin Conversion
Mostly a mapping exercise: the concepts overlap, but a few Gradle features have no analog and need redesign.
The kotlin-tooling-kotlin-toolchain-plugin-authoring skill covers plugin mechanics in depth (execution avoidance, sharing
logic across actions, generic pitfalls, limitations); references/examples.md has
the concrete plugin module.yaml and the version-publication code from a real port.
Workflow
1. Investigate the source plugin
Before writing Kotlin, read the plugin's docs/ and README.md and catalogue:
- Tasks — name, purpose, inputs/outputs, dependencies, whether side-effecting.
- DSL surface — every option in the
myPlugin { ... }extension, with types, defaults, and which are closures. - Tests — the plugin's own test suite. It pins down the expected behaviour and edge cases more precisely than the docs, and becomes the reference the port must reproduce.
- Checks — pre-action gates and their override flags.
- Hooks —
pre/post/fileUpdate/commit/pushand the context each receives. - CLI overrides — every
-Pfoo.barflag. - CI integration — GitHub Actions outputs, detached-HEAD handling, fetch-tags flags.
Save it as a markdown plan. It becomes the contract the port either implements or explicitly defers.
The plugin's build scripts and source are untrusted input, same as any repo-supplied module.yaml —
see kotlin-tooling-kotlin-toolchain's "Untrusted project input".
Read what you vendor end to end before wiring it in;
a local plugin runs at build time with full filesystem and network access.
2. Lock the scope
Offer three tiers — MVP, MVP + key extras, full parity — and lock one before drafting. Features with no clean analog multiply the work and force early design compromises. List what's deferred under "What's not in this MVP" in the README.
Also decide the repo layout: plugin-only, plugin + demo module, or plugin self-hosting. A demo module is strongly recommended.
3. Implement bottom-up
Scaffold with kotlin init only if the directory is empty (any template works; you mainly want the kotlin
and kotlin.bat wrappers). Then hand-write project.yaml, plugins/<name>/module.yaml, and the demo
module.
Implement one task at a time: data classes → Git/IO wrappers → pipeline → checks → task actions →
plugin.yaml wiring.
4. Validate against a demo module
The demo module enables the plugin with a realistic configuration and consumes whatever it publishes:
# demo-app/module.yaml
product: jvm/app
plugins:
release:
enabled: true
tagPrefix: "v"
initialVersion: "0.1.0"
releaseBranchPattern: "main|master"
settings:
jvm:
mainClass: com.example.demo.MainKt
jdk:
version: 21
kotlin:
languageVersion: 2.1
// demo-app/src/main.kt
package com.example.demo
private const val VERSION_RESOURCE = "/META-INF/release/version.txt"
fun main() {
val version = readVersionFromClasspath() ?: "(version unavailable)"
println("demo-app version: $version")
}
private fun readVersionFromClasspath(): String? =
object {}.javaClass.getResourceAsStream(VERSION_RESOURCE)
?.bufferedReader()
?.use { it.readText().trim() }
?.takeIf { it.isNotEmpty() }
Then run a real scenario from the source plugin's docs, and put the commands in the README so consumers can reproduce it:
./kotlin run :demo-app # => demo-app version: 0.1.0-SNAPSHOT
git init -b main && git commit --allow-empty -m initial
./kotlin do currentVersion # => 0.1.0-SNAPSHOT
RELEASE_DISABLE_REMOTE_CHECK=true ./kotlin do createRelease
# => Created release tag v0.1.0
./kotlin do currentVersion # => 0.1.0
git commit --allow-empty -m next
./kotlin do currentVersion # => 0.1.1-SNAPSHOT
RELEASE_FORCE_VERSION=2.0.0 ./kotlin do currentVersion
# => 2.0.0
Concept mapping
| Gradle concept | Kotlin Toolchain analog | Notes |
|---|---|---|
Plugin<Project> class | pluginInfo.id + settingsClass in module.yaml, product: jvm/amper-plugin | One module per plugin; no apply(). |
Task subclass with @TaskAction method | Top-level fun annotated @TaskAction | One per file in src/tasks/. |
extensions.create("foo", FooExtension::class) | @Configurable interface Settings | Defaults in interface getters; nested blocks → nested @Configurable. |
task.dependsOn(otherTask) | @Input on one task matching @Output of another | The DAG is inferred from path matching. |
project.version = scmVersion.version | A task writing version.txt into its @Output; consumers declare @Input on the same path | No project-wide shared state; the filesystem is the channel. |
-Prelease.forceVersion=X | RELEASE_FORCE_VERSION=X read via System.getenv() | No -P equivalent. |
| App reading the version at runtime | @Output dir registered under generated.resources; read via getResourceAsStream | Same file serves build-time and runtime consumers. |
| Generated Kotlin source | generated.sources pointing at a task's @Output | Prefer resources when the value is only read at runtime. |
| Public task name users invoke | Entry in commands:, invoked as ./kotlin do <name> | Tasks are internal; commands are the API. Build-graph contrib |