From 31cfed7023b95de7db66d8de8f386e6eaf3966fa Mon Sep 17 00:00:00 2001 From: Dongubak Date: Sun, 23 Aug 2026 15:03:20 +0900 Subject: [PATCH] Document Android build steps Covers the rustup requirement (Homebrew rust can't cross-compile to Android), env vars needed for cargo tauri android build, install via adb, and the cleartext-traffic gotcha for release builds against ws:// rosbridge endpoints. --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d558495..4c8d377 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# PCD Viewer — macOS 네이티브 빌드 +# PCD Viewer — 네이티브 빌드 (macOS / Android) FAST-LIVO2용 포인트 클라우드 뷰어(`pcd_viewer.html`, Three.js)를 Tauri 2로 감싼 macOS 앱. 빌드 없는 단일 HTML이 웹의 단일 소스이고, `src-tauri/`가 그걸 그대로 실어 네이티브 창으로 띄운다. @@ -44,6 +44,67 @@ open "target/release/bundle/macos/PCD Viewer.app" `web/`은 빌드 시점에 바이너리로 임베드되므로, `pcd_viewer.html`만 고쳐서는 네이티브 앱에 반영되지 않는다. 위 빌드 절차(`stage-web.sh` → `cargo build --release` → 바이너리 동기화)를 다시 밟아야 한다. +## Android 빌드 + +같은 `pcd_viewer.html`을 Android WebView로 감싼다(React Native/Expo 대신 — WebView도 진짜 +하드웨어 가속 WebGL을 쓰므로 렌더링 경로 자체는 동일하고, 코드베이스를 두 벌로 안 나눠도 된다). +`src-tauri/gen/android/`는 `cargo tauri android init`이 생성한 Android Studio 프로젝트다. + +### 준비물 + +- Rust는 **rustup으로 설치되어 있어야 함** — Homebrew의 `rust` 패키지(고정 타깃 하나만 빌드)로는 + `aarch64-linux-android` 같은 크로스 타깃을 추가할 수 없다. `brew install rustup`(또는 공식 + 설치 스크립트) 후: + ```sh + rustup target add aarch64-linux-android armv7-linux-androideabi \ + i686-linux-android x86_64-linux-android + ``` +- Android SDK + NDK (`sdkmanager`로 platform-tools, platform, NDK 설치, 라이선스 동의까지) +- JDK 17+ (Temurin 21 확인됨) +- `cargo install tauri-cli --version "^2" --locked` + +macOS에 Homebrew rust와 rustup이 공존하면 `cargo`/`rustc`가 PATH상 Homebrew 쪽으로 잡힐 수 있다 +(데스크톱 빌드는 그대로 Homebrew rust를 쓰도록 건드리지 않았다) — Android 명령은 rustup 툴체인의 +`cargo`를 명시적으로 가리켜서 실행한다: + +```sh +export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home +export ANDROID_HOME=~/Library/Android/sdk +export NDK_HOME=~/Library/Android/sdk/ndk/<설치된 버전> +export PATH="$HOME/.rustup/toolchains/stable-aarch64-apple-darwin/bin:$HOME/.cargo/bin:$PATH" +``` + +### 빌드 + +```sh +cd src-tauri +sh stage-web.sh +cargo tauri android build --debug --target aarch64 # 갤럭시 대부분은 arm64-v8a +``` + +산출물: +- APK: `gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk` +- AAB: `gen/android/app/build/outputs/bundle/universalDebug/app-universal-debug.aab` + +### 기기에 설치 + +```sh +adb install "gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk" +``` + +(갤럭시에서 설정 → 휴대전화 정보 → 빌드 번호 7번 탭으로 개발자 옵션 열고, USB 디버깅 켠 뒤 +USB로 연결 — `adb devices`에 기기가 떠야 설치된다.) USB 없이는 APK 파일을 기기로 옮겨 직접 +설치(출처를 알 수 없는 앱 허용 필요)해도 된다. + +### 알아둘 점 + +- `usesCleartextTraffic`이 디버그 빌드에선 자동으로 켜지지만 **release 빌드에선 꺼진다** — + rosbridge 주소가 `ws://`(평문)라면 release APK에서 연결이 막힌다. `wss://`로 옮기거나 + `gen/android/app/src/main/AndroidManifest.xml`에서 명시적으로 허용해야 한다. +- 아이콘은 기본 Tauri 플레이스홀더다. `cargo tauri icon `로 교체 가능. +- `gen/android/`는 커밋되어 있지만 `build/`·`.gradle/`·생성된 Kotlin 소스·`jniLibs/*.so`는 + 중첩 `.gitignore`로 제외된다 — 클론 후 첫 빌드에서 다시 만들어진다. + ## 그 밖의 문서 - `PCD_Viewer_가이드.md` — 사용법(측정/실시간 모니터링). 아직 vendoring·Tauri 반영 전 버전.