flutter_compile 0.9.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>

After activation, both flutter_compile and the shorter fcp alias are available:

fcp sdk list          # same as flutter_compile sdk list
fcp sync flutter      # same as flutter_compile sync flutter

Requirements: macOS, Linux, or Windows; git, python3. On Windows, Visual Studio with C++ workload is required for engine builds.

---

Quick Reference

Every command at a glance. Detailed usage follows below.

Command	Alias	Description
install flutter	i flutter	Clone flutter/flutter, set up git remotes, run update-packages
install devtools	i devtools	Clone flutter/devtools, configure PATH for devtools_tool
install engine	i engine	Install depot_tools, generate .gclient, run gclient sync, set up remotes
uninstall <env>	delete, remove	Remove an installed contributor environment and clean up config
switch [mode]	s	Toggle PATH between contributor-built Flutter and system Flutter
sync	sy	Sync all contributor environments with upstream in one shot
sync flutter	sy flutter	git fetch upstream + git rebase upstream/master + flutter update-packages
sync engine	sy engine	git fetch upstream + git rebase upstream/main + gclient sync
sync devtools	sy devtools	git fetch upstream + git rebase upstream/master
build engine	b engine	Run GN + ninja to compile the Flutter engine for a target platform
run	r	Run a Flutter app using a locally-built engine
test	t	Run Flutter tests using a locally-built engine
clean	c	List or delete engine build output directories
status	st	Show engine path, available builds, host CPU, project detection
sdk install <ver>		Install a Flutter SDK by version tag or channel name
sdk list	sdk ls	List all installed SDKs with global/project markers
sdk remove <ver>		Delete an installed SDK and clean up config if needed
sdk global [ver]		Set or show the global default SDK version
sdk use [ver]		Pin or show the per-project SDK version (.flutter-version)
sdk exec <cmd>		Run any command through the resolved SDK (project -> global)
config list	cf list	Display all ~/.flutter_compilerc entries
config get <key>	cf get	Read a single config value
config set <k> <v>	cf set	Write a config value
doctor	dr	Health-check required tools, config file, and contributor environments
update	up	Self-update flutter_compile to the latest pub version

---

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.

sdk install — Install an SDK

Downloads and installs a Flutter SDK. The first install automatically becomes the global default.

flutter_compile sdk install 3.19.0    # Specific version tag
flutter_compile sdk install stable    # Channel name
flutter_compile sdk install beta

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

sdk list (alias: ls) — List installed SDKs

Shows all installed SDK versions with their paths. Marks which version is set as the global default and which is pinned to the current project.

flutter_compile sdk list
# Output:
#   3.19.0    /Users/you/flutter_compile/versions/3.19.0  (global)
#   stable    /Users/you/flutter_compile/versions/stable   (project)

sdk global — Set or show global default

Sets the global default SDK version. This is the version used when no project-level .flutter-version file exists. Running without an argument shows the current global version.

flutter_compile sdk global 3.19.0     # Set 3.19.0 as the global default
flutter_compile sdk global            # Show current global version

Setting a global version updates your shell config (~/.zshrc / ~/.bashrc) with the SDK bin/ directory and an isolated PUB_CACHE.

sdk use — Pin a version per project

Creates a .flutter-version file in the current directory. When sdk exec is used from this directory, it picks up the pinned version instead of the global default.

flutter_compile sdk use 3.19.0        # Pin 3.19.0 for this project
flutter_compile sdk use               # Show currently pinned version

sdk exec — Run commands through the resolved SDK

Executes any command using the resolved Flutter SDK. Resolution order: project .flutter-version first, then global default.

This is the key command for multi-version workflows — it ensures flutter, dart, and any other SDK tool run from the correct version without manually switching PATH.

flutter_compile sdk exec flutter doctor
flutter_compile sdk exec dart analyze
flutter_compile sdk exec flutter build apk
flutter_compile sdk exec dart run build_runner build

The resolved SDK's bin/ is prepended to PATH and its isolated PUB_CACHE is set, so all tools (flutter, dart, pub) operate in the correct version context.

sdk remove — Remove an installed SDK

Deletes the SDK directory. If you remove the current global default, the rc config and shell PATH block are cleaned up automatically.

flutter_compile sdk remove 3.19.0

---

Contributor Environment Setup

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

install (alias: i) — Set up a contributor environment

Each subcommand clones the relevant repository, configures git remotes (upstream = flutter org, origin = your fork), and performs environment-specific setup.

install flutter — Clones flutter/flutter, sets up git remotes, runs flutter update-packages, and optionally configures IDE settings for IntelliJ.

install devtools — Clones flutter/devtools, configures git remotes, and adds devtools_tool to your PATH.

