How to build

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 Started.

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 / 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.

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.