Novidade Auto app updates, a week of requests, and crypto donations

Writing patches

API: Patches

Everything here is in app.reseam.patch. The other API pages cover targets and points, code blocks, the manifest, resources, and files, settings, Hermes, raw bytecode, the app runtime your extensions call, and the Gradle plugin.

Wherever a parameter is a type written as a String, you can pass a descriptor (Ljava/lang/String;), a dotted name (java.lang.String), or a Type constant.

Declaring a patch

patch

Function Description
patch(name: StringRef, block: PatchBuilder.() -> Unit): ReseamPatch A patch users see, under name, a string from the module's string table. The name doesn't have to be unique. See Names in every language.
patch(block: PatchBuilder.() -> Unit): ReseamPatch An internal patch. Users never see it, and it only runs when a patch that runs depends on it.

Assign the result to a public top-level val. The engine finds patches by their declarations, and the patch's ID is the declaration's package.property.

PatchDeclaration

What every patch declaration can say: which apps it is for and what it needs. PatchBuilder and the settings host builder extend it.

Member Description
compatibleWith(vararg packageNames: String) The patch is for these packages, any version.
compatibleWith(vararg packages: CompatiblePackage) The patch is for these packages, limited to the versions each one lists.
dependsOn(vararg patches: ReseamPatch) These patches run first. If one of them is skipped or fails, this patch is skipped.

A patch with no compatibleWith works on any app. See Which apps.

PatchBuilder

The receiver of patch { }.

Member Description
description(text: StringRef) The text users see under the name, from the module's string table.
enabledByDefault(value: Boolean) Whether the patch starts selected. A patch for specific apps defaults to true, a patch for any app to false.
hidden() Keeps a named patch off the lists users see. It still runs when selected or needed as a dependency.
stringOption(key, title: StringRef, description: StringRef? = null, default: String? = null, validValues: List<String>? = null, required = false): StringOption Declares a text option. With validValues, the user picks one of them.
boolOption(key, title: StringRef, description: StringRef? = null, default: Boolean? = null, required = false): BoolOption Declares an on/off option.
intOption(key, title: StringRef, description: StringRef? = null, default: Long? = null, required = false): IntOption Declares a whole-number option.
floatOption(key, title: StringRef, description: StringRef? = null, default: Double? = null, required = false): FloatOption Declares a decimal option.
stringListOption(key, title: StringRef, description: StringRef? = null, default: List<String>? = null, required = false): StringListOption Declares a list-of-text option.
pathOption(key, title: StringRef, description: StringRef? = null, required = false): PathOption Declares a folder the user picks. It has no default.
settings(host: SettingsHost, vararg sections: SettingsSection) Adds these sections to the app's settings screen. host becomes a dependency.
settings(host: SettingsHost, sections: PatchRuntime.() -> List<SettingsSection>) The same, with sections computed after execute, so they can depend on options.
execute(block: PatchRuntime.() -> Unit) The change itself. It runs once all dependencies have run.
afterDependents(block: PatchRuntime.() -> Unit) Runs after every patch that depends on this one has finished.
afterWrite(block: OutputRuntime.() -> Unit) Runs on the written APK files, before they are signed.

When each block runs explains the three blocks.

ReseamPatch

What patch returns, and what the engine reads. You use the value to name a dependency or a settings host. You don't implement this interface.

Member Description
name: StringRef? The display name, or null for an internal patch.
hidden: Boolean Whether the patch is kept off the lists.
description: StringRef? The description, or null for none.
dependencies: List<ReseamPatch> The patches it depends on.
compatibleWith: List<CompatiblePackage> The packages it is for. Empty for a patch that works on any app.
universal: Boolean True when the patch declares no package.
enabled: Boolean Whether it starts selected.
options: List<Option<*>> Its options, in declaration order.
execute(ctx: PatchRuntime) Runs the execute block.
afterDependents(ctx: PatchRuntime) Runs the afterDependents block.
finalizes: Boolean Whether the patch has an afterDependents block. The engine only calls it when this is set.
afterWrite(ctx: OutputRuntime) Runs the afterWrite block.
rewritesOutput: Boolean Whether the patch has an afterWrite block. Mount builds and the browser patcher leave such patches out.

CompatiblePackage

One app a patch is for, optionally limited to some versions.

Member Description
CompatiblePackage(name: String, versions: List<String> = emptyList(), versionCodes: List<Int> = emptyList()) An APK matches when its version name is in versions or its version code is in versionCodes. With both empty, every version matches.
name: String The package name.
versions: List<String> Version names.
versionCodes: List<Int> android:versionCode values.

Two shortcuts build one from a package name:

Function Description
String.invoke(vararg versions: String): CompatiblePackage "com.example.app"("2.14.0", "2.14.1"): these version names.
String.invoke(versionName: String, versionCode: Int): CompatiblePackage "com.example.app"("2.14.0", 214001): one version, matched by its name or its code.

ExternalPatch

A patch from another bundle, for dependsOn. The Gradle plugin generates one value per patch of every bundle your module declares with reseam { bundle(...) }. You never construct one yourself.

Member Description
bundle: String The other bundle's name.
id: String The patch's ID in that bundle.

