Build Openshell Mxc Windows

Build OpenShell-MXC for Windows

This skill maintains the existing native Windows MSVC build lane in the OpenShell repository. The Windows lane is already present in main; do not treat this skill as a first-time porting recipe unless the user explicitly asks for a new fork or a from-scratch bring-up.

The lane is build-only. It validates that OpenShell can compile and test on Windows MSVC for the supported deliverables:

• openshell-gateway.exe
• openshell.exe

It intentionally does not make Windows a Docker, Kubernetes, Podman, or VM runtime host.

Current Repository Shape

The Windows build lane is implemented by these tracked files:

Use the code that is already in the repo. Do not generate a parallel Windows build system, duplicate the wrapper, or add repository automation that the user did not request.

Scope

In scope:

• Refreshing a local checkout to the latest upstream GitHub main.
• Maintaining tasks/windows.toml and tasks/scripts/windows-msvc.ps1.
• Running x64 and ARM64 MSVC checks.
• Building x64 and ARM64 release binaries for openshell-gateway and openshell.
• Running workspace tests on a native x64 or ARM64 host.
• Running focused unsupported-driver contract tests.
• Reporting test counts, skipped/gated areas, warnings, artifacts, and logs.
• Keeping Linux and macOS build paths unchanged.
• Keeping unsupported Windows compute drivers explicit and testable.

Out of scope:

• Docker Desktop support on Windows.
• Kubernetes support on Windows.
• Podman, Podman machine, or Podman Desktop support on Windows.
• VM, Hyper-V, WSL, libkrun, or VM-backed sandbox execution on Windows.
• New MXC compute driver crate.
• OpenShell to MXC policy translation.
• Windows named-pipe driver IPC.
• Windows Credential Manager or DPAPI integration.
• MSI, WinGet, Windows service registration, or installer work.
• Windows supervisor runtime port.

Hard Rules

• Do not enable Docker, Kubernetes, Podman, or VM runtimes on Windows.
• Do not build, package, ship, or smoke-test standalone Windows binaries for unsupported compute drivers.
• Exclude unsupported Windows runtime crates from the Windows gateway dependency graph.
• Unsupported Windows runtime entry points must return a clear unsupported error.
• Keep Windows-specific code behind #[cfg(target_os = "windows")].
• Keep Unix/Linux-only code behind #[cfg(unix)] or #[cfg(target_os = "linux")].
• Do not modify the default Linux mise run ci path unless the user explicitly asks for it.
• Use mise run --skip-tools windows:* for Windows validation. The Windows toolchain is rustup plus Visual Studio Build Tools, not mise-provisioned Rust.
• Prefer one cross-platform run command when the underlying tool supports it (for example, npm --prefix). Add run_windows only when the Windows shell or validation contract genuinely differs.

Recommended Checkout Flow

From a fork checkout where upstream points to the official NVIDIA/OpenShell GitHub repository, use:

git fetch upstream main
git switch main
git merge --ff-only upstream/main
git branch --set-upstream-to=upstream/main main
git status --short --branch

For a direct checkout of the official repository, use origin instead of upstream. Confirm the remote URLs with git remote -v before refreshing.

If there are local changes, preserve or resolve them before refreshing. Do not discard user work unless the user explicitly asks to clean the checkout.

Prerequisites

The lane targets a Windows host with Visual Studio Build Tools and rustup.

Do not install Visual Studio, Rust, Docker, Kubernetes, Podman, WSL, or Hyper-V from this skill.

Environment Variables

Legacy fork variables such as OPENSHELL_UPSTREAM, OPENSHELL_MXC_FORK_DIR, and OPENSHELL_MXC_FORK_BRANCH are no longer part of the normal maintenance workflow. Use them only if the user explicitly asks for a new disposable fork.

Validation Workflow

Run the smallest useful slice first, then broaden:

mise run --skip-tools windows:check:x64
mise run --skip-tools windows:check:arm64
mise run --skip-tools windows:build:x64
mise run --skip-tools windows:build:arm64
mise run --skip-tools windows:test:x64
mise run --skip-tools windows:test:unsupported:x64

For full validation, detect the Windows host architecture first and choose the native lane dynamically:

$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
switch ($arch.ToString()) {
    "X64" {
        mise run --skip-tools windows:ci
    }
    "Arm64" {
        mise run --skip-tools windows:check:arm64
        mise run --skip-tools windows:build:arm64
        mise run --skip-tools windows:test:arm64
        mise run --skip-tools windows:test:unsupported:arm64
        mise run --skip-tools windows:artifacts
    }
    default {
        throw "Unsupported Windows host architecture for OpenShell MSVC validation: $arch"
    }
}

On x64 hosts, windows:ci is the full current CI contract and runs in this order:

1. x64 check.
2. ARM64 check, unless OPENSHELL_MXC_SKIP_ARM64=1.
3. x64 release build.
4. ARM64 release build, unless skipped.
5. Native x64 workspace tests.
6. Focused unsupported-driver contract tests.
7. Artifact reporting.

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 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 windows branch cache because GitHub scopes caches by branch. Merge queues do not run this workflow. Release-branch seed and build jobs use job-level continue-on-error: true; opt-in PR jobs report failures normally. Applying the label alone does not start a run: re-run all jobs in the current mirror push run, or push a new mirrored commit. The binaries are not uploaded or published.

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 static library.

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 compatibility under emulation is not part of these tasks. The aggregate windows:ci task remains the x64-host CI contract; run the explicit ARM64 commands above on an ARM64 host.

The repository-wide mise run pre-commit task is also supported on Windows. Run rust:lockfiles:check, sdk:ts:ci, and go:ci through the Windows-aware tasks when validating those surfaces. Do not count the Go Windows ARM64 race-detector exclusion or POSIX permission-bit skips as security coverage. SDK test dependencies must remain at their lockfile versions. Its Rust check, Clippy, and test dependencies enter the same MSVC environment for the native host target and use an inherited compiler wrapper when it is available. Linux glibc installer tests and Linux service/RPM packaging-asset tests skip explicitly; the Linux build-environment shell-helper test also skips; cross-platform checks continue to run. The blocking Windows Clippy pass excludes unsupported Windows runtime packages as top-level targets. It allows only unused imports, dead code, and unused async functions that result from cfg-gated Windows stubs; other warnings remain errors.

The wrapper limits Cargo to four jobs by default and serializes wrapper-owned Cargo commands with a host-local mutex. It deliberately does not set CL or _CL_: those variables are also consumed by clang-cl, where a global MSVC option such as /MP4 can be interpreted as an input file and break ARM64 crypto dependency builds.