# Developer Setup & Build Guide {#developer-setup--build-guide}


This guide provides instructions for developers configuring, building, testing, and packaging the **MQUAD** cross-platform mobile and desktop field application.

---


## 1. Prerequisites & Toolchains {#1-prerequisites--toolchains}



### Required SDKs: {#required-sdks}
| Tool | Minimum Version | Purpose |
|------|-----------------|---------|
| **Flutter SDK** | `^3.41.0` (stable) | Multi-platform UI framework |
| **Dart SDK** | `^3.11.0` (bundled with Flutter) | Core programming language |
| **Xcode** | `15.0+` (macOS only) | iOS and macOS builds, simulators |
| **Android Studio / CLI** | SDK 34+, NDK 26+ | Android builds, emulators |
| **Visual Studio 2022** | Latest (Windows only) | Windows C++ desktop toolchain |
| **Clang & CMake** | Latest (Linux only) | Linux GTK desktop compilation |
| **Git** | `2.x` | Source code control |


### Verifying Toolchains: {#verifying-toolchains}
```bash
flutter doctor -v
```
Ensure there are no blocking issues for the target platforms you intend to build or test.

---


## 2. Platform-Specific Setup {#2-platform-specific-setup}



### Android Setup: {#android-setup}
```bash
# Configure Android Home in your shell profile (~/.zshrc or ~/.bashrc)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# Accept Android SDK licenses
flutter doctor --android-licenses
```


### iOS & macOS Setup (macOS only): {#ios--macos-setup-macos-only}
```bash
# Switch to active Xcode command line tools
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

# Pre-cache iOS artifacts and install CocoaPods
flutter precache --ios
cd mobile/ios && pod install && cd ..
```


### Linux Desktop Setup (Ubuntu / Debian): {#linux-desktop-setup-ubuntu--debian}
```bash
sudo apt-get update
sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libsecret-1-dev
```


### Windows Desktop Setup: {#windows-desktop-setup}
- Install **Visual Studio 2022 Community / Professional**.
- Under workloads, select **Desktop development with C++**.
- Ensure **Windows 10/11 SDK** and **CMake tools for Windows** are checked.

---


## 3. Project Initialization {#3-project-initialization}



### 1. Clone & Enter Directory {#1-clone--enter-directory}
```bash
cd mobile
```


### 2. Install Dart Dependencies {#2-install-dart-dependencies}
```bash
flutter pub get
```


### 3. Environment Configuration {#3-environment-configuration}
Copy the sample environment file and configure backend connection settings:
```bash
cp .env.example .env
```

Key environment properties in `.env`:
```ini
# Backend Gateway / API Base URL
API_BASE_URL=http://localhost:8000/api/v1

# Environment: development | staging | production
APP_ENV=development

# Optional Feature Flags
ENABLE_BIOMETRIC_AUTH=true
ENABLE_SCREENSHOT_PREVENTION=false # Set false during development for easy debugging
```


### 4. Run Code Generation {#4-run-code-generation}
MQUAD uses `build_runner` for generating Drift database classes, Freezed immutable models, and JSON serialization:
```bash
dart run build_runner build --delete-conflicting-outputs
```



> [!TIP]
> During active development on database schemas or DTOs, run the code generator in watch mode:
> ```bash
> dart run build_runner watch --delete-conflicting-outputs
> ```


---


## 4. Running the Application Locally {#4-running-the-application-locally}


View available attached devices and emulators:
```bash
flutter devices
```


### Running on Specific Targets: {#running-on-specific-targets}
```bash
# Run on default connected device or running simulator
flutter run

# Run on macOS Desktop
flutter run -d macos

# Run on Android Emulator / Physical Device
flutter run -d android

# Run on iOS Simulator / Physical iPhone
flutter run -d ios

# Run on Windows Desktop
flutter run -d windows

# Run on Linux Desktop
flutter run -d linux
```

---


## 5. Testing & Quality Assurance {#5-testing--quality-assurance}


MQUAD maintains a comprehensive test suite across unit, widget, and integration layers:


### Running All Unit & Widget Tests: {#running-all-unit--widget-tests}
```bash
flutter test
```


### Running Specific Test Suites: {#running-specific-test-suites}
```bash
# Run form engine evaluation tests
flutter test test/unit/form_engine_test.dart

# Run sync engine reconciliation tests
flutter test test/unit/sync_engine_test.dart

# Run settings & UI tests
flutter test test/unit/settings_screen_test.dart
```


### Running with Code Coverage: {#running-with-code-coverage}
```bash
flutter test --coverage
# Output generated at coverage/lcov.info
```


### Code Analysis & Formatting: {#code-analysis--formatting}
```bash
# Run static analysis
flutter analyze

# Verify code formatting
dart format --set-exit-if-changed lib/ test/
```

---


## 6. Building Production Release Artifacts {#6-building-production-release-artifacts}


MQUAD provides automated build scripts located in `mobile/scripts/build.sh`. You can also compile release binaries manually:


### Android: {#android}
```bash
# Build standalone universal APK for direct side-loading
flutter build apk --release

# Build split-per-ABI APKs (smaller file size for arm64-v8a / armeabi-v7a)
flutter build apk --release --split-per-abi

# Build Google Play App Bundle
flutter build appbundle --release
```
*Artifacts are generated in `build/app/outputs/flutter-apk/` and `build/app/outputs/bundle/release/`.*


### iOS (macOS required): {#ios-macos-required}
```bash
# Build release IPA archive
flutter build ipa --release
```
*Artifact is generated in `build/ios/archive/` or `build/ios/ipa/`.*


### Desktop Releases: {#desktop-releases}
```bash
# macOS .app bundle
flutter build macos --release
# Output: build/macos/Build/Products/Release/MQUAD.app

# Windows .exe binary
flutter build windows --release
# Output: build/windows/x64/runner/Release/

# Linux binary
flutter build linux --release
# Output: build/linux/x64/release/bundle/
```


### Automated Multi-Platform Build Script: {#automated-multi-platform-build-script}
```bash
chmod +x scripts/build.sh
./scripts/build.sh --all
```

---


## 7. Common Troubleshooting {#7-common-troubleshooting}



### Drift Database Schema Conflict {#drift-database-schema-conflict}
If you modify Drift tables (`database.dart`) and tests fail with column mismatches:
```bash
# 1. Clean build artifacts
flutter clean
flutter pub get

# 2. Re-run code generation cleanly
dart run build_runner build --delete-conflicting-outputs
```


### CocoaPods Dependency Failures (iOS/macOS) {#cocoapods-dependency-failures-iosmacos}
```bash
cd ios
rm -rf Pods Podfile.lock .symlinks
pod repo update
pod install
cd ..
```


### Android Gradle Build Errors {#android-gradle-build-errors}
Ensure your JDK version matches Flutter requirements (JDK 17 or JDK 21 recommended):
```bash
java -version
cd android && ./gradlew clean && cd ..
```