|
| 1 | +# Flutter Builder |
| 2 | + |
| 3 | +English | [简体中文](../../zh-Hans/builders/flutter.md) |
| 4 | + |
| 5 | +Flutter Builder invokes the Flutter CLI from the project environment, builds for a platform, locates raw artifacts, and returns a normalized build result. The top-level `fastforge build` command currently uses this builder directly. |
| 6 | + |
| 7 | +## Project Requirements |
| 8 | + |
| 9 | +- Run from the root of a project containing `pubspec.yaml` |
| 10 | +- Install the Flutter SDK and make `flutter` available in `PATH` |
| 11 | +- Prepare the target platform SDK, signing configuration, and build tools |
| 12 | + |
| 13 | +The builder reads `version` from `pubspec.yaml` and passes the version name and build number through `FLUTTER_BUILD_NAME` and `FLUTTER_BUILD_NUMBER` respectively. |
| 14 | + |
| 15 | +## Platforms and Targets |
| 16 | + |
| 17 | +| Platform | Target | Output | |
| 18 | +| --------- | ---------------- | -------------- | |
| 19 | +| `android` | `apk` | APK | |
| 20 | +| `android` | `aab` | AAB | |
| 21 | +| `ios` | `ipa` or omitted | IPA | |
| 22 | +| `macos` | May be omitted | `.app` | |
| 23 | +| `windows` | May be omitted | Windows bundle | |
| 24 | +| `linux` | May be omitted | Linux bundle | |
| 25 | +| `web` | May be omitted | Web directory | |
| 26 | +| `ohos` | `hap`, `app` | HAP or APP | |
| 27 | + |
| 28 | +## Common Commands |
| 29 | + |
| 30 | +```bash |
| 31 | +fastforge build --platform android --target apk |
| 32 | +fastforge build --platform web |
| 33 | +fastforge build --platform macos |
| 34 | +``` |
| 35 | + |
| 36 | +An iOS IPA requires export configuration: |
| 37 | + |
| 38 | +```bash |
| 39 | +fastforge build --platform ios --target ipa \ |
| 40 | + --build-export-options-plist ios/ExportOptions.plist |
| 41 | +``` |
| 42 | + |
| 43 | +You can also use `--build-export-method`. |
| 44 | + |
| 45 | +## Build Options |
| 46 | + |
| 47 | +| Fastforge option | Effect | |
| 48 | +| ------------------------------- | -------------------------------------- | |
| 49 | +| `--clean` | Clean before building | |
| 50 | +| `--build-target` | Use a custom entry point | |
| 51 | +| `--build-flavor` | Select a flavor | |
| 52 | +| `--build-target-platform` | Select target architectures | |
| 53 | +| `--build-export-options-plist` | Provide iOS export configuration | |
| 54 | +| `--build-export-method` | Select an iOS export method | |
| 55 | +| `--build-dart-define KEY=VALUE` | Compile-time variable; repeatable | |
| 56 | +| `--build-obfuscate` | Enable obfuscation | |
| 57 | +| `--build-split-debug-info` | Set the debug-symbol output directory | |
| 58 | +| `--build-tree-shake-icons` | Enable icon tree shaking | |
| 59 | +| `--build-profile` | Use Profile mode | |
| 60 | +| `--flutter-build-args` | Other build arguments, comma-separated | |
| 61 | + |
| 62 | +Within `--flutter-build-args`, entries without an equals sign are treated as boolean switches, while `key=value` entries become key-value arguments. Do not use this option when a value itself contains a comma. |
| 63 | + |
| 64 | +## Artifact Locations |
| 65 | + |
| 66 | +| Platform | Default search location | |
| 67 | +| --------------- | --------------------------------------------- | |
| 68 | +| Android APK | `build/app/outputs/flutter-apk/` | |
| 69 | +| Android AAB | `build/app/outputs/bundle/` | |
| 70 | +| iOS | `build/ios/ipa/` | |
| 71 | +| macOS | `build/macos/Build/Products/` | |
| 72 | +| Windows | `build/windows/<arch>/runner/<mode>/` | |
| 73 | +| Linux | `build/linux/<arch>/<mode>/bundle/` | |
| 74 | +| Web | `build/web/` | |
| 75 | +| OpenHarmony HAP | `ohos/entry/build/<flavor>/outputs/<flavor>/` | |
| 76 | +| OpenHarmony APP | `ohos/build/outputs/<flavor>/` | |
| 77 | + |
| 78 | +Fastforge reports a failure if the build command succeeds but no artifact is found in the expected directory. |
| 79 | + |
| 80 | +## Relationship to Packagers |
| 81 | + |
| 82 | +Flutter Builder can build all platforms listed above, but `fastforge package` currently connects only its macOS DMG, PKG, and ZIP paths. When a Flutter project runs `fastforge package` for another platform, the build completes normally and then fails with `Unsupported package target` because the matching packager is not connected. Use `fastforge build` to generate the raw artifact first. |
| 83 | + |
| 84 | +## Host Restrictions |
| 85 | + |
| 86 | +- iOS and macOS builds run only on macOS. |
| 87 | +- Windows builds run only on Windows. |
| 88 | +- Linux builds run only on Linux. |
| 89 | +- Android, Web, and OpenHarmony builders do not enforce a fixed host, but still require the relevant platform toolchains. |
0 commit comments