doc: Guide for migrating patches code from ReVanced to Morphe

[LisoUseInAIKyrios]

Instructions to migrate your patches codebase from ReVanced to Morphe:

Required project changes:

Rebase your patches off the morphe-patches-template repo (if you forked it), or manually apply the following changes to your repo:

libs.versions.toml

morphe-patcher = "1.3.2"
smali = "b6365a84f4"

settings.gradle.kts

pluginManagement {
    repositories {
        mavenLocal()
        gradlePluginPortal()
        google()
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/MorpheApp/registry")
            credentials {
                username = providers.gradleProperty("gpr.user").getOrElse(System.getenv("GITHUB_ACTOR"))
                password = providers.gradleProperty("gpr.key").getOrElse(System.getenv("GITHUB_TOKEN"))
            }
        }
        maven { url = uri("https://jitpack.io") }
    }
}

plugins {
    id("app.morphe.patches") version "1.2.0"
}

Required patch code changes

1. Change all patcher class imports from app.revanced.* to app.morphe.*
2. Change iterating using ProxyClassList.forEach{} to classDefForEach()
3. Change class lookup using ProxyClassList.find{} to classDefBy(classDef) or mutableClassDefBy(classDef)
4. Change proxy(classDef).mutableClass to mutableClassDefBy(classDef)
5. Fuzzy pattern scan is no longer supported. Either change to instruction filters or update the opcode pattern one last time and remove fuzzy.
6. Replace patternMatch.firstIndex -> instructionMatches.first().index and patternMatch.lastIndex -> instructionMatches.last().index
7. Update extension hook if needed.

Optional patch code changes

1. Change from DSL fingerprints to object fingerprints so exception stack traces show fingerprint class names (recommended but not required). Migrate DSL fingerprint opcodes { Opcode... } to class parameter filters = OpcodesFilter.opcodesToFilters(Opcode...)
2. Read the patcher guide on how to start using instruction filters.

Other changes

Update/rename the repo patch name to use a supplemental description of "Compatible with Morphe" or "XYZ patches for Morphe". See template repo for exact details.

 

Getting your patches into Morphe Manager

The template repo is setup to automatically create patches-bundle.json when creating releases. See other notes and setup steps in the patches template repo: https://github.com/morpheapp/morphe-patches-template

 

Motivation

Because developers want the best!

[LisoUseInAIKyrios]

If anyone encounters additional changes they needed to make, or any part of the instruction filter guide could be improved, then please leave a comment here.

[wchill]

Extension hooks that made use of the extensionHook utility methods here need to be modified. For example, activityOnCreateExtensionHook can be used.

[LisoUseInAIKyrios]

Template patch bundle generation is basically ready. See here: MorpheApp/morphe-patches-template#2

[wchill]

Fingerprint::patternMatch no longer exists, so migrating to instruction filters is required for patches that use it.

[LisoUseInAIKyrios]

Previously there was a depreciated wrapper method to access the pattern match indexes.

You can get the same by replacing:

patternMatch.startIndex
with
instructionMatches.first().index

patternMatch.endIndex
with
instructionMatches.last().index

[wchill]

are instructionMatches.last().index and instructionMatches.lastIndex equivalent? Was trying to wrap my head around this and came up with the latter one instead.

[LisoUseInAIKyrios]

The old opcode based fingerprints will still work and the easiest migration is to keep using them until they break or you need to dramatically change a patch, and then upgrade them to filters.

[LisoUseInAIKyrios]

are instructionMatches.last().index and instructionMatches.lastIndex equivalent? Was trying to wrap my head around this and came up with the latter one instead.

filters = OpcodesFilter.opcodesToFilters(Opcode...)

Is a list of opcode filters, where each opcode must appear exactly after the previous.

So (first match index) + (number of opcodes) = (last match index).

[LisoUseInAIKyrios]

Oh I mis read what you asked.

instructionMatches.lastIndex is the index of the matches in the list (kotlin).
It's not what is needed.

instructionMatches.last() is the match object, which has the instruction that matched and some helper methods and the index of that instruction. instructionMatches.last().index is what is wanted.

[wchill]

The updated fingerprinting doc doesn't talk about this, but it might be good to note, because I just ran into this - adding a string filter is a very different operation from passing a string to the fingerprint constructor. The fingerprinting documentation doesn't mention the strings parameter at all, so I thought that strings had to be defined using filters only.

[wchill]

How should use of fuzzyPatternScanThreshold in the old fingerprint API be handled? Do the existing opcode filters handle this already?

Edit: InstructionLocation.MatchAfterWithin(fuzzyDistance) technically works but the fuzzy threshold isn't added up across all instructions. Not sure if there is a good way to handle this cleanly.

[LisoUseInAIKyrios]

Fuzzy pattern scan functionality was removed.

It wasn't used by ReVanced patches anymore and from experience it never worked well because it could not handle if single opcodes were removed or added.

Any fingerprints that utilized fuzzy would need to be re-wrote, usually by picking out the method/field raw opcodes and replacing with fieldAccess/methodCall and other more specific filters, then ignore the junk opcodes such as move register unless the patch code needs the index. And yes, then use MatchAfterWithin to control matching to a general region after the previous filter.

[wchill]

It turned out that the patch that I was looking at didn't need it anymore, so I removed it. But good to know. This is still something worth documenting