Building

Build the Flutter App with the repository’s fl_build tool. Monitor agent is a separate Rust service and has its own build steps.

Prerequisites

Flutter SDK on the stable channel
Platform SDKs: Xcode for iOS, Android Studio and Android SDK for Android, or Visual Studio for Windows
Rust toolchain: the App builds crates/sbm_ffi using a Dart build hook, flutter_rust_bridge_hooks, and native assets

Initialize the Git submodules before fetching Dart packages:

git submodule update --init --recursive

Run a development build

# Run on the default device
flutter run

# Select a device explicitly
flutter run -d <device-id>

Release build

Pass the target platform to fl_build:

dart run fl_build -p <platform>

Supported platform names are ios, android, macos, linux, and windows.

Platform requirements

iOS

dart run fl_build -p ios

Builds require macOS and Xcode. Signing also requires an Apple Developer account.

Android

dart run fl_build -p android

Requires the Android SDK, a JDK, and a keystore for release signing. Release builds must use the keystore configured in key.properties. For local verification only, pass -PallowDebugReleaseSigning=true explicitly to use debug signing. Reproducible and F-Droid builds use -PallowUnsignedRelease=true, which omits signing configuration; scripts/release/android-build-env.sh exports this option.

macOS

dart run fl_build -p macos

Linux

dart run fl_build -p linux

Windows

dart run fl_build -p windows

Requires Visual Studio with the Desktop development with C++ workload and ATL support.

Build Monitor agent

Monitor agent is a standalone server binary. Build it separately from the Flutter App:

# From the repository root
cargo build --release

# Build the web panel
cd monitor/frontend
npm install
npm run build

After building the panel, Monitor agent serves it when frontend/dist exists. For development, run make monitor-dev from the repository root. It starts the API on :3770 and the Vite dev server on :3000.

The monitor-release.yml workflow builds release artifacts and currently runs only through workflow_dispatch. Monitor monitor-v* tags are separate from App releases. For a Docker build, see monitor/Dockerfile.

Build hooks

On every build, fl_build regenerates lib/data/res/build_data.dart, derives the build number from Git history, and writes the version to the Xcode configuration. Set the App name in the fl_build: section of pubspec.yaml.

Troubleshooting

Clean build

flutter clean
flutter pub get
dart run build_runner build

flutter clean removes build/, including the iOS Linux engine libraries when that engine is enabled. Rebuild the required target with scripts/build-ish-ios.sh device, simulator, or macos; otherwise linking will fail because those engine files are missing.

Dependency version conflict

Check package compatibility before upgrading dependencies:

flutter pub upgrade

After changing an annotated model, run code generation as well; see Code Generation.

Release checklist

Update the version in pubspec.yaml.
Run code generation and localization generation.
Run Dart, Flutter, and Rust tests.
Build every target platform.
Verify key features on real devices.
Create the GitHub release.