Skip to content

Gradle integration ​

Already have a Java project built with Gradle? The official dev.sprig plugin lets you add Sprig code to it. The plugin reads the project's real compile classpath, compiles the optional Java bridge code, runs Sprig's checks and tests, adds the generated Java and the project's own copy of the runtime to the project, and hooks all of it into Gradle's usual build.

Needs v0.6.0-beta.1 or newer

The plugin ships with the SDK starting with v0.6.0-beta.1. If sprig version shows an older version, run sprig upgrade first.

Adding the plugin ​

The plugin ships as source in the SDK's libraries/sprig-gradle/ directory and is used through Gradle's included-build mechanism, so you don't need a Gradle Plugin Portal account. Set the SPRIG_HOME environment variable to the SDK's root (or pass -PsprigHome=<path> to Gradle), then bring the plugin in from settings.gradle:

groovy
pluginManagement {
    def home = providers.gradleProperty('sprigHome')
        .orElse(providers.environmentVariable('SPRIG_HOME')).get()
    includeBuild(new File(home, 'libraries/sprig-gradle'))
    repositories { gradlePluginPortal(); mavenCentral() }
}

Then apply it in build.gradle:

groovy
plugins {
    id 'java'
    id 'dev.sprig'
}

sprig {
    targetSourceSet = 'main'
}

For a Minecraft mod built with Loom, target main for content both sides need, such as items and blocks, and client only for a client-only mod. Fabric mods walks through a complete project.

Everyday use ​

Use Gradle as usual:

sh
./gradlew check
./gradlew build
  • check runs sprigCheck and sprigTest.
  • build generates Java from your checked Sprig code and compiles it along with the project's own copy of the runtime.
  • Java bridge code goes in src/sprigBridge/java/ by default. The generated Java ends up in build/generated/sprig/<sourceSet>/java/, where you can read it.
  • Sprig's tasks only read sprig.lock and never go online. To update dependencies, run ./gradlew sprigResolve explicitly.
  • ./gradlew sprigInfo shows which compiler and runtime are in use, the target source set, the bridge code, the generated directory and package, the test directory, the lock status and the size of the classpath.

The plugin looks for the sprig compiler in this order: an explicit setting such as sprig { executable = ... }, then SPRIG_HOME, then your PATH, and finally an SDK installed under ~/.sprig.

Using Sprig classes from Java ​

Sprig generates your classes into a package named after the project. With name = "ordinary-project" in sprig.toml, the package is sprig.user.ordinary_project (every character a Java package name can't hold becomes _). Java code in the project names the classes with that package:

java
import sprig.user.ordinary_project.$Counter;

System.out.println(new $Counter().current());

If you forget the package, run ./gradlew sprigInfo and look for the Generated package line.

The Sprig runtime your project uses sits below the same package (sprig.user.ordinary_project.runtime), one copy per project. So two jars built with Sprig have no class name in common, and they can share a JVM without getting in each other's way: two Fabric mods in one game, for example.

Two things to keep in mind:

  • Rename the project and the package changes with it. javac points at every piece of Java code that still uses the old one.
  • Pass values between two such jars as Java types (String, numbers, an interface of your own). Each has its own runtime, so one project's Sprig List isn't the other's.

Needs v0.9.0-beta.1 or newer

SDK v0.8.0-beta.1 and earlier generate every project's classes into sprig.user, with the runtime in sprig.runtime. When you move on from one of them, change sprig.user. in your Java code to sprig.user.<project>..

When a top-level let is initialized for Java callers ​

Under sprig run, a module's top-level statements, including the initial values of its top-level lets and vars, run as soon as the program starts. A Java project has no such start: Java calls a function directly, or makes an object with new. Say src/store.spr is this module:

spr
let names: MutableList[String] = []

func remember(name: String) -> Unit:
    names.append(name)

func seen() -> Int:
    return names.size()

Java uses it like this, with no "init" call first:

java
sprig.user.ordinary_project.$M_store.fn$remember("x");
System.out.println(sprig.user.ordinary_project.$M_store.fn$seen());   // 1

The first time Java calls one of a module's functions, or makes an object of one of its classes that has methods, that module's top-level statements run first: those of the modules it imports, then its own, and only once. So however your Sprig code is entered, the top-level variables it reads already have their values.

Three things to keep in mind:

  • If a top-level statement fails, that first call is what fails. An unchecked failure such as Sprig's Error reaches Java as it is. A checked Java exception arrives as an IllegalStateException with the original as its cause. The statements don't run a second time, so treat it as fatal.
  • Make the first call before other threads use the code. The statements run once, on the thread that makes the first call. A call from another thread during that time doesn't wait for them, and it may read a variable that has no value yet. A framework's initializer, such as Fabric's ModInitializer, is the right place for the first call.
  • Don't read a top-level variable's field from Java, such as $M_store.names. Reading a field doesn't run the statements, so before the first call it's still null. Read it through a function.

This describes the main branch

SDK v0.9.0-beta.1 and earlier don't do this: when Java calls a function directly, the top-level statements haven't run, and top-level variables are null or 0. With one of those versions, call $init() on the module's class once before the first call, for example sprig.user.ordinary_project.$M_store.$init() (it declares throws Exception).

The dev.sprig plugin guide covers the remaining options, compatibility and every task in detail. The plugin saves you from writing the same build setup in every project. It doesn't replace Gradle, Loom or Java, and it says nothing about whether Sprig is more productive than Java.

Sprig is licensed under Apache-2.0 · v0.7.1-beta.1 published as a prerelease