Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 34 additions & 21 deletions .agents/skills/build-openshell-mxc-windows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,9 @@ The Windows build lane is implemented by these tracked files:
| `tasks/windows.toml` | Mise task entry points for `windows:*` commands. |
| `tasks/rust.toml`, `tasks/test.toml`, and `tasks/markdown.toml` | Windows routing for compiler-bearing checks, explicit Unix-only test skips, and Markdown dependency setup. |
| `tasks/scripts/windows-msvc.ps1` | PowerShell wrapper that enters the Visual Studio developer environment and invokes Cargo. |
| `.github/workflows/windows-msvc.yml` | Opt-in PR lint and test plus advisory `windows` branch cache seeding and dependent binary builds on native x64 and ARM64 runners. |
| `.github/workflows/windows-msvc.yml` | Opt-in PR lint, test, and release builds plus advisory `windows` branch cache seeding and dependent binary builds on native x64 and ARM64 runners. |
| `tasks/scripts/windows-runtime.ps1` | Architecture and normal/delay PE import checks for static CRT/Z3 packages. |
| `.cargo/windows-msvc.toml` | Windows wrapper-only dependency profiles that keep native Z3 optimized in dev/test builds, matching the previous prebuilt solver. |
| `.agents/skills/build-openshell-mxc-windows/` | This skill and companion reference material. |

Use the code that is already in the repo. Do not generate a parallel Windows
Expand Down Expand Up @@ -184,7 +186,7 @@ The lane targets a Windows host with Visual Studio Build Tools and rustup.
| Visual C++ ARM64 tools | `vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.ARM64 -property installationPath` | Required for native ARM64 check, build, and tests and for x64-to-ARM64 check/build. Tests always require a native runner. |
| Visual C++ ARM64 Spectre-mitigated libraries | `vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Runtimes.ARM64.Spectre -property installationPath` | Required by `regorus` through `msvc_spectre_libs`; the build fails when the selected MSVC toolset lacks `lib\spectre\arm64`. |
| Visual C++ Clang tools | `vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Llvm.Clang -property installationPath` | Provides host-native `libclang.dll` for `bindgen` and `clang-cl.exe` for ARM64 crypto dependencies such as `aws-lc-sys`. On ARM64, the wrapper uses `VC\Tools\Llvm\Arm64\bin`. |
| Visual C++ CMake tools | `vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.CMake.Project -property installationPath` | Provides CMake and Ninja for native dependencies. The x64-to-ARM64 path adds Ninja to `PATH`; Z3 uses an architecture-specific prebuilt release. |
| Visual C++ CMake tools | `vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.CMake.Project -property installationPath` | Provides CMake and Ninja for native dependencies, including static Z3. The wrapper adds Ninja to `PATH`. |
| Windows SDK | `where.exe rc.exe` from a Developer PowerShell | Install an SDK containing target libraries and ARM64 tools. |
| Rust via rustup | `rustc --version` | Add each target being validated: `x86_64-pc-windows-msvc` and/or `aarch64-pc-windows-msvc`. The wrapper also adds the selected target. |
| mise | `mise --version` | Used as a task runner only. |
Expand All @@ -203,10 +205,10 @@ from this skill.
| `OPENSHELL_MXC_SKIP_ARM64` | `0` | Set to `1` to skip ARM64 when using `all` tasks. |
| `OPENSHELL_WINDOWS_BUILD_JOBS` | `CARGO_BUILD_JOBS`, then `4` | Positive Cargo job limit used by the wrapper. |
| `CARGO_TARGET_DIR` | `target` under repo root | Override Cargo output location. Use a short absolute path when x64-to-ARM64 builds approach Windows path-length limits. |
| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing target-compatible system `libz3.lib` and `libz3.dll`, used instead of the prebuilt download. |
| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing a target-compatible static `libz3.lib` built with `/MT`. Directories containing `libz3.dll` fall back to the pinned source build; release dependency checks reject import libraries. |
| `Z3_SYS_Z3_HEADER` | unset | Full `z3.h` path required with a system Z3 library. |
| `Z3_SYS_Z3_VERSION` | `5.1.0` | Pinned official prebuilt Z3 release selected by the wrapper. |
| `READ_ONLY_GITHUB_TOKEN` | unset | Optional token for the Z3 release lookup; GitHub Actions supplies `github.token`. |
| `Z3_SRC_SOURCE_DIR` | downloaded source cache | Optional local Z3 5.1.0 source tree; the default archive is checksum-pinned. |
| `Z3_SYS_Z3_VERSION` | `5.1.0` | Pinned source version selected by the wrapper. |
| `RUSTC_WRAPPER` | inherited | The wrapper resolves an available command to an absolute path. If it is unavailable, the wrapper warns and continues without compiler caching. |

