Builders

July 18, 2026 · View on GitHub

English | 简体中文

Builders select a project's build tool, run the build command, and locate generated artifacts. Packagers consume build results; the two have distinct responsibilities.

Current Builders

BuilderPlatforms or targetsCLI integrationDocumentation
Gradle AndroidAndroid APK, AABConnected through packageGradle
Gradle MultiplatformAndroid, desktop, iOS frameworkNo top-level CLI integrationGradle
XcodeiOS IPA, macOS .appConnected to the package actionXcode
FlutterAndroid, iOS, macOS, Windows, Linux, Web, OpenHarmonyConnected to build; package for macOS onlyFlutter Builder
CustomUser-defined commands and artifact rulesNo top-level CLI integrationCustom Builder

“Implemented” and “connected to the CLI” are different states. A builder without a top-level entry point cannot be selected directly through fastforge build.

Current Routing

fastforge package and the fastforge/package action select a build path based on the presence of pubspec.yaml in the project root and the value of --platform:

  1. No pubspec.yaml, and the platform is macos or ios: select Xcode Builder.
  2. No pubspec.yaml, and the platform is android: select Gradle Builder.
  3. Otherwise, including every Flutter project with pubspec.yaml: select Flutter Builder.

Important

The Flutter Builder path is currently connected only to the macOS dmg, pkg, and zip packagers. Running fastforge package --platform android or --platform ios in a Flutter project completes the build, then fails because the corresponding packager is not connected. Use fastforge build to generate the raw artifact instead.

The current detection rules are intentionally simple. Run commands from the actual project root to avoid selecting the wrong builder.

Choosing an Entry Point

  • Native Android Gradle projects: use fastforge package or the workflow package action.
  • Native iOS / macOS Xcode projects: use the workflow package action and pass project arguments through build-args.
  • Flutter projects packaging macOS formats: use fastforge package; for other platforms, generate raw artifacts with fastforge build.
  • Builders without CLI integration: continue to use the project's own build commands; do not assume the Fastforge CLI supports them yet.

See Building for build commands and the result structure.