Developer Setup & Build Guide

Complete instructions for configuring the local Flutter development environment, running tests, code generation, and multi-platform compilation.

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

1. Prerequisites & Toolchains

Required SDKs:

ToolMinimum VersionPurpose
Flutter SDK^3.41.0 (stable)Multi-platform UI framework
Dart SDK^3.11.0 (bundled with Flutter)Core programming language
Xcode15.0+ (macOS only)iOS and macOS builds, simulators
Android Studio / CLISDK 34+, NDK 26+Android builds, emulators
Visual Studio 2022Latest (Windows only)Windows C++ desktop toolchain
Clang & CMakeLatest (Linux only)Linux GTK desktop compilation
Git2.xSource code control

Verifying Toolchains:

flutter doctor -v

Ensure there are no blocking issues for the target platforms you intend to build or test.

2. Platform-Specific Setup

Android Setup:

# 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):

# 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):

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:

  • 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

1. Clone & Enter Directory

cd mobile

2. Install Dart Dependencies

flutter pub get

3. Environment Configuration

Copy the sample environment file and configure backend connection settings:

cp .env.example .env

Key environment properties in .env:

# 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

MQUAD uses build_runner for generating Drift database classes, Freezed immutable models, and JSON serialization:

dart run build_runner build --delete-conflicting-outputs
Tip

During active development on database schemas or DTOs, run the code generator in watch mode:

dart run build_runner watch --delete-conflicting-outputs

4. Running the Application Locally

View available attached devices and emulators:

flutter devices

Running on Specific Targets:

# 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

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

Running All Unit & Widget Tests:

flutter test

Running Specific Test Suites:

# 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:

flutter test --coverage
# Output generated at coverage/lcov.info

Code Analysis & Formatting:

# Run static analysis
flutter analyze

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

6. Building Production Release Artifacts

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

Android:

# 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):

# Build release IPA archive
flutter build ipa --release

Artifact is generated in build/ios/archive/ or build/ios/ipa/.

Desktop Releases:

# 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:

chmod +x scripts/build.sh
./scripts/build.sh --all

7. Common Troubleshooting

Drift Database Schema Conflict

If you modify Drift tables (database.dart) and tests fail with column mismatches:

# 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)

cd ios
rm -rf Pods Podfile.lock .symlinks
pod repo update
pod install
cd ..

Android Gradle Build Errors

Ensure your JDK version matches Flutter requirements (JDK 17 or JDK 21 recommended):

java -version
cd android && ./gradlew clean && cd ..
Docs by Sourcey
↑↓ navigate↵ selectesc close