构建系统与任务编排

相关源文件

• .github/workflows/android_ci.yaml.bak
• .github/workflows/release.yml
• .github/workflows/rust_coverage.yml
• CHANGELOG.md
• frontend/.vscode/launch.json
• frontend/.vscode/tasks.json
• frontend/Makefile.toml
• frontend/scripts/docker-buildfiles/Dockerfile
• frontend/scripts/docker-buildfiles/docker-compose.yml
• frontend/scripts/install_dev_env/install_linux.sh
• frontend/scripts/install_dev_env/install_macos.sh
• frontend/scripts/install_dev_env/install_windows.sh
• frontend/scripts/makefile/flutter.toml
• frontend/scripts/makefile/tool.toml

本文档涵盖了 AppFlowy 的构建系统架构、使用 cargo-make 进行任务编排、跨平台构建流程以及 CI/CD 流水线集成。构建系统协调 Rust 后端和 Flutter 前端在包括桌面（Windows、macOS、Linux）和移动端（iOS、Android）在内的多个平台上的编译。

有关实际 CI/CD 流水线工作流程和测试的信息，请参阅 CI/CD 流水线和测试。

构建系统架构

AppFlowy 采用复杂的、多层次的构建系统，可协调不同平台和技术之间的编译。

来源：frontend/Makefile.toml1-311 frontend/scripts/makefile/flutter.toml1-332 frontend/scripts/makefile/tool.toml1-112

cargo-make 任务编排

构建系统围绕 cargo-make 展开，它通过声明式的 TOML 配置提供跨平台任务编排。主配置为不同的构建场景定义了环境配置文件。

环境配置文件和变量

AppFlowy 为每个平台和构建类型组合定义了特定的环境配置文件。

配置文件	平台	架构	构建类型	Crate 类型
development-mac-arm64	macOS	ARM64	调试	staticlib
production-mac-universal	macOS	通用	发布	staticlib
development-windows-x86	Windows	x86_64	调试	cdylib
production-linux-x86_64	Linux	x86_64	发布	cdylib
development-android	Android	Multi-arch	调试	cdylib

关键环境变量控制构建过程。

• RUST_COMPILE_TARGET：Rust 目标三元组（例如 aarch64-apple-darwin）
• CRATE_TYPE：库类型（iOS/macOS 为 staticlib，其他为 cdylib）
• BUILD_FLAG：Debug 或 release 模式
• FLUTTER_DESKTOP_FEATURES：不同平台的特性标志。

来源：frontend/Makefile.toml60-218

任务依赖图

构建过程遵循明确定义的依赖链。

来源：frontend/Makefile.toml16-21 frontend/scripts/makefile/flutter.toml6-41

动态 Crate 类型管理

构建系统使用 duckscript 根据目标平台动态修改 Rust Crate 配置。

这使得同一代码库可以在不维护单独配置文件的情况下生成不同的库类型（iOS/macOS 的静态库，其他平台的动态库）。

来源：frontend/Makefile.toml235-257

特定平台构建流程

桌面平台

桌面构建遵循统一模式，带有平台特定变体。

来源：frontend/scripts/makefile/flutter.toml6-41 .github/workflows/release.yml126-462

移动平台

移动端构建需要额外的配置以实现交叉编译和平台特定的工具链。

iOS 构建流程

• 为 aarch64-apple-ios 和 aarch64-apple-ios-sim 编译 Rust。
• 使用 staticlib Crate 类型进行原生集成。
• 构建启用了混淆和调试符号的 Flutter iOS 应用。
• 生成用于分发的 .ipa 文件。

Android 构建流程

• 交叉编译 Rust 以支持多种 Android 架构。
• 使用 cdylib Crate 类型进行 JNI 集成。
• 支持用于开发环境的 debug 构建和具有混淆功能的 release 构建。
• 按架构拆分生成 APK 文件。

来源：frontend/scripts/makefile/flutter.toml43-82 frontend/Makefile.toml178-218

CI/CD 流水线集成

发布流水线架构

GitHub Actions 发布流水线负责编排多平台构建。

来源：.github/workflows/release.yml1-522

构建环境一致性

CI/CD 系统确保跨平台构建环境的一致性。

• Flutter 版本：所有构建均固定为 3.27.4
• Rust 工具链：锁定为 1.85.0 以实现可重现的构建。
• 构建工具：特定版本的 cargo-make 和 duckscript_cli。
• 依赖项：特定于平台的包安装确保所有必需的库都可用。

来源：.github/workflows/release.yml9-11 frontend/scripts/install_dev_env/install_linux.sh39-58

开发环境集成

VS Code 集成

构建系统通过任务和启动配置与 VS Code 集成。

构建任务

• AF: Build Appflowy Core：为当前平台编译 Rust 后端。
• AF: Clean + Rebuild All：执行完整的清理和重建，包括代码生成。
• AF: Code Gen：重新生成 Dart 和 Protocol Buffer 文件。

启动配置

• AF: Build Dart Only：仅 Flutter 开发模式。
• AF-desktop: Build All：带有 Rust 后端的完整桌面构建。
• AF-iOS/Android: Build All：移动平台构建。

来源：frontend/.vscode/tasks.json1-257 frontend/.vscode/launch.json1-126

代码生成流程

构建系统包含多个组件的自动化代码生成。

来源：frontend/.vscode/tasks.json174-235 frontend/scripts/makefile/flutter.toml301-331

Docker构建系统

容器化构建流程

AppFlowy 提供基于 Docker 的构建系统，以实现一致、可重现的构建。

构建阶段

1. Builder 阶段：完整的开发环境，包含 Rust、Flutter 和所有构建工具。
2. Runtime 阶段：最小化的运行时环境，仅包含必需的依赖项。

关键构建命令

来源：frontend/scripts/docker-buildfiles/Dockerfile1-86 frontend/scripts/docker-buildfiles/docker-compose.yml1-28

开发环境设置

构建系统包含用于不同平台的自动化设置脚本。

Linux 设置（install_linux.sh）

• 安装 Rust 工具链和 Flutter。
• 配置桌面开发环境。
• 安装系统依赖（keybinder、libnotify、mpv）。
• 设置 git hooks 和开发工具。

macOS 设置（install_macos.sh）

• 使用 Homebrew 进行依赖管理。
• 配置代码签名和公证工具。
• 为 macOS 桌面开发设置 Flutter。

Windows 设置（install_windows.sh）

• 处理 vcpkg 集成以支持原生依赖项。
• 配置开发工具的 PATH 变量。
• 设置特定于 Windows 的构建环境。

来源： frontend/scripts/install_dev_env/install_linux.sh1-119 frontend/scripts/install_dev_env/install_macos.sh1-94 frontend/scripts/install_dev_env/install_windows.sh1-113