Build and tools reference

Lookup material. Nothing here is a how-to; for that, see Install and run the app, Build for Android, Build for iOS and Branding.

Run every command on this page from the project root, the folder that holds pubspec.yaml.

Build flags

The app reads exactly one compile-time flag.

Pass it on any build or run command:

flutter build appbundle --release --dart-define=STORE_RESTRICTED_MODULES=true

There is no flag for the backend address, the keys, an environment or a flavour, and the Android project has no product flavours. All of that comes from assets/config/app_config.json, which is packed into the build as an asset. See the configuration reference.

The standard Flutter flags that matter for this app:

Flutter commands

A configuration change never needs flutter clean. Stop the app and build again; a hot restart does not pick up a changed asset.

The web and desktop folders in the package are not targets. The app does not start on the web.

apply_app_config.dart

Makes the build follow assets/config/app_config.json on both platforms, and prints what each platform will use.

dart run tool/apply_app_config.dart [--check] [--release] [--icons]
                                    [--root <dir>] [--allow-template-id]

Exit codes: 0 done, 1 something must be fixed, 64 a bad command line.

Only the iOS bundle ID and the Apple team are written, because they are Xcode build settings that signing reads before any build phase runs. Everything else is read by the build itself: Gradle reads appName and androidApplicationId on every Android build, the Apply app_config.json phase writes appName into every iOS build, and the app reads the colours when it starts. Run the tool again whenever you change iosBundleId or iosTeamId, and after taking a new release's Xcode project.

What it checks. Every problem is reported at once, with the same rules the build and the app apply:

Any of these keys holding a number or true instead of a string in quotes is an error. The tool does not check the other keys; see the configuration reference.

What it prints. A summary in four blocks, then warnings, then the next step:

Applied assets/config/app_config.json

Name
  in the app             "Acme Exchange"
  Android home screen    "Acme Exchange"  (android/app/build.gradle.kts reads appName on every build)
  iOS home screen        "Acme Exchange"  (the "Apply app_config.json" build phase writes it into every build)

Identifiers
  Android applicationId  com.acme.exchange  (androidApplicationId in app_config.json; Gradle reads it on every build, nothing to write)
  iOS bundle id          com.acme.exchange  (iosBundleId; ...)
  iOS signing team       A1B2C3D4E5  (iosTeamId; ...)

Colours (read by the app at start-up)
  primaryColor           #2F6BFF    custom
  buyColor               #0ECE7A    default
  sellColor              #FF5A5F    default
  accentColor            #1890FF    default

Icon
  assets/icons/app_icon.png: 1024x1024 PNG

Next: dart run tool/release_preflight.dart

With --check the first line reads Checked instead of Applied. Read the Identifiers lines before every release: the first two are the IDs the stores know your app by, and the third is the Apple team the iOS app is signed with.

Without --release, an http:// or ws:// address is printed as a warning starting warning: for a RELEASE build:. With --release it is an error, and the error block starts error: assets/config/app_config.json has 1 problem for a release build:.

Release preflight

Reports every way the project is still the template, and the release mistakes that do not stop a build. It builds nothing and changes nothing.

dart run tool/release_preflight.dart                 # the verdict
dart run tool/release_preflight.dart --explain       # the verdict, and the fix for each item
dart run tool/release_preflight.dart --android-only  # skip the iOS checks

--android-only is for a build that never goes to Apple. It first prints release preflight: --android-only, so the iOS checks were skipped, then drops the iOS findings (ios-name-phase-missing, ios-bundle-id-mismatch, ios-team, ios-team-mismatch, ios-push, and the iOS parts of bundle-id and launcher-icon). Every Android check still runs. The flags combine.

A passing run prints release preflight: this build has been differentiated from the template and exits 0. A failing one prints RELEASE PREFLIGHT FAILED — N item(s) still ours, not yours:, one line per finding as [id] what is wrong, and exits 1. Run it before every release build. The installers run it at the end, as advice only. Why the stores make this a requirement is on Differentiation.

