Skip to content

Commit a101a60

Browse files
haslinghuishaslinghuis
committed
Update path for ADB
1 parent 35c46eb commit a101a60

File tree

2 files changed

+364
-1
lines changed

2 files changed

+364
-1
lines changed

‎ANDROID.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
# Android Development Guide
2+
3+
This guide covers the complete setup and workflow for building and running the Betaflight Configurator on Android using Tauri.
4+
5+
## Prerequisites
6+
7+
### Required Software
8+
- **Node.js**: v20.x (LTS)
9+
- **Yarn**: v1.22.x
10+
- **Android Studio**: Latest version (for SDK, NDK, and emulator)
11+
- **Rust**: Latest stable version
12+
- **Android SDK**: API Level 34+
13+
- **Android NDK**: Version 29.0.14033849
14+
- **Java**: JDK 17+ (bundled with Android Studio)
15+
16+
### Android SDK Setup
17+
1. Install Android Studio from [developer.android.com](https://developer.android.com/studio)
18+
2. Open Android Studio → SDK Manager
19+
3. Install:
20+
- Android SDK Platform 34+
21+
- Android SDK Build-Tools 35.0.0
22+
- Android NDK 29.0.14033849
23+
- Android SDK Command-line Tools
24+
- Android Emulator
25+
26+
### Rust Targets
27+
Install Android targets for Rust:
28+
```bash
29+
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
30+
```
31+
32+
## Environment Configuration
33+
34+
### 1. Create `android-env.sh`
35+
Create this file in the project root:
36+
37+
```bash
38+
#!/bin/bash
39+
40+
# Android SDK path (adjust if needed)
41+
export ANDROID_HOME="$HOME/Android/Sdk"
42+
export ANDROID_SDK_ROOT="$ANDROID_HOME"
43+
44+
# Find the latest NDK version
45+
NDK_VERSION=$(ls -1 "$ANDROID_HOME/ndk" 2>/dev/null | sort -V | tail -n 1)
46+
47+
if [ -z "$NDK_VERSION" ]; then
48+
echo "Error: No NDK found in $ANDROID_HOME/ndk"
49+
exit 1
50+
fi
51+
52+
export NDK_HOME="$ANDROID_HOME/ndk/$NDK_VERSION"
53+
54+
echo "Found NDK version: $NDK_VERSION"
55+
echo ""
56+
echo "Android environment variables set:"
57+
echo "ANDROID_HOME=$ANDROID_HOME"
58+
echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT"
59+
echo "NDK_HOME=$NDK_HOME"
60+
echo ""
61+
echo "Setup complete! You can now run: yarn tauri:dev:android"
62+
```
63+
64+
Make it executable:
65+
```bash
66+
chmod +x android-env.sh
67+
```
68+
69+
### 2. Add Android Tools to PATH
70+
Add these lines to your `~/.bashrc` or `~/.zshrc`:
71+
```bash
72+
export PATH="$PATH:$HOME/Android/Sdk/platform-tools"
73+
export PATH="$PATH:$HOME/Android/Sdk/emulator"
74+
```
75+
76+
Then reload:
77+
```bash
78+
source ~/.bashrc # or source ~/.zshrc
79+
```
80+
81+
### 3. Source Environment Variables
82+
Before running any Android commands:
83+
```bash
84+
source ./android-env.sh
85+
```
86+
87+
## Project Structure
88+
89+
### Key Files
90+
- **`src-tauri/Cargo.toml`**: Rust library configuration with mobile targets
91+
- **`src-tauri/src/lib.rs`**: Mobile entry point with `#[tauri::mobile_entry_point]`
92+
- **`src-tauri/src/main.rs`**: Desktop entry point
93+
- **`src-tauri/tauri.conf.json`**: Tauri configuration (devUrl, frontendDist, capabilities)
94+
- **`src-tauri/gen/android/`**: Generated Android project files
95+
- **`dist/`**: Built frontend assets (must exist for build to succeed)
96+
97+
### Important Configuration
98+
99+
#### `src-tauri/Cargo.toml`
100+
```toml
101+
[lib]
102+
name = "betaflight_app"
103+
path = "src/lib.rs"
104+
crate-type = ["staticlib", "cdylib", "rlib"]
105+
```
106+
107+
#### `src-tauri/src/lib.rs`
108+
```rust
109+
#[cfg_attr(mobile, tauri::mobile_entry_point)]
110+
pub fn run() {
111+
tauri::Builder::default()
112+
.plugin(tauri_plugin_shell::init())
113+
.run(tauri::generate_context!())
114+
.expect("error while running tauri application");
115+
}
116+
```
117+
118+
#### `src-tauri/tauri.conf.json`
119+
```json
120+
{
121+
"build": {
122+
"devUrl": "http://localhost:8000",
123+
"frontendDist": "../dist"
124+
}
125+
}
126+
```
127+
128+
#### `src-tauri/gen/android/app/build.gradle.kts`
129+
```kotlin
130+
rust {
131+
rootDirRel = "../../../../" // Important: points to project root for Yarn
132+
}
133+
```
134+
135+
## Android Emulator
136+
137+
### List Available AVDs
138+
```bash
139+
yarn android:emu:list
140+
```
141+
142+
### Check if Emulator is Running
143+
```bash
144+
yarn android:emu:check
145+
```
146+
147+
### Start Emulator
148+
Default emulator (Medium_Phone_API_35):
149+
```bash
150+
yarn android:emu:start
151+
```
152+
153+
Custom AVD:
154+
```bash
155+
AVD=Your_Device_Name yarn android:emu:start
156+
```
157+
158+
With host GPU acceleration (if supported):
159+
```bash
160+
yarn android:emu:start:host
161+
```
162+
163+
### Emulator Troubleshooting (Linux/Wayland)
164+
165+
If you encounter EGL or graphics errors:
166+
167+
1. **Force X11 mode**: The scripts use `QT_QPA_PLATFORM=xcb` automatically
168+
2. **SwiftShader fallback**: Default scripts use `-gpu swiftshader_indirect`
169+
3. **Disable snapshots**: Scripts use `-no-snapshot-load` to avoid boot issues
170+
171+
For persistent issues:
172+
- Update Mesa drivers: `sudo apt install mesa-vulkan-drivers`
173+
- Use host GPU: `yarn android:emu:start:host`
174+
- Check AVD config in Android Studio → AVD Manager
175+
176+
## Development Workflow
177+
178+
### First-Time Setup
179+
1. Install dependencies:
180+
```bash
181+
yarn install
182+
```
183+
184+
2. Create dist directory placeholder:
185+
```bash
186+
mkdir -p dist && touch dist/.gitkeep
187+
```
188+
189+
3. Source Android environment:
190+
```bash
191+
source ./android-env.sh
192+
```
193+
194+
4. Start emulator:
195+
```bash
196+
yarn android:emu:start
197+
```
198+
199+
5. Wait for emulator to fully boot (check with `adb devices`)
200+
201+
### Development Mode
202+
203+
#### Run Android Dev Build
204+
```bash
205+
source ./android-env.sh
206+
yarn tauri:dev:android
207+
```
208+
209+
This will:
210+
1. Start Vite dev server at `http://localhost:8000`
211+
2. Build Rust library for Android (x86_64 for emulator)
212+
3. Compile Android APK
213+
4. Install and launch on connected device/emulator
214+
215+
#### Live Reload Setup
216+
To enable hot module replacement on the emulator:
217+
218+
1. Ensure Vite dev server is accessible:
219+
```bash
220+
adb reverse tcp:8000 tcp:8000
221+
```
222+
223+
2. The app should automatically connect to `http://localhost:8000` (devUrl)
224+
225+
3. Make code changes in `src/` - Vite will hot-reload automatically
226+
227+
#### Verify DevUrl Connectivity
228+
Open Chrome on the emulator and navigate to `http://localhost:8000` to verify the dev server is accessible.
229+
230+
### Production Build
231+
232+
Build release APK:
233+
```bash
234+
source ./android-env.sh
235+
yarn tauri:build:android
236+
```
237+
238+
The APK will be in: `src-tauri/gen/android/app/build/outputs/apk/`
239+
240+
## Common Issues & Solutions
241+
242+
### Issue: "Couldn't find a package.json file in src-tauri"
243+
244+
**Solution**: The Gradle `rootDirRel` is incorrect. Edit `src-tauri/gen/android/app/build.gradle.kts`:
245+
```kotlin
246+
rust {
247+
rootDirRel = "../../../../"
248+
}
249+
```
250+
251+
### Issue: "No library targets found in package"
252+
253+
**Solution**: Add library target to `src-tauri/Cargo.toml`:
254+
```toml
255+
[lib]
256+
name = "betaflight_app"
257+
crate-type = ["staticlib", "cdylib"]
258+
```
259+
260+
And create `src-tauri/src/lib.rs` with mobile entry point.
261+
262+
### Issue: "frontendDist path doesn't exist"
263+
264+
**Solution**: Create the dist directory:
265+
```bash
266+
mkdir -p dist && touch dist/.gitkeep
267+
```
268+
269+
### Issue: Code changes not reflected on Android
270+
271+
**Causes**:
272+
1. Emulator not connected to devUrl (missing `adb reverse`)
273+
2. App loaded from packaged dist instead of dev server
274+
275+
**Solutions**:
276+
1. Run `adb reverse tcp:8000 tcp:8000`
277+
2. Verify Vite is running at port 8000
278+
3. Check browser console in app for devUrl connection
279+
280+
### Issue: Emulator hangs or EGL errors (Linux)
281+
282+
**Solutions**:
283+
1. Use provided emulator scripts (includes Qt/GPU fixes)
284+
2. Force X11: `QT_QPA_PLATFORM=xcb`
285+
3. Use SwiftShader: `-gpu swiftshader_indirect`
286+
4. Update graphics drivers
287+
288+
### Issue: "tauri android dev" waits indefinitely
289+
290+
**Cause**: No emulator/device detected
291+
292+
**Solutions**:
293+
1. Start emulator first: `yarn android:emu:start`
294+
2. Check devices: `adb devices`
295+
3. Ensure emulator is fully booted (not just window open)
296+
297+
### Issue: "adb: command not found"
298+
299+
**Cause**: Android SDK platform-tools not in PATH
300+
301+
**Solutions**:
302+
1. Add to your shell profile (`~/.bashrc` or `~/.zshrc`):
303+
```bash
304+
export PATH="$PATH:$HOME/Android/Sdk/platform-tools"
305+
export PATH="$PATH:$HOME/Android/Sdk/emulator"
306+
```
307+
2. Reload: `source ~/.bashrc`
308+
3. Verify: `which adb` should show the path
309+
310+
## Available Scripts
311+
312+
### Emulator Management
313+
- `yarn android:emu:list` - List all AVDs
314+
- `yarn android:emu:check` - Check if emulator is running
315+
- `yarn android:emu:start` - Start emulator with SwiftShader
316+
- `yarn android:emu:start:host` - Start with host GPU
317+
318+
### Tauri Android
319+
- `yarn tauri:dev:android` - Development build with hot reload
320+
- `yarn tauri:build:android` - Production release build
321+
322+
### Capacitor Android (Alternative)
323+
- `yarn android:dev` - Capacitor dev build
324+
- `yarn android:run` - Capacitor production build
325+
- `yarn android:sync` - Sync web assets to Android
326+
- `yarn android:open` - Open in Android Studio
327+
328+
## Architecture Notes
329+
330+
### Tauri Mobile vs Desktop
331+
- **Desktop**: Uses `src-tauri/src/main.rs` directly
332+
- **Mobile**: Uses `src-tauri/src/lib.rs` with `#[tauri::mobile_entry_point]`
333+
- **Shared**: Both call the same `run()` function for consistency
334+
335+
### Build Process
336+
1. **BeforeDevCommand**: Runs `yarn dev` (Vite)
337+
2. **Rust Compilation**: Builds lib for Android target (e.g., x86_64-linux-android)
338+
3. **Gradle Build**: Invokes Yarn to run `tauri android android-studio-script`
339+
4. **APK Assembly**: Packages Rust lib + assets into APK
340+
5. **Installation**: ADB installs APK on device/emulator
341+
342+
### DevUrl vs FrontendDist
343+
- **DevUrl** (`http://localhost:8000`): Used in dev mode for hot reload
344+
- **FrontendDist** (`../dist`): Used in production builds (packaged assets)
345+
- **Fallback**: If devUrl unreachable, Tauri falls back to frontendDist
346+
347+
## Additional Resources
348+
349+
- [Tauri Mobile Docs](https://v2.tauri.app/develop/mobile/)
350+
- [Android Developer Guide](https://developer.android.com/studio)
351+
- [Rust Android Targets](https://doc.rust-lang.org/nightly/rustc/platform-support.html)
352+
353+
## Contributing
354+
355+
When making changes to Android configuration:
356+
1. Test on both emulator and physical device
357+
2. Verify both debug and release builds
358+
3. Document any new environment requirements
359+
4. Update this guide with new troubleshooting steps
360+
361+
---
362+
363+
**Last Updated**: October 24, 2025

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
"android:sync": "vite build && node capacitor.config.generator.mjs && npx cap sync android",
2222
"android:release": "vite build && node capacitor.config.generator.mjs && npx cap build android --release",
2323
"android:emu:list": "$ANDROID_HOME/emulator/emulator -list-avds",
24-
"android:emu:check": "adb devices | grep -q emulator && echo 'Emulator running' || echo 'No emulator'",
24+
"android:emu:check": "$ANDROID_HOME/platform-tools/adb devices | grep -q emulator && echo 'Emulator running' || echo 'No emulator'",
2525
"android:emu:start": "QT_QPA_PLATFORM=xcb $ANDROID_HOME/emulator/emulator -avd ${AVD:-Medium_Phone_API_35} -gpu swiftshader_indirect -no-snapshot-load &",
2626
"android:emu:start:host": "QT_QPA_PLATFORM=xcb $ANDROID_HOME/emulator/emulator -avd ${AVD:-Medium_Phone_API_35} -gpu host -no-snapshot-load &",
2727
"format": "prettier --write {src,test}/**/*.{js,vue,css,less}",

0 commit comments

Comments
 (0)