+ 
@@ -15,7 +16,7 @@
client for retro handhelds: send and receive files with your phone
or PC over Wi-Fi, no cable or SSH. Compatible with the official LocalSend apps.
-It targets [PortMaster-compatible](https://portmaster.games/supported-devices.html) Linux handhelds and the Miyoo Mini Plus and Flip running OnionOS, both of which are gamepad-only systems without a compositor. It also runs on regular desktop Linux too.
+It targets [PortMaster-compatible](https://portmaster.games/supported-devices.html) Linux handhelds and the Miyoo Mini Plus and Flip running OnionOS, both of which are gamepad-only systems without a compositor. It also runs on regular desktop Linux and on Android handhelds and phones too.
| Receive | Request | Save | Transfer |
|:---:|:---:|:---:|:---:|
@@ -60,6 +61,18 @@ The zip carries an SDL2 built for the Miyoo's panel and a launcher that asks for
the software renderer, since the SSD202D has no GPU at all. What ships inside it,
in full: [onionos/App/Retsend/lib/README.md](onionos/App/Retsend/lib/README.md).
+## Install (Android)
+
+Grab `retsend-android-arm64.apk` from
+[Releases](https://github.com/mxmgorin/retsend/releases) and sideload it. Same
+app, driven by touch or by a pad, with the system Back button as B: tap a device
+to send to it, a file to pick it, a row to open it, and the button hints along
+the bottom are themselves the buttons.
+
+Grant **All files access** when it asks and received files land in `Download/`,
+where an emulator or file manager can reach them; deny it and the app is confined
+to its own folder. See [android/README.md](android/README.md).
+
## Building & running (desktop)
System SDL2 is the only native dependency. On Debian/Ubuntu:
@@ -86,6 +99,20 @@ Tests are headless (no SDL, no network setup needed):
cargo test
```
+### Building the APK
+
+With the Android SDK and an NDK installed:
+
+```sh
+rustup target add aarch64-linux-android
+cargo install cargo-ndk --locked
+./android/scripts/build.sh release # android/app/build/outputs/apk/release/app-release.apk
+```
+
+It builds `libSDL2.so` on the first run, cross-compiles the Rust cdylib SDL loads,
+and assembles the APK — see [android/README.md](android/README.md) for how the
+port fits together.
+
## Controls
Touch works too, where there is a touchscreen: tap a row to act on it, or tap a
@@ -114,10 +141,10 @@ Settings screen edits everything in it except:
- `[transfer] pinned_paths`, `last_send_dir` — written by Y and by sending
Environment variables override paths and control logging at launch:
-`RETSEND_DATA_DIR`, `RETSEND_CONFIG`, `RETSEND_SAVE_DIR`, `RETSEND_SCALE`,
-`RETSEND_GLES=0|1`, `RETSEND_SOFTWARE=1`, `RETSEND_BLIT=1`,
-`RETSEND_KEYMAP=miyoo|desktop`, `RETSEND_LOG_LEVEL`, `RETSEND_LOG_FILE`,
-`RETSEND_PANIC_FILE`.
+`RETSEND_DATA_DIR`, `RETSEND_CONFIG`, `RETSEND_SAVE_DIR`, `RETSEND_BROWSER_ROOTS`
+(`:`-separated), `RETSEND_ALIAS`, `RETSEND_SCALE`, `RETSEND_GLES=0|1`,
+`RETSEND_SOFTWARE=1`, `RETSEND_BLIT=1`, `RETSEND_KEYMAP=miyoo|desktop`,
+`RETSEND_LOG_LEVEL`, `RETSEND_LOG_FILE`, `RETSEND_PANIC_FILE`.
`RETSEND_BLIT=1` rasterizes the UI offscreen and presents it as a single texture
copy per frame, for drivers that show nothing else — the Miyoo Mini's panel driver
diff --git a/android/.gitignore b/android/.gitignore
new file mode 100644
index 0000000..3a3e7de
--- /dev/null
+++ b/android/.gitignore
@@ -0,0 +1,14 @@
+# Generated by android/scripts/sync-sdl.sh (copied from sdl2-sys, or built):
+app/src/main/java/org/libsdl/app/
+app/src/main/jniLibs/
+app/src/main/res/mipmap-*/
+gradle/wrapper/gradle-wrapper.jar
+gradlew
+gradlew.bat
+
+# Gradle / build output:
+.gradle/
+build/
+app/build/
+local.properties
+*.keystore
diff --git a/android/README.md b/android/README.md
new file mode 100644
index 0000000..28a652b
--- /dev/null
+++ b/android/README.md
@@ -0,0 +1,125 @@
+# Android port
+
+retsend on Android is the same app: SDL2 has a mature Android port, so the Rust
+code ships as a cdylib (`libretsend.so`) that SDL's Java `SDLActivity` loads and
+enters through the C `SDL_main` in `src/lib.rs`. Windowing, the GLES context,
+gamepad input and the whole net stack carry over. What is Android's alone is
+packaging, storage paths, touch, and the Back button — all of it behind
+`#[cfg(target_os = "android")]` or additive Cargo entries, so the Linux and
+handheld builds are untouched.
+
+Targets `arm64-v8a` only, which is every Android handheld and phone worth
+running this on, from API 24 (Android 7).
+
+## Install
+
+Grab `retsend-android-arm64.apk` from
+[Releases](https://github.com/mxmgorin/retsend/releases) and sideload it.
+
+On first launch it asks for **All files access**. Grant it and received files
+land in `Download/`, and the file browser can reach the whole card — which is
+the point on a device where an emulator has to find what you sent. Denied, the
+app still works, but it is confined to its own external directory
+(`Android/data/com.retsend/files/`), which file managers can't open on Android
+11+. The grant screen is only offered once; afterwards it's
+**Settings → Apps → retsend → All files access**, and the save folder is then
+changed in-app under **Settings → Save folder**.
+
+## Building
+
+One-time setup:
+
+```sh
+rustup target add aarch64-linux-android
+cargo install cargo-ndk --locked
+# Android Studio (SDK + an NDK + CMake), or the sdkmanager equivalents:
+sdkmanager --install "ndk;27.2.12479018" "platforms;android-34" "build-tools;34.0.0"
+```
+
+Then one command builds `libSDL2.so` (first run only), cross-compiles the cdylib
+and assembles the APK:
+
+```sh
+./android/scripts/build.sh # debug -> android/app/build/outputs/apk/debug/app-debug.apk
+./android/scripts/build.sh release # release -> android/app/build/outputs/apk/release/app-release.apk
+adb install -r android/app/build/outputs/apk/release/app-release.apk
+```
+
+It auto-detects the SDK and the newest installed NDK (override with
+`ANDROID_SDK_ROOT` / `ANDROID_NDK_HOME`). Debug and release sign with the same
+`app/debug.keystore`, so `-r` updates in place.
+
+In Android Studio: run `build.sh` once so the `.so` files exist under
+`app/src/main/jniLibs/`, then open `android/` and use Run — Gradle only packages
+what is already there, it never builds Rust. Re-run the `cargo ndk` step
+whenever the Rust code changes.
+
+Logs go to logcat: `adb logcat -s retsend`.
+
+## How the pieces fit
+
+- **Entry point** — `RetsendActivity.getLibraries()` returns `{"SDL2",
+ "retsend"}`, so SDL loads `libretsend.so` and calls its `SDL_main`, which hands
+ off to the same `run_app()` the desktop binary uses.
+- **Paths** — `RetsendActivity.onCreate` sets the same `RETSEND_*` env vars the
+ PortMaster and OnionOS launchers set, before SDL starts: `RETSEND_DATA_DIR`
+ (internal `getFilesDir()`: config, TLS identity, history), `RETSEND_SAVE_DIR`,
+ `RETSEND_BROWSER_ROOTS` (the storage volumes it can reach), `RETSEND_ALIAS`
+ (`Build.MODEL`), `RETSEND_SCALE` (display density) and `RETSEND_PANIC_FILE`.
+- **Permissions** — `RetsendLauncherActivity` is the launcher entry and asks for
+ all-files access *before* starting SDL, because the paths above are read once
+ at startup and the save folder is persisted on first run.
+- **Discovery** — the activity holds a `WifiManager.MulticastLock` for its
+ lifetime; without one the Wi-Fi driver filters out the multicast announces.
+- **Input** — touch or a gamepad. SDL's own touch→mouse synthesis is off, since
+ egui-sdl2 builds a pointer stream from the finger events itself. A tap becomes
+ the same `AppCommand` a button would: on a row it places the cursor and
+ confirms, and each footer hint slot *is* the button it names, which is what
+ makes Start/Select/X/Y reachable without a pad.
+- **Back** — `SDL_ANDROID_TRAP_BACK_BUTTON` makes it an `AC_BACK` key instead of
+ backgrounding the activity, mapped to the Back command; at the top level it
+ quits, since on Android Back has to lead somewhere.
+- **Orientation** — locked to `sensorLandscape`. The UI is the handhelds'
+ 640x480 one, and a fixed aspect also avoids relayout on rotation, which
+ egui-sdl2 drives off a cached window size that an Android rotation can outrun.
+
+## SDL version coupling
+
+`sdl2-sys 0.38` vendors SDL 2.26.4. `scripts/sync-sdl.sh` copies the
+`org.libsdl.app` Java glue and builds `libSDL2.so` from that same source, so the
+glue, the runtime `.so` and the Rust bindings all match. Everything it produces
+(Java glue, wrapper jar, `jniLibs/`, `res/mipmap-*`) is git-ignored and
+regenerated.
+
+## Not done yet
+
+- **GL surface loss on background.** Android destroys the EGL surface when the
+ app leaves the foreground; SDL blocks the app thread across that, but a
+ context loss would leave egui's textures stale. Transfers run on their own
+ threads and are unaffected. Untested on a device.
+- **Sending files the system hands us.** No `ACTION_SEND` intent filter yet, so
+ retsend can't be a share target; files are picked in its own browser.
+- **Save folder via SAF.** All-files access is used instead, which is what plain
+ file I/O needs and what sideloading allows.
+- **Portrait.** Would need a per-frame window-size sync that `EguiWindow` doesn't
+ expose yet, hence the orientation lock.
+
+## Signing
+
+CI restores a stable key from the `RETSEND_KEYSTORE_BASE64` secret (decoded to
+`app/release.keystore`, passed via `RETSEND_KEYSTORE`) so every release APK has
+the same signature; without the secret it falls back to an ephemeral key so
+forks still build. One-time setup:
+
+```sh
+keytool -genkeypair -keystore release.keystore -storepass android -keypass android \
+ -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000 \
+ -dname "CN=retsend,O=retsend,C=US"
+base64 -w0 release.keystore # save as the repo secret RETSEND_KEYSTORE_BASE64
+```
+
+Non-default passwords or alias also need `RETSEND_KEYSTORE_PASS`,
+`RETSEND_KEY_ALIAS` and `RETSEND_KEY_PASS`. Play distribution would need a real
+upload key through the same env — and a different storage story, since
+`MANAGE_EXTERNAL_STORAGE` is not something Play grants a file-transfer app
+lightly.
diff --git a/android/app/build.gradle b/android/app/build.gradle
new file mode 100644
index 0000000..6bc5836
--- /dev/null
+++ b/android/app/build.gradle
@@ -0,0 +1,72 @@
+apply plugin: 'com.android.application'
+
+// Cargo.toml is the single source of truth for the version, so the APK can't
+// drift from the crate the About screen names.
+def crateVersion = {
+ def toml = new File(rootDir, "../Cargo.toml").getText("UTF-8")
+ def matcher = (toml =~ /(?m)^version = "([^"]+)"/)
+ if (!matcher) throw new GradleException("no package version found in ../Cargo.toml")
+ return matcher[0][1]
+}()
+
+// Strides pack semver into a monotonically increasing versionCode, each bounding
+// the place below it (minor < 100, patch < 100).
+def MINOR_STRIDE = 100
+def MAJOR_STRIDE = 10000
+def (verMajor, verMinor, verPatch) = crateVersion.split('-')[0].tokenize('.').collect { it.toInteger() }
+
+android {
+ namespace 'com.retsend'
+ compileSdk 34
+
+ defaultConfig {
+ applicationId "com.retsend"
+ minSdk 24
+ targetSdk 34
+ versionCode verMajor * MAJOR_STRIDE + verMinor * MINOR_STRIDE + verPatch
+ versionName crateVersion
+ // One 64-bit ABI, which is every Android handheld. The Rust cdylib,
+ // libSDL2.so and libc++_shared.so are placed under src/main/jniLibs by
+ // cargo-ndk and scripts/sync-sdl.sh; Gradle builds no native code here.
+ ndk {
+ abiFilters 'arm64-v8a'
+ }
+ }
+
+ // Sideloading, not Play: the release APK is signed with the same key CI
+ // restores from a secret. See android/README.md for a real upload key.
+ signingConfigs {
+ release {
+ storeFile file(System.getenv("RETSEND_KEYSTORE") ?: "debug.keystore")
+ storePassword System.getenv("RETSEND_KEYSTORE_PASS") ?: "android"
+ keyAlias System.getenv("RETSEND_KEY_ALIAS") ?: "androiddebugkey"
+ keyPassword System.getenv("RETSEND_KEY_PASS") ?: "android"
+ }
+ }
+
+ buildTypes {
+ // Debug signs with the SAME key as release. AGP would otherwise use
+ // ~/.android/debug.keystore, and the signature mismatch makes
+ // `adb install -r` fail whenever you switch profiles.
+ debug {
+ signingConfig signingConfigs.release
+ }
+ release {
+ minifyEnabled false
+ signingConfig signingConfigs.release
+ }
+ }
+
+ sourceSets {
+ main {
+ jniLibs.srcDirs = ['src/main/jniLibs']
+ }
+ }
+
+ lint {
+ abortOnError false
+ }
+}
+
+// No dependencies: the SDL Java glue compiles from src/main/java/org/libsdl/app.
+dependencies {}
diff --git a/android/app/proguard-rules.pro b/android/app/proguard-rules.pro
new file mode 100644
index 0000000..2c8e8c4
--- /dev/null
+++ b/android/app/proguard-rules.pro
@@ -0,0 +1,4 @@
+# Release is not minified, so these only matter if shrinking is ever turned on:
+# SDL reaches its Java glue and our activities by name through JNI/reflection.
+-keep class org.libsdl.app.** { *; }
+-keep class com.retsend.** { *; }
diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
new file mode 100644
index 0000000..6dbec4a
--- /dev/null
+++ b/android/app/src/main/AndroidManifest.xml
@@ -0,0 +1,66 @@
+
+It is a separate activity because the save folder and browser roots are
+ * derived from the granted permissions and read once, before SDL starts: asking
+ * from inside the SDL activity would settle those paths a launch too early, and
+ * the save folder is persisted to config.toml on first run.
+ */
+public class RetsendLauncherActivity extends Activity {
+
+ private static final String TAG = "retsend";
+ private static final String PREFS = "retsend";
+ private static final String KEY_ASKED = "storage_asked";
+
+ /** Set while the grant UI is up; the return trip runs onResume again. */
+ private boolean asking;
+
+ @Override
+ protected void onResume() {
+ super.onResume();
+
+ if (!asking && !Storage.hasAllFilesAccess(this) && !alreadyAsked()) {
+ markAsked();
+ if (requestAllFilesAccess()) {
+ asking = true;
+ return;
+ }
+ }
+
+ // Whatever the answer: denied only costs the shared folders.
+ startActivity(new Intent(this, RetsendActivity.class));
+ finish();
+ }
+
+ /** Whether any grant UI came up — false means carry on without it. */
+ private boolean requestAllFilesAccess() {
+ if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
+ requestPermissions(
+ new String[] {android.Manifest.permission.WRITE_EXTERNAL_STORAGE}, 1);
+ return true;
+ }
+ Intent perApp = new Intent(
+ Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION,
+ Uri.parse("package:" + getPackageName()));
+ Intent list = new Intent(Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION);
+ for (Intent intent : new Intent[] {perApp, list}) {
+ try {
+ startActivity(intent);
+ return true;
+ } catch (ActivityNotFoundException e) {
+ Log.w(TAG, "no screen for " + intent.getAction());
+ }
+ }
+ return false;
+ }
+
+ private boolean alreadyAsked() {
+ return prefs().getBoolean(KEY_ASKED, false);
+ }
+
+ private void markAsked() {
+ prefs().edit().putBoolean(KEY_ASKED, true).apply();
+ }
+
+ private SharedPreferences prefs() {
+ return getSharedPreferences(PREFS, MODE_PRIVATE);
+ }
+}
diff --git a/android/app/src/main/java/com/retsend/Storage.java b/android/app/src/main/java/com/retsend/Storage.java
new file mode 100644
index 0000000..096be94
--- /dev/null
+++ b/android/app/src/main/java/com/retsend/Storage.java
@@ -0,0 +1,22 @@
+package com.retsend;
+
+import android.content.Context;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import android.os.Environment;
+
+/** Whether the app may use plain file I/O across the card. */
+final class Storage {
+
+ private Storage() {}
+
+ static boolean hasAllFilesAccess(Context context) {
+ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+ return Environment.isExternalStorageManager();
+ }
+ // Up to API 29 the legacy runtime permission is the same thing, given
+ // android:requestLegacyExternalStorage in the manifest.
+ return context.checkSelfPermission(android.Manifest.permission.WRITE_EXTERNAL_STORAGE)
+ == PackageManager.PERMISSION_GRANTED;
+ }
+}
diff --git a/android/app/src/main/res/values/strings.xml b/android/app/src/main/res/values/strings.xml
new file mode 100644
index 0000000..2e6fa2e
--- /dev/null
+++ b/android/app/src/main/res/values/strings.xml
@@ -0,0 +1,4 @@
+
+