Engine Builds

Build the Flutter engine from source, run apps with your local engine, and manage build outputs.

Prerequisite: You must first set up the contributor environment with flutter_compile install flutter and flutter_compile install engine. See Contributor Setup.

Building the Engine

flutter_compile build engine

By default this builds a debug, unoptimized build for the host platform. The build process has two steps:

GN — generates ninja build files (auto-skipped if build.ninja already exists)
Ninja — compiles the engine

Depot_tools is automatically prepended to PATH during the build.

Platform and architecture

# Build for Android ARM64
flutter_compile build engine --platform android --cpu arm64

# Build for iOS simulator
flutter_compile build engine --platform ios --simulator

# Build for macOS
flutter_compile build engine --platform macos

# Build for Linux
flutter_compile build engine --platform linux

# Build for web
flutter_compile build engine --platform web

Build modes

# Debug (default)
flutter_compile build engine --mode debug

# Profile
flutter_compile build engine --mode profile

# Release
flutter_compile build engine --mode release

Optimized builds

By default, builds use --unoptimized for faster compilation during development. For optimized builds:

flutter_compile build engine --no-unoptimized

All flags

Flag	Short	Default	Description
`--platform`	`-p`	`host`	Target platform: android, ios, macos, linux, web, host
`--cpu`	`-c`	—	Target CPU: arm, arm64, x64
`--mode`	`-m`	`debug`	Build mode: debug, profile, release
`--unoptimized`	—	`true`	Build with --unoptimized (faster dev builds)
`--simulator`	—	`false`	Build for iOS simulator
`--clean`	—	`false`	Clean output before building
`--gn`	—	—	Force re-running GN even if build.ninja exists
`--no-gn`	—	—	Skip GN step entirely

GN Auto-Detection

GN generates the ninja build files based on your platform/mode/cpu configuration. flutter_compile automatically detects whether GN needs to run:

Auto-skip: If build.ninja already exists in the output directory, GN is skipped
Force GN: Use --gn to re-run GN (needed after changing build flags)
Skip GN: Use --no-gn to skip entirely (pure ninja rebuild)

Running With Local Engine

flutter_compile run

This launches your Flutter app using flutter run --local-engine with the matching build configuration. Pass extra arguments to flutter run after --:

# Run on a specific device
flutter_compile run -- -d macos

# Run with a profile build
flutter_compile run --mode profile -- -d chrome

# Run on Android with ARM64
flutter_compile run --platform android --cpu arm64

Testing With Local Engine

flutter_compile test

Same flags as run. Extra arguments are forwarded to flutter test:

# Test specific file
flutter_compile test -- test/widget_test.dart

# Test with profile engine
flutter_compile test --mode profile

Checking Build Status

flutter_compile status

Shows engine configuration and lists all available builds with disk sizes:

Engine Configuration:
  Path: ~/flutter_compile/engine
  Source: exists
  Host CPU: arm64

Available Builds:
  host_debug_unopt     4.2 GB
  android_debug_unopt  1.8 GB

Use --json for machine-readable output.

Cleaning Builds

# List available builds
flutter_compile clean

# Remove a specific build
flutter_compile clean host_debug_unopt

# Remove all builds
flutter_compile clean --all

Build Output Names

Build outputs are named using the pattern: {platform}_{mode}[_unopt]

Configuration	Output Directory Name
Host debug unoptimized	`host_debug_unopt`
Host release	`host_release`
Android debug unopt ARM64	`android_debug_unopt_arm64`
iOS profile	`ios_profile`
iOS simulator debug unopt	`ios_debug_sim_unopt`