Skip to content

Commit f3d287f

Browse files
SaicharanKandukuriSaicharanKandukuri
committed
docs: add user-focused project guides
Simplify the public README, add an everyday user guide, move build and release details into developer documentation, and remove the inactive container-image documentation.
1 parent 1381404 commit f3d287f

6 files changed

Lines changed: 261 additions & 300 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -12,132 +12,43 @@ supervised way to install and use Linux distributions on Android.
1212

1313
## Download and install
1414

15-
[Download uDroid from GitHub Releases](https://github.com/RandomCoderOrg/udroid-app/releases),
16-
open the newest prerelease, and select its `.apk` file. Android may ask you to
17-
allow installs from the browser or file manager you used.
18-
19-
Existing stable-signed builds can also download and verify newer releases from
20-
the app's **About** page.
21-
22-
## Current feature support
23-
24-
| Area | What is supported |
25-
| --- | --- |
26-
| Linux installation | Search uDroid and PRoot-Distro archives, review the download size, resume transfers, verify SHA-256 digests, and retain validated data across retries. |
27-
| Multiple systems | Keep multiple distributions installed. Selecting an installed system opens its own status and controls page instead of immediately starting a terminal. |
28-
| Terminal | Use the bundled Termux terminal emulator and persistent, service-owned PTY without installing Termux separately. Each terminal action targets the selected rootfs. |
29-
| Linux applications | Discover freedesktop `.desktop` entries, launch graphical or terminal applications, publish dynamic shortcuts, and pin selected applications to the Android home screen. |
30-
| Embedded X11 | Use the bundled Termux:X11 server and uDroid display surface without installing the separate Termux:X11 application. Keyboard, direct-pointer, trackpad-style, native multi-touch, and display settings are available inside uDroid. |
31-
| Desktop environments | Detect installed X11 sessions from standard `xsessions` directories. Start, stop, or restart the selected desktop while uDroid reports which rootfs and desktop own `DISPLAY :0`. |
32-
| Compositing | Enable or disable compositing for supported XFCE, Plasma, and MATE sessions, then apply the setting through a supervised desktop restart. GNOME is treated as compositor-required. |
33-
| Audio | Play Linux audio through Android with an app-owned PulseAudio/OpenSL ES bridge. Enable microphone input per Linux system with Android runtime consent; guest traffic stays on authenticated device-local loopback. |
34-
35-
### Current limitations
36-
37-
- uDroid currently supervises one active Linux runtime and one X11 display,
38-
`DISPLAY :0`, at a time. Multiple distributions can remain installed, but
39-
their live desktop sessions are not concurrent.
40-
- Desktop lifecycle support currently targets X11 sessions advertised through
41-
`/usr/share/xsessions` or `/usr/local/share/xsessions`. Wayland sessions are
42-
not launched.
43-
- Compositor control is desktop-specific. LXQt and unknown/custom sessions are
44-
still launchable, but uDroid does not guess at a compositor switch when no
45-
safe standard adapter is known.
46-
- PRoot provides the Linux userspace. It is not a virtual machine, does not
47-
provide a normal systemd/logind boot, and cannot reproduce every native Linux
48-
service or sandbox boundary.
49-
- The embedded display is functional, but general-purpose GPU acceleration is
50-
not yet a supported app contract. Desktop responsiveness depends on the
51-
device, resolution, applications, and compositor choice.
52-
- Background desktop recovery, multiple displays, and production-level desktop
53-
compatibility remain incomplete. Audio currently targets PulseAudio clients;
54-
direct ALSA-only applications may require a PulseAudio compatibility plugin.
55-
56-
See the [distribution catalogue](docs/DISTRIBUTION_CATALOGUE.md),
57-
[Linux application launcher](docs/LINUX_APPLICATION_LAUNCHER.md),
58-
[X11 runtime architecture](docs/X11_RUNTIME_ARCHITECTURE.md),
59-
[audio runtime](docs/AUDIO_RUNTIME.md),
60-
[performance notes](docs/PERFORMANCE.md), and
61-
[app updates](docs/APP_UPDATES.md) for current behavior and technical details.
62-
63-
## Development releases
64-
65-
Git tags matching `v*` are built by GitHub Actions. Each resulting prerelease
66-
contains:
67-
68-
- one universal, optimized APK covering `arm64-v8a`, `armeabi-v7a`, and
69-
`x86_64`, signed with the persistent project update key;
70-
- `SHA256SUMS` for verifying the downloaded APK;
71-
- GitHub's source archives, including the vendored Termux terminal components
72-
and the corresponding third-party notices.
73-
74-
Pull requests and non-tag workflow runs publish a separate optimized
75-
`uDroid Dev` APK for 30 days. It uses the `org.randomcoder.udroid.dev`
76-
application ID and the Android debug key, so it can be installed beside the
77-
update-signed app without replacing it. PR artifacts are named with the pull
78-
request number and head commit, for example `udroid-pr-24-cf9c1ed-dev.apk`.
79-
They are test artifacts and cannot update either the official app or another
80-
machine's debug build.
81-
82-
The published `v0.0.2` APK predates stable update signing and retains its
83-
original debug asset name. It is a development build, not a Play Store or
84-
production-signed release:
85-
86-
```sh
87-
adb install -r udroid-v0.0.2-debug.apk
88-
```
89-
90-
Tagged releases after this updater checkpoint require these GitHub Actions
91-
secrets:
92-
93-
- `UDROID_SIGNING_STORE_BASE64`
94-
- `UDROID_SIGNING_STORE_PASSWORD`
95-
- `UDROID_SIGNING_KEY_ALIAS`
96-
- `UDROID_SIGNING_KEY_PASSWORD`
97-
98-
The first stable-signed development release cannot replace the older
99-
ephemeral-debug-signed APK in place. Existing testers must uninstall and
100-
install that release once; subsequent releases signed by the same key can use
101-
the in-app updater.
102-
103-
## Build
104-
105-
Requirements:
106-
107-
- JDK 17 or newer
108-
- Android SDK platform 36
109-
- Android NDK 28.2 (the probes also build with NDK 26+)
110-
111-
```sh
112-
export ANDROID_HOME="$HOME/Library/Android/sdk"
113-
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/28.2.13676358"
114-
./app/src/main/cpp/build-runtime-probe.sh
115-
./tools/build-proot-assets.sh
116-
./tools/build-gnu-tar-assets.sh
117-
./tools/build-pulseaudio-assets.sh
118-
./gradlew :app:assembleRelease
119-
```
120-
121-
The app targets API 36. On Android 10 and newer it launches packaged Android
122-
ELFs through `/system/bin/linker(64)`. PRoot's static guest loader is installed
123-
as an extracted APK native library so its second execution hop is not blocked
124-
by Android's writable-app-data execution policy.
125-
126-
UI performance is measured from optimized builds with device Macrobenchmarks,
127-
Perfetto traces, and generated Baseline Profiles. See
128-
[Performance](docs/PERFORMANCE.md) for the commands and current catalogue
129-
results.
130-
131-
## Licensing
132-
133-
The uDroid-owned Android shell is MIT-licensed, matching
134-
`fs-manager-udroid`. Packaged PRoot is GPL-2.0 and statically links talloc,
135-
whose library is LGPL-3.0-or-later. The rootfs installer also packages GNU tar
136-
and Termux's BSD-licensed libandroid-glob implementation. The vendored Termux
137-
terminal emulator and view are the Apache-2.0 components identified by
138-
Termux's upstream license exception. The embedded Termux:X11 module is GPLv3,
139-
so APKs containing it are distributed as GPLv3 combined works. Exact source
140-
versions, checksums, local changes, and build commands are recorded in
141-
`tools/` and `third_party/`; binary releases must also provide the applicable
142-
corresponding source and license texts. See
143-
[Third-party notices](THIRD_PARTY_NOTICES.md).
15+
1. Download the newest `.apk` from
16+
[GitHub Releases](https://github.com/RandomCoderOrg/udroid-app/releases).
17+
2. Open it and approve the installation.
18+
19+
Android may ask you to allow installs from your browser or file manager. Once
20+
installed, uDroid can check for updates from **About**.
21+
22+
## Feature support
23+
24+
- Install Linux images from uDroid and PRoot-Distro.
25+
- Keep and manage multiple Linux systems.
26+
- Use a built-in, persistent terminal.
27+
- Launch X11 desktops and installed Linux apps.
28+
- Use touch, mouse, keyboard, and multi-touch input.
29+
- Play audio and optionally use the microphone.
30+
- Configure mounts and environment variables per system.
31+
- Check for updates and copy diagnostic logs.
32+
33+
## Limitations
34+
35+
- One Linux system and one X11 display can run at a time.
36+
- Wayland sessions are not supported yet.
37+
- PRoot is not a virtual machine and cannot grant real root privileges. Docker,
38+
LXC, Flatpak, Snap, and tools that need privileged mounts, namespaces, or
39+
device access may not work.
40+
- Graphics acceleration is experimental and device-dependent.
41+
- Desktop integration varies between environments.
42+
43+
## Documentation
44+
45+
User guide: [Using uDroid](docs/USER_GUIDE.md).
46+
47+
Developer reference: [builds and releases](docs/DEVELOPMENT.md),
48+
[product scope](docs/PRODUCT_SCOPE.md), [Linux systems](docs/DISTRIBUTION_CATALOGUE.md),
49+
[Linux apps](docs/LINUX_APPLICATION_LAUNCHER.md),
50+
[desktop](docs/X11_RUNTIME_ARCHITECTURE.md), [audio](docs/AUDIO_RUNTIME.md),
51+
[updates](docs/APP_UPDATES.md), and [performance](docs/PERFORMANCE.md).
52+
53+
Licensing: [MIT license](LICENSE) and
54+
[third-party notices](THIRD_PARTY_NOTICES.md).

‎docs/APP_UPDATES.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@ Redirects may remain on HTTPS but cannot downgrade to cleartext HTTP.
4949

5050
Android updates must use the same signing certificate as the installed app.
5151
Tagged CI builds therefore fail closed unless the four update-signing secrets
52-
listed in the README are configured. Normal branch and pull-request builds can
52+
listed in [Development](DEVELOPMENT.md) are configured. Normal branch and
53+
pull-request builds can
5354
continue using Android's local debug key because they are not published as
5455
updates.
5556

‎docs/DEVELOPMENT.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Development
2+
3+
## CI builds and releases
4+
5+
Git tags matching `v*` are built by GitHub Actions. Each prerelease contains:
6+
7+
- one universal, optimized APK for `arm64-v8a`, `armeabi-v7a`, and `x86_64`,
8+
signed with the project update key;
9+
- `SHA256SUMS` for the APK;
10+
- GitHub source archives with vendored Termux components and third-party
11+
notices.
12+
13+
Pull requests and non-tag workflow runs publish an optimized `uDroid Dev` APK
14+
for 30 days. It uses the `org.randomcoder.udroid.dev` application ID and the
15+
Android debug key, so it can be installed beside the update-signed app. PR
16+
artifacts include the pull request number and head commit, for example
17+
`udroid-pr-24-cf9c1ed-dev.apk`. These artifacts cannot update the official app
18+
or a debug build signed on another machine.
19+
20+
The published `v0.0.2` APK predates stable update signing and retains its
21+
original debug asset name:
22+
23+
```sh
24+
adb install -r udroid-v0.0.2-debug.apk
25+
```
26+
27+
Tagged releases require these GitHub Actions secrets:
28+
29+
- `UDROID_SIGNING_STORE_BASE64`
30+
- `UDROID_SIGNING_STORE_PASSWORD`
31+
- `UDROID_SIGNING_KEY_ALIAS`
32+
- `UDROID_SIGNING_KEY_PASSWORD`
33+
34+
The first stable-signed build cannot replace an older ephemeral-debug-signed
35+
APK. Testers must reinstall once; later builds signed with the same key can use
36+
the in-app updater.
37+
38+
## Build locally
39+
40+
Requirements:
41+
42+
- JDK 17 or newer
43+
- Android SDK platform 36
44+
- Android NDK 28.2 (runtime probes also build with NDK 26 or newer)
45+
46+
```sh
47+
export ANDROID_HOME="$HOME/Library/Android/sdk"
48+
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/28.2.13676358"
49+
./app/src/main/cpp/build-runtime-probe.sh
50+
./tools/build-proot-assets.sh
51+
./tools/build-gnu-tar-assets.sh
52+
./tools/build-pulseaudio-assets.sh
53+
./gradlew :app:assembleRelease
54+
```
55+
56+
The app targets API 36. On Android 10 and newer it launches packaged Android
57+
ELFs through `/system/bin/linker(64)`. PRoot's static guest loader is installed
58+
as an extracted APK native library so Android can execute its second hop.
59+
60+
UI performance is measured from optimized builds with device Macrobenchmarks,
61+
Perfetto traces, and generated Baseline Profiles. See
62+
[Performance](PERFORMANCE.md) for commands and current results.
63+
64+
## Licensing and redistribution
65+
66+
The uDroid-owned Android shell is MIT-licensed, matching `fs-manager-udroid`.
67+
Packaged PRoot is GPL-2.0 and statically links LGPL-3.0-or-later talloc. The
68+
rootfs installer packages GNU tar and Termux's BSD-licensed libandroid-glob.
69+
The vendored Termux terminal components use Apache-2.0 under Termux's upstream
70+
license exception. The embedded Termux:X11 module is GPLv3, so APKs containing
71+
it are distributed as GPLv3 combined works.
72+
73+
Exact source versions, checksums, patches, and build commands are recorded in
74+
`tools/` and `third_party/`. Binary releases must provide the applicable source
75+
and license texts. See the repository [license](../LICENSE) and
76+
[third-party notices](../THIRD_PARTY_NOTICES.md).

‎docs/DISTRIBUTION_CATALOGUE.md‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -41,21 +41,6 @@ was marked broken on Android 15 and newer. An image is not shown merely because
4141
an archive exists; its architecture, checksum, extraction layout, and PRoot
4242
startup must be understood first.
4343

44-
## Official container images
45-
46-
The same searchable list also includes active operating-system repositories
47-
from Docker Hub's official `library` namespace. Selecting one opens a version
48-
page containing only tags that publish an image for the phone's OCI platform.
49-
The review page records the selected platform, compressed size, tag, and
50-
immutable manifest digest before installation begins.
51-
52-
Container images follow a separate verified OCI pipeline; they are not passed
53-
to Docker, containerd, or a daemon. uDroid resolves the manifest, downloads and
54-
verifies each referenced blob, applies ordered filesystem layers and OCI
55-
whiteouts in app-private staging storage, adds Android/PRoot compatibility
56-
files, executes the standard rootfs health probe, and only then activates the
57-
installation. See [OCI image architecture](OCI_IMAGES.md).
58-
5944
## Visual identity
6045

6146
Distribution marks are packaged VectorDrawables derived from the Simple Icons

0 commit comments

Comments
 (0)