How tbsten/cream works
Project type and purpose
• This is an open-source Kotlin Multiplatform library and toolset.
• cream-ksp: a KSP (Kotlin Symbol Processing) plugin that generates cross-class copy functions at compile time.
• cream-runtime: a Kotlin library providing the generated functions at runtime.
• buildLogic: a custom Gradle convention plugin to enforce consistent build settings.
• optionBuilder: a multiplatform sample/demo application (desktopApp, sharedUI, webApp) showcasing an interactive Option Builder UI.
• test module: validates core library behavior across platforms.
File structure
• Top-level modules:
• buildLogic/ : custom Gradle plugin (LintPlugin, DSL helpers)
• cream-ksp/ : KSP processor that reads annotations (@CopyTo, @CombineFrom, etc.) and emits Kotlin source in META-INF/services
• cream-runtime/ : core library consumed by user code and by optionBuilder
• optionBuilder/ : demo app with 3 sub-modules
– desktopApp (Compose Desktop main.kt)
– sharedUI (Compose Multiplatform UI components)
– webApp (JS target using sharedUI)
• test/ : multiplatform tests for functionality
• Configuration artifacts: build.gradle.kts at root, settings.gradle.kts, GitHub workflows, gradle.properties, gradle/libs.versions.toml
Readme insights
• The README describes:
• How cream-ksp hooks into KSP to generate mapping functions based on annotations.
• How cream-runtime supplies those functions at runtime for state transitions and data copy.
• A live Option Builder tool (optionBuilder) for visualizing and experimenting with configuration options.
Main components & relationships
• Developer’s project source (annotated Kotlin classes)
• Gradle build system + buildLogic plugin
• KSP processor (cream-ksp)
• Generated code (build/generated for commonMain and platform sources)
• Runtime library (cream-runtime)
• Demo application (optionBuilder: sharedUI → desktopApp/webApp)
• Unit/integration tests (test module)
1. Developer writes Kotlin code with cream annotations →
2. Gradle invokes KSP (cream-ksp) at compile time →
3. KSP scans source, emits generated Kotlin files →
4. Generated files + cream-runtime are compiled →
5. optionBuilder apps and user code invoke generated functions at runtime →
6. test module validates behavior
c. Architectural patterns & design principles:
• Plugin architecture: clear separation between compile-time (KSP) and runtime (library)
• Kotlin Multiplatform: commonMain, jsMain, jvmMain, desktop, web
• Convention over configuration: buildLogic plugin enforces common rules
• Modularization: each module has single responsibility (processor, runtime, UI, tests)
Key details to capture
• Exactly which modules depend on which (cream-ksp has no runtime dependency on cream-runtime, but generated code does).
• The multiplatform source sets in cream-runtime and optionBuilder/sharedUI.
• The custom Gradle plugin (buildLogic) hooking into all modules.
• Test module illustrating multiplatform validation.