You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix: Added progress bar to first time GUI download + Switched from materials icon to materials symbol + Cleaned up home screen code (MorpheApp#234)
- Added a progress bar to the initial download of the gui from the jar
file.
- Surface first run download failures instead of exiting silently. A
failed gui download or checksum mismatch used to call exitProcess(1)
behind only a log line, so a gui user just saw the app never open. It
now throws BootstrapException and shows a "Setup failed" window with the
reason and a quit button.
- Moved the material icons back to the jar file so ProGuard can
tree-shake it to just the 50 odd icons we actually use. This drops
another 36mb in size.
Copy file name to clipboardExpand all lines: README.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ All modifications made by Morphe can be found in the Git history.
30
30
1. Java Runtime Environment 21 or above ([Azul Zulu JRE](https://www.azul.com/downloads/?version=java-21-lts&package=jre#zulu), [Temurin](https://adoptium.net/temurin/releases?version=21&os=any&arch=any) or [OpenJDK](https://jdk.java.net/archive/)).
31
31
2. Morphe Desktop jar file (morphe-desktop-*-all.jar). Download the latest from [here](https://github.com/MorpheApp/morphe-desktop/releases/latest).
32
32
3. If using CLI: Patches mpp file (patches-*.mpp). Download the latest Morphe official patch files from [here](https://github.com/MorpheApp/morphe-patches/releases/latest).
33
-
4.If using CLI: Desired app file (app.apk or app.apkm). Download your apk from [APK Mirror](https://www.apkmirror.com/).
33
+
4. Desired app file (app.apk or app.apkm). Download your apk from [APK Mirror](https://www.apkmirror.com/).
34
34
5.[Optional][Android Debug Bridge (ADB)](https://developer.android.com/studio/command-line/adb) If you want to install the patched APK file to your device directly from your computer.
35
35
36
36
## Documentation
@@ -60,6 +60,9 @@ The GUI is far more user-friendly and straightforward than the CLI. On your firs
60
60
61
61
62
62
63
+
> [!NOTE]
64
+
> **First launch only.** Morphe ships as a single small jar. The command-line tool runs on its own, but the GUI needs a couple of platform-specific components (the Skiko renderer and JNA) that aren't bundled, so the download stays small. The **first** time you open the GUI, Morphe fetches the right components for your operating system into `morphe-data/libs/` and shows a brief setup window before the home screen appears. This happens only once. Later launches reuse the cached files and need no internet connection.
65
+
63
66
2. Drag and drop your `.apk` (or `.apkm` / `.xapk` / `.apks` bundle) into the window. Once it's analyzed, click **PATCH** to begin:
Copy file name to clipboardExpand all lines: docs/documentation.md
+16-2Lines changed: 16 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,17 +45,22 @@ Now that you've done your first run, let's dig deeper into how the magic happens
45
45
Morphe keeps its runtime data: cached patch files, logs, scratch space for patching, and the default signing keystore in a single **`morphe-data/`** folder. By default, this folder is created **next to the JAR** you run, so it survives upgrades and is easy to find.
46
46
If that location isn't writable (e.g. running from an IDE, or from a read-only install path), Morphe falls back to **`~/morphe/`**. The startup logs print which one is in use (look for `Morphe data root: ...`).
47
47
48
+
You can override the location entirely with the **`MORPHE_DATA_DIR`** environment variable. Point it at a writable directory and Morphe uses that as the data root, ahead of both the JAR-adjacent default and the `~/morphe/` fallback. This is meant for read-only or package-manager installs, where the JAR's own folder isn't writable and you'd rather choose the location than land in `~/morphe/`. If the path you set isn't writable, Morphe logs a warning and ignores it.
49
+
48
50
```
49
51
morphe-data/
50
52
patches/ # cached .mpp patch bundles
51
53
logs/ # application logs
52
54
tmp/ # per-run patching scratch (the default --temporary-files-path location)
55
+
libs/ # GUI runtime (Skiko, JNA) downloaded on the first GUI launch
53
56
morphe.keystore # shared default signing key (see --keystore)
54
57
config.json # preferences + configured sources
55
58
```
56
59
57
60
Both the GUI and the CLI use this folder. In the GUI you can open it from **Tools → Open App Data**. On the CLI, `--temporary-files-path` defaults to `tmp/` (override it to send scratch elsewhere) and `--keystore` defaults to `morphe.keystore` here.
58
61
62
+
The **`libs/`** folder is special: it only appears once you open the **GUI**. Morphe ships as a single small jar, and to keep that download small it does not bundle the GUI's platform-specific rendering library (Skiko) or its native-access library (JNA). The first time you launch the GUI, Morphe downloads the correct builds for your operating system and architecture from Maven Central, verifies each one by checksum, and caches them here while showing a brief setup window. The CLI needs none of these, so running from a terminal never downloads anything. Every later GUI launch reuses this cache and works offline.
63
+
59
64
> [!TIP]
60
65
> **Choosing a custom location.** If neither default suits you (for example, a package-manager install lands the JAR in a read-only, system-wide path), set the **`MORPHE_DATA_DIR`** environment variable to a writable directory. When it's set and usable, Morphe uses it as the data root ahead of everything else. If the value isn't a writable directory, Morphe logs a warning and ignores it. On Linux, if `MORPHE_DATA_DIR` is unset but `XDG_DATA_HOME` is exported, a *fallback* install uses `$XDG_DATA_HOME/morphe`. An existing `~/morphe/` folder is always kept as-is so upgrades never strand your data. Either way, the startup log line (`Morphe data root: ...`) tells you which location won.
61
66
@@ -118,6 +123,9 @@ The home screen has a top bar (on the top):
118
123
| 🟡 |**STABLE OLDER**| a stable release, but a newer one exists |
| 🩵 |**LOCAL**| a local `.mpp` file or folder source |
127
+
128
+
A **disabled** source shows a **dimmed** LED, and a source that **failed to load** shows a **red** LED and raises an error banner. Those two states take priority over the channel color.
121
129
122
130
In Expert mode, click the pill to open the **source manager** – add, remove, refresh, or reorder sources (see [Managing patch sources](#gui-expert-sources)). In Quick mode it's informational. The same LED colors appear on each row inside the source manager.
123
131
@@ -191,6 +199,8 @@ The sources Morphe fetches from are configurable: add community sources (GitHub
191
199
192
200
**Channel badge.** Each enabled source shows a small badge for the release it resolved to, color-coded by release channel, the same colors (and meanings) as the sources-pill LEDs in [The TopBar](#gui-window).
193
201
202
+
**When a source fails to load.** Morphe no longer spins forever on a source it can't fetch or parse. It stops with an error, turns that source's badge and LED **red**, and shows a banner naming the source and the reason, so you can fix or remove it while the other sources still load.
203
+
194
204
**Local sources.** A source can also be a local `.mpp` file on disk. If you're *building* patches, enable [Developer options](#gui-settings-developer) to point a source at a **folder** instead. Morphe then always loads the newest `.mpp` in it, so a rebuild is picked up without having to re-select the file.
195
205
196
206
<palign="center">
@@ -386,6 +396,7 @@ The gear icon opens Settings – Morphe's persistent preferences. Think of it as
386
396
|**Strip Libs**| Native-lib architectures to keep | Keep all |`--striplibs`|
387
397
|**Patched app runtime logs**| Capture logcat from a device after a patched app misbehaves | – | – |
388
398
|**Route links to patched app**| After an ADB install, auto-route the app's web links to it (with an optional "disable stock app's links") | Off |[`utility install --route-links`](#utility-install)|
399
+
|**Developer options**| Unlock patch-developer workflows (currently: point a local source at a folder so its newest .mpp auto-loads) | Off | – |
@@ -454,7 +465,7 @@ A debugging aid: capture logcat from a connected device after a patched app cras
454
465
455
466
This section is for people **building** patches and other developers. Off by default. Toggling it on unlocks a suite of workflow options to better assist you in your development. Please feel free to make a request in the issues tab if you feel a feature could be added here.
456
467
457
-
**Folder sources.** Normally a local source points at a single `.mpp` file. With Developer options on, the add/edit source dialog gains a **FOLDER** button next to **FILE**. Pick a folder and Morphe always loads the **newest `.mpp`** inside it. Point it at your patch build-output directory once and you never re-pick the file: each rebuild is used on the next load. The [source sheet](#gui-expert-sources) also gains a **refresh** button (top-right) that re-scans on demand, so a patch you just built shows up without leaving the screen.
468
+
**Folder sources.** Normally a local source points at a single `.mpp` file. With Developer options on, the add/edit source dialog gains a **FOLDER** button next to **FILE**. Pick a folder and Morphe always loads the **newest `.mpp`** inside it. Point it at your patch build-output directory once and you never re-pick the file: each rebuild is used on the next load. The [source sheet](#gui-expert-sources) also gains a **refresh** button (top-right) that re-scans on demand, so a patch you just built shows up without leaving the screen. Build outputs like `*-sources.mpp` and `*-javadoc.mpp` are always ignored, and you can set your own exclude patterns for a folder source from the source manager.
458
469
459
470
> [!NOTE]
460
471
> Existing folder sources keep working even if you later turn Developer options back off. The toggle only gates *creating* them.
@@ -470,7 +481,7 @@ The wrench icon opens Tools – one-off actions and reference info, kept out of
470
481
|**OPEN APP DATA**| Open Morphe's data folder – the`morphe-data/` directory (see [Where Morphe stores its files](#where-files-stored)) |
471
482
|**CLEAR CACHE**| Delete downloaded patches and logs (they re-download as needed) |
472
483
|**VIEW LICENSES**| Browse the open-source licenses of Morphe's dependencies |
473
-
| Version | The running app version is shown at the bottom |
484
+
| Version | The running app version, plus the bundled **Morphe Patcher** and **Morphe Library** versions, are shown at the bottom |
@@ -665,6 +676,9 @@ Default: a subfolder named after the app, created next to the input APK – `<ap
665
676
666
677
Specify a custom output path for the patched APK.
667
678
679
+
> [!NOTE]
680
+
> `<appVersion>` in the default name is read from the APK's manifest (`versionName`). Patching two different versions of the same app therefore produces two differently-named files instead of overwriting each other, even when the input files happen to share a name (for example both called `base.apk`).
0 commit comments