Development

Introduction to GitHub pull request flow

1. If you have forked this repository long time ago, please go to Settings, scroll down to the bottom, and click Delete Repository.

2. Go to MAA main repository and click Fork, then Create fork.

3. Clone the dev branch of the (forked) repository to local with submodules:

   git clone --recurse-submodules <link to your forked repo> -b dev
   

   If you are using a Git GUI such as Visual Studio that without --recurse-submodules, do git submodule update --init after cloning to clone the submodules.

4. Download pre-built third-party libraries

   Please install Python first if you don't have it.

   python maadeps-download.py
   

5. Configure development environment

   1. Download and install Visual Studio 2022 Community. Select Desktop development with C++ and .NET Desktop Development.

6. Double-click to open the file MAA.sln. Visual Studio will load the project automatically.

7. Run a build to test whether the development environment has been configured correctly. Choose Release & x64, right-click MaaWpfGui to set it as the startup project, and run it. If the build is successful, the MaaWpfGui window will appear. You can connect to the emulator in order to confirm again that the development environment has been configured correctly.

8. Now you are free to contribute to MAA.

9. Remember to commit once you have proper number of changes. Don't forget to write a commit message.

   If you are a beginner of git, you might want to make changes on a newly created branch instead of committing to dev directly

   git branch your_own_branch
   git checkout your_own_branch
   

   so that your new commits would grow on the new branch, without being interrupted by updates of dev

10. After development, push your local changes to the remote (your own repository).

    git push origin dev
    

11. Go to MAA repository and submit a Pull Request. Wait until the administrator approves it. Please note that the changes should be based on dev instead of master branch, and should be merged to dev branch as well.

12. When there are changes from other contributors on upstreaming MAA repository, it might be necessary for you to add them to your own branch.

    1. Add MAA upstream repository.

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

    2. Fetch upstream changes from the repository.

       git fetch upstream
       

    3. rebase (recommended) or merge changes.

       git rebase upstream/dev
       

       or

       git merge
       

    4. Repeat step 7-10.

Note: operations regarding Git can be done by VS2022 instead of command line tools, using the Git changes tab.

Enable clang-format in Visual Studio

1. Install clang-format version 17 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 and select Use custom clang-format.exe file to use the clang-format.exe you have got 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 envirinments:

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