From 4ad95e327864a1e2769138fe8415ad5e2e550577 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 21:58:05 +0100 Subject: [PATCH 01/12] Add overview and basic usage to README Replace the placeholder "under development" note with production-grade documentation: a project overview, a "How it works" pipeline summary, Gradle plugin setup, a plugin-authoring example, a modules table, and reference links. Closes #72. Co-Authored-By: Claude Opus 4.8 --- README.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 138 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 49d2b60773..0fe92592b3 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,141 @@ [![codecov.io][codecov-badge]][codecov-report] [![license][apache-badge]][apache-license] -Spine Compiler is a collection of tools for generating quality -domain models from Protobuf definitions. +Spine Compiler is a collection of tools for generating quality domain models from Protobuf +definitions. It plugs into your Gradle build and extends the code that `protoc` produces, +turning plain `.proto` messages into rich domain types — with validation, factory methods, +and other conveniences contributed by pluggable code generators. -The project is under development right now. Proceed with caution. +The Compiler is part of the [Spine SDK][spine-site] and powers code generation across +Spine-based projects. It is not limited to them, though: any Protobuf-based JVM project can +apply the Compiler and drive it with its own code-generation plugins. + +## How it works + +The Compiler treats your Protobuf definitions as a model and processes it reactively: + +1. `protoc` parses the `.proto` files. A `protoc` plugin bundled with the Compiler captures + the result as a code-generation request. +2. The Compiler reads that request and represents the Protobuf files, types, fields, and + options as a model, delivered as a stream of events. +3. The plugins you attach observe the model through *views* and react to it through + *policies*, then emit source code through *renderers*. +4. The renderers create new source files or edit the ones `protoc` generated, producing the + final domain model. + +A *plugin* bundles these parts together, so attaching one plugin is enough to contribute a +whole feature to the generated code. + +## Getting started + +### Requirements + +- JDK 17 or newer. +- The [Protobuf Gradle Plugin][protobuf-gradle] (`com.google.protobuf`), which the Compiler + builds upon. + +### Apply the Gradle plugin + +The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal under the +`io.spine.compiler` ID. Apply it alongside the Protobuf Gradle Plugin: + +```kotlin +plugins { + kotlin("jvm") + id("com.google.protobuf") + id("io.spine.compiler") version "2.0.0" +} +``` + +Once applied, the Compiler hooks into the `generateProto` tasks, so the generated model is +refreshed on every build. + +### Configure code-generation plugins + +Out of the box the Compiler runs the pipeline without changing the generated code. To make it +do something, attach one or more Compiler plugins: name their classes through the `compiler { }` +extension, and put them on the Compiler classpath with the `spineCompiler` configuration. + +```kotlin +spine { + compiler { + plugins( + "com.acme.codegen.MyPlugin", + ) + } +} + +dependencies { + spineCompiler("com.acme:my-codegen:1.0.0") +} +``` + +Then build the project as usual: + +```bash +./gradlew build +``` + +## Writing a plugin + +A Compiler plugin is a class with a parameterless constructor that bundles the components doing +the work. The most common component is a *renderer*, which creates or edits source files: + +```kotlin +import io.spine.tools.code.Java +import io.spine.tools.compiler.plugin.Plugin +import io.spine.tools.compiler.render.Renderer +import io.spine.tools.compiler.render.SourceFileSet + +/** Modifies the Java sources produced for the Protobuf model. */ +public class MyRenderer : Renderer(Java) { + + override fun render(sources: SourceFileSet) { + // Inspect the Protobuf model and create or edit source files here. + } +} + +/** Exposes the renderer — and any views or policies — to the Compiler. */ +public class MyPlugin : Plugin(renderers = listOf(MyRenderer())) +``` + +Compile the plugin against the public API artifact: + +```kotlin +dependencies { + implementation("io.spine.tools:compiler-api:2.0.0") +} +``` + +Renderers can inspect the Protobuf model through views and react to it through policies. See the +`api` module and its API documentation for the full set of building blocks. + +## Modules + +The build publishes its modules under the `io.spine.tools` group with the `compiler-` prefix +(for example, `io.spine.tools:compiler-api`). The Gradle plugin is published separately to the +Gradle Plugin Portal as `io.spine.compiler`. + +| Module | Role | +|-----------------|------------------------------------------------------------------| +| `gradle-plugin` | The `io.spine.compiler` Gradle plugin — the entry point for most users. | +| `api` | Public API for writing plugins, renderers, views, and policies. | +| `gradle-api` | Public Gradle-facing API: settings, task names, and artifact names. | +| `backend` | The code-generation engine that runs the pipeline. | +| `protoc-plugin` | The `protoc` plugin that captures the code-generation request. | +| `cli` | Command-line entry point that runs the pipeline. | +| `params` | The parameter model passed to the Compiler. | +| `jvm` | JVM-specific code-generation support. | + +## Further reading + +- [Spine SDK website][spine-site] +- [Contributing guidelines](CONTRIBUTING.md) +- [Code of conduct](CODE_OF_CONDUCT.md) + +## License + +Spine Compiler is released under the [Apache License, Version 2.0](LICENSE.md). [ubuntu-badge]: https://github.com/SpineEventEngine/compiler/actions/workflows/build-on-ubuntu.yml/badge.svg [ubuntu-build]: https://github.com/SpineEventEngine/compiler/actions/workflows/build-on-ubuntu.yml @@ -19,5 +150,8 @@ The project is under development right now. Proceed with caution. [codecov-badge]: https://codecov.io/github/SpineEventEngine/compiler/coverage.svg?branch=master [codecov-report]: https://codecov.io/github/SpineEventEngine/compiler?branch=master -[apache-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat +[apache-badge]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat [apache-license]: https://www.apache.org/licenses/LICENSE-2.0 + +[spine-site]: https://spine.io/ +[protobuf-gradle]: https://github.com/google/protobuf-gradle-plugin From 66d09fbb1ae1681af760d5bf8a97568951f4cc74 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 21:59:42 +0100 Subject: [PATCH 02/12] Bump version -> `2.0.0-SNAPSHOT.057` Co-Authored-By: Claude Opus 4.8 --- version.gradle.kts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/version.gradle.kts b/version.gradle.kts index a76f6ab32e..e6860dfd24 100644 --- a/version.gradle.kts +++ b/version.gradle.kts @@ -1,5 +1,5 @@ /* - * Copyright 2025, TeamDev. All rights reserved. + * Copyright 2026, TeamDev. All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -30,7 +30,7 @@ * This version is also used by integration test projects. * E.g. see `tests/consumer/build.gradle.kts`. */ -val compilerVersion: String by extra("2.0.0-SNAPSHOT.056") +val compilerVersion: String by extra("2.0.0-SNAPSHOT.057") /** * The version, same as [compilerVersion], which is used for publishing From ddbe26442e38f12fe057d4542676aeee1a639cf2 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 22:09:33 +0100 Subject: [PATCH 03/12] Update dependency reports Co-Authored-By: Claude Opus 4.8 --- docs/dependencies/dependencies.md | 44 +++++++++++++++---------------- docs/dependencies/pom.xml | 2 +- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/dependencies/dependencies.md b/docs/dependencies/dependencies.md index 28bdd11628..08125a602c 100644 --- a/docs/dependencies/dependencies.md +++ b/docs/dependencies/dependencies.md @@ -1,6 +1,6 @@ -# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-api:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -1067,14 +1067,14 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-api-tests:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-api-tests:2.0.0-SNAPSHOT.057` ## Runtime ## Compile, tests, and tooling @@ -1444,14 +1444,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-backend:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-backend:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -2522,14 +2522,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-cli:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-cli:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -3759,14 +3759,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-gradle-api:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-gradle-api:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -4783,14 +4783,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-gradle-plugin:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-gradle-plugin:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -5851,14 +5851,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-jvm:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-jvm:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -6946,14 +6946,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-params:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-params:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -8012,14 +8012,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:25 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-protoc-plugin:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-protoc-plugin:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -8852,14 +8852,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:23 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-test-env:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-test-env:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -9926,14 +9926,14 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:compiler-testlib:2.0.0-SNAPSHOT.056` +# Dependencies of `io.spine.tools:compiler-testlib:2.0.0-SNAPSHOT.057` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.22.0. @@ -11107,6 +11107,6 @@ This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Jun 26 18:10:51 WEST 2026** using +This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/docs/dependencies/pom.xml b/docs/dependencies/pom.xml index 957a2fdd3e..33c1655644 100644 --- a/docs/dependencies/pom.xml +++ b/docs/dependencies/pom.xml @@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject. --> io.spine.tools compiler -2.0.0-SNAPSHOT.056 +2.0.0-SNAPSHOT.057 2015 From 885d021c196cd5cbeb559ed0b48f374b8bd5123d Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 22:38:01 +0100 Subject: [PATCH 04/12] Clarify Gradle setup in README per review feedback Apply the `java` plugin instead of `kotlin("jvm")` in the Getting started example so Java-only projects are not implied to require Kotlin, and note that either language works. Clarify that the `compiler { }` DSL block is nested inside the `spine { }` extension. Co-Authored-By: Claude Opus 4.8 --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0fe92592b3..9e898ac922 100644 --- a/README.md +++ b/README.md @@ -45,20 +45,22 @@ The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal unde ```kotlin plugins { - kotlin("jvm") + java id("com.google.protobuf") id("io.spine.compiler") version "2.0.0" } ``` -Once applied, the Compiler hooks into the `generateProto` tasks, so the generated model is -refreshed on every build. +The example applies the `java` plugin; use `kotlin("jvm")` instead for a Kotlin project — the +Compiler generates code for both. Once applied, the Compiler hooks into the `generateProto` +tasks, so the generated model is refreshed on every build. ### Configure code-generation plugins Out of the box the Compiler runs the pipeline without changing the generated code. To make it -do something, attach one or more Compiler plugins: name their classes through the `compiler { }` -extension, and put them on the Compiler classpath with the `spineCompiler` configuration. +do something, attach one or more Compiler plugins: list their classes in the `compiler { }` +block — nested inside the `spine { }` extension — and put them on the Compiler classpath with +the `spineCompiler` configuration. ```kotlin spine { From 9d23bebb353cc7f30a0067839d5cb7a08a6f6789 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:08:48 +0100 Subject: [PATCH 05/12] Bump CoreJvm --- buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt index 54029eb046..d4b8a18ccc 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvm.kt @@ -39,7 +39,7 @@ typealias CoreJava = CoreJvm @Suppress("ConstPropertyName", "unused") object CoreJvm { const val group = Spine.group - const val version = "2.0.0-SNAPSHOT.380" + const val version = "2.0.0-SNAPSHOT.381" const val coreArtifact = "spine-core" const val clientArtifact = "spine-client" From 597996af5fd422e44b9e2c021cc01d2ab03349db Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:09:23 +0100 Subject: [PATCH 06/12] Improve README wording around Protobuf Gradle Plugin --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 9e898ac922..f6280cfcf9 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,13 @@ whole feature to the generated code. ### Apply the Gradle plugin The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal under the -`io.spine.compiler` ID. Apply it alongside the Protobuf Gradle Plugin: +`io.spine.compiler` ID. It applies the Protobuf Gradle Plugin automatically, +so you don't need to apply it explicitly.: ```kotlin plugins { java - id("com.google.protobuf") - id("io.spine.compiler") version "2.0.0" + id("io.spine.compiler") version "$version" } ``` @@ -122,16 +122,16 @@ The build publishes its modules under the `io.spine.tools` group with the `compi (for example, `io.spine.tools:compiler-api`). The Gradle plugin is published separately to the Gradle Plugin Portal as `io.spine.compiler`. -| Module | Role | -|-----------------|------------------------------------------------------------------| +| Module | Role | +|-----------------|-------------------------------------------------------------------------| | `gradle-plugin` | The `io.spine.compiler` Gradle plugin — the entry point for most users. | -| `api` | Public API for writing plugins, renderers, views, and policies. | -| `gradle-api` | Public Gradle-facing API: settings, task names, and artifact names. | -| `backend` | The code-generation engine that runs the pipeline. | -| `protoc-plugin` | The `protoc` plugin that captures the code-generation request. | -| `cli` | Command-line entry point that runs the pipeline. | -| `params` | The parameter model passed to the Compiler. | -| `jvm` | JVM-specific code-generation support. | +| `api` | Public API for writing plugins, renderers, views, and policies. | +| `gradle-api` | Public Gradle-facing API: settings, task names, and artifact names. | +| `backend` | The code-generation engine that runs the pipeline. | +| `protoc-plugin` | The `protoc` plugin that captures the code-generation request. | +| `cli` | Command-line entry point that runs the pipeline. | +| `params` | The parameter model passed to the Compiler. | +| `jvm` | JVM-specific code-generation support. | ## Further reading From ef40ed4a871b989dcd30faef80cf81d3b0156dc4 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:12:49 +0100 Subject: [PATCH 07/12] Update dependency reports --- docs/dependencies/dependencies.md | 22 +++++++++++----------- docs/dependencies/pom.xml | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/dependencies/dependencies.md b/docs/dependencies/dependencies.md index 08125a602c..3c7981933f 100644 --- a/docs/dependencies/dependencies.md +++ b/docs/dependencies/dependencies.md @@ -1067,7 +1067,7 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -1444,7 +1444,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:23 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -2522,7 +2522,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -3759,7 +3759,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -4783,7 +4783,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -5851,7 +5851,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -6946,7 +6946,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -8012,7 +8012,7 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:25 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -8852,7 +8852,7 @@ This report was generated on **Sat Jun 27 22:02:25 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:23 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -9926,7 +9926,7 @@ This report was generated on **Sat Jun 27 22:02:23 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -11107,6 +11107,6 @@ This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Sat Jun 27 22:02:26 WEST 2026** using +This report was generated on **Sat Jun 27 23:12:24 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/docs/dependencies/pom.xml b/docs/dependencies/pom.xml index 33c1655644..7f838991c9 100644 --- a/docs/dependencies/pom.xml +++ b/docs/dependencies/pom.xml @@ -137,7 +137,7 @@ all modules and does not describe the project structure per-subproject. io.spine spine-server - 2.0.0-SNAPSHOT.380 + 2.0.0-SNAPSHOT.381 compile @@ -209,7 +209,7 @@ all modules and does not describe the project structure per-subproject. io.spine.tools server-testlib - 2.0.0-SNAPSHOT.380 + 2.0.0-SNAPSHOT.381 compile From f21d34dd024e9bdcc51e1767378914e120637220 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 22:34:29 +0100 Subject: [PATCH 08/12] Update READMEs for the Spine Compiler rename and current API Rename ProtoData references to Spine Compiler in `tests/README.md` and `gradle-plugin/README.md`. Identifiers are verified against the source: the `compiler { }` extension, the `spineCompiler` configuration, the `LaunchSpineCompiler` task type, and the `io.spine.compiler` plugin id. Also bring `gradle-plugin/README.md` back in line with the current API: - use the real `Plugin` package `io.spine.tools.compiler.plugin.Plugin`; - document the real DSL options (`plugins`, `subDirs`, `outputBaseDir`) via the `spine { compiler { } }` block, dropping options that no longer exist; - fix the Maven coordinates to `io.spine.tools:compiler-gradle-plugin` and `io.spine.tools:compiler-api`. Fix a typo in `tests/README.md` and minor prose issues. Co-Authored-By: Claude Opus 4.8 --- gradle-plugin/README.md | 83 +++++++++++++++++++---------------------- tests/README.md | 6 +-- 2 files changed, 41 insertions(+), 48 deletions(-) diff --git a/gradle-plugin/README.md b/gradle-plugin/README.md index 72761986df..15c8ccd8fb 100644 --- a/gradle-plugin/README.md +++ b/gradle-plugin/README.md @@ -1,6 +1,6 @@ -# ProtoData Gradle plugin +# Spine Compiler Gradle plugin -This Gradle plugin allows Java developers launch ProtoData without extra CLI commands. +This Gradle plugin allows Java developers to launch the Compiler without extra CLI commands. ## Usage @@ -10,7 +10,7 @@ To apply the plugin to the project, use the `plugins { }` block syntax. ```kotlin plugins { - id("io.spine.compiler") version("") + id("io.spine.compiler") version("") } ``` @@ -24,77 +24,70 @@ buildscript { } dependencies { - classpath("io.spine:compiler:") + classpath("io.spine.tools:compiler-gradle-plugin:") } } apply(plugin = "io.spine.compiler") ``` -See the plugin [homepage](https://plugins.gradle.org/plugin/io.spine.protodata) for more. +See the plugin [homepage](https://plugins.gradle.org/plugin/io.spine.compiler) for more. -### Launching ProtoData +### Launching the Compiler -When used from Gradle, ProtoData does not require installation. +When used from Gradle, the Compiler does not require installation. -Just launch [configure](#Configuration) code generation and start a build: +Just [configure](#configuration) code generation and start a build: ``` ./gradlew build ``` ### Configuration -ProtoData requires Renderers and Plugins for meaningful operation. You can specify those and more -via a Gradle extension. +The Compiler runs the plugins you specify via the `compiler { }` extension, nested under the +`spine { }` block. The plugins' own classpath is declared via the `spineCompiler` configuration. Here is the complete list of configuration options: -| Name | Format | Description | Default value | -|---------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| -| `renderers` | Java class names | Implementations of `io.spine.compiler.renderer.Renderer`. Renderer ordering is preserved. | N/A | -| `plugins` | Java class names | Implementations of `io.spine.compiler.plugin.Plugin`. | N/A | -| `optionProviders` | Java class names | Implementations of `io.spine.compiler.option.OptionProvider`. | N/A | -| `requestFile` | File path | Where the serialized `CodeGeneratorRequest` should be stored. | A file under the `build` dir. | -| `srcBaseDir` | Directory path | Base directory where files generated by Protoc are located. | A directory under the `build` dir. | -| `targetBaseDir` | Directory path | Base directory where files generated by ProtoData are placed. Files from the source directory are copied into the target directory as well. | `$projectDir/generated/` | -| `subDir` | Directory path part | Subdirectory within `srcBaseDir` where files generated by the given Protoc plugin are located. This structure is mirrored in `targetBaseDir`. | `java` | -| Configuration `protoData` | Dependencies | The dependencies required to launch ProtoData with the given args. | N/A | +| Name | Format | Description | Default value | +|-----------------|------------------|-------------------------------------------------------------------------------------------|----------------------------------------| +| `plugins` | Java class names | Class names of `io.spine.tools.compiler.plugin.Plugin` implementations the Compiler runs. | None | +| `subDirs` | Directory names | Subdirectories under the generated source set that the Compiler processes. | `java`, `kotlin`, `grpc`, `js`, `dart` | +| `outputBaseDir` | Directory | Base directory where the files generated by the Compiler are placed. | `$projectDir/generated/` | A complete configuration may look as follows: ```kotlin plugins { - id("io.spine.compiler") version("") + id("io.spine.compiler") version("") } -protoData { - renderers("com.acme.MyInsertionPointPrinter", "com.acme.MyRenderer", "org.example.Renderer") - plugins("com.acme.MyPlugin") - optionProviders("com.acme.MyOptions") - - requestFile("${rootProject.buildDir}/commonRequestFile/request.bin") - srcBaseDir("$projectDir/my-generated-files/") - targetBaseDir("$projectDir/my-complete-files/") - subDir("foobar") +spine { + compiler { + plugins("com.acme.MyPlugin", "org.example.MyOtherPlugin") + subDirs = listOf("java", "kotlin") + outputBaseDir.set(project.layout.projectDirectory.dir("generated")) + } } dependencies { - protoData(project(":my-compiler-plugin")) - protoData("org.example:compiler-plugin:1.42") + spineCompiler(project(":my-compiler-plugin")) + spineCompiler("org.example:compiler-plugin:1.42") } ``` ## Source sets -For each source set in the project, the plugin generates a distinct task launching ProtoData. +For each source set in the project, the plugin generates a distinct task launching the Compiler. Each task only processes the sources of the associated source set. This allows users to apply -ProtoData to production and test code alike. +the Compiler to production and test code alike. -To reference a specific task by name, use the following format: `launchProtoData`, -for example, `launchProtoData`, `launchTestProtoData`, `launchIntegrationTestProtoData`, etc. +To reference a specific task by name, use the following format: +`launchSpineCompiler`, for example, `launchSpineCompiler`, +`launchTestSpineCompiler`, `launchIntegrationTestSpineCompiler`, etc. -To find all the tasks in a Gradle script, use the `LaunchProtoData` task type. For example: +To find all the tasks in a Gradle script, use the `LaunchSpineCompiler` task type. For example: ```kotlin -tasks.withType { +tasks.withType { onlyIf { moon.phase >= 0.7 } } ``` @@ -103,13 +96,13 @@ tasks.withType { The plugin changes the configuration of the Protobuf Gradle plugin in such a way that the files generated from Protobuf are placed under the `build` directory. After the files are then processed -by ProtoData, they will end up in ProtoData target directory, which is, by default, -`$projectDir/generated/`. To change the output dir, see the ProtoData plugin configuration. +by the Compiler, they will end up in the Compiler's target directory, which is, by default, +`$projectDir/generated/`. To change the output dir, see the Compiler plugin configuration. ## Caveat The plugin relies on the Java Project structure, the Java Gradle plugin, the Protobuf Gradle -plugin, and the ProtoData Maven repository. +plugin, and the Spine Compiler Maven repository. To make everything work, at this stage, users have to add the following config: @@ -117,12 +110,12 @@ To make everything work, at this stage, users have to add the following config: plugins { java id("com.google.protobuf") version("") - id("io.spine.compiler") version("") + id("io.spine.compiler") version("") } repositories { maven { - url = uri("https://maven.pkg.github.com/SpineEventEngine/ProtoData") + url = uri("https://maven.pkg.github.com/SpineEventEngine/compiler") credentials { username = "" password = "" @@ -131,9 +124,9 @@ repositories { } ``` -Users who wish to extend ProtoData must also add the dependency to the API: +Users who wish to extend the Compiler must also add the dependency to the API: ```kotlin dependencies { - implementation("io.spine.compiler:compiler-compiler:") + implementation("io.spine.tools:compiler-api:") } ``` diff --git a/tests/README.md b/tests/README.md index b2b473ed4e..4328568397 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,7 +1,7 @@ -# ProtoData integration tests +# Spine Compiler integration tests This subdirectory —`tests`— contains a separate Gradle product that runs integration -tests of the ProtoData command-line application and the ProtoData Gradle plugin. +tests of the Spine Compiler command-line application and the Compiler's Gradle plugin. This directory is a separate Gradle project, which fetches the artifacts from the primary Gradle project, via a Gradle [composite build][composite-build]. @@ -23,7 +23,7 @@ please run the following command: ./gradlew integrationTest ``` -If your current directory is `tests`, just run the Gradle build as usualy: +If your current directory is `tests`, just run the Gradle build as usual: ```bash ./gradlew clean build From 9362212595ca661053fe208ffa72f97fa1933e97 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:17:37 +0100 Subject: [PATCH 09/12] Require Protobuf Gradle Plugin in README Getting started The Compiler does not auto-apply the Protobuf Gradle Plugin; `Plugin.kt` fails fast when `com.google.protobuf` is absent. Restore `id("com.google.protobuf")` in the plugins block and state the requirement, matching `gradle-plugin/README.md` and the code. Also drops a stray `.:` typo. Co-Authored-By: Claude Opus 4.8 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f6280cfcf9..cc1824ed7b 100644 --- a/README.md +++ b/README.md @@ -41,12 +41,12 @@ whole feature to the generated code. ### Apply the Gradle plugin The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal under the -`io.spine.compiler` ID. It applies the Protobuf Gradle Plugin automatically, -so you don't need to apply it explicitly.: +`io.spine.compiler` ID. It requires the Protobuf Gradle Plugin, so apply both: ```kotlin plugins { java + id("com.google.protobuf") id("io.spine.compiler") version "$version" } ``` From e43fd8d05f972fa1092cd57925e0ccefa577e08d Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:24:42 +0100 Subject: [PATCH 10/12] Use a version placeholder in README examples Replace the unresolved `$version` reference (and the not-yet-published `2.0.0`) in the Getting started and plugin-authoring snippets with the `` placeholder, matching `gradle-plugin/README.md`. Co-Authored-By: Claude Opus 4.8 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cc1824ed7b..7417aa4359 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal unde plugins { java id("com.google.protobuf") - id("io.spine.compiler") version "$version" + id("io.spine.compiler") version "" } ``` @@ -109,7 +109,7 @@ Compile the plugin against the public API artifact: ```kotlin dependencies { - implementation("io.spine.tools:compiler-api:2.0.0") + implementation("io.spine.tools:compiler-api:") } ``` From d6cf6d4aae21c02392c9fb021d1b86d0a87593c1 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:34:40 +0100 Subject: [PATCH 11/12] Move module overview from README into docs/project.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The per-module breakdown is architecture detail, not user-facing documentation, so the `## Modules` section is dropped from `README.md`. `docs/project.md` already lists every module; this folds the README's unique detail — the `compiler-` artifact prefix and the `io.spine.compiler` plugin ID — into that doc's Architecture section. Co-Authored-By: Claude Opus 4.8 --- README.md | 17 ----------------- docs/project.md | 10 ++++++---- 2 files changed, 6 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 7417aa4359..0c0d477d8d 100644 --- a/README.md +++ b/README.md @@ -116,23 +116,6 @@ dependencies { Renderers can inspect the Protobuf model through views and react to it through policies. See the `api` module and its API documentation for the full set of building blocks. -## Modules - -The build publishes its modules under the `io.spine.tools` group with the `compiler-` prefix -(for example, `io.spine.tools:compiler-api`). The Gradle plugin is published separately to the -Gradle Plugin Portal as `io.spine.compiler`. - -| Module | Role | -|-----------------|-------------------------------------------------------------------------| -| `gradle-plugin` | The `io.spine.compiler` Gradle plugin — the entry point for most users. | -| `api` | Public API for writing plugins, renderers, views, and policies. | -| `gradle-api` | Public Gradle-facing API: settings, task names, and artifact names. | -| `backend` | The code-generation engine that runs the pipeline. | -| `protoc-plugin` | The `protoc` plugin that captures the code-generation request. | -| `cli` | Command-line entry point that runs the pipeline. | -| `params` | The parameter model passed to the Compiler. | -| `jvm` | JVM-specific code-generation support. | - ## Further reading - [Spine SDK website][spine-site] diff --git a/docs/project.md b/docs/project.md index a785162ca6..5a442db963 100644 --- a/docs/project.md +++ b/docs/project.md @@ -24,10 +24,12 @@ with these modules: published separately from the rest of the modules. - `test-env`, `testlib` — shared test fixtures and utilities. -Module artifacts are published under `io.spine.tools` (see -[`dependencies.md`](dependencies/dependencies.md) for the published coordinates). Public -API boundaries live in `api` and `gradle-api`; downstream Spine repos depend -on these. +Module artifacts are published under the `io.spine.tools` group with the +`compiler-` prefix — for example, `io.spine.tools:compiler-api` (see +[`dependencies.md`](dependencies/dependencies.md) for the full coordinates) — +and the Gradle plugin to the Gradle Plugin Portal as `io.spine.compiler`. +Public API boundaries live in `api` and `gradle-api`; downstream Spine repos +depend on these. Read [`.agents/guidelines/jvm-project.md`](../.agents/guidelines/jvm-project.md) for build stack, coding style, tests, and versioning. From 89c103545ad1f55617b7711584a01f893aab8478 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Sat, 27 Jun 2026 23:46:10 +0100 Subject: [PATCH 12/12] Make README plugin snippets self-contained Address PR review: add the required Protobuf Gradle Plugin (with a `` placeholder) to the `plugins {}` examples in both READMEs so they work when copied, and replace the undefined `moon.phase` example in `gradle-plugin/README.md` with a comment. Co-Authored-By: Claude Opus 4.8 --- README.md | 2 +- gradle-plugin/README.md | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0c0d477d8d..3ef5a3a46a 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ The Compiler ships as a Gradle plugin published to the Gradle Plugin Portal unde ```kotlin plugins { java - id("com.google.protobuf") + id("com.google.protobuf") version "" id("io.spine.compiler") version "" } ``` diff --git a/gradle-plugin/README.md b/gradle-plugin/README.md index 15c8ccd8fb..256627ea97 100644 --- a/gradle-plugin/README.md +++ b/gradle-plugin/README.md @@ -10,6 +10,8 @@ To apply the plugin to the project, use the `plugins { }` block syntax. ```kotlin plugins { + java + id("com.google.protobuf") version("") id("io.spine.compiler") version("") } ``` @@ -58,6 +60,8 @@ Here is the complete list of configuration options: A complete configuration may look as follows: ```kotlin plugins { + java + id("com.google.protobuf") version("") id("io.spine.compiler") version("") } @@ -88,7 +92,7 @@ To reference a specific task by name, use the following format: To find all the tasks in a Gradle script, use the `LaunchSpineCompiler` task type. For example: ```kotlin tasks.withType { - onlyIf { moon.phase >= 0.7 } + // Configure every Compiler launch task here. } ```