Building the app
Local Desktop is one Rust crate, plus a few Java classes, packaged into an APK with a patched version of xbuild. This page shows how to build it on a computer, in Docker, or on your phone.
What you need
- Rust, with the Android target:
rustup target add aarch64-linux-android - JDK 17 and Gradle 8, since xbuild uses Gradle to compile the Java code and package the APK
- The Android SDK. xbuild downloads the NDK it needs by itself.
If you use VS Code or Cursor, the Local Desktop Dev extension has a Doctor that checks all of this for you and tells you what's missing.
Build
-
Clone the repository:
git clone https://github.com/localdesktop/localdesktop.github.io.git
cd localdesktop.github.io -
Install our patched xbuild. It adds Android services, Java sources and a few other things that upstream xbuild doesn't support yet (see Patching dependencies):
cargo install --path patches/xbuild/xbuild --forceThis installs the
xcommand. Use--forceso that an olderxgets replaced when the patch changes. -
Build a debug APK:
x build --platform android --arch arm64 --format apkOr a release APK:
x build --release --platform android --arch arm64 --format apk
The APKs are in:
| Build | APK |
|---|---|
| Debug | target/x/debug/android/gradle/app/build/outputs/apk/debug/app-debug.apk |
| Release | target/x/release/android/gradle/app/build/outputs/apk/release/app-release.apk |
For a debug build, the unstripped .so files (with symbols, for a debugger or a crash report) are in target/x/debug/android/gradle/app/src/main/jniLibs/arm64-v8a/.
Install it with adb install -r <apk>. Only arm64 devices are supported.
If adb install fails with a signature mismatch (for example, a debug build over a release from GitHub), don't uninstall the app unless you are ready to lose its data. Uninstalling deletes Arch Linux and everything in it.
With make or Docker
The Makefile has two shortcuts:
make buildinstalls the patched xbuild and builds a release APK.make build-dockerbuilds inside Docker (Android SDK 30, JDK 17, Gradle 8 and Rust are set up in theDockerfile), then copiestarget/back to your machine. Use it if you don't want to install the toolchain.
Release builds
You don't build releases yourself: GitHub Actions builds and signs them from the label on your pull request. See Contributing.
FAQ
Can I test a release-signed APK from a PR?
Yes, see Contributing.
Can I build on Termux?
Yes, right on your phone. See Anyone Can Code for the whole story.
For the simplest path, install Rust in Termux and run:
pkg i rust
cargo run
This uses our own small APK builder (src/bin/build_apk.rs) instead of xbuild and Gradle, and writes localdesktop.apk in the project root. It packages the prebuilt src/android/dex/classes.dex instead of compiling the Java code, so if you change a .java file, rebuild the dex first (see src/android/dex/README.md).
If you want the same patched xbuild pipeline as CI, run:
bash scripts/build-termux.sh
It installs the Termux packages it needs (Rust, OpenJDK 17, Gradle, the NDK and aapt2), sets up the SDK, then builds a release APK at target/x/release/android/gradle/app/build/outputs/apk/release/app-release.apk.
Can I build inside Local Desktop, or Termux + proot-distro?
Not easily. The cargo run builder only runs on Android itself (Termux), not inside a Linux distro. The xbuild pipeline needs the Android SDK, and Google doesn't publish its build tools for ARM64 Linux. Use Termux on the same phone instead, it's the path we test.