4.1 Build Guide

TIP

You only need to read this chapter if you are ready to develop MaaFramework itself. If you only want to develop applications based on MaaFramework, please refer to Quick Start.

Before you start, ensure Git, Python 3, and CMake 3.24+ are installed, along with the toolchain for your platform (Windows: MSVC 2022; Linux/macOS: Ninja + g++/clang).

Local Development

1. Clone the repo with all submodules (recommended)
   Submodules contain third-party dependencies and must be initialized before building. You can re-run this step anytime to keep them in sync.

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

   or

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

2. Download prebuilt MaaDeps

   python3 tools/maadeps-download.py

   The script downloads and verifies the prebuilt dependencies. If the network is unstable, simply rerun it.

3. Configure CMake preset

   • Windows

   cmake --preset "MSVC 2022"

   • Linux

   # Run one of the following:
   cmake --preset "NinjaMulti Linux x64"
   # Or
   cmake --preset "NinjaMulti Linux arm64"

   • macOS

   cmake --preset "NinjaMulti"

4. Build and install

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

Switch --config to Debug/RelWithDebInfo as needed. Binaries and related files are placed in the install directory by default.

For more details, refer to Build CI.

ADB child-pipe regression tests

On Linux or macOS, add -DBUILD_ADB_PIPE_TESTING=ON to the configure command (WITH_ADB_CONTROLLER=ON is required), then run:

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

The tests use real child processes to cover read deadlines, successful exit during cleanup, inherited stdout, complete or empty output, nonzero exit, and the next read after failure. No emulator is needed. Each case has an eight-second outer timeout. This option does not support Windows or Android builds.

Additional checks require both process-failure and incomplete-output diagnostics when both occur, and verify that a simulated fork failure cannot pass the inherited-stdout test.

Build MaaPiCli

MaaPiCli is developed, built, and distributed in the independent MaaXYZ/MaaPiCli repository. See that repository for build instructions and releases.

Online Development

Use Codespaces (Dev Container) to set up the basic development environment with one click (Ninja, CMake, g++-13):

Then follow the steps in Local Development.