flutter_compile 0.8.0

A CLI that automates Flutter framework, DevTools, and engine contributor environment setup — depot_tools, gclient sync, GN flags, and ninja builds.

flutter_compile

A Dart CLI for Flutter contributors and power users. Automates contributor environment setup (framework, DevTools, engine), manages multiple Flutter SDK versions side-by-side, and wraps the engine build/run/test cycle into simple commands.

---

Getting Started

dart pub global activate flutter_compile

Or from source:

dart pub global activate --source=path <path to this package>

Requirements: macOS or Linux, git, python3

---

SDK Management

Install and manage multiple Flutter SDK versions side-by-side — by version tag or channel. Each SDK gets its own isolated PUB_CACHE to avoid snapshot incompatibility.

# Install a specific version or channel
flutter_compile sdk install 3.19.0
flutter_compile sdk install stable
flutter_compile sdk install beta

# List all installed SDKs (shows global/project markers)
flutter_compile sdk list

# Set the global default SDK (updates PATH and PUB_CACHE in shell config)
flutter_compile sdk global 3.19.0
flutter_compile sdk global             # Show current global version

# Pin an SDK version for the current project (.flutter-version)
flutter_compile sdk use 3.19.0
flutter_compile sdk use                # Show current project version

# Run a command through the resolved SDK (project → global)
flutter_compile sdk exec flutter doctor
flutter_compile sdk exec dart analyze
flutter_compile sdk exec flutter build apk

# Remove an SDK (cleans up global config if removing the global default)
flutter_compile sdk remove 3.19.0

The first sdk install automatically sets the installed version as the global default. Resolution order for sdk exec: project .flutter-version → global default.

SDKs are stored in ~/.flutter_compile/versions/<version>/, each with its own .pub-cache directory.

---

Contributor Environment Setup

One-command setup for Flutter framework, DevTools, and engine contributor environments. Replaces the multi-step wiki guides.

install (alias: i)

flutter_compile install flutter    # Framework contributor environment
flutter_compile install devtools   # DevTools contributor environment
flutter_compile install engine     # Engine contributor environment (default: host platform)
flutter_compile install engine --platform android

The engine install automates:

• depot_tools installation and PATH configuration
• .gclient file generation with your fork URL
• gclient sync (streams output — takes 20-40 min on first run)
• Git remote setup (upstream = flutter/engine, origin = your fork)

uninstall (aliases: delete, remove)

flutter_compile uninstall flutter
flutter_compile uninstall devtools
flutter_compile uninstall engine    # optionally removes depot_tools too

switch (alias: s)

Toggle your PATH between the contributor-built Flutter (from install flutter) and your system Flutter installation.

flutter_compile switch             # Toggle to whichever isn't active
flutter_compile switch compiled    # Use the contributor-built Flutter
flutter_compile switch normal      # Use your system Flutter

---

Engine Workflow

Build, run, and test with a locally-built Flutter engine.

build engine (alias: b)

flutter_compile build engine                              # Host platform, debug, unoptimized
flutter_compile build engine --platform android --cpu arm64
flutter_compile build engine --platform ios --simulator
flutter_compile build engine --mode release --no-unoptimized
flutter_compile build engine --gn                         # Force GN re-run
flutter_compile build engine --no-gn                      # Skip GN step
flutter_compile build engine --clean                      # Clean build

GN is auto-skipped on incremental rebuilds when build.ninja already exists.

run (alias: r)

Run a Flutter app with a local engine build.

flutter_compile run
flutter_compile run -p android -c arm64
flutter_compile run -p ios --simulator -- -d "iPhone 15"

Everything after -- is forwarded to flutter run.

test (alias: t)

Run Flutter tests with a local engine build.

flutter_compile test
flutter_compile test -p android -c arm64
flutter_compile test -- test/my_widget_test.dart

Everything after -- is forwarded to flutter test.

clean (alias: c)

flutter_compile clean                        # List builds with sizes
flutter_compile clean host_debug_unopt_arm64  # Delete a specific build
flutter_compile clean --all                   # Delete all builds

status (alias: st)

flutter_compile status

Displays engine path, source directory status, host CPU, available build directories with sizes, and whether the current directory is a Flutter project.

Engine options

These options are shared by build engine, run, and test:

Option	Values	Default
--platform, -p	android, ios, macos, linux, web, host	host
--cpu, -c	arm, arm64, x64	auto-detected
--mode, -m	debug, profile, release	debug
--unoptimized	flag	true
--simulator	flag (iOS only)	false

build engine also accepts --clean, --gn, and --no-gn.

---

Configuration & Maintenance

config (alias: cf)

flutter_compile config list               # Show all settings
flutter_compile config get engine          # Get a value (flutter, engine, devtools, depot_tools)
flutter_compile config set engine /path    # Set a value

doctor (alias: dr)

flutter_compile doctor

Reports status of required tools (git, python3, dart, flutter), engine tools (depot_tools, ninja, Xcode), config file, and contributor environments.

update (alias: up)

flutter_compile update

Other

flutter_compile --version
flutter_compile --help

---

Running Tests

dart test

With coverage:

dart pub global activate coverage 1.2.0
dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info
genhtml coverage/lcov.info -o coverage/
open coverage/index.html

---