构建指南 - Luna Launcher
Description: Luna Launcher 构建指南

# 构建指南

本文介绍如何从源代码构建 Luna Launcher。

## 前置要求

- Git
- Java Development Kit 8 或更高版本
- CMake 3.16 或更高版本
- Qt 6 (推荐 6.6.2) 或 Qt 5 (推荐 5.15.2)

## 获取源代码

    git clone --recursive https://github.com/AndreaFrederica/LunaLauncher.git
    cd LunaLauncher

注意：使用 --recursive 参数来克隆子模块（包含 website）。

## Windows 构建

### 自动化构建：MSYS2 + GCC（推荐）

#### 使用 Msys2Manager (m2m)

Msys2Manager (m2m) 是专门用于管理 MSYS2 环境的 CLI 工具。从 GitHub Releases 下载最新版本并添加到 PATH。

    # 设置 JAVA_HOME
    $env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-17.0.12.101-hotspot"
    # 引导安装 MSYS2（仅首次）
    m2m bootstrap
    # 配置和构建
    m2m run configure
    m2m run build
    # 安装
    m2m run install

#### 使用 PowerShell 脚本

    # 设置 JAVA_HOME
    $env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-17.0.12.101-hotspot"
    # 初始化 MSYS2 环境（仅首次）
    .\tools\msys2\bootstrap.ps1
    # 配置和构建
    .\tools\msys2\run.ps1 configure
    .\tools\msys2\run.ps1 build
    # 安装
    .\tools\msys2\run.ps1 install

### 手动构建：MSYS2 + GCC

推荐使用 CLANG64 或 UCRT64 msystem，CLANG64 编译速度更快且 bug 更少。

#### 准备 MSYS2

1. 从开始菜单打开 MSYS2 快捷方式
2. 安装辅助工具：`pacman -Syu pactoys git mingw-w64-ucrt-x86_64-binutils`
3. 使用 pacboy 安装构建依赖：`pacboy -S toolchain:p cmake:p ninja:p qt6-base:p qt6-5compat:p qt6-svg:p qt6-imageformats:p quazip-qt6:p extra-cmake-modules:p ccache:p`
4. 或使用 Qt 5：`pacboy -S toolchain:p cmake:p ninja:p qt5-base:p qt5-svg:p qt5-imageformats:p quazip-qt5:p extra-cmake-modules:p ccache:p`

#### 从命令行编译

    # 进入源代码目录
    cd /path/to/LunaLauncher
    # 配置 CMake（Debug 构建）
    cmake -Bbuild -DCMAKE_INSTALL_PREFIX=install -DENABLE_LTO=ON -DCMAKE_BUILD_TYPE=Debug -G Ninja
    # 构建
    cmake --build build
    # 安装
    cmake --install build
    # 便携版（数据存储在应用目录）
    cmake --install build --component portable

注意：Qt 5 构建时需要手动复制 OpenSSL DLL：`cp /ucrt64/bin/libcrypto-1_1-x64.dll /ucrt64/bin/libssl-1_1-x64.dll install`

### 自动化构建：Pixi + MSVC

仅需 MSVC，建议从 x64 Native Tools Command Prompt 运行。

    # 检查/配置 MSVC 环境
    pixi run check_msvc
    # 安装 Qt
    pixi run install_qt
    # 安装 vcpkg
    pixi run install_vcpkg
    # 配置
    pixi run configure
    # 构建
    pixi run build
    # 安装
    pixi run install

### 手动构建：MSVC

#### 依赖项

- Visual Studio - 从"x64 Native Tools Command Prompt"运行
- Java Development Kit 8 或更高版本
- Qt 6.6.2 (推荐) 或 Qt 5.15.2

#### 从命令行编译

    # 配置 CMake（调整 Qt 路径）
    cmake -Bbuild -DCMAKE_INSTALL_PREFIX=install -DENABLE_LTO=ON -DCMAKE_PREFIX_PATH=C:\Qt\6.6.2\msvc2019_64\lib\cmake
    # 构建（Debug）
    cmake --build build --config Debug -- /p:UseMultiToolTask=true /p:EnforceProcessCountAcrossBuilds=true
    # 安装
    cmake --install build --config Debug
    # 便携版
    cmake --install build --config Debug --component portable

注意：Qt 5 构建时需要手动复制 OpenSSL DLL：`robocopy C:\Qt\Tools\OpenSSL\Win_x64\bin\ install libcrypto-1_1-x64.dll libssl-1_1-x64.dll`

## Linux 构建

### 构建依赖

- 支持 C++17 的 C++ 编译器
- Qt 6.0+ 或 Qt 5.12+ (`qt6-base-dev qt6-5compat-dev` 或 `qtbase5-dev`)
- cmake 3.15+ (`cmake`)
- ninja (`ninja-build`)
- extra-cmake-modules
- zlib (`zlib1g-dev`)
- Java JDK (`openjdk-17-jdk`)
- GL 头文件 (`libgl1-mesa-dev`)

### 构建便携版

    cmake -S . -B build -G Ninja \
       -DCMAKE_INSTALL_PREFIX=install
    cmake --build build
    cmake --install build
    cmake --install build --component portable

### 构建并安装到系统

    cmake -S . -B build -G Ninja \
       -DCMAKE_BUILD_TYPE=Release \
       -DCMAKE_INSTALL_PREFIX="/usr" \
       -DENABLE_LTO=ON
    cmake --build build
    cmake --install build

构建 Linux 软件包时使用 `/usr`，个人构建使用 `/usr/local`。

## macOS 构建

### 安装前置要求

- XCode Command Line tools：`xcode-select --install`
- CMake：cmake.org
- extra-cmake-modules
- JDK 8：Adoptium
- Qt 6 (推荐) 或 Qt 5.12+

#### 使用 Homebrew 安装

    brew update
    brew install qt openjdk@17 cmake ninja extra-cmake-modules
    # 使用 qt@5 安装 Qt 5

### 构建

    mkdir build
    cmake \
      -S . \
      -B build \
      -G Ninja \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX="dist" \
      -DCMAKE_PREFIX_PATH="/opt/homebrew/opt/qt" \
      -DCMAKE_OSX_DEPLOYMENT_TARGET=11 \
      -DLauncher_QT_VERSION_MAJOR=6 \
      -DENABLE_LTO=ON \
      -DLauncher_BUILD_PLATFORM=macOS
    cmake --build build
    cmake --install build

注意：最终应用包可能由于代码签名问题无法运行，需要使用 `codesign -fs -` 修复。

## 构建输出

- 标准构建：install/ 目录
- 便携版：使用 --component portable 参数

## 上游参考

Luna Launcher 基于 Prism Launcher，更详细的构建说明可以参考上游文档：

- Windows 构建说明
- Linux 构建说明
- macOS 构建说明

返回首页 需要帮助？