Build Guide

This document details how to build the DesktopDanmaku project, including setting up the build environment, build commands, and common issues during the build process.

1. Build Environment

1.1 Required Tools

• Operating System: Windows 10 or later
• C++ Compiler: A compiler supporting C++17, callable via the g++ command (such as GCC, MinGW-w64, etc.)
• GNU Make: For executing build commands

1.2 Recommended Tools

• MSYS2: Provides MingGW64 compilation environment (optional, convenient for obtaining g++ compiler)

1.3 Environment Setup

1.3.1 Installing C++ Compiler

Here are the methods to install a C++ compiler on Windows systems, ensuring it can be called via the g++ command. You have two options:

Option 1: Using MSYS2 (Recommended, most convenient way on Windows)

1. Download and install the Windows version of MSYS2 from MSYS2 official website
2. After installation, open the MSYS2 MSYS terminal
3. Run the following command to update system packages:

pacman -Syu

4. Restart the terminal and run the update command again:

pacman -Syu

5. Install the MingGW64 toolchain (including g++ compiler):

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make

6. Add C:\msys64\mingw64\bin to the system environment variable PATH

Option 2: Directly Installing MinGW-w64

1. Download the Windows version of MinGW-w64 from MinGW-w64 official website
2. Run the installer and select the appropriate architecture and version
3. Add the bin folder under the installation directory to the system environment variable PATH

1.3.2 Installing GNU Make

If after installing MinGW-w64 using Option 2, running make --version shows the command not found, you need to install GNU Make separately:

1. Download the installer from GNU Make for Windows
2. Run the installer
3. Add the bin folder under the installation directory to the system environment variable PATH

1.3.3 Verifying Environment Installation

Run the following commands in the command prompt to verify if the compiler is installed successfully:

g++ --version
make --version

2. Building the Project

2.1 Basic Build Commands

Run the following commands in the project root directory:

2.1.1 Building DEBUG Version (Default 64-bit)

make

This will generate the executable file danmaku.exe in the build/64/debug directory.

2.1.2 Building 32-bit DEBUG Version

make ARCH=32

This will generate the 32-bit executable file danmaku.exe in the build/32/debug directory.

2.1.3 Building RELEASE Version (64-bit)

make DEBUG=0

This will generate the optimized executable file danmaku.exe in the build/64/release directory.

2.1.4 Building 32-bit RELEASE Version

make ARCH=32 DEBUG=0

This will generate the optimized 32-bit executable file danmaku.exe in the build/32/release directory.

2.2 Build Options

2.3 Other Build Targets

2.3.1 Viewing Help Information

make help

Displays makefile help information (actually displays the content of docs/makefileHelper.txt file).

2.3.2 Cleaning Build Files

make clean

Deletes all build-generated files and directories (the entire build directory).

2.3.3 Running Compiled Results

make run

Compiles and runs the program (default runs the 64-bit version).

2.3.4 Building All Release Versions

make release

Cleans and builds 64-bit and 32-bit release versions.

2.3.5 Building 64-bit Release Version

make release64

Builds 64-bit release version.

2.3.6 Building 32-bit Release Version

make release32

Builds 32-bit release version.

2.3.7 Building Installation Packages

make installer

Cleans and builds 64-bit and 32-bit installation packages.

2.3.8 Building 64-bit Installation Package

make installer64

Builds 64-bit installation package.

2.3.9 Building 32-bit Installation Package

make installer32

Builds 32-bit installation package.

3. Detailed Build Process

3.1 Build Directory Structure

The build process creates a build directory in the project root directory, and creates subdirectories based on architecture and build type:

build/
├── 64/
│   ├── debug/       # 64-bit debug version
│   │   ├── obj/     # Object file directory
│   │   └── danmaku.exe  # Executable file
│   └── release/     # 64-bit release version
│       ├── obj/     # Object file directory
│       └── danmaku.exe  # Executable file
└── 32/
    ├── debug/       # 32-bit debug version
    │   ├── obj/     # Object file directory
    │   └── danmaku.exe  # Executable file
    └── release/     # 32-bit release version
        ├── obj/     # Object file directory
        └── danmaku.exe  # Executable file