It deliberately does not judge taste. It checks that each decision was made, not whether it was made well.

ios_app_identity.dart

The script the Apply app_config.json build phase of the Runner target runs on every iOS build. You do not run it yourself, except to preview.

dart tool/ios_app_identity.dart --dry-run [--root <dir>]

On each iOS build it:

• writes appName into the built Info.plist (CFBundleDisplayName and CFBundleName), so the tracked ios/Runner/Info.plist never changes;
• stops the build with an error: line when iosBundleId is set and differs from the bundle ID Xcode is signing, saying which side to change;
• warns, without stopping, when app_config.json is missing or empty and the build falls back to the example.

--dry-run prints what an iOS build would do, compares iosBundleId with the Xcode project, and exits 1 with error: [dry run] an iOS build would stop here: ... when a Mac build would stop. It needs no Xcode and writes nothing, so it works on Windows and Linux.

The iOS build runs this file from tool/. Keep the tool/ folder in the project, or every iOS build fails.

The installers

setup/installers/install.sh (macOS and Linux) and setup/installers/install.bat (Windows) walk through a first setup. They find the project root on their own.

In order, they:

Check the file they write before you build for release:

• Choosing "Create new configuration" replaces app_config.json completely. Any key the installer does not ask about is reset or gone afterwards: it writes "iosTeamId": "", so a team you had set is cleared, and it leaves googleAuthEnabled out.
• The Google button follows the client ID you give. With googleAuthEnabled left out, the button shows when you entered a Google client ID and stays hidden when you left it empty. If your Android build takes the client ID from google-services.json instead, add "googleAuthEnabled": true.
• The "app version" answer is only a fallback. The version the app shows comes from the version: line of pubspec.yaml.
• It writes only keys the app reads. It no longer asks for a CryptoCompare key (market news comes from your server) or about "Coming Soon" features (which modules appear is your server's decision), and it writes none of the keys in Keys the app ignores.

run_tests.sh

The package's test suite, as one command. It is a bash script; on Windows, run it from Git Bash. It needs flutter on the PATH.

./run_tests.sh               # static analysis, then every suite
./run_tests.sh contract      # only test/contract
./run_tests.sh --no-analyze  # skip static analysis
./run_tests.sh --help

It runs flutter pub get (the one stage that stops the run on failure), flutter analyze, then flutter test on each suite in this order:

Every stage runs even after one fails. The last lines say ALL GREEN, GREEN, for what ran (with a NOT RUN: line naming any suite folder that is missing), or FAILED: with the stages that failed. The exit code is 1 when anything failed.

The restricted-modules test is written to pass both ways. To check a build with the flag on:

flutter test --dart-define=STORE_RESTRICTED_MODULES=true test/features/dashboard/opt_in_modules_test.dart

flutter_launcher_icons

The icon generator, configured in the flutter_launcher_icons: section of pubspec.yaml. It reads assets/icons/app_icon.png and writes every Android and iOS launcher icon, and the web icons. It makes no Android adaptive icon: the android_adaptive_icon: block in that section is not a setting the generator's version (0.13.1) reads.

dart run flutter_launcher_icons

Prefer dart run tool/apply_app_config.dart --icons. It runs the same generator, but first refuses the shipped placeholder and warns about an icon that is not square or is smaller than 1024x1024. Replacing the PNG changes nothing until one of the two has run; the preflight reports stale icons as launcher-icon.

What the build prints

Three lines come from android/app/build.gradle.kts on Android builds. Flutter's normal output filters them out, so look for them in a --verbose build:

Gradle stops the build, whatever the verbosity, on a config it cannot use: assets/config/app_config.json is not valid JSON (at line N column M), an appName or androidApplicationId that must be a string in quotes, an appName that contains a control character, or an androidApplicationId that is not a valid Android application ID. More build messages are on Build for Android and Troubleshooting.