Building

构建指南

本页回答两个问题：应该用哪套构建系统，以及构建后你会得到哪些产物。

先看结论

• Windows 上推荐用 CMake + MSVC。
• Linux、macOS 和 Windows MinGW 交叉编译使用 Make。
• 项目会同时产出 GUI 程序和独立 CLI。
• 构建前需要初始化子模块；libshijima 已集成在仓库里，不是子模块。

前置依赖

依赖	说明
C++17 编译器	MSVC 2022 / GCC / Clang
Qt 6.8+	Core、Gui、Widgets、Concurrent、Network、LinguistTools；Multimedia 可选
Git	需要拉取子模块
CMake 3.21+	Windows/MSVC 主构建方式
Make	Linux / macOS / MinGW 路径

先拉源码并初始化子模块：

git clone https://github.com/qingchenyouforcc/NeurolingsCE.git
cd NeurolingsCE
git submodule update --init --recursive

当前需要一起参与构建的重要目录包括：

• libshimejifinder/
• cpp-httplib/
• ElaWidgetTools/

两套构建系统怎么选

场景	推荐方式
Windows 本机开发	CMake + MSVC
Visual Studio 调试	CMake + CMakeSettings.json
Linux 本机构建	Make
macOS 本机构建	Make
Windows 交叉编译 / CI 对齐	Docker + MinGW + Make

Windows：MSVC + CMake

这是 Windows 本机开发的推荐方案。

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DQt6_DIR=D:/Qt/6.8.3/msvc2022_64/lib/cmake/Qt6
cmake --build build

要点：

• 必须使用 x64 工具链；32 位 MSVC 会被直接拒绝。
• Qt6_DIR 也可以换成 CMAKE_PREFIX_PATH 或环境变量 QTDIR。
• 如果检测到 conda 提供的 Qt，CMake 会调整 MSVC runtime 以避免 CRT 冲突。
• 如果本机能找到 windeployqt，构建后会自动部署 Qt 运行时到输出目录。

构建后通常会看到两个目标：

• NeurolingsCE
• NeurolingsCECli，输出名为 NeurolingsCE-cli

Windows 发布打包

Release 构建完成后，可以使用仓库脚本生成便携包和安装包：

powershell -ExecutionPolicy Bypass -File .\src\tools\package-windows-bin.ps1 -SourceDir out/build/x64-Release/bin
powershell -ExecutionPolicy Bypass -File .\installer\wix\build-msi.ps1
powershell -ExecutionPolicy Bypass -File .\installer\wix\build-bundle.ps1

常见输出：

• out/package/NeurolingsCE_windows_x86_64_v<version>.zip
• out/installer/NeurolingsCE_windows_x86_64_v<version>.msi
• out/installer/NeurolingsCE_windows_x86_64_v<version>-setup.exe

其中 -setup.exe 是引导安装器，会把主 MSI 和 VC 运行库安装流程串起来。

Windows：MinGW 交叉编译 via Docker

适合复现 CI 或生成 Windows 发布目录。

docker build -t neurolingsce-dev dev-docker
docker run -e CONFIG=release --rm -v "$(pwd)":/work neurolingsce-dev bash -c 'mingw64-make -j$(nproc)'

调试版：

docker run -e CONFIG=debug --rm -v "$(pwd)":/work neurolingsce-dev bash -c 'mingw64-make -j$(nproc)'

产物位置：

• publish/Windows/release/
• publish/Windows/debug/

该目录会同时包含 GUI 程序、NeurolingsCE-cli.exe、Qt DLL 和插件。

Linux：Make

Ubuntu / Debian 常见依赖：

sudo apt-get install -y build-essential qt6-base-dev qt6-multimedia-dev qt6-tools-dev qt6-l10n-tools libarchive-dev libwayland-dev wayland-protocols libxcb-cursor0 pkg-config

Fedora 常见依赖：

sudo dnf install -y qt6-qtbase-devel qt6-qtmultimedia-devel qt6-linguist libarchive-devel wayland-devel wayland-protocols-devel

构建：

CONFIG=release make -j$(nproc)

或：

CONFIG=debug make -j$(nproc)

产物位置：

• publish/Linux/<config>/

常见内容：

• shijima-qt，当前 GUI 可执行名
• NeurolingsCE-cli
• libunarr.so.1

生成 AppImage：

CONFIG=release make -j$(nproc)
make appimage

安装：

make install PREFIX=/usr/local

卸载：

make uninstall PREFIX=/usr/local

macOS：Make

基于仓库当前脚本，文档默认使用 MacPorts。

sudo port install qt6-qtbase qt6-qtmultimedia pkgconfig libarchive
CONFIG=release make -j$(nproc)

生成 .app：

make macapp

产物位置：

• publish/macOS/<config>/
• publish/macOS/<config>/NeurolingsCE.app

发布目录同样会包含 NeurolingsCE-cli。

重要构建选项

选项	默认值	说明
SHIJIMA_USE_QTMULTIMEDIA	ON	是否启用音效
SHIJIMA_WITH_DEFAULT_MASCOT	ON	必须开启；当前不支持关闭
SHIJIMA_WITH_LICENSES_TEXT	ON	必须开启；当前不支持关闭

补充说明：

• translations/shijima-qt_zh_CN.ts 会在有 Qt6::lrelease 或 lrelease 时被编译并嵌入。
• 项目不会自动运行 lupdate 去覆盖手工维护的翻译源文件。

输出与命名说明

类型	常见名字
GUI 程序	CMake 下为 NeurolingsCE；Make 发布目录中的可执行名当前为 shijima-qt
CLI 程序	NeurolingsCE-cli 或 NeurolingsCE-cli.exe
Linux 可分发包	NeurolingsCE.AppImage
macOS 应用包	NeurolingsCE.app

如果你在写文档、脚本或自动化，请区分“品牌名”和“当前构建产物名”。仓库整体项目名是 NeurolingsCE，但 Make 路径下的 GUI 可执行文件名当前仍是 shijima-qt。

常见问题

CMake 找不到 Qt6

显式传入 Qt 路径：

cmake -B build -DQt6_DIR=/path/to/Qt/6.8.x/<kit>/lib/cmake/Qt6

MSVC 报 32-bit toolchain 错误

请切换到 x64 Native Tools，或在 Visual Studio 中选择 x64 配置。

子模块不完整

git submodule update --init --recursive

windeployqt 缺失

Windows 本机构建可以成功，但输出目录可能缺少 Qt 运行时，导致程序离开 Qt 开发环境后无法启动。

Qt6::Multimedia 缺失

项目会退化为无音效构建，而不是直接失败。

相关页面

• 架构概览
• 贡献指南
• HTTP API 与 CLI