mirror of
https://github.com/meshtastic/Meshtastic-Android.git
synced 2026-04-20 22:23:37 +00:00
43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
# KMP Source-Set Bridging Playbook
|
|
|
|
Use this playbook when introducing platform-specific behavior into shared modules.
|
|
|
|
## 1) Decide if `expect`/`actual` is needed
|
|
|
|
Use `expect`/`actual` only when a platform API cannot be abstracted cleanly behind an interface passed from app wiring.
|
|
|
|
- Prefer interface + DI when behavior is already app-owned.
|
|
- Prefer `expect`/`actual` for small platform primitives and utilities.
|
|
|
|
Examples in current code:
|
|
- `core/common/src/commonMain/kotlin/org/meshtastic/core/common/util/CommonUri.kt`
|
|
- `core/common/src/androidMain/kotlin/org/meshtastic/core/common/util/CommonUri.android.kt`
|
|
- `core/repository/src/commonMain/kotlin/org/meshtastic/core/repository/LocationRepository.kt`
|
|
|
|
## 2) Keep source-set boundaries strict
|
|
|
|
- `commonMain`: business logic, shared models, coroutine/Flow orchestration.
|
|
- `androidMain`: Android framework integration (`Context`, system services, Android SDK).
|
|
- `app`: app bootstrap, DI root inclusion, Activity/service wiring, flavor-specific providers.
|
|
|
|
## 3) Resource and UI bridging rules
|
|
|
|
- Shared strings/resources must come from `core:resources`.
|
|
- Platform/flavor UI implementations should be injected via `CompositionLocal` from app.
|
|
|
|
Examples:
|
|
- Contract: `core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/util/MapViewProvider.kt`
|
|
- Provider wiring: `app/src/main/kotlin/org/meshtastic/app/MainActivity.kt`
|
|
|
|
## 4) DI and module activation checks
|
|
|
|
- If a new feature/core module adds Koin annotations, verify it is included by app root module includes.
|
|
- App root includes are defined in `app/src/main/kotlin/org/meshtastic/app/di/AppKoinModule.kt`.
|
|
|
|
## 5) Verification checklist
|
|
|
|
- No Android-only imports in `commonMain`.
|
|
- `expect`/`actual` declarations compile across relevant source sets.
|
|
- Routing/DI still resolves from app startup (`MeshUtilApplication`).
|
|
- Run verification tasks from `docs/agent-playbooks/testing-and-ci-playbook.md` appropriate to touched modules.
|
|
|