4.1 构建指南

TIP

仅当您准备开发 MaaFramework 本身时，才需要阅读本章节内容。若您仅希望基于 MaaFramework 开发自己的应用，则请参考 快速开始。

开始前，请确保已安装 Git、Python 3、CMake 3.24+，以及对应平台的编译链（Windows: MSVC 2022；Linux/macOS: Ninja + g++/clang）。

本地开发

1. 完整克隆本仓库及子模块（推荐一次性同步）
   子模块包含第三方依赖，构建前必须初始化，可重复执行以保证同步。

   git clone --recurse-submodules https://github.com/MaaXYZ/MaaFramework.git

   或

   git clone https://github.com/MaaXYZ/MaaFramework.git
   cd MaaFramework
   git submodule update --init --recursive

2. 下载 MaaDeps prebuilt

   python3 tools/maadeps-download.py

   脚本会自动下载并校验预编译依赖，如遇网络问题可重复执行。

3. 配置 CMake 预设

   • Windows

   cmake --preset "MSVC 2022"

   • Linux

   # 根据实际情况择一执行
   cmake --preset "NinjaMulti Linux x64"
   # 或者
   cmake --preset "NinjaMulti Linux arm64"

   • macOS

   cmake --preset "NinjaMulti"

4. 构建并安装

   cmake --build build --config Release
   cmake --install build --prefix install

根据需要可将 --config 切换为 Debug/RelWithDebInfo。生成的二进制及相关文件默认位于 install 目录。

详情请参考 Build CI 。

ADB 子进程管道回归测试

在 Linux 或 macOS 上，可在配置命令中追加 -DBUILD_ADB_PIPE_TESTING=ON（需要 WITH_ADB_CONTROLLER=ON），然后运行：

cmake --build build --config Debug --target AdbPipeTesting
ctest --test-dir build -C Debug -R '^adb_pipe_' --output-on-failure

测试通过真实子进程覆盖读取超时、清理期间正常退出、继承 stdout、完整或空输出、非零退出和失败后的下一次读取，无需连接模拟器。每个用例有 8 秒外层超时。此选项不支持 Windows 或 Android 构建。

补充检查确保进程失败与输出不完整同时发生时保留两种诊断，并验证模拟 fork 失败时，继承 stdout 的测试不会误报通过。

构建 MaaPiCli

MaaPiCli 已迁移至独立仓库 MaaXYZ/MaaPiCli，源码、构建说明及发布包均由该仓库维护。

在线开发

使用 Codespaces (Dev Container) 一键配置基础开发环境 (Ninja、CMake、g++-13)：

随后按照 本地开发 流程进行配置。