MaaAssistantArknights/docs/en-us/develop/development.md

order, icon

order	icon
1	iconoir:developer

Getting Started with Development

Introduction to GitHub Pull Request flow

I don't know programming but just want to modify some JSON files/documents, how can I do it?

Welcome to the GitHub Pull Request Tutorial that anyone can understand (purely web-based on Github.com)

I can program, but I've never used GitHub/C++/..., how do I get started?

1. If you forked the repository long ago, first delete it via your repository's Settings at the bottom.

2. Visit the MAA main repository, click Fork, then Create fork.

3. Clone the dev branch of your repository with submodules:

   git clone --recurse-submodules <your repository link> -b dev
   

   ::: warning If using Git GUI clients like Visual Studio without --recurse-submodules support, run git submodule update --init after cloning to initialize submodules. :::

4. Download prebuilt third-party libraries
   Python environment required - search for Python installation tutorials if needed
   （maadeps-download.py is located in the project root）

   python maadeps-download.py
   

5. Configure development environment

   • Download and install Visual Studio 2022 Community, selecting Desktop development with C++ and .NET Desktop Development during installation.

6. Double-click MAA.sln to open the project in Visual Studio.

7. Configure Visual Studio settings

   • Select RelWithDebInfo and x64 in the top configuration bar (Skip for Release builds or ARM platforms)
   • Right-click MaaWpfGui -> Properties -> Debug -> Enable native debugging (This enables breakpoints in C++ Core)

8. Now you're ready to happily mess around start developing!

9. Commit regularly with meaningful messages during development
   Beginners should create a new branch instead of committing directly to dev:

   git branch your_own_branch
   git checkout your_own_branch
   

   This keeps your changes isolated from upstream dev updates.

10. After development, push your local branch (e.g. dev) to your remote repository:

    git push origin dev
    

11. Submit a Pull Request at the MAA main repository. Ensure your changes are based on the dev branch, not master.

12. To sync upstream changes:

    1. Add upstream repository:

       git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
       

    2. Fetch updates:

       git fetch upstream
       

    3. Rebase or merge:

       git rebase upstream/dev
       

       or

       git merge
       

    4. Repeat steps 7, 8, 9, 10.

::: tip After opening Visual Studio, Git operations can be performed using VS's built-in "Git Changes" instead of command-line tools. :::

MAA file formatting requirements

MAA uses a series of formatting tools to ensure that the code and resource files in the repository are visually unified for easy maintenance and reading.

Please ensure that it has been formatted before submission, or enable Pre commit Hooks for automatic formatting.

The currently enabled formatting tools are as follows:

File Type	Format Tool
C++	clang-format
Json/Yaml	Prettier
Markdown	markdownlint

Use Pre-commit Hooks to Automatically Format Code

1. Ensure that you have Python and Node environments on your computer.

2. Execute the following command in the root directory of the project:

   pip install pre-commit
   pre-commit install
   

If pre-commit still cannot be used after pip install, please check if the pip installation path has been added to the PATH.

The formatting tool will automatically run every time you submit to ensure that your code format conforms to the style guide.

Enable clang-format in Visual Studio

1. Install clang-format version 20.1.0 or higher.

   python -m pip install clang-format
   

2. Use tools like 'Everything' to locate the installation location of clang-format.exe. As a reference, if you are using Anaconda, clang-format.exe will be installed in YourAnacondaPath/Scripts/clang-format.exe.

3. In Visual Studio, search for 'clang-format' in Tools-Options.

4. Click Enable ClangFormat support and select Use custom clang-format.exe file and choose the clang-format.exe located in Step 2.

You are all set with the clang-format integrated in Visual Studio supporting c++20 features!

You can also format with tools\ClangFormatter\clang-formatter.py directly, by executing in the root folder of the project:

• python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MaaCore

Develop in cloud using GitHub codespace

Create GitHub codespace with pre-configured C++ dev environments:

Then follow the instructions in vscode or Linux tutorial to configure GCC 12 and the CMake project.