跳转至

命令行与构建参考

English · 上一章：Engine 能力 · 下一章：故障排查

最低构建环境

  • C++20 编译器；
  • CMake 3.25+；
  • Ninja；
  • Qt 6.8+ Base/Widgets/SVG；
  • Protobuf 29+。

默认构建只使用经许可策略允许的 Qt 模块。构建脚本不会安装 Engine。

macOS / Linux

# 完整 Debug 构建、测试、离线 smoke
./scripts/build.sh

# 只检查依赖
./scripts/build.sh --check-only

# 缺依赖就失败，不自动安装
./scripts/build.sh --no-install

# Release
./scripts/build.sh --preset release

# 跳过测试
./scripts/build.sh --skip-tests

# 指定并行数
./scripts/build.sh --jobs 4

可用环境变量：VMA_QT_ROOT、VMA_DEPS_ROOT、VCPKG_ROOT、CMAKE_PREFIX_PATH。

手工的最小开发验证：

cmake --preset dev
cmake --build --preset dev
ctest --preset dev
./build/dev/vm-accelerator-studio --smoke-exit

macOS 应用路径是：

build/dev/vm-accelerator-studio.app/Contents/MacOS/vm-accelerator-studio

Studio 1.1 原生打包

打包脚本执行 Release 构建、部署 Qt/运行时依赖、离线 smoke，并更新 dist/SHA256SUMS。 macOS 和 Linux 必须在对应目标系统运行：

# macOS：默认 ZIP；也可用 --format dmg|all
./scripts/macos/build-and-package.sh --version 1.1

# Linux：默认 tar.gz；也可用 --format deb|appimage|all
./scripts/linux/build-and-package.sh --version 1.1

完整格式、签名、公证、glibc 兼容性与发布义务见仓库级 docs/building_and_packaging.md 和 docs/licensing.md。校验和只证明取得的字节与发布记录一致。

Windows

# Debug 构建和测试
.\scripts\windows\build-and-test.ps1

# Release
.\scripts\windows\build-and-test.ps1 -Configuration Release

# 只检查
.\scripts\windows\build-and-test.ps1 -CheckOnly

# 不自动安装
.\scripts\windows\build-and-test.ps1 -NoInstall

默认可执行文件位于 build\windows-msvc-debug\vm-accelerator-studio.exe 或对应 release 目录。脚本可使用 WinGet、项目本地 Qt 和 vcpkg Protobuf。 脚本会忽略 Visual Studio 自带的 manifest-only vcpkg；如设置 VCPKG_ROOT 或 -VcpkgRoot，必须指向独立 vcpkg checkout。

使用下列命令生成 Windows 原生发布包：

# 同时生成 ZIP、MSI 和 NSIS EXE
.\scripts\windows\build-and-package.ps1

.\scripts\windows\build-and-package.ps1 -Format msi
.\scripts\windows\build-and-package.ps1 -Format nsis
.\scripts\windows\build-and-package.ps1 -Format zip

MSI/NSIS 打包要求 CMake/CPack 3.30+、WiX 和 NSIS；不指定 -NoInstall 时，打包脚本可以获取后两项工具。

Studio 命令行

vm-accelerator-studio [options] [project]
选项 用途
--offline 明确标记本次启动为离线；启动时不恢复或对账远端
--theme system|light|dark 本次启动主题
--language system|en|zh-CN 本次启动语言
--physics-inputs 加载项目后打开 Physics Inputs
--local-results 打开并复验 Screening Results
--screening-study 打开 Screening Study
--nonlinear-dynamics 打开 Nonlinear Dynamics
--nonlinear-view setup|da|fma|losses|convergence|evidence 选择非线性页签
--orbit-correction 打开 Errors & Orbit Correction
--orbit-view setup|horizontal|vertical|correctors|response|tolerance|evidence 选择轨道页签
--historical-catalog <path> 打开历史迁移目录
--screenshot <path> 渲染主窗口截图并退出
--smoke-exit 短暂打开外壳后成功退出
--help / --version 帮助/版本

例子：

./build/dev/vm-accelerator-studio \
  --offline --theme dark --language zh-CN \
  --nonlinear-dynamics --nonlinear-view fma \
  protocol/nonlinear_lattice_projection_v0_1/fixtures/portable-sextupole-ring.studio-project.json

./build/dev/vm-accelerator-studio \
  --offline --orbit-correction --orbit-view tolerance \
  protocol/orbit_error_model_v0_1/fixtures/portable-fodo-reference-ring.studio-project.json

普通启动本身已经不联网：命令行载入项目/页面不会认证、恢复 pending work、对账 registry 或协商 runtime capability。--offline 用来明确保留这项离线审阅策略/状态。上面的命令只 打开草稿或本地保留证据；若要保持整个会话不联网，之后也不要执行 Test、Run、Reconnect、 Recover 或远端 Refresh。

Xsuite importer 命令

必填参数为 --input、--output、--project-id、--display-name 和 --expected-sha256；--project-json、--evidence-json 为可选 sidecar。完整例子见导入与历史迁移。

本地预览本指南

本指南通过仓库固定的 MkDocs Material 版本构建：

python3 -m venv .deps/user-guide-docs
.deps/user-guide-docs/bin/python -m pip install -r docs/user-guide/requirements.txt
.deps/user-guide-docs/bin/mkdocs build --config-file mkdocs.user-guide.yml --strict
rsync -a docs/images/ build/user-guide-site/images/
python3 -m http.server 8000 --directory build/user-guide-site

站点输出在 build/user-guide-site/。docs/images 位于 MkDocs docs_dir 之外，因此发布包 必须在构建后复制该目录；提交或部署前应同时检查中英文导航、图片与站内链接。