Legacy fork variables such as `OPENSHELL_UPSTREAM`,
Expand Down Expand Up @@ -291,7 +293,8 @@ The GitHub Actions jobs layer architecture-specific `Swatinem/rust-cache`
entries for Cargo registry and dependency target artifacts with sccache's GHA
backend for cacheable Rust compiler outputs. Failed runs also save their usable
dependency artifacts. Pull-request mirrors labeled `test:windows` run Clippy for the
Windows-supported workspace and e2e crates plus Rust tests. Pushes to `windows` and
Windows-supported workspace and e2e crates, Rust tests, packaging helper regressions,
and release builds with static-runtime import checks. Pushes to `windows` and
manual dispatches on that branch run the same lint and test commands in a cache-seed job,
followed by a dependent release-binary build job. The seed and PR jobs use the
same cache namespaces, but pull-request mirrors cannot restore the
Expand All @@ -304,7 +307,7 @@ jobs in the current mirror push run, or push a new mirrored commit. The binaries
The ARM64 check/build steps in this x64-host contract are cross-builds. The
wrapper discovers and adds host-native LLVM and Ninja to `PATH`, requires the
ARM64 compiler and Spectre-mitigated libraries, lets ARM64 crypto crates select
`clang-cl`, and downloads the official prebuilt ARM64 Z3 package.
`clang-cl`, and builds the pinned Z3 source for ARM64 with static CRT linkage.

On ARM64 hosts, validate the native ARM64 check, build, and test path. The
wrapper rejects test targets that do not match the host architecture, so x64
Expand Down Expand Up @@ -390,7 +393,7 @@ MXC on Windows. Each other `compute-driver-*` feature installs its own Windows
rejection stub without linking that driver crate. The default
`in-tree-compute-drivers` alias enables all five features. An MXC-only build
uses `--no-default-features --features compute-driver-mxc` (add `telemetry`
and `openshell-server/prebuilt-z3` as needed).
and `openshell-server/vendored-z3` as needed).

| Driver | Windows build behavior | Runtime behavior |
|---|---|---|
Expand Down Expand Up @@ -423,14 +426,14 @@ architecture through Windows system configuration (not an emulated SSH shell),
caches uploads by SHA256, and runs the unchanged real E2E harness. Results and
host probes return to `target/windows-remote-results`, including nonzero test
outcomes. The remote host needs SSH, OpenSSL, and MXC, not a compiler toolchain.
Package the matching `libz3.dll` from the target-specific Cargo cache alongside
the gateway: Windows prebuilt Z3 uses an import library, not static linkage.
The `windows:build:*` tasks now stage the pinned DLL, check PE architecture,
reject conflicting cache hashes, and verify the copied hash. Local MXC E2E
requires the adjacent DLL and reports a preflight error if it is missing.
Use `-Z3DllPath` when discovery is ambiguous. The native Visual C++ runtime
must be present on the remote host. Verify DLL architecture and the gateway
loader before E2E; do not count missing-DLL crashes as MXC enforcement failures.
The four OpenShell executables use static CRT linkage; the gateway embeds Z3.
The `windows:build:*` tasks verify architecture and reject normal or delayed
imports of Z3 and redistributable CRT DLLs. Do not package `libz3.dll` or require
the Visual C++ redistributable for these binaries. The separate MXC executor
retains its own prerequisites. The remote runner checks imports and gateway
startup before E2E; do not count loader crashes as MXC enforcement failures.
The deprecated `-Z3DllPath` argument remains accepted and ignored for existing
automation; do not restore DLL packaging to implement it.
Verify the SSH host key beforehand. Never send the private SSH key or bundle
the harness signing-key directories. `-SkipBuild` is an explicit stale-artifact
opt-in, not evidence that artifacts match current sources. See the MXC driver
Expand Down Expand Up @@ -515,11 +518,21 @@ Useful log files:
| `test-x86_64-pc-windows-msvc-mxc-real.log` | Native x64 real-MXC integration output. |
| `test-aarch64-pc-windows-msvc-mxc-real.log` | Native ARM64 real-MXC integration output. |

