Files
2026-11-14 04:30:55 +01:00

233 lines
15 KiB
Markdown

# Native Windows MSVC build
Prepared 2026-11-14. The native `Prepare` phase was attempted in the retained
case `b208282f-d950-4f5a-bc5e-9e071ccb4d93` and stopped before any download or
installer: `SETUP_PREEXISTING_REBOOT_PENDING`. Separate read-only inspection
confirmed both the CBS `RebootPending` and Windows Update `RebootRequired` keys
already existed; PendingFileRenameOperations had24 entries (contents not read
into the report). No compiler installation, Windows update, restart, trust-store
change, daemon replacement or RMM job was performed. Agent PID5140 and helper
PID6240 remained running; W32Time remained stopped. This is an incomplete
prerequisite, not a successful MSVC qualification. No flag is cleared or ignored.
`Build-NativeMsvc.ps1` is a development build runner, not an installer. Run it in
64-bit Windows PowerShell5.1 from a source bundle containing the exact repository
sources and this script. `Preflight` inventories installed tools and records
private source/tool hashes. `Build` requires an explicitly selected successful
preflight receipt, creates a different private case, and builds an isolated
source copy. It never reuses a partial build case.
## Required native tools
- Rust `1.99.1-x86_64-pc-windows-msvc`, including `cargo`, `rustc`, `rustdoc`,
`clippy-driver`, `rustfmt`, supplied by the official rustup installation.
- Installed Visual Studio C++ tools in the selected range `[17.14,19.0)`;
VS2022 or VS2026 is selected by its signed `vswhere.exe`. The actual product,
compiler version, signer thumbprints and tool hashes are recorded. The current
official [VS release history](https://learn.microsoft.com/en-us/visualstudio/releases/2026/release-history)
includes VS2026; the runner does not download a mutable latest bootstrapper.
- The x64 `cl.exe`, `link.exe`, `lib.exe`, `dumpbin.exe`, and Windows SDK
`10.0.26100.0` x64 `midl.exe`. Microsoft signatures must be valid. The selected
SDK is explicit through `vcvarsall.bat amd64 10.0.26100.0`; see Microsoft's
[native build environment](https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170).
- At least20GiB available on the evidence/build volume by default. This is the
runner's conservative admission threshold, not a measured installation size.
- The locked Cargo dependencies must already be available in the build user's
registry cache. Builds are `--locked --offline`. A missing crate is a failed
prerequisite, never a reason for an automatic online retry. An explicit
development preparation can populate the public dependencies with
`cargo +1.99.1-x86_64-pc-windows-msvc fetch --locked --target x86_64-pc-windows-msvc`.
Do not transfer an entire Cargo home containing credentials or configuration.
The parent's actual read-only VM report
`devstate/windows-client/native-msvc-tools-readonly-20261114.json` now records
103300169728 free bytes, x64, no `vswhere`, no `rustup`, no SDK directories,
W32Time stopped and all execution-policy scopes undefined. No installation was
performed by this preparation. No extra private key, server token or production
signing certificate is needed for source build.
[Rust's MSVC target contract](https://doc.rust-lang.org/rustc/platform-support/windows-msvc.html)
defines native Windows support, Microsoft calling conventions and PE/COFF output.
## Explicit tool-setup plan, not executed
If preflight reports missing C++ tools, first select a **fixed-version** Build
Tools bootstrapper from Microsoft's release history, retain its download URL,
SHA-256, ProductVersion, valid Microsoft Authenticode signature and thumbprint.
Verify the intended absent/new install directory and sufficient disk before
starting setup. Reuse a suitable existing installation rather than updating it.
The exact required component IDs are:
```text
Microsoft.VisualStudio.Workload.VCTools
Microsoft.VisualStudio.Component.VC.Tools.x86.x64
Microsoft.VisualStudio.Component.Windows11SDK.26100
```
The planned bootstrapper arguments are:
```text
--wait --passive --norestart --installPath C:\RmmBuildTools
--add Microsoft.VisualStudio.Workload.VCTools
--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64
--add Microsoft.VisualStudio.Component.Windows11SDK.26100
```
There is no `--force`, repair, OS update, automatic retry or reboot. Persist the
actual setup process/result before returning a bootstrap reply. `0` completes
the setup operation; `3010` means installation requires a restart **before use**,
so stop without building, clearing the flag or implicitly rebooting. `1641`
means a reboot was initiated and violates this no-restart plan. `1618`/`1001`
mean another installation is active; preserve the case and inspect, never kill
the other installer or blindly rerun. A lost SSH reply permits only process/log
readback of that same setup. The build runner itself never launches setup.
[Microsoft component IDs](https://learn.microsoft.com/en-us/visualstudio/install/workload-component-id-vs-build-tools?view=visualstudio),
[parameters and actual exit-code semantics](https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022).
## Build invocation and evidence
Planned, not executed:
```powershell
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Build-NativeMsvc.ps1 -Mode Preflight -SourceRoot C:\Source\rust-discovery
# Review that exact private preflight.json, then use a NEW build case:
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Build-NativeMsvc.ps1 -Mode Build -SourceRoot C:\Source\rust-discovery `
-ExpectedPreflight C:\Users\Administrator\RmmNativeBuilds\<preflight-id>\preflight.json
```
The runner imports only selected developer environment values, rejects caller
compiler flags/wrappers, pins the native compiler/linker/MIDL paths, and keeps
each process's stdout/stderr private. It copies only explicit source extensions
under `crates/` and `proto/`, root Cargo/toolchain files and the MSVC runner/probe;
no `credentials/`, `devstate/`, client key material, repository metadata or local
server state. A protected build root and new protected case prevent unrelated
service users from changing the copied inputs. Source/tool hashes must match
before and after the build.
Before Cargo, Microsoft MIDL generates the real IDL with `/env amd64 /Oicf
/robust /Zp8`; `win64` is intentionally avoided because MIDL documents it as
IA64. The native C probe asserts Microsoft LLP64, numeric Rust ABI64 bytes,
wire-status ABI120 bytes and explicit field offsets. It raises/catches only a
local RPC exception1722 using the same SDK SEH macros/filter; it does not query
W32Time, contact RPC or claim trusted time. There is no vendored WIDL stub or
SEH workaround. [MIDL AMD64/packing](https://learn.microsoft.com/en-us/windows/win32/midl/-env),
[robust NDR checking](https://learn.microsoft.com/en-us/windows/win32/midl/-robust),
[C11 assertions](https://learn.microsoft.com/en-us/cpp/c-language/static-assert-c?view=msvc-170),
[SDK RPC SEH](https://learn.microsoft.com/en-us/windows/win32/rpc/rpctryexcept).
The product build script adds only the native MSVC branch, preserving the GNU
WIDL/clang branch and the C exception boundary. Both still compile the actual
clock sources and preserve their static assertions; SDK or compiler failure is
fatal. The Clock readiness gate stays unqualified. The separate native
service-SID authentication candidate is not qualified by an ABI or build pass.
Cargo then checks Windows Clippy with warnings denied, builds agent/helper and
examples in release, and **links without running** Windows/core unit tests.
The runner records AMD64 PE headers, artifact hashes, generated RPC hashes,
dependency listings and actual Authenticode status. Development output may be
unsigned; this is no signing/installer/production-PKI acceptance. Native unit
execution, LocalService/SYSTEM behavior and a preserving daemon deployment
remain separate explicit gates. A timeout retains its exact process/evidence;
no process-tree kill or retry is implied.
Locally executed preparation checks: PowerShell AST parse; isolated compilation
and Clippy of `build.rs` using locked-version `cc1.11.1`; rustfmt/source checks.
These checks do not prove that Microsoft MIDL, MSVC, the ABI probe or the final
agent/helper builds have run successfully on Windows.
## Concrete native tool bootstrap, prepared separately
`Install-NativeBuildTools.ps1` supplies separate `Prepare`, `InstallVs`,
`InstallRust`, and read-only `Read` phases. Only `Prepare` has been attempted;
the pre-existing reboot need blocked it before downloads. Neither install phase
has run. Both install calls consume create-only start intents
before launching their fixed worker. Each worker runs in its own protected,
demand-only Task Scheduler entry as SYSTEM, without a trigger, automatic retry
or autostart; a second worker entry refuses before installation. This keeps a
long setup independent of the40s SSH/bootstrap reply limit. Results, actual
installer PID and exit code are retained, and the task is disabled after its
worker result. Lost reply/timeout permits readback only. These are explicitly
authorized development-tool bootstrap tasks, never WebUI/RMM jobs or a generic
SYSTEM execution provider. [Task registration](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/register-scheduledtask?view=windowsserver2025-ps),
[fixed service-account principal](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtaskprincipal?view=windowsserver2025-ps).
Inputs are fixed official TLS URLs with ordinary certificate/name validation:
| Input | Pinned SHA-256 |
|---|---|
| Microsoft Build Tools18.11.4 LTSC bootstrapper, file version18.11.12405.450 | `386b5d9a3d6576eab3772c1ecaa7c107ded38146a9c483f41679c194ae1e63b4` |
| rustup1.29.3 Windows x64 MSVC bootstrapper | `38027d51d69a5d05493627a0634dbea52d6cd793c8f072d2373d3f4163eec7db` |
| Rust1.99.1 official distribution manifest | `fb152be80975c194aa5fc684b2aec3a6e14e2b855efe2faa4e5f8ae6e590f463` |
The Microsoft EXE additionally requires valid Microsoft Authenticode and the
exact product/file version. Rustup is checked against its exact
[official archived checksum](https://static.rust-lang.org/rustup/archive/1.29.3/x86_64-pc-windows-msvc/rustup-init.exe.sha256),
with [official archive/install options](https://rust-lang.github.io/rustup/installation/other.html).
Its homes are private case subdirectories; `--no-modify-path`,
`--no-update-default-toolchain`, minimal profile and exactly clippy/rustfmt keep
the developer's default Rust installation/profile/PATH untouched. The fixed
Rust distribution origin is set only for that worker process. Using isolated
homes is an [official rustup option](https://rust-lang.github.io/rustup/installation/index.html).
VS setup uses only `--wait --quiet --norestart --noUpdateInstaller`, the new
fixed target `C:\RmmBuildTools`, and the three components above. It relies on the
official installer's standard Microsoft metadata/package verification. No
custom channel/catalog, checksum override, certificate import or weaker
verification flag is supplied. Installed VS version must then match exactly
18.11.12405.450 and SDK26100 must be present; drift remains incomplete. Setup's
required transitive development dependencies remain Microsoft's responsibility;
this is no general production-installer trust acceptance. No Windows Update
command is invoked. Boot/OS build, machine trust-store fingerprints, machine
PATH, execution policies, W32Time and both exact RMM service states/PIDs are
observed before/after. Detected changes, unexpected setup version,3010/1641 or
restart need stop completion without resetting/undoing or retrying anything.
Scope decision2026-11-14: an initial **custom manual catalog-bundle** design was
rejected. Its channel declared catalog size31851991 and hash
`ef56e369d92855a9667cd03602019375f42b3cd2145041df31cacc071a40e1af`;
the exact official URL instead returned18733589 bytes with hash
`805d16fd14a370cbeb6568179950826ba0cdc6e2cffa44936fddc408ef05cba3`.
Those inputs and rejected source remain privately retained; no mismatching
catalog was accepted or installed. The extra manual bundle was our design,
not an AGENTS/product requirement. The selected replacement uses the supported,
independently hash/Authenticode-pinned official EXE and its own verification,
not a checksum exception or undocumented JSON-signature workaround.
Microsoft documents [standard acquisition and fixed-version bootstrappers](https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022).
Future successful-case sequence; installation and build remain **not executed**.
The failed case above is retained and must not be reused after a prerequisite
change. A manual VM restart has been requested for later coordination; it is
neither implicitly authorized nor an RMM reboot acceptance.
```powershell
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Install-NativeBuildTools.ps1 -Phase Prepare
# Review that exact printed private case and its prepared.json first:
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Install-NativeBuildTools.ps1 -Phase InstallVs -CaseDirectory <case>
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Install-NativeBuildTools.ps1 -Phase Read -CaseDirectory <case>
# Continue only after verified VS exit0 and no restart need:
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Install-NativeBuildTools.ps1 -Phase InstallRust -CaseDirectory <same-case>
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Install-NativeBuildTools.ps1 -Phase Read -CaseDirectory <same-case>
```
This uses the already authorized **development/bootstrap-only** process option
`-ExecutionPolicy RemoteSigned`, as in the previous Windows dev-access and
passive-client bootstrap. The worker uses that same process option and invokes
the hash-checked `.ps1` file normally with `& $p`; it never executes file content
through `ScriptBlock::Create`. A small encoded hash launcher is only transport
for that ordinary file invocation. There is no `Set-ExecutionPolicy`, registry
policy write, Machine/User/GPO change or Bypass option. Persistent scopes stay
unchanged; process scopes are consistently RemoteSigned and GPO precedence is
retained. This permission does **not** decide or authorize the separate RMM
PowerShell job executor's still-unqualified policy contract.
After actual successful setup, pass the recorded private homes to the builder:
```powershell
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\deploy\windows\Build-NativeMsvc.ps1 -Mode Preflight -SourceRoot C:\Source\rust-discovery `
-RustupExe <case>\cargo_home\bin\rustup.exe -RustupHome <case>\rustup_home -CargoHome <case>\cargo_home
```
Use those same arguments with `-Mode Build -ExpectedPreflight <actual-receipt>`.
Populate the isolated public Cargo cache explicitly before an offline build;
there is no automatic fetch/retry in the builder. Native setup, native MIDL/ABI,
unit execution and deployment results are still outstanding until actually run.