The rest of its members are those of ReseamPatch. The engine runs the real patch from the other bundle, which users must also load.

Options

Option

The base of every option type. options[option] reads its value.

Member Description
key: String The key users set it by, for example --option "Clone app.packageName=..." on the CLI.
title: StringRef The label users see.
description: StringRef? Help text users see, or null for none.
required: Boolean Whether patching refuses to start without a value.
kind: OptionKind The value's type.
default: T? The value when the user sets none.
validValues: List<String>? The values a text option allows, or null for any.

The subclasses fix the value type: StringOption (String), BoolOption (Boolean), IntOption (Long), FloatOption (Double), StringListOption (List<String>), and PathOption (OptionPath). The PatchBuilder functions above create them.

StringOption

A text option, read as String.

BoolOption

An on/off option, read as Boolean.

IntOption

A whole-number option, read as Long.

FloatOption

A decimal option, read as Double.

StringListOption

A list-of-text option, read as List<String>. On the CLI, repeat --option once per item.

PathOption

A folder the user picks, read as OptionPath.

OptionKind

STRING, BOOL, INT, FLOAT, STRING_LIST, or PATH.

OptionPath

The folder a user picked for a PathOption.

Member Description
path: String The folder's path on the device or computer doing the patching.
listContents(): List<String> The names of the files in the folder, sorted.
readFile(relativePath: String): ByteArray? A file inside the folder. A path that leads outside the folder fails.

RuntimeOptions

The options of a running patch.

Member Description
get(option: Option<T>): T options[option]: the value, with the default filled in. Fails when the option is optional, has no default, and the user set nothing.
getOrNull(option: Option<T>): T? The value, or null when there is none.

Before patching starts, the engine checks each value against its option: the type, the allowed values of a text option, and that a path exists. A patch only ever sees valid values.

While a patch runs

PatchRuntime

The receiver of execute { } and afterDependents { }.

Member Description
manifest: ManifestScope The manifest.
resources: ResourceScope The resources.
files: FileScope Any file in the APK.
bytecode: BytecodeScope Every class, for lookups and app-wide changes.
hermes: HermesScope The app's Hermes bundle.
options: RuntimeOptions This patch's option values.
log: PatchLogger Messages in the patch log.
explain(target: Target<*>): MatchReport Why a target resolved the way it did.

OutputRuntime

The receiver of afterWrite { }. The patched app has been written by then, so only the files, the bundle, and the options are left.

Member Description
output: OutputFiles The written base APK.
options: RuntimeOptions This patch's option values.
log: PatchLogger Messages in the patch log.
bundleFile(path: String): File A file shipped in your bundle, at the path files.copy takes.
tempFile(name: String): File A path for a new file, in a folder the engine deletes after the run. It is on the same disk as the output, so output.replace can move it.

OutputFiles

One written APK, unsigned.

Member Description
file: File The APK file. Read it, but don't write to it. Use replace instead.
replace(replacement: File) Moves replacement over this APK. The engine signs whatever file is in place at the end.
components(): List<String> The names of every written APK, the same names files.components() lists.
component(name: String): OutputFiles Another written APK, such as a split.

PatchLogger

Member Description
info(message: String) A message users see in the patch log.
warn(message: String) A warning in the patch log.
debug(message: String) A message shown only when debug logging is on.

RunList

Values that the patches of one run collect for another patch to use. A typical use is hooks that dependents register and a shared patch emits in its afterDependents.

Use a RunList instead of a top-level mutable list. A plain list outlives the run, and keeps values from a patch that failed and was undone. A RunList starts empty on every run, and drops the values of an undone patch.

private val hooks = RunList<ExtMethod>()

fun registerHook(hook: ExtMethod) = hooks.add(hook)

val hookOwner = patch {
    afterDependents { hooks.values.forEach { hook -> dispatch.before { call(hook) } } }
}
Member Description
RunList<T>() An empty list. Declare it as a top-level value.
add(value: T) Adds a value for the rest of the run. Only works while a patch is running.
values: List<T> What the run has collected so far, in the order it was added.

Targets and reports

Target

The base of every target: something a patch looks for. A target is searched for the first time a patch uses it, and the result is kept for the rest of that patch. The next patch searches again.

Member Description
debugName: String? The label used in errors and reports.
explain(): MatchReport Why the target resolved as it did. Only works while a patch is running.

API: Targets and points lists the kinds of target.

MatchReport

Member Description
name: String The target's label.
winner: String The method, class, or field it picked.
considered: Int How many candidates the search looked at.
reasons: List<String> What the query matched on.
nearMisses: List<String> The closest candidates that didn't match, each with the reason.

Types

Type

Descriptors for the types patches name most: Void, Boolean, Byte, Short, Char, Int, Long, Float, Double, Object, String, CharSequence, List, ArrayList, Map, Context, View, Activity, and Application.

Type helpers

Function Description
descriptor(type: String): String Any accepted form of a type as a descriptor: descriptor("java.lang.String") is "Ljava/lang/String;".
className(descriptor: String): String A class descriptor as a dotted name.
proto(returns: String, vararg params: String): String A method prototype: proto(Type.Boolean, Type.String) is "(Ljava/lang/String;)Z".
Editar esta página