3.2 Build Flow

1. Checks if the build directory exists, creates it if not
2. Compiles source files, generates object files (stored in obj directory)
3. Compiles resource files (src/list.rc), generates manifest.o
4. Links all object files and resource files, generates executable file danmaku.exe
5. After build completion, displays build result information

3.3 Dependency Management

The project uses makefile to automatically manage dependencies. When source files or header files change, it automatically recompiles related files.

4. Common Issues and Solutions

4.1 Build Failures

4.1.1 Compiler Not Found

Error Message:

make: gcc: Command not found

Solution:

• Check if MSYS2 and MingGW64 are installed correctly
• Check if the environment variable PATH includes C:\msys64\mingw64\bin
• Try reopening the command prompt to ensure environment variables take effect

4.1.2 Header File Not Found

Error Message:

fatal error: danmaku/dmkitem.hpp: No such file or directory

Solution:

• Check if the project directory structure is correct
• Ensure header file paths are under the include directory
• Check include path settings in makefile

4.1.3 Link Error

Error Message:

undefined reference to `GdiplusStartup'

Solution:

• Check if the GDI+ library is linked correctly
• Ensure the LIBS variable in makefile includes -lgdiplus

4.2 Runtime Errors

4.2.1 Missing DLL Files

Error Message:

This program cannot start because libgcc_s_seh-1.dll is missing from your computer.

Solution:

• Copy DLL files from MSYS2 to the executable file directory
• Or add the MSYS2 bin directory to the system environment variable PATH

4.2.2 Permission Error

Error Message:

Access denied.

Solution:

• Run the command prompt or executable as administrator
• Check file and directory permission settings

5. Advanced Build Options

5.1 Custom Compilation Flags

You can customize compilation flags via command line parameters:

make CXXFLAGS="-Wall -Wextra -g -std=c++17 -O2"

5.2 Parallel Build

Using the -j option enables parallel build to speed up the build process:

make -j4

Where 4 is the number of parallel tasks, which can be adjusted according to the number of CPU cores.

5.3 Cross Compilation

The project supports cross-compilation, allowing you to build 32-bit versions on 64-bit systems:

make ARCH=32

6. Build Scripts

6.1 Batch Scripts

You can create batch scripts to simplify the build process, for example:

build_debug.bat:

@echo off
make
pause

build_release.bat:

@echo off
make RELEASE=1
pause

6.2 PowerShell Scripts

build_debug.ps1:

make
Read-Host "Press Enter to continue..."

build_release.ps1:

make RELEASE=1
Read-Host "Press Enter to continue..."

7. Continuous Integration

If you need to set up continuous integration, you can refer to the following configuration:

7.1 GitHub Actions

Create a .github/workflows/build.yml file in the project root directory:

name: Build

on:
  push:
    branches: [ main, dev ]
  pull_request:
    branches: [ main, dev ]

jobs:
  build:
    runs-on: windows-latest

    steps:
    - uses: actions/checkout@v2

    - name: Set up MSYS2
      uses: msys2/setup-msys2@v2
      with:
        msystem: MINGW64
        update: true
        install: >-
          mingw-w64-x86_64-gcc
          mingw-w64-x86_64-make

    - name: Build DEBUG
      shell: msys2 {0}
      run: make

    - name: Build RELEASE
      shell: msys2 {0}
      run: make RELEASE=1

    - name: Build 32-bit DEBUG
      shell: msys2 {0}
      run: make ARCH=32

    - name: Build 32-bit RELEASE
      shell: msys2 {0}
      run: make ARCH=32 RELEASE=1

8. Summary

This guide details the build process of the DesktopDanmaku project, including environment setup, build commands, and solutions to common issues. By following this guide, you should be able to successfully build the project and resolve issues encountered during the build process.

If you encounter other issues during the build process, please refer to the project’s GitHub Issues page or contact the project maintainer.

We hope this guide is helpful to you!