install engine — The most involved setup. Installs depot_tools (Google's build toolchain), generates a .gclient configuration pointing to your engine fork, runs gclient sync (20-40 min on first run), and configures git remotes.

flutter_compile install flutter
flutter_compile install devtools
flutter_compile install engine
flutter_compile install engine --platform android

uninstall (aliases: delete, remove) — Remove a contributor environment

Removes the cloned repository directory, cleans PATH exports from your shell config, and removes the path entry from ~/.flutter_compilerc.

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

switch (alias: s) — Toggle Flutter PATH

Toggles your PATH between the contributor-built Flutter (from install flutter) and your normal system Flutter installation. Useful when you want to quickly move between contributing to the framework and using a release Flutter.

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

After switching, restart your terminal or source your shell config for the change to take effect.

---

Sync

Keep contributor environments up to date with upstream. Each sync subcommand fetches the latest changes from the upstream Flutter organization and rebases your local branch on top.

sync (alias: sy) — Sync all environments

When run without a subcommand, syncs all three environments sequentially. Each environment is synced independently — if one fails, the others still run. A summary at the end reports which succeeded and which failed.

flutter_compile sync
# Syncs flutter, engine, and devtools in order.
# Reports: "Synced: flutter, devtools" / "Failed: engine"

sync flutter — Sync the framework

Fetches from upstream, rebases on upstream/master, and runs flutter update-packages to keep dependencies current.

flutter_compile sync flutter

sync engine — Sync the engine

Fetches from upstream in the src/flutter subdirectory, rebases on upstream/main, then runs gclient sync to update all engine dependencies. After syncing, prints a reminder to rebuild.

flutter_compile sync engine
# → "Run "flutter_compile build engine" to rebuild."

sync devtools — Sync DevTools

Fetches from upstream and rebases on upstream/master.

flutter_compile sync devtools

Each sync subcommand reads its install path from ~/.flutter_compilerc. If an environment hasn't been installed yet, it prints an error suggesting you run install first.

---

Engine Workflow

Build, run, and test with a locally-built Flutter engine. These commands wrap the GN + ninja build system and the --local-engine flags so you don't have to remember them.

build engine (alias: b) — Compile the engine

Runs GN (flag resolution) then ninja (compilation) for the specified target. GN is auto-skipped on incremental rebuilds when build.ninja already exists in the output directory.

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 entirely
flutter_compile build engine --clean                      # Clean build (removes output dir first)

run (alias: r) — Run with local engine

Runs a Flutter app using your locally-built engine. Automatically resolves --local-engine and --local-engine-src-path from your config and the last build target.

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) — Test with local engine

Runs Flutter tests using your locally-built engine, with the same automatic --local-engine resolution as run.

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) — Manage build outputs

Lists engine build directories with their disk sizes, or deletes specific builds.

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) — Show engine status

Displays engine configuration: engine path, source directory status, host CPU architecture, available build directories with disk sizes, and whether the current directory contains a Flutter project.

flutter_compile status
# Engine path: /Users/you/flutter_compile/engine
# Source dir:  /Users/you/flutter_compile/engine/src [OK]
# Host CPU:    arm64
#
# Available builds:
#   host_debug_unopt_arm64         4.2G
#   android_debug_unopt_arm64      2.1G
#
# Flutter project: yes (pubspec.yaml found)

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) — Manage settings

Read and write ~/.flutter_compilerc, the central config file that stores paths to contributor environments, depot_tools, and the global SDK version.

config list — Show all stored key-value pairs.

config get <key> — Read a single value. Accepts friendly names (flutter, engine, devtools, depot_tools, global_sdk) which map to their internal key names.

config set <key> <value> — Write a value. Useful for manually correcting paths if you moved a directory.

flutter_compile config list
flutter_compile config get engine
flutter_compile config set engine /new/path/to/engine

doctor (alias: dr) — Health check

Checks that required tools are installed (git, python3, dart, flutter), engine tools are available (gclient, ninja, Xcode on macOS), ~/.flutter_compilerc is valid, and each contributor environment has correct git remotes (upstream + origin).

flutter_compile doctor
# [+] git is installed
# [+] python3 is installed
# [+] dart is installed
# [+] flutter is installed
# [+] depot_tools (gclient) is installed
# [+] ninja is installed
# [+] .flutter_compilerc is valid
# [+] Flutter contributor environment: installed
# [-] DevTools contributor environment: not configured
# [+] Engine contributor environment: installed

update (alias: up) — Self-update

Checks pub.dev for a newer version of flutter_compile and updates if available.

flutter_compile update

JSON Output

Several commands support --json for machine-readable output, useful for IDE extensions and scripting:

flutter_compile sdk list --json        # JSON array of installed SDKs
flutter_compile doctor --json          # Health checks as JSON array
flutter_compile config list --json     # Config as JSON object
flutter_compile status --json          # Engine status as JSON object

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

---