Building

构建指南

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

先看结论

Windows 上推荐用 CMake + MSVC。
Linux 使用 Make。
macOS 推荐 CMake + Homebrew（Make 仍可用作备选）。
Windows MinGW 交叉编译使用 Docker + Make。
项目会同时产出 GUI 程序和独立 CLI。
VERSION.txt 是版本与应用信息的单一事实源，打包脚本会读取它。
构建前需要初始化子模块；libshijima 已集成在仓库里，不是子模块。
Release workflow 会生成 Windows、Linux、macOS x86_64 与 macOS arm64 产物。

前置依赖

依赖	说明
C++17 编译器	MSVC 2022 / GCC / Clang
Qt 6.8+	`Core`、`Gui`、`Widgets`、`Concurrent`、`LinguistTools`；`Multimedia` 可选
Git	需要拉取子模块
CMake 3.21+	Windows/MSVC 与 macOS 主构建方式
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`（内置 x64-Debug / x64-Release）
Linux 本机构建	Make
macOS 本机构建	CMake + Homebrew（首选）或 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 运行时到输出目录。
也可以直接用 Visual Studio 打开项目，CMakeSettings.json 已配置 x64-Debug 和 x64-Release 两个方案。

构建后通常会看到这些目标：

NeurolingsCE
NeurolingsCECli，输出名为 NeurolingsCE-cli
NeurolingsCETests 与 NeurolingsCEBubbleTests（测试）

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 运行库安装流程串起来。

package-windows-bin.ps1 默认读取 VERSION.txt 生成输出目录名，并将 out/build/x64-Release/bin 复制到 out/package/ 后压缩。常用参数：

powershell -ExecutionPolicy Bypass -File .\src\tools\package-windows-bin.ps1 `
  -SourceDir out/build/x64-Release/bin `
  -OutputRoot out/package `
  -SkipVcRedist `
  -SkipZip

如果还没安装 WiX，可以先只生成 .wxs 文件检查内容：

powershell -ExecutionPolicy Bypass -File .\installer\wix\build-msi.ps1 -GenerateOnly

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，Make 路径下的 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：CMake + Homebrew（推荐）

macOS 同时支持 Apple Silicon（arm64）与 Intel（x86_64）。Qt6 可通过 Homebrew 或 MacPorts 安装；Homebrew 与 CMake 流程对齐得最好。

安装依赖（Homebrew，推荐）：

brew install qt qttools libarchive cmake pkg-config

或使用 MacPorts：

sudo port install qt6-qtbase qt6-qtmultimedia qt6-qttools pkgconfig libarchive cmake

构建（推荐使用 CMake，与其他平台一致）：

cmake -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release \
  -DQt6_DIR="$(brew --prefix qtbase)/lib/cmake/Qt6"
cmake --build build -j$(sysctl -n hw.ncpu)

构建产物会输出到 build/bin/，包括 NeurolingsCE、NeurolingsCE-cli 以及测试可执行文件 NeurolingsCETests。

如果使用 MacPorts，把 Qt6_DIR 改为 /opt/local/libexec/qt6/lib/cmake/Qt6 即可。

（备选）使用顶层 Makefile：

CONFIG=release make -j$(sysctl -n hw.ncpu)

common.mk 在 macOS 上会自动探测 Homebrew 的 qtbase、qtmultimedia、qttools 与 libarchive；如果同时安装了 MacPorts，也会回退到 /opt/local/libexec/qt6。如需指定其他 Qt 路径，可在命令行覆盖：

CONFIG=release make QT_MACOS_PATH=/your/Qt/lib \
  MOC=/your/Qt/libexec/moc RCC=/your/Qt/libexec/rcc \
  LRELEASE=/your/Qt/bin/lrelease -j$(sysctl -n hw.ncpu)

生成 .app：

make macapp

产物位置：

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

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

更新清单发布

仓库使用 GitHub Pages 托管静态更新清单：

https://blog.qingchenyou.asia/NeurolingsCE/update/latest.json

发布 Release 后，Publish update manifest workflow 会读取 Release metadata 和 assets：先用 tools/generate_sha256sums.py 生成确定性的 SHA256SUMS.txt 并补传到 Release，刷新并校验元数据后，再用 tools/generate_update_manifest.py 生成 latest.json 并部署到 Pages。维护者需要确认仓库 Pages Source 是 GitHub Actions；如果 Release assets 是发布之后才补传的，重新运行该 workflow 即可同步。

运行测试

构建完成后运行：

ctest --test-dir build -C Debug --output-on-failure

当前注册的测试目标：

NeurolingsCETests：核心协议、包安全、脚本与广播等行为测试。
NeurolingsCEBubbleTests：气泡排版与 Codex Markdown 渲染测试。

重要构建选项

选项	默认值	说明
`SHIJIMA_USE_QTMULTIMEDIA`	`ON`	是否启用音效；找不到 Qt Multimedia 时会退化为关闭而不是失败
`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` 缺失

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

NeurolingsCE Wiki

首页 / Home

用户入口

资源包与模板

资源包制作指南

Building

构建指南

先看结论

前置依赖

两套构建系统怎么选

Windows：MSVC + CMake

Windows 发布打包

Windows：MinGW 交叉编译 via Docker

Linux：Make

macOS：CMake + Homebrew（推荐）

更新清单发布

运行测试

重要构建选项

输出与命名说明

常见问题

CMake 找不到 Qt6

MSVC 报 32-bit toolchain 错误

子模块不完整

windeployqt 缺失

Qt6::Multimedia 缺失

相关页面

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NeurolingsCE Wiki

用户入口

资源包与模板

开发者入口

Clone this wiki locally

`windeployqt` 缺失

`Qt6::Multimedia` 缺失