構建指南
本指南涵蓋從源代碼構建 LeviLamina，包括環境設置、構建命令、依賴項和版本管理。
前置要求
必需工具
- XMake 3.0.0+ — 構建系統 (xmake.io)
- LLVM/Clang — Windows 構建使用
clang-cl工具鏈 - MSVC 2022+ — 提供
clang-cl所依賴的 Windows SDK 與標準庫 - Git — 用於版本控制和版本號生成
- Windows 10/11 x64 — 主要構建平臺。服務端構建也可以面向 Linux x86_64（
-p linux，使用clang工具鏈）；客戶端只能在 Windows 上構建
具體的工具和依賴版本以 xmake.lua 為準；.github/workflows/build.yml 中的工作流展示了當前實際
驗證過的組合。
安裝 XMake
# 使用 PowerShell
Invoke-Expression (Invoke-Webrequest 'https://xmake.io/psget.text' -UseBasicParsing).Content
# 或使用 Scoop
scoop install xmake安裝 MSVC
安裝 Visual Studio 2022 並選擇"使用 C++ 的桌面開發"工作負載，或安裝 Visual Studio 2022 生成工具。
安裝 LLVM
從 releases.llvm.org 下載安裝，或使用 scoop install llvm，並確保
clang-cl 已加入 PATH。
構建命令
基本構建
# 克隆仓库
git clone https://github.com/LiteLDev/LeviLamina.git
cd LeviLamina
# 构建服务端（默认）
xmake
# 或显式指定服务端
xmake f --target_type=server
xmake構建客戶端
xmake f --target_type=client
xmake構建並啟用測試
xmake f --tests=y
xmake發佈構建
xmake f --publish=y
xmake清理構建
xmake c
xmake構建選項
| 選項 | 值 | 默認值 | 說明 |
|---|---|---|---|
--target_type | server, client | server | 構建目標類型 |
--tests | y, n | n | 啟用基於 GTest 的測試 |
--publish | y, n | n | 標記為發佈版本（影響版本字符串） |
--levimc_repo | URL | - | 自定義 xmake-repo URL |
示例
# 服务端构建并启用测试
xmake f --target_type=server --tests=y
xmake
# 客户端发布构建
xmake f --target_type=client --publish=y
xmake
# 自定义仓库
xmake f --levimc_repo=https://custom.repo.url
xmake依賴項
LeviLamina 依賴 25+ 個外部庫，全部通過 xmake.lua 中的 add_requires 聲明，由 XMake 自動下載。
版本以 xmake.lua 為唯一來源，因此本頁只說明各依賴的用途。執行 xmake require --list 可查看
當前配置下實際解析到的版本。
核心庫
| 庫 | 用途 |
|---|---|
entt | 實體組件系統 |
fmt | 字符串格式化 |
nlohmann_json | JSON 解析 |
rapidjson | 快速 JSON 解析 |
leveldb | 鍵值數據庫 |
gsl | 指南支持庫 |
性能
| 庫 | 用途 |
|---|---|
mimalloc | 高性能內存分配器 |
parallel-hashmap | 快速哈希表 |
concurrentqueue | 無鎖隊列 |
工具
| 庫 | 用途 |
|---|---|
ctre | 編譯期正則表達式 |
magic_enum | 枚舉反射 |
type_safe | 類型安全工具 |
expected-lite | Expected/Result 類型 |
glm | 數學庫 |
cpr | HTTP 客戶端 |
stb | 圖像與字體解碼 |
LeviLamina 專用
這些依賴來自 levimc-repo xmake 倉庫，可通過 --levimc_repo 覆蓋。
| 庫 | 用途 |
|---|---|
pcg_cpp | 隨機數生成 |
pfr | 反射 |
demangler | C++ 名稱反修飾 |
levibuildscript | 構建腳本 |
preloader | DLL 預加載 |
symbolprovider | 符號解析 |
trampoline | 函數鉤子 |
平臺特定
| 庫 | 平臺 | 用途 |
|---|---|---|
libhat | Windows | 內存操作 |
bedrockdata | Windows | MC 二進制與數據，按 --target_type |
gtest | - | 測試框架，僅在 --tests=y 時需要 |
bedrockdata 與 LeviLamina 當前適配的 Minecraft 版本鎖定，其 -server / -client 變體由
--target_type 選擇。升級它屬於適配新 Minecraft 版本的工作，而非常規依賴更新。
版本號生成
LeviLamina 的版本號從 Git 標籤自動生成：
版本格式
v{major}.{minor}.{patch}{-prerelease}+{commit_hash}示例
- 正式版:
v26.51.8 - 預發佈版:
v26.51.8-rc.2 - 開發版:
v26.51.8-rc.2+ce09050f05（--publish=n時包含提交哈希）
主版本號與次版本號跟隨所適配的 Minecraft 版本，當前版本參見 tooth.json 與 CHANGELOG.md。
版本來源優先級
- Git 標籤 — 如果當前提交有匹配
v*.*.*的標籤 - tooth.json — 回退到
tooth.json中的version字段
版本注入
版本在構建期間注入到 src/ll/core/Version.h.in：
// 生成的 Version.h
#define LL_VERSION_MAJOR 26
#define LL_VERSION_MINOR 51
#define LL_VERSION_PATCH 8
#define LL_VERSION_PRERELEASE "rc.2"
#define LL_VERSION_BUILD "ce09050f05"編譯器設置
C++ 標準
- C++20 必需
- C++23 特性通過
_HAS_CXX23=1啟用
編譯器標誌
Windows 構建使用 clang-cl，採用兼容 MSVC 的標誌。完整列表以 xmake.lua 中
target("LeviLamina") 塊為準。
- 運行時:
/MD（動態，非調試） - 異常:
/EHa與/EHs，並在 xmake 層面關閉異常 - 警告:
/W4及特定升級： /w44265— 虛函數無 override/w44289— 循環變量在循環外使用/w44296— 表達式始終為真/假/w45263— 對臨時對象調用 std::move/w44738— 在內存中存儲浮點數
構建輸出
目錄結構
LeviLamina/
├── build/
│ └── windows/
│ └── x64/
│ └── release/
│ └── LeviLamina.dll
└── bin/
└── LeviLamina/
├── LeviLamina.dll
└── manifest.json產物
- LeviLamina.dll — 主加載器 DLL
- manifest.json — 包含版本信息的模組元數據
CI/CD
LeviLamina 使用 GitHub Actions 進行持續集成：
自動化構建
- 觸發器: 任意分支的推送，以及改動源碼或
xmake.lua的拉取請求 - 平臺: Windows x64
- 構建矩陣: 服務端與客戶端，各含 debug 與 release，測試開關各一份
發佈流程
- 為提交打標籤:
git tag v26.51.8 - 推送標籤:
git push origin v26.51.8 - CI 使用
--publish=y構建 - 產物上傳到 GitHub Releases
故障排除
XMake 緩存問題
xmake c -a # 清理所有
xmake f -c # 重新配置依賴下載失敗
# 使用镜像
xmake g --proxy_pac=github_mirror.lua找不到工具鏈
確保已安裝 Visual Studio 2022 或生成工具以提供 Windows SDK，已安裝 LLVM 使 clang-cl 可在
PATH 中解析，並從"VS 2022 開發人員命令提示符"運行。