[dotfiles] / setup-windows-with-uac.ps1

#Requires -RunAsAdministrator\r
<#\r
  setup-windows-with-uac.ps1\r
  Elevated portion of the Windows provisioning. Invoked by setup-windows.bat\r
  via Start-Process -Verb RunAs, or run manually from an Administrator prompt.\r
\r
  What this installs / configures:\r
    - OpenSSH Client capability (the ssh.exe rsync shells out to, and the\r
      System32 libcrypto.dll the release's own ssh.exe links against)\r
    - ssh-agent set to automatic + started\r
    - OpenSSH Server (sshd) capability: automatic + started + inbound TCP 22\r
    - rsync for Windows (nuket/rsync-windows) in C:\Tools\rsync, on the machine\r
      PATH: rsync.exe plus the ssh.exe it runs, out of the release zip for this\r
      architecture - x86, x64 and arm64 are all published, so both binaries are\r
      native everywhere. The ssh.exe is kept only if it actually starts.\r
    - Visual Studio Community (C++ desktop workload, x86/x64 AND ARM64 build\r
      tools, Spectre libs, Win11 SDK 26100, and - on x64 only - the WDK VSIX,\r
      Clang/LLVM, and the v141 + Windows XP targeting toolset). VS 2022 on x64,\r
      VS 2026 on ARM64; see $VsChannel.\r
    - Windows Driver Kit 10.0.26100 (x64 only)\r
    - Windows Performance Toolkit - xperf, wpr and Windows Performance Analyzer\r
      (wpa.exe) - on the machine PATH\r
\r
  Change $VsEdition below to Professional or Enterprise if needed. $VsChannel\r
  picks the Visual Studio generation and is architecture-split by default:\r
  17 (VS 2022) on x64, where the v141 / Windows XP toolset is wanted, and\r
  18 (VS 2026) on ARM64, where that toolset cannot exist anyway.\r
\r
  ARCHITECTURE. Runs on x64 and on ARM64 (Windows 11 on Arm). On ARM64 the\r
  Visual Studio installer and MSVC are native ARM64 and cross-compile\r
  ARM64/x64/x86 targets.\r
\r
  The two architectures deliberately provision DIFFERENT things. x64 is the full\r
  workstation; ARM64 is a constrained VM set up as a single-compiler build box -\r
  MSVC only, with clang-cl and the WDK dropped there. Neither is dropped for lack\r
  of an ARM64 build; see the comments on $ClangComponents and the WDK step.\r
  What changes is called out at each step, and $HostArch below is what drives it.\r
#>\r
\r
$ErrorActionPreference = 'Stop'\r
\r
# ---------------------------------------------------------------------------\r
# Host architecture\r
#\r
# Read from the machine environment in the registry, because this script can be\r
# launched by a 32-bit or an emulated x64 PowerShell and BOTH of the obvious\r
# sources report the emulated architecture in that case. Measured on this box,\r
# from the x64 PowerShell an x64 shell resolves to:\r
#     [RuntimeInformation]::OSArchitecture      X64     <- wrong\r
#     $env:PROCESSOR_ARCHITECTURE               AMD64   <- wrong\r
#     HKLM\...\Session Manager\Environment      ARM64   <- right\r
# OSArchitecture is documented as the OS's architecture, and on .NET Core it is;\r
# under .NET Framework on Prism it is not, so it is kept only as a fallback.\r
#\r
# $IsArm64 gates:\r
#   - which rsync-windows release zip is fetched (x86 / x64 / arm64, all native)\r
#   - which Visual Studio generation is driven ($VsChannel: 18 on Arm, 17 on x64)\r
#   - the Visual Studio component groups: ARM64 build tools in; the v141/XP\r
#     toolset out because it has no ARM64-hosted compiler and Microsoft does not\r
#     ship Windows XP targeting for Arm hosts; Clang/LLVM and the WDK VSIX out by\r
#     policy rather than by limitation - both are available and native on Arm\r
#   - whether the Windows Driver Kit is installed at all\r
#   - what the VTune and WPT steps report\r
# ---------------------------------------------------------------------------\r
$rawArch  = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment' -ErrorAction SilentlyContinue).PROCESSOR_ARCHITECTURE\r
if (-not $rawArch) { $rawArch = [Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() }\r
$IsArm64  = ($rawArch -eq 'ARM64')\r
$HostArch = if ($IsArm64) { 'Arm64' } elseif ($rawArch -eq 'AMD64') { 'X64' } else { $rawArch }\r
\r
function Write-Step([string]$Msg) {\r
    Write-Host "`n==> $Msg" -ForegroundColor Cyan\r
}\r
\r
function Assert-ExitCode([int]$Code, [string]$Step) {\r
    # 0 = success, 3010 = success + reboot required\r
    if ($Code -notin @(0, 3010)) {\r
        throw "$Step failed with exit code $Code"\r
    }\r
    if ($Code -eq 3010) {\r
        Write-Host "    [reboot required after $Step]" -ForegroundColor Yellow\r
    }\r
}\r
\r
function Show-VsSetupLogs {\r
    # The VS Installer writes dd_*.log to the invoking user's %TEMP%. Because\r
    # this script runs elevated, that %TEMP% belongs to the elevated user and is\r
    # readable here even when it is NOT readable by the non-elevated caller. Fold\r
    # only the NEWEST installer + bootstrapper log into the transcript (the setup\r
    # engine log is where per-component / product errors actually appear) and\r
    # keep it short so the transcript stays readable.\r
    Write-Host "`n==> Collecting VS Installer logs from $env:TEMP" -ForegroundColor Cyan\r
    $recent = Get-ChildItem $env:TEMP -Filter 'dd_*.log' -ErrorAction SilentlyContinue |\r
              Where-Object { $_.LastWriteTime -gt (Get-Date).AddMinutes(-15) }\r
    $picks = @()\r
    $picks += $recent | Where-Object { $_.Name -like 'dd_installer_*'    } | Sort-Object LastWriteTime | Select-Object -Last 1\r
    $picks += $recent | Where-Object { $_.Name -like 'dd_bootstrapper_*' } | Sort-Object LastWriteTime | Select-Object -Last 1\r
    $picks = $picks | Where-Object { $_ }\r
    if (-not $picks) {\r
        Write-Host '    (no VS Installer logs modified in the last 15 minutes)' -ForegroundColor Yellow\r
        return\r
    }\r
    foreach ($l in $picks) {\r
        Write-Host "`n----- $($l.Name) (tail) -----" -ForegroundColor Yellow\r
        Get-Content $l.FullName -Tail 40\r
    }\r
}\r
\r
function Get-VsInstallPath {\r
    # The install path of a Visual Studio matching $script:VsChannel, or $null.\r
    #\r
    # -version is the point. A bare `vswhere -products *` returns EVERY Visual\r
    # Studio on the box, newest first, and handing that path to a bootstrapper of\r
    # a different generation is not a no-op: `vs_community.exe` (17.x) told to\r
    # `modify --installPath <a VS 2026 install>` is a 17.x engine pointed at an\r
    # 18.x product. On a box that already has VS 2026 - increasingly the default -\r
    # every pass below would target the wrong install. Scope the query to the\r
    # generation this script is actually driving.\r
    if (-not (Test-Path $script:VsWhere)) { return $null }\r
    $range = "[$script:VsChannel.0,$($script:VsChannel + 1).0)"\r
    & $script:VsWhere -products '*' -version $range -property installationPath -format value |\r
        Select-Object -First 1\r
}\r
\r
function Invoke-VsModify {\r
    # Run one VS install/modify pass for a named group of components. Splitting\r
    # the install into separate passes makes it obvious WHICH group fails: each\r
    # call prints its label and exit code before Assert-ExitCode throws.\r
    #\r
    # -Optional downgrades a failure to a warning. Used for groups that are not\r
    # available on every host architecture (the v141/XP toolset on ARM64) or that\r
    # the rest of the box does not depend on, so one unavailable component cannot\r
    # cost you the toolchain.\r
    param(\r
        [string]   $Label,\r
        [string[]] $Ids,\r
        [switch]   $Optional\r
    )\r
    Write-Step "Visual Studio: $Label"\r
    if (-not $Ids) {\r
        Write-Host '    (no components in this group for this architecture - skipping)' -ForegroundColor DarkGray\r
        return\r
    }\r
    $addStr = ($Ids | ForEach-Object { "--add $_" }) -join ' '\r
    # --installPath must be quoted: it contains spaces ("C:\Program Files\...").\r
    # Windows PowerShell 5.1's Start-Process does not quote array elements, so we\r
    # hand-build a single string. Component IDs / flags have no spaces.\r
    $common = '--includeRecommended --quiet --norestart --wait'\r
    if ($script:InstallPath) {\r
        $argString = "modify --installPath `"$script:InstallPath`" $addStr $common --force"\r
    } else {\r
        # No existing install yet -> this first pass performs the base install.\r
        $argString = "$addStr $common"\r
    }\r
    Write-Host "    > $script:VsBootstrapper $argString" -ForegroundColor DarkGray\r
    $p = Start-Process -FilePath $script:VsBootstrapper -ArgumentList $argString -Wait -PassThru -NoNewWindow\r
    Write-Host "    exit code: $($p.ExitCode)"\r
    if ($Optional -and $p.ExitCode -notin @(0, 3010)) {\r
        Write-Warning "Visual Studio ($Label) failed with exit code $($p.ExitCode); continuing (this group is optional)."\r
    } else {\r
        Assert-ExitCode $p.ExitCode "Visual Studio ($Label)"\r
    }\r
\r
    # After the first (fresh) install, re-detect the install path so subsequent\r
    # passes use `modify`.\r
    if (-not $script:InstallPath) { $script:InstallPath = Get-VsInstallPath }\r
}\r
\r
# ---------------------------------------------------------------------------\r
# This runs in a separate elevated window that closes the moment it exits, so\r
# the non-elevated caller (setup-windows.bat) can't see what happened. Mirror\r
# all output to a log next to the script and exit with a real code so the\r
# caller can detect success/failure and show the log.\r
# ---------------------------------------------------------------------------\r
$LogFile  = Join-Path $PSScriptRoot 'setup-windows-uac.log'\r
$ExitCode = 0\r
try { Start-Transcript -Path $LogFile -Force | Out-Null } catch {}\r
\r
try {\r
\r
Write-Step "Host architecture: $HostArch"\r
if ($IsArm64) {\r
    # x64 emulation ("Prism") is what carries every x64-only tool this script\r
    # installs - rsync.exe, the WDK and ADK installers, BinSkim in the\r
    # non-elevated half. It is present on Windows 11 on Arm and absent on\r
    # Windows 10 on Arm (x86-only there) and on some Server images, so check\r
    # rather than assume: without it those steps install binaries that cannot\r
    # start, and the failure would otherwise surface much later.\r
    $Prism = Join-Path $env:WINDIR 'System32\xtajit64.dll'\r
    if (Test-Path $Prism) {\r
        Write-Host '    x64 emulation (Prism) present - x64-only tools will run.' -ForegroundColor Green\r
    } else {\r
        Write-Warning "x64 emulation not found ($Prism is missing). rsync.exe, the WDK/ADK installers and BinSkim have no ARM64 build and will not run on this box."\r
    }\r
}\r
\r
# ---------------------------------------------------------------------------\r
# Base tools via winget\r
# ---------------------------------------------------------------------------\r
\r
# ---------------------------------------------------------------------------\r
# OpenSSH Client\r
#\r
# Present by default on Windows 10 1809+ / Windows 11, but removable, and absent\r
# from some Server images. Two things below want it: rsync does not speak ssh\r
# itself, it execs an ssh binary, and the release's own ssh.exe links against the\r
# libcrypto.dll this capability puts in System32. It also owns the ssh-agent\r
# service configured next, so a missing client is why that step would fail.\r
#\r
# Non-fatal, like the server half below: a box that cannot have it should still\r
# finish provisioning.\r
# ---------------------------------------------------------------------------\r
Write-Step 'OpenSSH Client'\r
try {\r
    $sshc = Get-WindowsCapability -Online -Name 'OpenSSH.Client*' |\r
            Select-Object -First 1\r
    if (-not $sshc) {\r
        Write-Warning 'OpenSSH.Client capability not offered by this Windows image - skipping.'\r
    } elseif ($sshc.State -eq 'Installed') {\r
        Write-Host "    OK: $($sshc.Name) already installed"\r
    } else {\r
        Write-Host "    Installing $($sshc.Name) ..."\r
        $r = Add-WindowsCapability -Online -Name $sshc.Name\r
        if ($r.RestartNeeded) { Write-Host '    [reboot required after OpenSSH Client]' -ForegroundColor Yellow }\r
    }\r
} catch {\r
    Write-Warning "OpenSSH Client setup failed: $($_.Exception.Message)"\r
}\r
\r
# ---------------------------------------------------------------------------\r
# SSH agent\r
# ---------------------------------------------------------------------------\r
Write-Step 'Enabling ssh-agent'\r
Set-Service -Name ssh-agent -StartupType Automatic\r
if ((Get-Service ssh-agent).Status -ne 'Running') { Start-Service ssh-agent }\r
\r
# ---------------------------------------------------------------------------\r
# OpenSSH Server (sshd)\r
#\r
# Used to reach the test VMs (VirtualBox) from the host: remote shell plus the\r
# transport rsync rides on when seeding test data in. Ships with Windows 10\r
# 1809+ / Windows 11 as an on-demand capability, so no third-party install.\r
#\r
# The capability normally adds the "OpenSSH Server (sshd)" inbound firewall\r
# rule; we verify and create it if missing (it is absent on some images).\r
#\r
# Non-fatal: a box that can't run sshd should still finish provisioning.\r
# ---------------------------------------------------------------------------\r
Write-Step 'OpenSSH Server (sshd)'\r
try {\r
    $sshd = Get-WindowsCapability -Online -Name 'OpenSSH.Server*' |\r
            Select-Object -First 1\r
    if (-not $sshd) {\r
        Write-Warning 'OpenSSH.Server capability not offered by this Windows image - skipping.'\r
    } else {\r
        if ($sshd.State -ne 'Installed') {\r
            Write-Host "    Installing $($sshd.Name) ..."\r
            $r = Add-WindowsCapability -Online -Name $sshd.Name\r
            if ($r.RestartNeeded) { Write-Host '    [reboot required after OpenSSH Server]' -ForegroundColor Yellow }\r
        } else {\r
            Write-Host "    OK: $($sshd.Name) already installed"\r
        }\r
\r
        Set-Service -Name sshd -StartupType Automatic\r
        if ((Get-Service sshd).Status -ne 'Running') { Start-Service sshd }\r
        Write-Host '    sshd: Automatic + running'\r
\r
        # Firewall: allow inbound 22 on all profiles. VirtualBox host-only and\r
        # bridged adapters are frequently classified Public, and the capability's\r
        # own rule is Private-only on some images, which is what leaves a plainly\r
        # running sshd plainly unreachable.\r
        #\r
        # OpenSSH-Server-In-TCP is the name the capability itself uses, so this\r
        # WIDENS that rule rather than adding a second one next to it. Creating\r
        # our own under a different name would leave the narrow rule in place and\r
        # the box still unreachable on a Public-classified adapter; creating one\r
        # under the same name would collide. Adopt it if present, create it if not.\r
        $ruleName = 'OpenSSH-Server-In-TCP'\r
        if (Get-NetFirewallRule -Name $ruleName -ErrorAction SilentlyContinue) {\r
            Set-NetFirewallRule -Name $ruleName -Enabled True -Profile Any\r
            Write-Host "    Widened firewall rule $ruleName to all profiles"\r
        } else {\r
            New-NetFirewallRule -Name $ruleName -DisplayName 'OpenSSH SSH Server (sshd)' `\r
                -Enabled True -Direction Inbound -Protocol TCP -Action Allow `\r
                -LocalPort 22 -Profile Any | Out-Null\r
            Write-Host "    Added firewall rule $ruleName (TCP 22, all profiles)"\r
        }\r
    }\r
} catch {\r
    Write-Warning "OpenSSH Server setup failed: $($_.Exception.Message)"\r
}\r
\r
# ---------------------------------------------------------------------------\r
# rsync for Windows (github.com/nuket/rsync-windows)\r
#\r
# Windows' OpenSSH ships the transport only - no rsync - so pushing test data\r
# from a Linux box needs an rsync.exe on the Windows side.\r
#\r
# The release is one zip per architecture - rsync-windows-x64.zip and\r
# rsync-windows-x86.zip - each holding rsync.exe, the ssh.exe it runs, and the\r
# licence texts under exactly those names. Both exes are installed, together:\r
# rsync.exe prefers an ssh.exe in its own directory, and the release's build is\r
# what makes a push FROM this box run at line rate. The ssh.exe Windows ships\r
# reads its stdin 3KB at a time, which holds a send at ~17MB/s however fast the\r
# link is. Nothing else about it differs - same ~/.ssh, same ssh-agent, same\r
# known_hosts - and a bare `ssh` still resolves to the in-box client, which sits\r
# ahead of C:\Tools\rsync on the machine PATH.\r
#\r
# That ssh.exe links against the libcrypto.dll the OpenSSH Client capability\r
# above puts in System32: Windows' own LibreSSL, and the fast one, since it uses\r
# AES-NI. No copy of it ships in the zip, so where the capability is missing we\r
# unpack rsync alone rather than an ssh.exe that will not start.\r
#\r
# Installed to C:\Tools\rsync (NOT under "Program Files"): the remote end is\r
# invoked as `rsync --server ...` through cmd.exe, and a path with spaces makes\r
# the client-side --rsync-path escape hatch painful to quote. Added to the\r
# MACHINE PATH so it resolves for every account, including the non-interactive\r
# sshd session, which builds its environment from the machine + user registry\r
# PATH rather than from a login shell.\r
#\r
# Non-fatal: a download failure only warns.\r
# ---------------------------------------------------------------------------\r
Write-Step 'rsync for Windows'\r
$RsyncRepo  = 'nuket/rsync-windows'\r
# The release publishes x86, x64 and - since v3.5.0-gdeeda96f - arm64, so every\r
# architecture this script runs on gets a native build. ARM64 used to take the\r
# x64 zip under emulation, which was defensible (a transfer is bound by the\r
# socket, not by emulated CPU) but cost the release's ssh.exe: that x64 binary\r
# could not load the ARM64 libcrypto.dll in System32 and had to be deleted on\r
# every run. The arm64 asset ships an ARM64 rsync.exe AND an ARM64 ssh.exe, so\r
# both halves are now native and the fast client survives.\r
#\r
# Selected off $HostArch rather than Is64BitOperatingSystem, which answers "true"\r
# on ARM64 and so cannot tell the two 64-bit cases apart.\r
$RsyncAsset = switch ($HostArch) {\r
    'X64'   { 'rsync-windows-x64.zip' }\r
    'Arm64' { 'rsync-windows-arm64.zip' }\r
    default { 'rsync-windows-x86.zip' }\r
}\r
if ($IsArm64) {\r
    Write-Host '    ARM64: using the native arm64 asset (rsync.exe and ssh.exe both ARM64).' -ForegroundColor Green\r
}\r
# The /releases/latest/download/ redirect rather than the API: unauthenticated\r
# API calls are rate-limited to 60/hour per IP, which a provisioning run behind a\r
# shared NAT can genuinely exhaust, and the redirect costs none of that budget.\r
# To hold a box on a known build, pin the tag instead:\r
#     .../releases/download/v3.5.0-gABCDEF0/$RsyncAsset\r
$RsyncUrl   = "https://github.com/$RsyncRepo/releases/latest/download/$RsyncAsset"\r
$RsyncDir   = 'C:\Tools\rsync'\r
try {\r
    New-Item -ItemType Directory -Force -Path $RsyncDir | Out-Null\r
    $RsyncExe = Join-Path $RsyncDir 'rsync.exe'\r
\r
    # Does the release's ssh.exe have the libcrypto it needs? Decided before the\r
    # download so the answer can also gate what comes out of the zip. This is a\r
    # cheap pre-filter only - the authoritative check is running the thing, which\r
    # happens after the unpack below.\r
    $SysCrypto = Join-Path $env:WINDIR 'System32\libcrypto.dll'\r
    $WantSsh   = Test-Path $SysCrypto\r
    if (-not $WantSsh) {\r
        Write-Warning "$SysCrypto is missing - the OpenSSH Client capability is not installed - and the release's ssh.exe needs it. Installing rsync.exe only; rsync will use the ssh on the PATH."\r
    } else {\r
        $v = (Get-Item $SysCrypto).VersionInfo.FileVersion\r
        if ($v -and ([version]($v -replace '[^0-9.]', '')) -lt [version]'3.8.2') {\r
            Write-Warning "$SysCrypto is LibreSSL $v; the release's ssh.exe is built against 3.8.2 (Windows OpenSSH Client 9.5). Update Windows, or expect ssh.exe not to start."\r
        }\r
        # No architecture special-case here any more: the asset chosen above\r
        # matches the host, so the release's ssh.exe and System32's libcrypto.dll\r
        # are the same architecture on every box. The run-it check below still\r
        # happens on all of them - it is cheap, and it is what caught the ARM64\r
        # mismatch back when this took the x64 zip.\r
    }\r
\r
    # Download and unpack beside the targets, not over them, so an interrupted\r
    # transfer can't leave a truncated rsync.exe sitting on the PATH. The scratch\r
    # name still has to END in .zip: Windows PowerShell 5.1's Expand-Archive\r
    # refuses any other extension outright ("*.download is not a supported\r
    # archive file format"), where PowerShell 7 just reads the file.\r
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\r
    $tmpZip = Join-Path $RsyncDir "download-$RsyncAsset"\r
    Invoke-WebRequest -Uri $RsyncUrl -OutFile $tmpZip -UseBasicParsing\r
    Write-Host "    Downloaded $RsyncAsset ($([math]::Round((Get-Item $tmpZip).Length / 1MB, 2)) MB)"\r
\r
    # Verify against the .sha256 published beside it. Same origin, so this is an\r
    # integrity check on the transfer rather than a defence against a hostile\r
    # release - but a truncated or proxy-mangled download is the failure that\r
    # actually happens, and it fails here instead of mid-transfer later.\r
    #\r
    # -OutFile, not .Content: GitHub serves the .sha256 as\r
    # application/octet-stream, and Invoke-WebRequest hands back a byte[] rather\r
    # than a string for any non-text content type, so .Content would compare the\r
    # first BYTE against the hash and fail on every correct download.\r
    $tmpSha = "$tmpZip.sha256"\r
    Invoke-WebRequest -Uri "$RsyncUrl.sha256" -OutFile $tmpSha -UseBasicParsing\r
    $want = (((Get-Content $tmpSha -Raw) -split '\s+')[0]).Trim().ToLower()\r
    Remove-Item $tmpSha -Force -ErrorAction SilentlyContinue\r
    $got  = (Get-FileHash $tmpZip -Algorithm SHA256).Hash.ToLower()\r
    if ($want -and $want -ne $got) {\r
        Remove-Item $tmpZip -Force\r
        throw "SHA-256 mismatch for ${RsyncAsset}: expected $want, got $got"\r
    }\r
    Write-Host "    SHA-256 verified: $got"\r
\r
    # Unpack to a scratch directory and move out the files we asked for, rather\r
    # than expanding straight over the install directory: the zip is the unit\r
    # that was checksummed, and this way a future release adding something to it\r
    # cannot quietly drop that something onto the machine PATH.\r
    $unpack = Join-Path $RsyncDir '.unpack'\r
    if (Test-Path $unpack) { Remove-Item -Recurse -Force $unpack }\r
    Expand-Archive -Path $tmpZip -DestinationPath $unpack -Force\r
    Remove-Item $tmpZip -Force\r
    foreach ($f in 'rsync.exe', 'ssh.exe', 'COPYING.txt', 'NOTICE-ssh.txt') {\r
        $src = Join-Path $unpack $f\r
        if (-not (Test-Path $src)) { continue }\r
        if ($f -eq 'ssh.exe' -and -not $WantSsh) { continue }\r
        Move-Item -Path $src -Destination (Join-Path $RsyncDir $f) -Force\r
    }\r
    Remove-Item -Recurse -Force $unpack\r
\r
    # Prove the unpacked ssh.exe actually starts, and DELETE it if it does not.\r
    #\r
    # This matters more than it looks. rsync.exe prefers an ssh.exe sitting in its\r
    # own directory, so a present-but-unstartable one does not degrade to the\r
    # in-box client - it breaks rsync outright, and the error you get is a remote\r
    # shell that died rather than anything naming ssh.exe. The way to land there\r
    # is a missing or too-old System32 libcrypto.dll. Removing it is the repair:\r
    # rsync then falls back to the ssh on the PATH, which is the in-box client.\r
    #\r
    # This also used to fire on every ARM64 run, when the x64 asset was the only\r
    # 64-bit one published and its ssh.exe could not load the ARM64 libcrypto\r
    # (exit 0xC0000135, STATUS_DLL_NOT_FOUND). The arm64 asset fixed that at the\r
    # source; the check stays because it is how that was found in the first place.\r
    #\r
    # EAP back to Continue for the call: ssh -V writes its version to STDERR, and\r
    # under $ErrorActionPreference = 'Stop' a native command's stderr becomes a\r
    # terminating error, so a WORKING client would look like a broken one.\r
    # $global:LASTEXITCODE is cleared first because an exe that cannot start at\r
    # all throws without setting one, and the stale 0 from the previous native\r
    # command would otherwise read as success.\r
    $SshExe = Join-Path $RsyncDir 'ssh.exe'\r
    if ($WantSsh -and (Test-Path $SshExe)) {\r
        $prevEap = $ErrorActionPreference\r
        $ErrorActionPreference = 'Continue'\r
        $global:LASTEXITCODE = $null\r
        $sshVer = $null\r
        try { $sshVer = (& $SshExe -V 2>&1 | Select-Object -First 1) } catch { }\r
        finally { $ErrorActionPreference = $prevEap }\r
        if ($LASTEXITCODE -eq 0) {\r
            Write-Host "    ssh.exe runs: $sshVer"\r
        } else {\r
            $why = if ($null -eq $LASTEXITCODE) { 'it would not start' } else { "exit $LASTEXITCODE" }\r
            Write-Warning "The release's ssh.exe does not run here ($why)$(if ($sshVer) { ": $sshVer" }). Removing it so rsync.exe falls back to the ssh on the PATH instead of failing on it."\r
            Remove-Item $SshExe -Force -ErrorAction SilentlyContinue\r
            $WantSsh = $false\r
        }\r
    }\r
    Write-Host "    Installed $RsyncExe$(if ($WantSsh) { ' and the ssh.exe it runs' })"\r
\r
    # Machine PATH (HKLM environment). Idempotent: only appends if absent.\r
    $m = [Environment]::GetEnvironmentVariable('Path', 'Machine')\r
    if (-not $m) { $m = '' }\r
    if (($m -split ';') -notcontains $RsyncDir) {\r
        $new = if ($m.Trim()) { $m.TrimEnd(';') + ';' + $RsyncDir } else { $RsyncDir }\r
        [Environment]::SetEnvironmentVariable('Path', $new, 'Machine')\r
        Write-Host "    Added $RsyncDir to the machine PATH (restart shells / sshd to pick it up)."\r
        # sshd caches the environment it was started with, so an already-running\r
        # service would not see the new PATH until restarted.\r
        if ((Get-Service sshd -ErrorAction SilentlyContinue).Status -eq 'Running') {\r
            Restart-Service sshd\r
            Write-Host '    Restarted sshd so it inherits the updated machine PATH.'\r
        }\r
    } else {\r
        Write-Host "    OK: $RsyncDir already in the machine PATH"\r
    }\r
\r
    & $RsyncExe --version | Select-Object -First 1\r
} catch {\r
    Write-Warning "rsync install failed: $($_.Exception.Message)"\r
    Write-Warning "Download $RsyncAsset from https://github.com/$RsyncRepo/releases manually"\r
    Write-Warning "and unpack it into $RsyncDir, keeping rsync.exe and ssh.exe together."\r
}\r
\r
# ---------------------------------------------------------------------------\r
# Visual Studio 2022 Community\r
# ---------------------------------------------------------------------------\r
$TempDir = Join-Path $env:TEMP 'dev_install'\r
New-Item -ItemType Directory -Force -Path $TempDir | Out-Null\r
\r
# Component IDs split into independent groups so each can be installed in its\r
# own pass. The base group is the known-good set; Clang and the Windows XP\r
# toolset are layered on afterwards so a failure clearly identifies the culprit.\r
# Component reference: https://learn.microsoft.com/visualstudio/install/workload-component-id-vs-community\r
$BaseComponents = @(\r
    # Core C++ desktop workload\r
    'Microsoft.VisualStudio.Workload.NativeDesktop'\r
\r
    # MSVC build tools. Named explicitly rather than left to --includeRecommended,\r
    # because what that pulls in depends on the host: on an ARM64 machine the\r
    # workload's recommended set is the ARM64-hosted toolchain targeting ARM64,\r
    # and the x64 cross-compiler is NOT implied. Ask for both and the box builds\r
    # every target it can, whichever architecture it is:\r
    #   on x64   -> x64-hosted, targeting x86/x64 and ARM64\r
    #   on ARM64 -> ARM64-hosted, targeting ARM64 and x86/x64\r
    # Both are native toolchains; neither cross-compile runs under emulation.\r
    'Microsoft.VisualStudio.Component.VC.Tools.x86.x64'\r
    'Microsoft.VisualStudio.Component.VC.Tools.ARM64'\r
\r
    # Spectre-mitigated MSVC runtime libs, for each target above\r
    'Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre'\r
    'Microsoft.VisualStudio.Component.VC.Runtimes.ARM64.Spectre'\r
\r
    # Spectre-mitigated ATL (needed for many driver/COM projects). The x86/x64 and\r
    # ARM64 ATL libraries are separate components; a driver or COM project built\r
    # for ARM64 wants the second one, and it is not implied by the first.\r
    'Microsoft.VisualStudio.Component.VC.ATL.Spectre'\r
    'Microsoft.VisualStudio.Component.VC.ATL.ARM64.Spectre'\r
\r
    # Windows 11 SDK — build number must match the WDK below\r
    'Microsoft.VisualStudio.Component.Windows11SDK.26100'\r
)\r
\r
# WDK Visual Studio extension (VSIX). The silent wdksetup.exe /quiet does NOT\r
# install this (it only prompts interactively), so it has to be asked for here.\r
#\r
# Follows the WDK itself: x64 only. On ARM64 the kit is not installed (see the\r
# WDK step for why), and this VSIX on its own is just the driver project\r
# templates and property pages with no headers, libs or tools behind them.\r
if (-not $IsArm64) {\r
    $BaseComponents += 'Component.Microsoft.Windows.DriverKit'\r
}\r
\r
# Clang/LLVM toolset (ClangCL, used in CMakePresets.json). Two parts: the Clang\r
# compiler itself, plus the MSBuild integration providing the "ClangCL" toolset.\r
#\r
# x64 ONLY, and NOT because ARM64 cannot have it - it can, natively. The VSIX is\r
# productArch=neutral with no chip/machineArch restriction, so the Arm installer\r
# offers it, and MSVC's VC\Tools\Llvm tree is partitioned by HOST architecture\r
# (bin = x86, x64\bin = x64, ARM64\bin = ARM64) with genuine ARM64 binaries in\r
# ARM64\bin, which is where clang-cl.exe lands. It was installed and working here\r
# before this split.\r
#\r
# It is dropped on ARM64 because that machine is a constrained VM provisioned as\r
# a single-compiler build box: MSVC and nothing else. Compiler diversity - MSVC,\r
# VS clang-cl and upstream LLVM over the same sources - now lives entirely on the\r
# x64 machine, which is the one with room for three toolchains. Empty here means\r
# Invoke-VsModify is never called for this group.\r
$ClangComponents = if ($IsArm64) { @() } else {\r
    @(\r
        'Microsoft.VisualStudio.Component.VC.Llvm.Clang'\r
        'Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset'\r
    )\r
}\r
\r
# Windows XP targeting (v141_xp toolset, used in CMakePresets.json). The v141\r
# (VS2017) build tools provide the 14.16 compiler that the XP toolset wraps;\r
# WinXP layers the XP-compatible CRT/SDK on top of it.\r
#\r
# NOT USED ON ARM64, and left empty there. The components are still listed in the\r
# catalog on Arm, so this is not strictly "unavailable" - but the 14.16 toolset\r
# predates Windows on Arm as a host and ships HostX86/HostX64 compilers only, so\r
# the best you could get is an x86-emulated compiler, and Microsoft does not\r
# support XP targeting from an Arm host. Nothing is lost that this box could have\r
# used: Windows XP never ran on ARM64, so an XP-targeting build from an ARM64\r
# host has no purpose beyond producing x86 binaries, which the current toolset\r
# does natively via -A Win32. On x64 the group is installed exactly as before.\r
$XpComponents = if ($IsArm64) { @() } else {\r
    @(\r
        'Microsoft.VisualStudio.Component.VC.v141.x86.x64'\r
        'Microsoft.VisualStudio.Component.WinXP'\r
    )\r
}\r
\r
# Which Visual Studio generation to drive: 17 = VS 2022, 18 = VS 2026. Both have\r
# native ARM64 installers and ARM64-hosted MSVC. This picks the bootstrapper URL,\r
# and - just as importantly - scopes the vswhere lookup below, so a box that\r
# already has a DIFFERENT generation installed is not mistaken for this one.\r
#\r
# Split by architecture on purpose:\r
#   x64   -> 17. The v141 / Windows XP targeting toolset in $XpComponents is the\r
#            reason; that group is the whole point of pinning a generation here.\r
#   ARM64 -> 18. The XP group is skipped on Arm regardless (no ARM64-hosted 14.16\r
#            compiler), so nothing holds this back to 17, and VS 2026 brings the\r
#            newer MSVC. Together with the native ARM64 clang-cl from\r
#            $ClangComponents above, that is the compiler diversity on this box.\r
$VsChannel = if ($IsArm64) { 18 } else { 17 }\r
$VsEdition = 'community'   # community | professional | enterprise\r
\r
# aka.ms path segment per generation. NOT the same word for both: VS 2022 is\r
# published under /release/, VS 2026 under /stable/. This is not cosmetic -\r
# https://aka.ms/vs/18/release/vs_community.exe is not a 404, it silently\r
# redirects to Bing and returns 200 with an HTML body, so a wrong guess here\r
# downloads a web page, names it vs_community.exe, and fails at Start-Process\r
# with something that looks nothing like a bad URL.\r
$VsChannelPath = if ($VsChannel -ge 18) { 'stable' } else { 'release' }\r
\r
# Detect an existing VS install via vswhere (ships with the VS Installer). Note\r
# that vswhere itself lives under the 32-bit Program Files on every architecture,\r
# ARM64 included - the VS Installer is x86-registered there by contract even\r
# though the installer binaries themselves are native.\r
# These are referenced by Invoke-VsModify via $script: scope.\r
$VsWhere = Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe'\r
$InstallPath = Get-VsInstallPath\r
\r
# Report any OTHER Visual Studio generations on the box. They are left alone -\r
# the passes below only ever touch $InstallPath - but when none of them matches\r
# $VsChannel this script is about to download and install a second, largely\r
# redundant toolchain, and that should be a visible decision rather than a\r
# surprise 10GB. (On ARM64, where $VsChannel is 18, an existing VS 2026 IS the\r
# match and gets modified in place rather than duplicated.)\r
if (Test-Path $VsWhere) {\r
    $others = & $VsWhere -products '*' -format value -property installationPath |\r
              Where-Object { $_ -and $_ -ne $InstallPath }\r
    if ($others) {\r
        Write-Step 'Other Visual Studio installations detected'\r
        foreach ($o in $others) { Write-Host "    $o" -ForegroundColor Yellow }\r
        Write-Host "    Not modified. This script drives VS generation $VsChannel only." -ForegroundColor Yellow\r
        Write-Host "    To use one of the above instead, set `$VsChannel at the top of this step." -ForegroundColor Yellow\r
    }\r
}\r
\r
Write-Step "Downloading VS $VsChannel $VsEdition bootstrapper (host: $HostArch)"\r
# aka.ms serves the bootstrapper for the requesting machine's architecture, so on\r
# ARM64 this is the native ARM64 installer - no --arch flag needed or offered.\r
$VsInstallerUrl = "https://aka.ms/vs/$VsChannel/$VsChannelPath/vs_$VsEdition.exe"\r
$VsBootstrapper = Join-Path $TempDir "vs_$VsEdition.exe"\r
Write-Host "    $VsInstallerUrl" -ForegroundColor DarkGray\r
Invoke-WebRequest -Uri $VsInstallerUrl -OutFile $VsBootstrapper -UseBasicParsing\r
\r
# Prove we got an installer and not a web page. The Bing redirect described above\r
# returns 200 with HTML, and every other aka.ms typo behaves the same way, so a\r
# bad channel/edition combination is otherwise only discovered when the "exe"\r
# fails to start. 'MZ' is the DOS header every PE begins with.\r
$vsHead = [IO.File]::ReadAllBytes($VsBootstrapper) | Select-Object -First 2\r
if (-not ($vsHead.Count -eq 2 -and $vsHead[0] -eq 0x4D -and $vsHead[1] -eq 0x5A)) {\r
    throw "Visual Studio: $VsInstallerUrl did not return an executable (no MZ header; $((Get-Item $VsBootstrapper).Length) bytes). Check `$VsChannel / `$VsChannelPath / `$VsEdition."\r
}\r
Write-Host "    OK: bootstrapper is a PE ($([math]::Round((Get-Item $VsBootstrapper).Length / 1MB, 2)) MB)"\r
\r
# Install in three sequential passes. The base set is installed first (this is\r
# the configuration that previously worked); Clang and the XP toolset are added\r
# afterwards. If one fails, its label pinpoints which group is responsible.\r
#\r
# The last two are -Optional: neither the Clang toolset nor XP targeting is\r
# needed to build with MSVC, and on a host where one of them is simply not\r
# offered a hard failure here would cost you the whole toolchain over a component\r
# you can add later from the installer UI.\r
Invoke-VsModify -Label 'base toolset + workload' -Ids $BaseComponents\r
if ($IsArm64) {\r
    Write-Step 'Visual Studio: Clang / LLVM'\r
    Write-Host '    Skipped on ARM64 by choice, not by limitation: a native ARM64 clang-cl is' -ForegroundColor Yellow\r
    Write-Host '    offered here and works. This box is provisioned with MSVC alone; the' -ForegroundColor Yellow\r
    Write-Host '    multi-compiler builds belong on the x64 machine.' -ForegroundColor Yellow\r
} else {\r
    Invoke-VsModify -Label 'Clang / LLVM' -Ids $ClangComponents -Optional\r
}\r
if ($IsArm64) {\r
    Write-Step 'Visual Studio: Windows XP (v141 + WinXP)'\r
    Write-Host '    Skipped on ARM64: the v141 (14.16) toolset ships x86/x64-hosted compilers only,' -ForegroundColor Yellow\r
    Write-Host '    and Windows XP targeting is not offered for Arm hosts. Build x86 with the' -ForegroundColor Yellow\r
    Write-Host '    current toolset instead (cmake -A Win32), which is native here.' -ForegroundColor Yellow\r
} else {\r
    Invoke-VsModify -Label 'Windows XP (v141 + WinXP)' -Ids $XpComponents -Optional\r
}\r
\r
# ---------------------------------------------------------------------------\r
# Verify what actually landed, on disk. Earlier runs silently skipped the v141\r
# toolset and the failure only surfaced at build time, so check here and say so\r
# loudly instead. Widened from that one check to every toolset worth naming,\r
# because the same "installed something, but not the thing you needed" failure is\r
# now possible per host architecture: this reports which MSVC host toolchains are\r
# present (HostARM64 is what proves the compiler is native rather than emulated),\r
# whether clang-cl is there, and - on x64 only - whether v141 is.\r
#\r
# Reporting, not throwing. A missing optional component is something to fix from\r
# the installer UI, not a reason to fail a provisioning run that installed a\r
# working compiler.\r
# ---------------------------------------------------------------------------\r
Write-Step 'Verifying the installed toolsets'\r
$InstallPath = Get-VsInstallPath\r
if (-not $InstallPath) {\r
    Write-Warning "No Visual Studio $VsChannel installation found after the passes above; cannot verify toolsets."\r
} else {\r
    Write-Host "    Install path: $InstallPath"\r
\r
    # What MSVC versions landed, and which host toolchains each one carries.\r
    # HostARM64 is the directory that proves the native ARM64 compiler is here\r
    # rather than an x64 one that would run under emulation.\r
    $msvcRoot = Join-Path $InstallPath 'VC\Tools\MSVC'\r
    foreach ($v in (Get-ChildItem $msvcRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {\r
        $hosts = Get-ChildItem (Join-Path $v.FullName 'bin') -Directory -ErrorAction SilentlyContinue |\r
                 ForEach-Object { $_.Name }\r
        Write-Host "    MSVC $($v.Name): $(if ($hosts) { $hosts -join ', ' } else { '(no bin dir)' })"\r
    }\r
    if ($IsArm64) {\r
        $armHost = Test-Path (Join-Path $msvcRoot '*\bin\HostARM64\ARM64\cl.exe')\r
        if ($armHost) {\r
            Write-Host '    OK: native ARM64-hosted cl.exe present.' -ForegroundColor Green\r
        } else {\r
            Write-Warning 'No HostARM64 cl.exe found - MSVC would run under x64 emulation. Add "MSVC v14x - VS 2022 C++ ARM64/ARM64EC build tools" in the installer.'\r
        }\r
    }\r
\r
    # clang-cl, for the ClangCL toolset in CMakePresets.json. Checked per host\r
    # directory, because the Llvm tree is partitioned by HOST architecture and\r
    # only the matching one is a native compiler.\r
    #\r
    # Look for clang-cl.exe specifically, NOT for the directory. VC\Tools\Llvm\*\bin\r
    # holds clang-format.exe and clang-tidy.exe on every host whether or not the\r
    # Clang component was ever installed - those ship with the NativeDesktop\r
    # workload - so a present ARM64\bin proves nothing on its own. That is the\r
    # false positive to avoid when checking this by hand.\r
    $llvmRoot = Join-Path $InstallPath 'VC\Tools\Llvm'\r
    $clangArm = Test-Path (Join-Path $llvmRoot 'ARM64\bin\clang-cl.exe')\r
    $clangX64 = Test-Path (Join-Path $llvmRoot 'x64\bin\clang-cl.exe')\r
    $clangX86 = Test-Path (Join-Path $llvmRoot 'bin\clang-cl.exe')\r
    $clangAny = $clangArm -or $clangX64 -or $clangX86\r
    if ($IsArm64) {\r
        # Not installed here by design, so its absence is the expected result and\r
        # must not read as a fault. Its PRESENCE is the thing worth a line: a box\r
        # provisioned before this split still carries it, and the component stays\r
        # until it is explicitly removed - the installer never uninstalls what you\r
        # simply stopped asking for.\r
        if ($clangAny) {\r
            Write-Host '    clang-cl: present but no longer provisioned on ARM64 - left over from an earlier run.' -ForegroundColor Yellow\r
            Write-Host '    Remove it with: vs_installer.exe modify --installPath "<path>" --remove Microsoft.VisualStudio.Component.VC.Llvm.Clang --remove Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --quiet' -ForegroundColor Yellow\r
        } else {\r
            Write-Host '    clang-cl: n/a on ARM64 (MSVC only by design; use the x64 box for ClangCL).' -ForegroundColor DarkGray\r
        }\r
    } elseif ($clangAny) {\r
        Write-Host "    clang-cl: $(@(if ($clangArm) {'ARM64'}; if ($clangX64) {'x64'}; if ($clangX86) {'x86'}) -join ', ')" -ForegroundColor Green\r
    } else {\r
        Write-Warning 'clang-cl not found - the ClangCL presets will fail. Add the "C++ Clang tools for Windows" component.'\r
    }\r
\r
    # v141 / XP. Only meaningful where the toolset can exist at all; on ARM64 the\r
    # group above was deliberately skipped, so warning here would be noise about\r
    # a decision this script made on purpose two steps ago.\r
    if ($IsArm64) {\r
        Write-Host '    v141 / Windows XP toolset: n/a on ARM64 (not offered for Arm hosts).' -ForegroundColor DarkGray\r
    } else {\r
        $V141 = Get-ChildItem $msvcRoot -Directory -ErrorAction SilentlyContinue |\r
                Where-Object { $_.Name -like '14.16.*' } | Select-Object -First 1\r
        if ($V141) {\r
            Write-Host "    OK: v141 toolset present ($($V141.Name))" -ForegroundColor Green\r
        } else {\r
            Write-Warning 'v141 (14.16.x) toolset NOT found - the XP build presets will fail.'\r
            Write-Warning 'Add it via Visual Studio Installer > Modify > Individual components:'\r
            Write-Warning '  - MSVC v141 - VS 2017 C++ x64/x86 build tools (v14.16)'\r
            Write-Warning '  - C++ Windows XP Support for VS 2017 (v141) tools'\r
        }\r
    }\r
}\r
\r
# ---------------------------------------------------------------------------\r
# Windows Driver Kit (WDK 10.0.26100)\r
# Build 26100 matches the Windows 11 SDK installed above.\r
# Provides IddCx (iddcx.h / iddcx.lib) and UMDF 2.x for Indirect Display Drivers.\r
# linkid=2335869 -> WDK 26100.6584 (per Microsoft "Other WDK Downloads").\r
#\r
# x64 ONLY. Two reasons, and the second is the one that decided it:\r
#\r
#   1. The ARM64 box builds user-mode software; no driver is developed on it.\r
#\r
#   2. This exact WDK cannot install next to the SDK that VS 2026 brings. The\r
#      WDK requires the MATCHING Windows SDK revision, and revisions are not\r
#      side-by-side - Include\10.0.26100.0 is one directory whichever revision\r
#      wrote it. VS 2026 installs SDK 26100.7705; linkid=2335869 is WDK\r
#      26100.6584, which is the kit paired with VS 2022. So wdksetup.exe aborts:\r
#      exit 15605, WER signature "WDK / 10.1.26100.6584 / Install / 0x80070642"\r
#      (0x642 = 1602, ERROR_INSTALL_USEREXIT - a silent install cancelling\r
#      itself on a failed prerequisite check). It is not an ARM64 or emulation\r
#      problem; the same pairing fails on x64.\r
#\r
#      If a driver ever does need building here, the fix is the WDK that matches\r
#      this generation - Microsoft's "Supported and other WDK downloads" table\r
#      pairs VS 2026 with the 28000.x kit - not this link.\r
#\r
# On x64 with VS 2022 the SDK and this WDK are the matched pair, so it installs.\r
# ---------------------------------------------------------------------------\r
$WdkVersion = '10.0.26100'\r
# Both hives. The WDK installer is a 32-bit program, so on x64 it writes under\r
# WOW6432Node - but which hive a given kit lands in has varied across kit\r
# versions and architectures, and reading only one of them makes an installed WDK\r
# look absent, which costs a needless multi-GB reinstall on every run. Check the\r
# native hive too and take whichever answers.\r
$WdkInstalledRoot = @(\r
    'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows Kits\Installed Roots'\r
    'HKLM:\SOFTWARE\Microsoft\Windows Kits\Installed Roots'\r
) | ForEach-Object { (Get-ItemProperty $_ -ErrorAction SilentlyContinue).WdkBinRootVersioned } |\r
    Where-Object { $_ } | Select-Object -First 1\r
\r
if ($IsArm64) {\r
    Write-Step 'Windows Driver Kit'\r
    Write-Host '    Skipped on ARM64: this box builds user-mode software only, and WDK 26100.6584' -ForegroundColor Yellow\r
    Write-Host '    cannot install beside the 26100.7705 SDK that Visual Studio 2026 brings - the' -ForegroundColor Yellow\r
    Write-Host '    kit needs the matching SDK revision and they are not side-by-side. See the' -ForegroundColor Yellow\r
    Write-Host '    comment above this step for the exit code and what to use instead.' -ForegroundColor Yellow\r
} elseif ($WdkInstalledRoot -and $WdkInstalledRoot -match [regex]::Escape($WdkVersion)) {\r
    # Re-running wdksetup.exe for an already-present version returns exit code\r
    # 2008 (maintenance mode / nothing to do), which is not a real failure.\r
    Write-Step "WDK $WdkVersion already installed - skipping ($WdkInstalledRoot)"\r
} else {\r
    Write-Step 'Downloading WDK installer'\r
    $WdkUrl       = 'https://go.microsoft.com/fwlink/?linkid=2335869'\r
    $WdkInstaller = Join-Path $TempDir 'wdksetup.exe'\r
    Invoke-WebRequest -Uri $WdkUrl -OutFile $WdkInstaller -UseBasicParsing\r
\r
    Write-Step 'Installing WDK'\r
    # wdksetup.exe is a 32-bit binary and runs under emulation on ARM64; the kit\r
    # it lays down does include the ARM64 target headers, libs and tools (the\r
    # signing/deployment tools under bin\arm64), so an ARM64 driver builds from\r
    # an ARM64 host. Only the installer is emulated, not the toolchain.\r
    $proc = Start-Process -FilePath $WdkInstaller -ArgumentList '/quiet /norestart' -Wait -PassThru -NoNewWindow\r
    Write-Host "    WDK installer exit code: $($proc.ExitCode)"\r
    if ($proc.ExitCode -eq 2008) {\r
        # 2008 = the WDK is already present; the installer has nothing to do.\r
        Write-Host '    [WDK already installed (exit 2008) - treating as success]' -ForegroundColor Yellow\r
    } else {\r
        Assert-ExitCode $proc.ExitCode 'WDK'\r
    }\r
}\r
\r
# ---------------------------------------------------------------------------\r
# Windows Performance Toolkit: xperf, wpr, and Windows Performance Analyzer\r
# (wpa.exe) -- ETW CPU + loader profiling and the GUI that reads the traces.\r
#\r
# WPA is NOT a Visual Studio component and has no relationship to VS's own\r
# Performance Profiler (a separate, .diagsession-based tool that cannot open an\r
# .etl). It ships in exactly two places: as an optional FEATURE of the Windows\r
# SDK ("Windows Performance Toolkit", OptionId.WindowsPerformanceToolkit), and\r
# in the Windows ADK, which bundles the same toolkit. Whether the SDK install\r
# that Visual Studio performs happens to select that feature varies with the VS\r
# and SDK version - when it does, WPT lands in\r
# %ProgramFiles(x86)%\Windows Kits\10\Windows Performance Toolkit and the SDK\r
# puts that directory on the machine PATH itself - so this step DETECTS first\r
# and only falls back to installing the ADK (winget owns the versioned download\r
# URL, which makes it the reliable source) when nothing is there. That fallback\r
# is a large download; to install just the toolkit instead, run the standalone\r
# SDK setup with\r
#     winsdksetup.exe /features OptionId.WindowsPerformanceToolkit /q\r
#\r
# There is also a newer WPA in the Microsoft Store (`winget install --id\r
# 9N0W1B2BXGNZ --source msstore`), which updates independently of the SDK. It is\r
# not installed here: the Store package needs an interactive, signed-in session,\r
# which is exactly what this elevated, unattended half does not have.\r
#\r
# Idempotent and non-fatal - it never aborts provisioning.\r
# ---------------------------------------------------------------------------\r
Write-Step 'Windows Performance Toolkit (xperf / wpr / WPA)'\r
$WptDirs = @(\r
    (Join-Path ${env:ProgramFiles(x86)} 'Windows Kits\10\Windows Performance Toolkit'),\r
    (Join-Path $env:ProgramFiles        'Windows Kits\10\Windows Performance Toolkit'),\r
    (Join-Path ${env:ProgramFiles(x86)} 'Windows Kits\10\Assessment and Deployment Kit\Windows Performance Toolkit')\r
)\r
function Find-WptDir { $script:WptDirs | Where-Object { Test-Path (Join-Path $_ 'xperf.exe') } | Select-Object -First 1 }\r
\r
$WptDir = Find-WptDir\r
if ($WptDir) {\r
    Write-Host "    OK: WPT already present ($WptDir)" -ForegroundColor Green\r
} else {\r
    try {\r
        # The ADK manifest offers no ARM64 installer, so on ARM64 winget fetches\r
        # the x64 one; it runs under emulation and lays down a toolkit that does\r
        # include the ARM64 binaries. The SDK feature is the lighter route on any\r
        # architecture and is worth preferring if this fallback ever gives\r
        # trouble - see the winsdksetup.exe line in the comment above.\r
        if ($IsArm64) {\r
            Write-Host '    ARM64: the ADK installer is x64 (emulated); the toolkit it installs is ARM64.' -ForegroundColor Yellow\r
        }\r
        winget install --id Microsoft.WindowsADK --exact --silent --disable-interactivity `\r
            --accept-source-agreements --accept-package-agreements\r
        Write-Host '    Windows ADK (includes Windows Performance Toolkit) installed.'\r
        $WptDir = Find-WptDir\r
    } catch {\r
        Write-Warning "WPT install failed: $($_.Exception.Message)"\r
        Write-Warning 'Install manually: winget install Microsoft.WindowsADK, or add the'\r
        Write-Warning 'Windows SDK "Windows Performance Toolkit" optional feature.'\r
    }\r
}\r
\r
if ($WptDir) {\r
    # Report what actually landed. wpa.exe is the piece people come looking for\r
    # and it is the one that is absent if a trimmed toolkit ever shows up.\r
    foreach ($tool in 'xperf.exe', 'wpr.exe', 'wpa.exe', 'wpaexporter.exe') {\r
        $p = Join-Path $WptDir $tool\r
        if (Test-Path $p) {\r
            Write-Host "    $tool $((Get-Item $p).VersionInfo.ProductVersion)"\r
        } else {\r
            Write-Warning "$tool is missing from $WptDir"\r
        }\r
    }\r
\r
    # The WPT installer normally adds this to the machine PATH itself (and the\r
    # Start Menu gets "Windows Kits > Windows Performance Toolkit" shortcuts for\r
    # WPA and WPR). Re-assert it anyway: on the machine PATH rather than a user\r
    # one so it also resolves for the non-interactive sshd sessions this box is\r
    # driven through, which build their environment from the registry PATH.\r
    # Compared trailing-backslash-insensitively - the installer's own entry has\r
    # one, and adding a second spelling of the same directory is just noise.\r
    $m = [Environment]::GetEnvironmentVariable('Path', 'Machine')\r
    if (-not $m) { $m = '' }\r
    $have = ($m -split ';') | Where-Object { $_.TrimEnd('\') -eq $WptDir.TrimEnd('\') }\r
    if ($have) {\r
        Write-Host "    OK: $WptDir already in the machine PATH"\r
    } else {\r
        $new = if ($m.Trim()) { $m.TrimEnd(';') + ';' + $WptDir } else { $WptDir }\r
        [Environment]::SetEnvironmentVariable('Path', $new, 'Machine')\r
        Write-Host "    Added $WptDir to the machine PATH (restart shells to pick it up)."\r
    }\r
}\r
\r
\r
# ---------------------------------------------------------------------------\r
# Intel VTune Profiler - reported, not installed\r
#\r
# Deliberately NOT automated, unlike everything above. The offline installer is\r
# a ~750 MB download from a URL carrying a per-release GUID\r
# (registrationcenter-download.intel.com/akdlm/IRC_NAS/<guid>/intel-vtune-<ver>_offline.exe)\r
# with no "latest" redirect behind it, so every new build means editing a\r
# hard-coded link in here - and it is only worth having on Intel silicon, since\r
# hardware event-based sampling reads Intel PMU counters. Not a good trade for a\r
# script that has to keep working unattended on any box.\r
#\r
# So this step only reports. To install it, take the Windows offline installer\r
# from\r
#     https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler-download.html\r
# and run it elevated; it installs unattended with\r
#     intel-vtune-<version>_offline.exe -a --silent --cli --eula accept\r
# ---------------------------------------------------------------------------\r
Write-Step 'Intel VTune Profiler (status only)'\r
if ($IsArm64) {\r
    # Not a "not installed yet" case - there is no Windows-on-Arm build of VTune,\r
    # and there is nothing for it to sample: its whole value is reading Intel PMU\r
    # counters. Say so plainly and point at what does work here, rather than\r
    # printing a download link for a product this box cannot run.\r
    Write-Host '    n/a on ARM64: Intel ships no Windows-on-Arm build, and hardware event-based' -ForegroundColor DarkGray\r
    Write-Host '    sampling reads Intel PMU counters. Use the Windows Performance Toolkit above' -ForegroundColor DarkGray\r
    Write-Host '    (wpr / xperf to collect, wpa to analyse) for profiling on this box.' -ForegroundColor DarkGray\r
    Write-Host '    Arm also publishes Arm Performance Studio / Streamline for Arm PMU sampling.' -ForegroundColor DarkGray\r
} else {\r
    $UninstallKeys = @(\r
        'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*'\r
        'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'\r
    )\r
    $vtune = Get-ItemProperty $UninstallKeys -ErrorAction SilentlyContinue |\r
             Where-Object { $_.DisplayName -match 'VTune' } |\r
             Select-Object -First 1\r
    if ($vtune) {\r
        Write-Host "    Installed: $($vtune.DisplayName.Trim()) $($vtune.DisplayVersion)" -ForegroundColor Green\r
        # The oneAPI layout keeps a `latest` junction beside the versioned directory,\r
        # so this path stays right across upgrades.\r
        $VTuneCli = Join-Path $vtune.InstallLocation 'vtune\latest\bin64\vtune.exe'\r
        if (Test-Path $VTuneCli) { Write-Host "    CLI: $VTuneCli" }\r
    } else {\r
        Write-Host '    Not installed.' -ForegroundColor Yellow\r
        Write-Host '    https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler-download.html' -ForegroundColor Yellow\r
        $cpu = (Get-CimInstance Win32_Processor -ErrorAction SilentlyContinue | Select-Object -First 1).Manufacturer\r
        if ($cpu -and $cpu -notmatch 'Intel') {\r
            Write-Host "    (This CPU reports itself as '$cpu' - VTune's hardware event-based sampling wants Intel silicon.)" -ForegroundColor Yellow\r
        }\r
    }\r
}\r
\r
# ---------------------------------------------------------------------------\r
Write-Host "`nAll done." -ForegroundColor Green\r
Write-Host "Host architecture was $HostArch."\r
Write-Host 'If a reboot was flagged above, restart before opening VS or building drivers.'\r
\r
}\r
catch {\r
    $ExitCode = 1\r
    Write-Host "`n==> SETUP FAILED: $($_.Exception.Message)" -ForegroundColor Red\r
    if ($_.ScriptStackTrace) { Write-Host $_.ScriptStackTrace -ForegroundColor DarkGray }\r
    # Only fold in the VS Installer logs when a VS step actually failed; for other\r
    # steps (e.g. WDK) those logs are stale and misleading, so the message above\r
    # is what matters.\r
    if ($_.Exception.Message -match 'Visual Studio') {\r
        try { Show-VsSetupLogs } catch {}\r
    }\r
}\r
finally {\r
    try { Stop-Transcript | Out-Null } catch {}\r
\r
    # This log was created by the elevated (admin) process, so by default the\r
    # non-elevated caller can't delete it (their token has Administrators marked\r
    # deny-only). Grant BUILTIN\Users Modify rights so the user account that runs\r
    # setup-windows.bat can remove the log later. S-1-5-32-545 is the well-known\r
    # Users SID, used here so this is locale-independent.\r
    try {\r
        if (Test-Path $LogFile) {\r
            $usersSid = New-Object System.Security.Principal.SecurityIdentifier('S-1-5-32-545')\r
            $acl  = Get-Acl -Path $LogFile\r
            $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(\r
                        $usersSid, 'Modify', 'Allow')\r
            $acl.AddAccessRule($rule)\r
            Set-Acl -Path $LogFile -AclObject $acl\r
        }\r
    } catch {\r
        Write-Host "    [warning] could not relax ACL on $LogFile : $($_.Exception.Message)" -ForegroundColor Yellow\r
    }\r
}\r
\r
exit $ExitCode\r