Fastforge Documentation

app_builder is the Rust implementation of the Fastforge Flutter build orchestration layer. It ensures that build parameters and output structures are consistent with the Dart implementation of Fastforge.

Key capabilities include:

• Encoding build parameters following Dart-compatible rules.
• Generating build result JSON structures compatible with Dart.
• Multi-platform builder registration and routing.
• Automatic injection of FLUTTER_BUILD_NAME and FLUTTER_BUILD_NUMBER from pubspec.yaml.
• Support for the FLUTTER_ROOT environment variable.

Fastforge is a CLI tool designed for app building, packaging, and publishing. Its current capabilities include:

• App package analysis: Fully implemented for APK, AAB, IPA, DMG, and .app files.
• Publishing: Multiple targets are implemented for artifact distribution.
• Store Management: Full implementation for App Store Connect, Google Play Console, and multi-store catalog synchronization.
• Local Workflows: Fully implemented via .fastforge/workflows.
• Packaging & Builders: Android, iOS, and macOS packaging, as well as various builders (Gradle, Xcode, Flutter), are currently partially implemented.

Note: Features like fastforge upgrade and online version checks are currently not implemented.

Fastforge provides three primary entry points for store management:

• fastforge appstore: Interacts with the App Store Connect API to manage builds and reviews.
• fastforge googleplay: Manages Google Play edits, AABs, and tracks.
• fastforge store: A unified command to process multiple configured store apps defined in your project configuration.

Fastforge currently supports the following platforms and output formats via the package command:

Important Platform Constraints:

• Flutter Projects: The fastforge package command currently supports only the three macOS formats (DMG, PKG, ZIP).
• Native Projects: The Android (APK, AAB) and iOS (IPA) packaging paths are only available for native projects that do not contain a pubspec.yaml file.

You can use environment variables within your distribute_options.yaml file to handle sensitive information like API keys. Use the ${VARIABLE_NAME} syntax to reference an environment variable.

variables:
  API_KEY: ${PGYER_API_KEY} # Uses the PGYER_API_KEY environment variable

You can include custom logic that runs during the package installation process by providing a directory of executable scripts.

Directory Structure

If you provide a path to the scripts option in make_config.yaml, the directory should follow this structure:

macos/packaging/pkg/
├── make_config.yaml
└── scripts/
    ├── preinstall     # Runs before file installation
    └── postinstall    # Runs after file installation

Requirements

• Naming: Scripts must be named exactly preinstall or postinstall.
• Permissions: Scripts must be executable (chmod +x).
• Privileges: Scripts run as root during installation.

When passing arguments to the builder, app_builder encodes them to match Dart's behavior:

When a .deb package is installed, Fastforge follows the Filesystem Hierarchy Standard (FHS) for third-party software. The application files are placed as follows:

Builders are responsible for selecting a project's build tool, executing the build command, and locating the resulting artifacts.

It is important to distinguish between Builders and Packagers:

• Builders generate the raw build artifacts (e.g., an APK or an IPA).
• Packagers consume those artifacts to create distributable formats (e.g., a .dmg or a .zip).

Note that a builder being 'implemented' is different from it being 'connected to the CLI'. If a builder lacks top-level CLI integration, you cannot select it directly via fastforge build and should instead use the project's native build commands.

The custom target allows you to execute an arbitrary script or command to publish your application artifact. This is the recommended approach when you need to integrate with a publishing platform that is not natively supported by fastforge.

When the command is executed, fastforge provides the path to the artifact via the ARTIFACT_PATH environment variable. You can also pass additional arguments which will be available as environment variables prefixed with PUBLISH_ARG_ (converted to uppercase with dashes replaced by underscores).

#!/bin/sh
set -e
echo "Publishing artifact: $ARTIFACT_PATH"
# Add your custom publish logic here

A Custom Builder is a mechanism that runs an arbitrary command and collects resulting files using glob patterns.

Important Note: As of the current version, the Custom Builder is not yet integrated into the top-level fastforge build or fastforge package commands. It is currently intended to be used as a manual step within a workflow rather than via a CLI flag like --platform custom (which does not exist).