Writing patches
Bundle projects
A bundle is built from a Gradle project with a fixed layout. The app.reseam.workspace plugin sets up a module for every folder it finds, so most modules need no build script at all.
Layout
my-patches/
manifest.toml
settings.gradle.kts
apps/<app>/patch/ patches for one app, and their names and descriptions
apps/<app>/settings/ that app's settings and strings (optional)
apps/<app>/extensions/<name>/ code added to that app
shared/<name>/ code added to several apps
shared/<name>/patch/ patches several apps share (optional)
shared/<name>/settings/ settings several apps share (optional)
resources/ files patches copy into apps (optional)
The build turns these into the files inside your bundle:
| Folder | Becomes |
|---|---|
apps/<app>/patch/ |
<app>-patches.jar |
shared/<name>/patch/ |
<name>-patches.jar |
apps/<app>/extensions/<name>/ |
<app>-<name>.dex |
apps/<app>/settings/ |
<app>-settings.dex |
resources/ |
resources/, as it is |
When your extensions use the Kotlin standard library, the bundle also gets kotlin.dex, with only the parts they use.
manifest.toml
[bundle]
name = "my-patches"
author = "Your Name"
description = "Patches for Example"
license = "GPL-3.0"
format_version = 1
name: lowercase letters, digits, and hyphens. It names the output file, and starts your patch references (my-patches/<id>). Changing it after you publish breaks every reference to your patches.author,description, andlicenseare shown to users.licenseis optional, and shows on your settings screen's about card.format_versionis1.
settings.gradle.kts
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
maven("https://git.reseam.app/api/packages/reseam/maven") {
mavenContent { includeGroupAndSubgroups("app.reseam") }
}
}
(System.getenv("RESEAM_WORKSPACE") ?: providers.gradleProperty("reseam.workspace").orNull)
?.takeIf { it.isNotBlank() }
?.let { includeBuild(it) }
}
plugins {
id("app.reseam.workspace") version "0.33.0"
}
rootProject.name = "my-patches"
The plugin version sets the patch API you compile against, and the engine your bundle is built for. Use a reseam CLI of the same version.
The RESEAM_WORKSPACE lines are only for working on the engine itself. They point the build at a local engine checkout instead of the published plugin.
Building
./gradlew bundle
This compiles everything, packs it, and signs it into build/reseam/<name>.reseam. While packing, the build loads your patches once to record their names, options, and compatibility in the bundle, so code that fails when the bundle loads fails the build.
The build finds:
- the CLI at
RESEAM_BIN(or-Preseam.bin), then in the engine checkoutRESEAM_WORKSPACEnames, then on yourPATH; - the signing key at
RESEAM_BUNDLE_KEY(or-Preseam.signingKey), then~/.reseam/bundle-signing.key.
API: Gradle plugin lists every property and task.
Module build scripts
Add a build.gradle.kts to a module only to declare dependencies:
- An extension's dependencies are covered in Shipping your own code.
- A patch module uses one to depend on another bundle.
- A patch or settings module uses one to name its string table, with
reseamStrings.
Every module can use Maven Central, Google's Maven repository, and the Reseam registry.
Fingerprints
Packing gives every patch a fingerprint. Apps that patch with your bundle compare fingerprints between releases, and update only the apps whose patches changed.
A patch's fingerprint is a hash of the files your build makes from its module and from every module that module uses: its patch jar, its extensions and settings, the modules it depends on, and resources/. A release that rebuilds only one app's modules leaves every other app's fingerprints as they were. Any change that alters a module's built files counts, including a change that only moves line numbers.
The Kotlin standard library and d8's shared classes are built once for all your extensions, shrunk to what all of them use together. They count by what they are built from, the stdlib and the tools, so an extension that starts using more of the stdlib changes only its own patches' fingerprints.
The Gradle build lists the modules for packing. A bundle packed without that list counts as one module, so any change to it changes every fingerprint.
What's in a .reseam file
A ZIP archive with:
mimetype: marks the file as a Reseam bundle.manifest.toml: your bundle's name, author, and description, the engine version it was built with, every patch's metadata and fingerprint, and a SHA-256 hash of every other file.manifest.pubkeyandmanifest.sig: your public key, and its signature over the manifest. A bundle packed withunsignedBundlehas neither until it is signed.- The patch jars, the extension and settings DEX files, and
resources/.
Changing any file breaks the signature or a hash, and the bundle won't load. Your sources and build scripts aren't included.
Next: Publishing.