chore: move DEVELOPMENT.md and TODO.md to docs/
This commit is contained in:
achmad
@@ -0,0 +1,238 @@
|
||||
# DroidScope — Development Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Version | Install |
|
||||
|---|---|---|
|
||||
| Go | 1.23+ | https://go.dev/dl |
|
||||
| Node.js | 20+ | https://nodejs.org |
|
||||
| Wails CLI | v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@latest` |
|
||||
| Git | any | — |
|
||||
|
||||
> **macOS only:** Wails requires Xcode Command Line Tools — `xcode-select --install`
|
||||
>
|
||||
> **Linux only:** Wails requires `libgtk-3-dev libwebkit2gtk-4.0-dev` (Debian/Ubuntu) or equivalent.
|
||||
>
|
||||
> **Windows only:** Wails requires WebView2 (ships with Windows 11, otherwise install from Microsoft).
|
||||
|
||||
---
|
||||
|
||||
## First-time Setup
|
||||
|
||||
```bash
|
||||
# 1. Install frontend dependencies
|
||||
cd frontend-react
|
||||
npm install
|
||||
|
||||
# 2. (Optional) Download bundled ADB binaries for distribution builds
|
||||
# Skip this for local dev — the app falls back to your system ADB
|
||||
bash scripts/download-adb.sh
|
||||
|
||||
# 3. Make sure your system ADB is accessible for local dev
|
||||
# Either via ANDROID_HOME or PATH:
|
||||
export ANDROID_HOME=~/Library/Android/sdk # macOS example
|
||||
# or: ensure `adb` is on your PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running in Development
|
||||
|
||||
```bash
|
||||
bash scripts/dev.sh
|
||||
```
|
||||
|
||||
**What `dev.sh` does, in order:**
|
||||
|
||||
| Step | Command | What it checks |
|
||||
|---|---|---|
|
||||
| 1 | `go build ./...` in `backend-go/` | Backend packages compile without errors |
|
||||
| 2 | `go build ./...` in `desktop/` | Desktop Go code (app.go, main.go, embeds) compiles |
|
||||
| 3 | `wails generate module` in `desktop/` | Regenerates `frontend-react/src/wailsjs/` from current `app.go` bindings |
|
||||
| 4 | `npm install` + `tsc -b --noEmit` in `frontend-react/` | Installs any new deps, type-checks TypeScript |
|
||||
| — | `wails dev` in `desktop/` | Starts the desktop app with hot reload |
|
||||
|
||||
If any step fails the script exits immediately (due to `set -e`) — fix the error and re-run.
|
||||
|
||||
**What happens once running:**
|
||||
- Wails compiles the Go backend and opens a native desktop window
|
||||
- Wails starts the Vite dev server (`npm run dev` in `frontend-react/`)
|
||||
- React/TS changes hot-reload instantly without restarting
|
||||
- Go changes (in `app.go`, `backend-go/`) require re-running `dev.sh`
|
||||
|
||||
> **When to re-run `dev.sh` vs just saving a file:**
|
||||
> - Edited only `.tsx` / `.ts` / `.css` → Vite hot-reloads automatically, no restart needed
|
||||
> - Edited `app.go` (added/changed a bound method) → re-run `dev.sh` to rebuild Go + regenerate bindings
|
||||
> - Edited anything under `backend-go/` → re-run `dev.sh` to rebuild
|
||||
|
||||
**Frontend only** (browser preview, no Wails bindings):
|
||||
|
||||
```bash
|
||||
cd frontend-react
|
||||
npm run dev
|
||||
# → http://localhost:5173
|
||||
```
|
||||
|
||||
> Wails bindings (`ListDevices`, `GetDeviceInfo`, etc.) are no-ops in plain browser mode — they only work inside the Wails desktop window.
|
||||
|
||||
---
|
||||
|
||||
## Building for Production
|
||||
|
||||
### Full desktop app (recommended)
|
||||
|
||||
```bash
|
||||
bash scripts/build.sh
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
# Step 1 — build frontend (outputs to desktop/frontend/dist/)
|
||||
cd frontend-react
|
||||
npm run build
|
||||
|
||||
# Step 2 — build desktop binary (embeds frontend dist + ADB binaries)
|
||||
cd desktop
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
wails build
|
||||
```
|
||||
|
||||
Output: `desktop/build/bin/DroidScope` (macOS/Linux) or `desktop/build/bin/DroidScope.exe` (Windows)
|
||||
|
||||
---
|
||||
|
||||
### Backend only
|
||||
|
||||
```bash
|
||||
cd backend-go
|
||||
go build ./...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Frontend only (static bundle)
|
||||
|
||||
```bash
|
||||
cd frontend-react
|
||||
npm run build
|
||||
# Output: desktop/frontend/dist/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Android SDK
|
||||
|
||||
```bash
|
||||
cd android-sdk
|
||||
./gradlew :sdk:assembleDebug # debug AAR
|
||||
./gradlew :sdk:assembleRelease # release AAR
|
||||
# Output: android-sdk/sdk/build/outputs/aar/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type Checking (no build)
|
||||
|
||||
```bash
|
||||
# TypeScript
|
||||
cd frontend-react
|
||||
npx tsc -b --noEmit
|
||||
|
||||
# Go
|
||||
cd backend-go && go build ./...
|
||||
cd desktop && go build ./...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Regenerating Wails JS Bindings
|
||||
|
||||
Run this after adding or changing any exported method on `App` in `desktop/app.go`:
|
||||
|
||||
```bash
|
||||
cd desktop
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
wails generate module
|
||||
# Output: frontend-react/src/wailsjs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
DroidScope/
|
||||
├── desktop/ ← Wails app (Go entry point)
|
||||
│ ├── app.go ← Wails-bound methods (called from frontend)
|
||||
│ ├── main.go ← App bootstrap
|
||||
│ ├── wails.json ← Wails config (frontend dir, dev server)
|
||||
│ └── internal/adbembed/ ← ADB binary embedding + runtime extraction
|
||||
│
|
||||
├── backend-go/ ← Go backend packages
|
||||
│ ├── adb/ ← ADB command wrapper
|
||||
│ ├── device/ ← Device manager + DeviceInfo fetcher
|
||||
│ ├── logcat/ ← (stub) Logcat streaming
|
||||
│ ├── network/ ← (stub) Network inspector
|
||||
│ ├── storage/ ← (stub) SharedPrefs, SQLite, files
|
||||
│ ├── runtime/ ← (stub) Runtime config override
|
||||
│ ├── session/ ← (stub) Session management
|
||||
│ └── protocol/ ← Shared event types (Go structs)
|
||||
│
|
||||
├── frontend-react/ ← Vite + React + TypeScript
|
||||
│ ├── src/
|
||||
│ │ ├── wailsjs/ ← Auto-generated Wails bindings (do not edit)
|
||||
│ │ ├── features/ ← Feature modules (devices, logcat, network…)
|
||||
│ │ ├── components/ ← Shared UI components (layout, shadcn/ui)
|
||||
│ │ ├── hooks/ ← Shared hooks (useActiveDevice)
|
||||
│ │ ├── store/ ← Zustand global state
|
||||
│ │ └── types/ ← Shared TypeScript types (protocol)
|
||||
│ └── vite.config.ts ← Build outputs to ../desktop/frontend/dist/
|
||||
│
|
||||
├── android-sdk/ ← Kotlin Android SDK (Gradle)
|
||||
│ └── sdk/src/main/kotlin/dev/achmad/droidscope/
|
||||
│
|
||||
├── scripts/
|
||||
│ ├── dev.sh ← Start full dev environment
|
||||
│ ├── build.sh ← Production build
|
||||
│ └── download-adb.sh ← Download ADB binaries for bundling
|
||||
│
|
||||
├── go.work ← Go workspace (links desktop + backend-go)
|
||||
├── README.md ← Project overview and feature roadmap
|
||||
└── docs/
|
||||
├── DEVELOPMENT.md ← This file
|
||||
└── TODO.md ← Implementation status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Conventions
|
||||
|
||||
### Adding a new Go method callable from the frontend
|
||||
|
||||
1. Add the method to `desktop/app.go` (must be exported, receiver `*App`)
|
||||
2. Run `wails generate module` from `desktop/`
|
||||
3. Import from `@/wailsjs/go/main/App` in React
|
||||
|
||||
### Adding a new backend-go package
|
||||
|
||||
1. Create the package under `backend-go/`
|
||||
2. The `go.work` workspace + `replace` directive in `desktop/go.mod` handle local resolution — no publishing needed
|
||||
|
||||
### Active device scoping (all features)
|
||||
|
||||
- Import `useActiveDevice` from `@/hooks/use-active-device`
|
||||
- Check `isMonitoring` before starting streams or polls
|
||||
- Store per-device data in `deviceCache` via `patchDeviceCache(deviceId, data)` — never cleared on device switch
|
||||
- Show `<NoDeviceSelected />` when `!isMonitoring`
|
||||
|
||||
---
|
||||
|
||||
## ADB Binary Bundling
|
||||
|
||||
For **local development** the app resolves ADB in this order:
|
||||
1. Embedded binary in `desktop/internal/adbembed/bin/` (empty until `download-adb.sh` is run)
|
||||
2. `$ANDROID_HOME/platform-tools/adb`
|
||||
3. `adb` on `$PATH`
|
||||
|
||||
For **distribution builds** run `scripts/download-adb.sh` once before `wails build` to embed ADB for all platforms.
|
||||
Reference in New Issue
Block a user