Wiadomości Auto app updates, a week of requests, and crypto donations

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, and license are shown to users. license is optional, and shows on your settings screen's about card.
  • format_version is 1.

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 checkout RESEAM_WORKSPACE names, then on your PATH;
  • 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:

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.pubkey and manifest.sig: your public key, and its signature over the manifest. A bundle packed with unsignedBundle has 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.

Edytuj tę stronę