Skip to content

build.md

Latest commit

 

History

History
181 lines (118 loc) · 5.17 KB

build.md

File metadata and controls

181 lines (118 loc) · 5.17 KB

Build & Development Process Overview

This documentation describes how to build and run the WebTrit Phone project. It includes melos script usage, flavor configuration, Flutter SDK version management, and tips for local development.

For all available melos scripts, see Melos Commands. For how a release pins its webtrit_callkeep version, see Release Versioning.

Version-based Flavor Selection Flavors

The build logic dynamically adapts to the VERSION specified in the root-level build.config file:

VERSION=0.0.2

This versioning ensures backward compatibility with older versions that do not use flavors.

Depending on the version:

  • legacy: flavors are not used
  • v0.0.1: only deeplink flavor is applied
  • v0.0.2+: both deeplink and SMS flavors are combined

Version logic is used to determine the correct flavor flags for build and run commands.

In the future, iOS flavor support may be added similarly

Dart Defines Based Flavor Computation

Values are parsed from dart_define.json:

  • WEBTRIT_APP_LINK_DOMAIN → determines deeplink flavor
  • WEBTRIT_CALL_TRIGGER_MECHANISM_SMS → determines smsReceiver flavor

Example combined flavor:

--flavor deeplinkssmsReceiverDisabled

This ensures only required Android permissions or receivers are included in the app build.

Build Commands

Use melos scripts to build. Extra Flutter flags are passed via the FLUTTER_FLAGS environment variable.

Command Description
melos run build:apk Build Android APK
melos run build:appbundle Build Android App Bundle
melos run build:ios Build iOS app
melos run build:ios:config Configure Xcode project only (no build)

Examples

# Debug build (default)
melos run build:apk

# Release build
FLUTTER_FLAGS="--release" melos run build:apk
FLUTTER_FLAGS="--release" melos run build:appbundle
FLUTTER_FLAGS="--release --no-codesign" melos run build:ios

# Custom version
FLUTTER_FLAGS="--build-name=1.2.3 --build-number=42 --release" melos run build:apk

All build commands read configuration from dart_define.json automatically.

Run Commands

Command Description
melos run start:android Run on Android with dart_define.json
melos run start:ios Run on iOS device/simulator

Examples

# Run on Android
melos run start:android

# Run on specific Android device
FLUTTER_FLAGS="-d emulator-5554" melos run start:android

# Run on iOS
melos run start:ios

Development Workflow Notes

During development you may need to adjust your environment manually to work efficiently with flavors.

Options:

  • Terminal (recommended):

    Use melos scripts from the project root:

    melos run start
melos run start:ios

  • IDE Configuration:

    In IntelliJ IDEA or Android Studio, sync run configurations via melos run ide:sync, then use the generated run configurations from .idea/runConfigurations/.

  • Manual Flavor Selection:

    When running directly from the IDE without melos, manually pass the correct --flavor (e.g., --flavor deeplinkssmsReceiverDisabled) in your launch configuration to match the current dart_define.json.

Tip:

  • Stick to a single flavor during development (e.g., the one most commonly enabled)
  • Run melos run ide:sync after updating run configurations in tool/run/

Melos scripts work best for CI/CD and structured builds. For day-to-day IDE development, use the synced run configurations or pass flags manually.

Flutter Version Configuration

The Flutter SDK version used for building the project is pinned in .fvmrc — the single source of truth, read by fvm locally and by the webtrit_phone_builder CI.

Format

{
  "flutter": "3.44.0"
}

Purpose

By declaring the Flutter version here:

  • One file drives both local development (fvm flutter ...) and CI — no drift between them
  • You avoid hardcoding versions in CI workflows
  • Builds remain reproducible and predictable

Install the pinned SDK once per machine with fvm install. The downloaded .fvm/ cache is gitignored.

The channel is implied by the pinned version (we ship exact stable releases). The CI defaults the channel to stable.

When to update

Update .fvmrc when:

  • You upgrade the Flutter SDK in local development
  • You have tested that the project works with the new version
  • You want to ensure CI uses the updated version

Keep the version noted in AGENTS.md in sync, and always validate builds locally before changing this file.

Legacy note: .github/flutter_version.yaml was the previous source. It was removed once .fvmrc became the single source and webtrit_phone_builder was updated to read it. Older release branches may still carry the yaml; the builder falls back to it there.