docs: protocol audit 2026-05-25, update architecture + Obsidian vault
Audit: - docs/AUDIT-2026-05-25.md: full protocol audit covering 8 findings (4 critical, 2 high, 5 medium, 4 low) with code references and fix effort estimates - vault/Audit/Tasks.md: Obsidian Tasks plugin file tracking all audit items with priorities, due dates, and per-step checklists Architecture docs updated for Wire format v2 and Wave 5/6 features: - ARCHITECTURE.md: adds wzp-video to dependency graph and project structure; wire format updated to v2 (16B header, 5B MiniHeader); relay concurrency section corrected (DashMap+RwLock is current, not a future optimization); test count 571→702; Android note - PROGRESS.md: Wave 5 and Wave 6 sections appended; test count 372→702; current status and open blockers as of 2026-05-25 - ROAD-TO-VIDEO.md: implementation status table inserted (✅/🟡/🔴/🔲 per phase); 6-step critical path to first video call - WZP-SPEC.md: MediaHeader updated to v2 (16B byte-aligned); MiniHeader updated to 5B with seq_delta; codec IDs 9-12 added (H.264/H.265/AV1); version negotiation section added Obsidian vault (vault/): - 114 files across Architecture/, PRDs/, Reports/, Android/, Reference/, Audit/ with YAML frontmatter - 00 - Home.md index note with wiki links - .obsidian/app.json config Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
160
vault/Android/Build-Guide.md
Normal file
160
vault/Android/Build-Guide.md
Normal file
@@ -0,0 +1,160 @@
|
||||
---
|
||||
tags: [android, wzp]
|
||||
type: reference
|
||||
---
|
||||
|
||||
# Build Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Version | Purpose |
|
||||
|------|---------|---------|
|
||||
| JDK | 17 | Android Gradle builds |
|
||||
| Android SDK | 34 | Compile SDK |
|
||||
| Android NDK | 26.1.10909125 | Native C++/Rust compilation |
|
||||
| Rust | 1.85+ | Native engine (edition 2024) |
|
||||
| cargo-ndk | latest | Cross-compile Rust → Android |
|
||||
| `aarch64-linux-android` target | - | Rust target for ARM64 |
|
||||
|
||||
### Install Rust Android target
|
||||
|
||||
```bash
|
||||
rustup target add aarch64-linux-android
|
||||
cargo install cargo-ndk
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"
|
||||
export ANDROID_HOME="$HOME/android-sdk"
|
||||
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/26.1.10909125"
|
||||
|
||||
# For manual cargo-ndk builds (Gradle sets these automatically):
|
||||
export CC_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang"
|
||||
export CXX_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang++"
|
||||
export AR_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
|
||||
```
|
||||
|
||||
## Build Commands
|
||||
|
||||
### Full Build (Gradle drives everything)
|
||||
|
||||
```bash
|
||||
cd android
|
||||
./gradlew assembleRelease
|
||||
```
|
||||
|
||||
This runs:
|
||||
1. `cargoNdkBuild` task: invokes `cargo ndk -t arm64-v8a -o app/src/main/jniLibs build --release -p wzp-android`
|
||||
2. Compiles Kotlin/Compose code
|
||||
3. Packages APK with signing
|
||||
|
||||
### Native Library Only
|
||||
|
||||
```bash
|
||||
cargo ndk -t arm64-v8a -o android/app/src/main/jniLibs build --release -p wzp-android
|
||||
```
|
||||
|
||||
Output: `android/app/src/main/jniLibs/arm64-v8a/libwzp_android.so`
|
||||
|
||||
### Skip Native Rebuild
|
||||
|
||||
If the `.so` hasn't changed:
|
||||
|
||||
```bash
|
||||
cd android
|
||||
./gradlew assembleRelease -x cargoNdkBuild
|
||||
```
|
||||
|
||||
### Debug Build
|
||||
|
||||
```bash
|
||||
cd android
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
Debug APK is ~8.9 MB (unstripped `.so`), release is ~6.9 MB.
|
||||
|
||||
## Signing
|
||||
|
||||
### Debug
|
||||
|
||||
```
|
||||
Keystore: android/keystore/wzp-debug.jks
|
||||
Password: android
|
||||
Key alias: wzp-debug
|
||||
```
|
||||
|
||||
### Release
|
||||
|
||||
```
|
||||
Keystore: android/keystore/wzp-release.jks
|
||||
Password: wzphone2024
|
||||
Key alias: wzp-release
|
||||
```
|
||||
|
||||
Both keystores are checked into the repo for development convenience. For production, replace with proper key management.
|
||||
|
||||
## Build Artifacts
|
||||
|
||||
| Artifact | Path | Size |
|
||||
|----------|------|------|
|
||||
| Debug APK | `android/app/build/outputs/apk/debug/app-debug.apk` | ~8.9 MB |
|
||||
| Release APK | `android/app/build/outputs/apk/release/app-release.apk` | ~6.9 MB |
|
||||
| Native lib | `android/app/src/main/jniLibs/arm64-v8a/libwzp_android.so` | ~5 MB |
|
||||
|
||||
## ABI Support
|
||||
|
||||
Currently only `arm64-v8a` (ARM64) is built. This covers 95%+ of modern Android devices.
|
||||
|
||||
To add more ABIs, edit `build.gradle.kts`:
|
||||
|
||||
```kotlin
|
||||
ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
|
||||
```
|
||||
|
||||
And update the cargo-ndk command in `cargoNdkBuild` task:
|
||||
|
||||
```kotlin
|
||||
commandLine("cargo", "ndk", "-t", "arm64-v8a", "-t", "armeabi-v7a", ...)
|
||||
```
|
||||
|
||||
## Oboe Dependency
|
||||
|
||||
The Oboe C++ audio library is fetched at build time by `build.rs`:
|
||||
|
||||
1. Attempts `git clone` of Oboe 1.8.1 into `$OUT_DIR/oboe`
|
||||
2. If successful, compiles `oboe_bridge.cpp` with Oboe headers
|
||||
3. If clone fails (no network), falls back to `oboe_stub.cpp` (no-op audio)
|
||||
|
||||
This means **first build requires internet** to fetch Oboe. Subsequent builds use the cached checkout.
|
||||
|
||||
## Common Build Issues
|
||||
|
||||
### `cargo ndk` not found
|
||||
|
||||
```bash
|
||||
cargo install cargo-ndk
|
||||
```
|
||||
|
||||
### Missing Android target
|
||||
|
||||
```bash
|
||||
rustup target add aarch64-linux-android
|
||||
```
|
||||
|
||||
### NDK not found
|
||||
|
||||
Ensure `ANDROID_NDK_HOME` points to the NDK directory containing `toolchains/llvm/`.
|
||||
|
||||
### C++ compilation errors
|
||||
|
||||
Check that `CXX_aarch64_linux_android` points to a valid clang++ from the NDK.
|
||||
|
||||
### Gradle daemon issues
|
||||
|
||||
```bash
|
||||
./gradlew --stop
|
||||
./gradlew assembleRelease --no-daemon
|
||||
```
|
||||
Reference in New Issue
Block a user