The first check downloads the pinned official Z3 archive for the target
architecture through `z3-sys`. GitHub Actions authenticates the lookup with its
read-only workflow token; local users can set `READ_ONLY_GITHUB_TOKEN` if an
unauthenticated lookup is rate-limited. Cargo stores the extracted library in
its target tree, so the Windows target cache reuses it. The artifact report
The first check downloads a checksum-pinned Z3 5.1.0 source archive unless
`Z3_SRC_SOURCE_DIR` supplies that version locally. Keep downloaded source under
`.cache/windows-z3-source`, outside Cargo target-cache pruning. The existing `vendored-z3`
feature builds a static library and selects the static MSVC runtime from the
Windows targets' `crt-static` setting. Keep this source pin separate from the
z3-src crate's bundled solver version. Cargo caches compiled Z3 per target;
cold builds require CMake and Ninja and take longer than prebuilt-library downloads.
The wrapper uses Ninja explicitly: implicit Visual Studio generator selection
in cmake-rs clears MSVC's Release optimization flags. Verify `/O2` in the
generated build rules when investigating solver performance.
The wrapper explicitly loads `.cargo/windows-msvc.toml` for workspace commands
so native Z3 uses Release optimization in dev/test builds. Do not loosen solver
budgets to compensate for a Debug native solver. Other Rust debug profiles and
non-Windows builds remain unchanged.
The artifact report
computes SHA256 through .NET directly and does not rely on the `Get-FileHash`
module being available inside the mise-launched Windows PowerShell process.

Expand Down
9 changes: 5 additions & 4 deletions .agents/skills/build-openshell-mxc-windows/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ when reading this reference on `main`.
|---|---|
| `tasks/windows.toml` | Mise task definitions for `windows:*`. |
| `tasks/scripts/windows-msvc.ps1` | Visual Studio environment discovery, rustup target setup, Cargo invocation, logs, artifact report. |
| `.github/workflows/windows-msvc.yml` | Opt-in PR lint and test plus `windows` branch cache seeding and dependent binary builds on native x64 and ARM64 runners. |
| `.github/workflows/windows-msvc.yml` | Opt-in PR lint, test, and release builds plus `windows` branch cache seeding and dependent binary builds on native x64 and ARM64 runners. |

## Commands

Expand Down Expand Up @@ -93,9 +93,10 @@ For ARM64, verify the Visual Studio instance contains the ARM64 MSVC tools,
ARM64 Spectre-mitigated libraries, Clang tools, CMake tools, and a Windows SDK.
Clang supplies host-native `libclang.dll` for `bindgen` and `clang-cl.exe` for
ARM64 crypto dependencies such as `aws-lc-sys`. Native and
x64-to-ARM64 builds use the official prebuilt Z3 5.1.0 import library and
`libz3.dll` for the target architecture. Release build tasks stage that DLL
beside the four executables; copy it with them to the runtime host.
x64-to-ARM64 builds compile checksum-pinned Z3 5.1.0 source with the static CRT.
The four executables use static CRT linkage and the gateway embeds Z3. Release
builds verify architecture and reject normal/delayed CRT or Z3 DLL imports.
Do not package `libz3.dll`; the executables do not require the VC++ redistributable.
An x64-to-ARM64 check/build discovers and adds host-native
Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short
`CARGO_TARGET_DIR` if Windows path-length limits are reached.
Expand Down
8 changes: 8 additions & 0 deletions .cargo/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,11 @@
# the header lives in /usr/include/z3/ rather than /usr/include/. The extra -I
# is harmless on systems where the path doesn't exist.
BINDGEN_EXTRA_CLANG_ARGS = "-I/usr/include/z3"

# Windows packages carry their C/C++ runtime rather than requiring the Visual
# C++ redistributable. Native build scripts (cc/cmake) also consume crt-static.
[target.x86_64-pc-windows-msvc]
rustflags = ["-C", "target-feature=+crt-static"]

[target.aarch64-pc-windows-msvc]
rustflags = ["-C", "target-feature=+crt-static"]
13 changes: 13 additions & 0 deletions .cargo/windows-msvc.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

# Loaded only by the Windows MSVC wrapper. Keep native Z3 optimized, as the
# previous prebuilt DLL was, without changing Rust application debug profiles.
# z3-sys forwards its OPT_LEVEL/DEBUG settings to the native CMake build.
[profile.dev.package.z3-sys]
opt-level = 3
debug = false

