Gradle plugin reference

The io.stoatflow convention plugin encapsulates StoatFlow's build conventions: the JDK 25 toolchain, the required preview + native-access JVM flags, a runnable fat JAR, and opt-in Docker (Jib) and GraalVM native-image builds. Configure it through the typed stoatflow { } extension (Kotlin DSL). For the Maven equivalent — the same conventions via a parent POM — see the Maven reference.

Apply it after registering the plugin-marker repository — see Project setup and Installation.

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.4.0"   // omit for a Java-only project
    id("io.stoatflow") version "<stoatflow-version>"
}

stoatflow {
    mainClass.set("com.example.MainKt")
}

The current release is 1.0.0-alpha.16 — substitute it for the <stoatflow-version> placeholder.

Extension DSL

The plugin registers a stoatflow { } extension. The full surface, with every default:

stoatflow {
    mainClass.set("com.example.MainKt")             // default: unset

    docker {
        enabled.set(true)                           // default: false
        imageName.set("my-app")                     // default: project.name
        port.set(8080)                              // default: 8080
        user.set("1000:1000")                       // default: 1000:1000
        baseImage.set("eclipse-temurin:25-jre-noble") // default shown (JVM/Jib only)
        stateDir.set("/data/state")                 // default: /data/state
        rocksdbMb.set(256)                          // default: auto-detect (see below)
        reproducibleBuild.set(true)                 // default: true
        jvmFlags.set(listOf("-XX:+UseG1GC"))        // overridable; preview/native-access always added
    }

    nativeImage {
        enabled.set(true)                           // default: false
        gc.set("G1")                                // default: absent (Serial GC)
        runtimeTarget.set("runtime")                // default: runtime; or "runtime-lean"
        additionalInitializeAtRunTime.add("com.example.MyClass")
        removeInitializeAtRunTime.add("org.rocksdb.RocksDB")
    }
}

stoatflow { }

docker { }

nativeImage { }

What the plugin applies

Applied unconditionally on every project the plugin is added to:

JVM args

--enable-preview is required because StoatFlow builds on JDK preview features; --enable-native-access=ALL-UNNAMED is required because RocksDB's state store uses the Foreign Function & Memory API. See Installation for the rationale behind -XX:+UseG1GC.

Tasks the plugin contributes

Docker image defaults

When docker.enabled = true, the Jib build is configured with:

See Docker for the full container guide.

Native image defaults

When nativeImage.enabled = true, the GraalVM build is configured from the bundled native-image.args (the single source of truth, identical for Gradle, Maven, and the containerized build), plus the dynamic gc / add / remove deltas:

The nativeDockerBuild task tags the resulting image <imageName>:native and <imageName>:<version>-native. See Native image for the full guide.

Version compatibility

The plugin pins the build tools it bundles. As of 1.0.0-alpha.16 the pins are:

Related

• Project setup — applying the conventions in a fresh project (Gradle or Maven).
• Maven reference — the same conventions for Maven projects.
• Docker — building and running the container image.
• Native image — ahead-of-time compilation with GraalVM.