CLI and Build Reference¶

简体中文 · Previous: Engine capabilities · Next: Troubleshooting

Minimum build environment¶

C++20 compiler;
CMake 3.25+;
Ninja;
Qt 6.8+ Base/Widgets/SVG;
Protobuf 29+.

The default build uses only Qt modules allowed by the repository licensing policy. It does not install the Engine.

macOS / Linux¶

./scripts/build.sh                 # Debug, tests, offline smoke
./scripts/build.sh --check-only    # dependencies only
./scripts/build.sh --no-install    # fail instead of installing
./scripts/build.sh --preset release
./scripts/build.sh --skip-tests
./scripts/build.sh --jobs 4

Supported environment variables are VMA_QT_ROOT, VMA_DEPS_ROOT, VCPKG_ROOT, and CMAKE_PREFIX_PATH.

Manual minimum developer validation:

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

The macOS executable is:

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

Windows¶

.\scripts\windows\build-and-test.ps1
.\scripts\windows\build-and-test.ps1 -Configuration Release
.\scripts\windows\build-and-test.ps1 -CheckOnly
.\scripts\windows\build-and-test.ps1 -NoInstall

The default executable is under build\windows-msvc-debug\vm-accelerator-studio.exe or the corresponding release directory. The driver can use WinGet, project-local Qt, and vcpkg Protobuf.

Studio command line¶

vm-accelerator-studio [options] [project]

Option	Use
`--offline`	Disable startup recovery and automatic remote reconciliation
`--theme system\|light\|dark`	Theme for this launch
`--language system\|en\|zh-CN`	Language for this launch
`--physics-inputs`	Open Physics Inputs after project load
`--local-results`	Open and reverify Screening Results
`--screening-study`	Open Screening Study
`--nonlinear-dynamics`	Open Nonlinear Dynamics
`--nonlinear-view setup\|da\|fma\|losses\|convergence\|evidence`	Select nonlinear tab
`--orbit-correction`	Open Errors & Orbit Correction
`--orbit-view setup\|horizontal\|vertical\|correctors\|response\|tolerance\|evidence`	Select orbit tab
`--historical-catalog <path>`	Open a historical catalog
`--screenshot <path>`	Render the main window and exit
`--smoke-exit`	Brief shell launch and successful exit
`--help` / `--version`	Help/version

Examples:

./build/dev/vm-accelerator-studio \
  --offline --theme dark --language en \
  --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

In offline mode, v0.8/v0.9 do not automatically negotiate runtime capability. These commands are for draft or retained-evidence review, not starting new remote jobs.

Xsuite importer¶

Required options are --input, --output, --project-id, --display-name, and --expected-sha256. --project-json and --evidence-json are optional sidecars. See Import and migration for an example.

Using this guide with GitBook¶

Use docs/user-guide as the content root. README.md is the language landing page and SUMMARY.md supplies navigation. Links are relative, so the guide also works directly in GitHub or Codex.