[profile.test.package.z3-sys]
opt-level = 3
debug = false
26 changes: 20 additions & 6 deletions .github/workflows/windows-msvc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ jobs:
env:
READ_ONLY_GITHUB_TOKEN: ${{ github.token }}
SCCACHE_GHA_ENABLED: "true"
SCCACHE_GHA_VERSION: windows-msvc-${{ matrix.arch }}
SCCACHE_GHA_VERSION: windows-msvc-static-v1-${{ matrix.arch }}
SCCACHE_CLIENT_SIDE: "1"
SCCACHE_BASEDIRS: ${{ github.workspace }}
steps:
Expand Down Expand Up @@ -90,14 +90,22 @@ jobs:
# wrapper; build steps still inherit sccache from the job.
RUSTC_WRAPPER: ""
with:
shared-key: windows-msvc-${{ matrix.arch }}
shared-key: windows-msvc-static-v3-${{ matrix.arch }}
cache-targets: "true"
cache-on-failure: "true"
cache-bin: "false"
- name: Check Windows packaging helpers
run: |
powershell -NoProfile -ExecutionPolicy Bypass -File tasks/scripts/windows-runtime-tests.ps1
if ($LASTEXITCODE -ne 0) { throw "Static runtime regressions failed." }
powershell -NoProfile -ExecutionPolicy Bypass -File tasks/scripts/test-mxc-remote-tests.ps1
if ($LASTEXITCODE -ne 0) { throw "Remote helper regressions failed." }
- name: Lint Windows-supported crates
run: mise run --skip-tools windows:lint:${{ matrix.arch }}
- name: Test
run: mise run --skip-tools windows:test:${{ matrix.arch }}
- name: Build and verify release binaries
run: mise run --skip-tools windows:build:${{ matrix.arch }}
- name: sccache stats
if: always()
run: sccache --show-stats
Expand All @@ -124,7 +132,7 @@ jobs:
env:
READ_ONLY_GITHUB_TOKEN: ${{ github.token }}
SCCACHE_GHA_ENABLED: "true"
SCCACHE_GHA_VERSION: windows-msvc-${{ matrix.arch }}
SCCACHE_GHA_VERSION: windows-msvc-static-v1-${{ matrix.arch }}
SCCACHE_CLIENT_SIDE: "1"
SCCACHE_BASEDIRS: ${{ github.workspace }}
steps:
Expand All @@ -150,10 +158,16 @@ jobs:
env:
RUSTC_WRAPPER: ""
with:
shared-key: windows-msvc-${{ matrix.arch }}
shared-key: windows-msvc-static-v3-${{ matrix.arch }}
cache-targets: "true"
cache-on-failure: "true"
cache-bin: "false"
- name: Check Windows packaging helpers
run: |
powershell -NoProfile -ExecutionPolicy Bypass -File tasks/scripts/windows-runtime-tests.ps1
if ($LASTEXITCODE -ne 0) { throw "Static runtime regressions failed." }
powershell -NoProfile -ExecutionPolicy Bypass -File tasks/scripts/test-mxc-remote-tests.ps1
if ($LASTEXITCODE -ne 0) { throw "Remote helper regressions failed." }
- name: Lint Windows-supported crates
# Keep the seed workload identical to the pull-request workload so the
# windows-branch cache reflects the same lint and test commands.
Expand Down Expand Up @@ -182,7 +196,7 @@ jobs:
env:
READ_ONLY_GITHUB_TOKEN: ${{ github.token }}
SCCACHE_GHA_ENABLED: "true"
SCCACHE_GHA_VERSION: windows-msvc-${{ matrix.arch }}
SCCACHE_GHA_VERSION: windows-msvc-static-v1-${{ matrix.arch }}
SCCACHE_CLIENT_SIDE: "1"
SCCACHE_BASEDIRS: ${{ github.workspace }}
steps:
Expand All @@ -205,7 +219,7 @@ jobs:
env:
RUSTC_WRAPPER: ""
with:
shared-key: windows-msvc-${{ matrix.arch }}
shared-key: windows-msvc-static-v3-${{ matrix.arch }}
cache-targets: "true"
cache-on-failure: "true"
cache-bin: "false"
Expand Down
2 changes: 2 additions & 0 deletions CI.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ The [Windows MSVC workflow on `windows`](https://github.com/NVIDIA/OpenShell/blo
runs native x64 and ARM64 lanes. Windows PR checks are opt-in: add
`test:windows`, then select **Re-run all jobs**
on the current Windows MSVC run. Subsequent mirrored commits run them automatically.
These lanes run packaging helper regressions, Clippy, native tests, and release
builds that reject Z3 or redistributable CRT DLL imports on both architectures.
Windows checks are not required for merging and do not run in merge queues.
Pushes to `windows` and manual runs on that branch seed the lint/test caches and run dependent
release binary builds. Those jobs use `continue-on-error: true`, so inspect
Expand Down
Loading
Loading