Skip to main content

Runtime Provisioning

The Gradle plugin can use an explicit local runtime, explicit artifacts, or a source checkout that it provisions itself.

Resolution order​

The extension exposes:

kanvas {
    home = ""
    sourceUrl = "https://github.com/Yuries-Public-Stuff/Kanvas.git"
    sourceRef = ""

    agentJar = ""
    nativeLibrary = ""
    autoBuildRuntime = true
}

The exact fields live in KanvasExtension.kt.

Why released plugins resolve version tags​

When sourceRef is blank, the plugin derives an effective ref:

  • released plugin version → matching vX.Y.Z
  • snapshot/development build → main

That behavior is implemented by effectiveSourceRef in KanvasPlugin.kt.

Why this matters

The Java agent, JNI ABI, native command protocol, and Gradle-side launch configuration evolve together. Pulling arbitrary main for a released plugin could combine a stable plugin JAR with a newer incompatible runtime. Pinning a release to its matching Git tag reduces that skew.

Why the source checkout is cached by URL + ref​

Kanvas hashes sourceUrl and includes the sanitized ref in the Gradle-user-home cache path.

Conceptually:

~/.gradle/caches/kanvas/source/<source-url-hash>/<ref>/

This avoids collisions between forks/mirrors while making a resolved runtime reusable between projects.

kanvasRefreshRuntime exists specifically to invalidate that cached source when you intentionally want a fresh runtime build.