# 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](1.1-QuickStarted.md)._

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.

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

    or

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

2. Download prebuilt MaaDeps

    ```sh
    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

    ```bash
    cmake --preset "MSVC 2022"
    ```

    - Linux

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

    - macOS

    ```bash
    cmake --preset "NinjaMulti"
    ```

4. Build and install

    ```bash
    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](https://github.com/MaaXYZ/MaaFramework/blob/main/.github/workflows/build.yml).

## Online Development

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

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=master&repo=632024122)

Then follow the steps in [Local Development](#local-development).
