kotlin-tooling-kotlin-toolchain-plugin-authoring

Kotlin Toolchain Plugin Authoring

Local plugins are the official escape hatch from declarative YAML: a jvm/amper-plugin module shipping task actions, settings, and generated sources/resources alongside your project. Code patterns to adapt are in references/examples.md.

When to write a plugin

Write one when you need:

• A build-time step a library's workflow expects (code generation, schema compilation, resource transformation, version stamping).
• Custom verification wired into the build (pre-release checks, schema validation, contract tests).
• A build-time value published into the JAR classpath or downstream tasks — the closest analog to Gradle's project.version.
• A named CLI command for a repeated workflow (./kotlin do release).

Don't write one when module.yaml already covers it (dependencies, JDK provisioning, source layouts, basic packaging), and never to reuse a Gradle plugin — the Kotlin Toolchain cannot consume them.

Layout

repo-root/
├── kotlin, kotlin.bat            # wrappers (from `kotlin init`)
├── project.yaml                  # registers the plugin
├── plugins/<name>/
│   ├── module.yaml               # product: jvm/amper-plugin
│   ├── plugin.yaml               # tasks: + commands: + generated:
│   └── src/
│       ├── Settings.kt           # @Configurable interface
│       ├── tasks/                # one @TaskAction per file
│       │   ├── Foo.kt
│       │   └── FooSteps.kt       # internal shared helpers (not @TaskAction)
│       └── <domain logic>/
└── <consumer-module>/
    └── module.yaml               # plugins: { <name>: enabled: true, ... }

Keep at least one consumer module in the repo — it is the only way to exercise the plugin end-to-end, and plugins cannot be published to any public registry yet.

project.yaml

modules:
  - consumer-app
  - plugins/<name>

plugins:
  - ./plugins/<name>

Without the top-level plugins: block the plugin id is unresolvable from any consumer.