[dotfiles] / README.md

# dotfiles

Windows development-box provisioning scripts.

`setup-windows.bat` takes a fresh Windows install to a working C++ / native
development environment: editors and shells, Python, the Visual Studio
toolchain (including the Clang and Windows XP targeting toolsets), the Windows
Driver Kit, Rust (rustup, with the stable MSVC toolchain for the host as the
default), Android Studio and a per-user Android SDK, Android's `adb`, and a
handful of analysis tools (Sysinternals, OpenCppCoverage, BinSkim, the Windows
Performance Toolkit). It also sets the box up to be driven remotely: OpenSSH
Server plus an rsync build for Windows, which is what makes a throwaway VM
reachable from a Linux host.

**Nothing happens until you have seen the plan.** It first lists every step it
can take on this machine and lets you choose which ones to run — see
[Choosing what runs](#choosing-what-runs).

Runs on **x64 and on ARM64** (Windows 11 on Arm), and installs *different things*
on each: x64 is the full workstation, ARM64 a lean build box with a single
C/C++ compiler. See
[Running on ARM64](#running-on-arm64) for what differs and why.

## Files

| File | Purpose |
| --- | --- |
| `setup-windows.bat` | Entry point. Shows the plan and lets you choose, then runs the winget installs, launches the elevated half and prints its log, then runs the non-elevated script. |
| `setup-windows-plan.ps1` | The plan. Run by the batch file before anything else: lists every step for this machine, grouped and numbered, and takes your choice. Run it on its own with `-WhatIf` to preview; add `-HostArch ARM64 -Elevation NOLUA`, or `-VirtualMachine Hyper-V` / `-VirtualMachine none`, to preview another kind of box. |
| `setup-windows-steps.ps1` | The catalog the other four read: every step's name, what it does, and where it cannot run and why. Defines functions only; it is dot-sourced, never run. |
| `setup-windows-current.ps1` | Asked by the batch file before the Claude Code, NASM and Android Studio installs: is what is on the box already current? Those are the installs that would otherwise run in full every time — see [Re-running](#re-running). |
| `setup-windows-no-uac.ps1` | The non-elevated, per-user half: `%USERPROFILE%\.local\bin` (where `claude.exe` lives), WinMerge, BinSkim and upstream LLVM on the user `PATH` (x64 only), the global git config (identity, plus `core.sshCommand`), the native `ninja` pinned ahead of the one Visual Studio bundles, and an architecture audit of everything provisioned. Can also be run directly from an ordinary prompt; it lists its steps and asks first. |
| `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, installs the OpenSSH Client and Server capabilities and starts `sshd`, unpacks the `rsync-windows` release zip for this architecture (`rsync.exe` plus the `ssh.exe` it runs) into `C:\Tools\rsync` on the machine `PATH`, then installs Visual Studio Community with the required components, the WDK, and the Windows Performance Toolkit, and reports whether Intel VTune Profiler is present. Can also be run directly from an Administrator prompt; it lists its steps and asks first. |
| `setup-windows-7-test-env.bat` | Prepares a **Windows 7 VM** as a test target driven from the host by `VBoxManage guestcontrol`. Copy it into the guest and run it there; it is idempotent, so re-run it after any snapshot restore. The per-user half needs no UAC (crash-dialog suppression, no screen blanking, a staging directory, the shared folder on `Z:`); the machine-wide half is skipped with a notice unless run elevated inside the guest. It then reports what the box can actually test: DWM composition, printers, audio capture devices. |

## Usage

1. **Edit `setup-windows-no-uac.ps1` first.** The global git identity near the
   top of the file is empty:

   ```powershell
   $GitUserName  = ''   # e.g. 'Ada Lovelace'
   $GitUserEmail = ''   # e.g. 'ada@example.com'
   ```

   Fill in your own name and email, or leave them empty to keep your identity
   per-repository - the script skips `user.name` / `user.email` rather than
   writing a placeholder, and says so. Everything else in that script is set
   either way.

2. Run it from a normal (non-elevated) prompt:

   ```bat
   setup-windows.bat
   ```

   Before doing anything it prints the plan — every step it can take on this
   machine, grouped and numbered — and waits:

   ```text
   Setup plan - nothing has been done yet
     host:      x64 - the full workstation
     elevation: not elevated; expect a UAC prompt partway through, for the elevated half

    U  Per-user installs (winget, except Claude Code)
      [x]  1 ClaudeCode          Claude Code, native installer: irm https://claude.ai/install.ps1 | iex
      [x]  2 Brave               Brave.Brave
      ...
    E  Elevated setup (setup-windows-with-uac.ps1) - one UAC prompt, runs in its own window
      [x] 25 OpenSshClient       OpenSSH Client capability (ssh.exe, and the libcrypto.dll rsync's ssh.exe needs)
      ...
      [x] 29 VisualStudio        Visual Studio 2022 Community, C++: MSVC for x86/x64 + ARM64, SDK 26100 (several GB)
      ...

     44 of 44 steps selected.

     Enter runs the selected steps. To change them, type step numbers or ranges
     (3 5-7), step names, or a group letter (U M E C) to switch them on or off;
     'all' or 'none' for everything; 'q' to quit without doing anything.
   ```

   Press Enter to run everything marked `[x]`, or switch steps off and on first;
   the list is redrawn after each change. Steps that cannot run on this machine
   are shown as `[-]` with the reason and have no number.

   After Enter it runs unattended apart from a single UAC prompt for the
   elevated half — none at all if you switched every elevated step off. Accept
   it; declining leaves Visual Studio and the WDK uninstalled, and the script
   says so.

3. Restart your shell afterwards so the updated user `PATH` is picked up, and
   reboot if a step reported that a restart was required.

## Choosing what runs

Arguments to `setup-windows.bat` set the starting point of the plan; you can
still adjust it before pressing Enter unless you also pass `-Yes`.

| | |
| --- | --- |
| `setup-windows.bat -WhatIf` | Show the plan for this machine and stop. Nothing is changed. |
| `setup-windows.bat -Skip VirtualBox,Brave` | Start with those switched off. |
| `setup-windows.bat -Only E` | Start with only the elevated half. |
| `setup-windows.bat -Yes` | Do not ask: run the plan as it stands. For unattended runs. |
| `setup-windows.bat /?` | Usage. |

- Steps are named as the plan shows them, comma-separated. A group letter works
  anywhere a name does: `U` per-user installs, `M` machine-wide installs and the
  WiX pin, `E` the elevated half, `C` per-user configuration and Pillow. A name
  it does not recognise stops the run before anything happens — a mistyped
  `-Skip` that was quietly ignored would install exactly what you meant to leave
  out.
- **With no console to ask on** — piped, scheduled, a non-interactive `ssh`
  command — it prints the plan and stops with exit code 2 unless given `-Yes`.
  It never assumes yes.
- The two halves take `-Only`, `-Skip` and `-Yes` too, and when run on their own
  print their part of the plan and ask before doing anything, e.g.
  `.\setup-windows-with-uac.ps1 -Only VisualStudio,Wdk`. From the batch file
  they are handed exactly what the plan left selected, with `-Yes`, since you
  were asked already. With nothing selected for a half it is not started — so
  no UAC prompt is raised for an elevated half with no steps.
- Every step is declared once, in `setup-windows-steps.ps1`: its name, what it
  does, and — with the reason — whether it is x64-only (`-X64Only`), kept off a
  Windows that is itself a virtual machine (`-NotInVM`), or needs an
  administrator (`-Admin`). The planner, the batch file and both halves read
  that one list and check each other: a step the list does not know is refused
  rather than run, and a selected step that nothing implements fails the run
  rather than quietly not happening. Adding a step means a row there plus the
  code that does it, gated on the same name.
- Some steps build on others — the WiX pin needs the .NET SDK, the Clang and XP
  toolsets need Visual Studio. The plan notes it when you switch the
  prerequisite off, but does not stop you: it may well be installed already.

## Re-running

Every step checks before it acts, so running `setup-windows.bat` again on a
provisioned box installs only what is missing or has a newer version out.
Nothing is reinstalled at the version it already has. Where a check cannot
decide — no network, a version string it does not recognise — it installs as
before rather than skipping: a failed check must never be why something is left
missing or out of date.

| step | how it decides |
| --- | --- |
| winget packages | `winget install` on a package winget can see is installed upgrades it when a newer version exists and otherwise does nothing — winget's own default. `--force`, which would install regardless, is never used. |
| `ClaudeCode` | Anthropic's installer always downloads and reinstalls, so `setup-windows-current.ps1` asks first: is `%USERPROFILE%\.local\bin\claude.exe` the latest release — the version the installer's own endpoint names — and the build for this host? Only both skip it. |
| `NASM` | Its per-user fallback install registers nothing, so winget cannot see it and would rerun the installer every time. `setup-windows-current.ps1` compares that `nasm.exe` with the version winget offers. A machine-wide NASM is left to winget. |
| `Rustup` | Needs no help: rustup registers itself under the manifest's product code and rewrites its version when it updates itself, so winget sees what is really there. |
| `AndroidStudio` | Installed only when it is missing. Studio updates itself in the app, and winget's package is marked never to upgrade it; the check keeps winget from installing over a Studio it cannot match to its package, as on a box where Studio was installed some other way. |
| `WiX` | Skipped when 5.0.2 is already in the .NET global tool store. |
| `OpenSshClient`, `OpenSshServer` | Installed only when the capability is not. |
| `Rsync` | The release's `.sha256` is fetched first and compared with the hash recorded when the files were installed (`rsync-windows.sha256`). The zip is downloaded only when they differ or a file is missing. |
| `VisualStudio`, `VsClang`, `VsWinXP` | `vswhere -requires` says whether the install already has every component of a pass. A pass with nothing to add does not run the installer, and with nothing to add anywhere the bootstrapper is not even downloaded. The script never updates Visual Studio itself; the Visual Studio Installer does that. |
| `Wdk`, `Wpt` | Skipped when the kit, or the toolkit, is already there. |
| `BinSkim` | Asks NuGet for the newest stable version before downloading a package well over 100 MB; `nupkg-version.txt` beside the tool records what is installed. |
| `RustToolchain` | `rustup toolchain install` updates stable when there is a newer one and otherwise reports it unchanged. |
| `AndroidSdk` | The command-line tools are re-downloaded only when Google's package index has a newer revision than the installed one; `android sdk install` updates the platform, build-tools and platform-tools only when they are out of date. A re-run with nothing new takes seconds. |
| `Pillow` | `pip install` leaves an installed Pillow alone. It does not upgrade it either. |
| the rest | Configuration: `PATH` entries are added only when missing, and settings are written with the values they already have. |

## Notes

- The elevated half writes a transcript to `setup-windows-uac.log` next to the
  script; the batch file prints it when the elevated window closes. The log is
  gitignored, as it contains local paths.
- **git uses a Win32-OpenSSH client.** `setup-windows-no-uac.ps1` sets
  `core.sshCommand`. Git for Windows otherwise prefers its own bundled MSYS2
  `ssh.exe`, which cannot reach the Windows `ssh-agent` service that the elevated
  half enables - Win32-OpenSSH publishes the agent on a named pipe the MSYS2
  build does not speak. Without this, keys loaded with `ssh-add` from PowerShell
  are invisible to `git`, and a push falls back to hunting for a key file and
  prompting for its passphrase. The value uses forward slashes on purpose: git
  parses `core.sshCommand` with shell quoting rules, in which a backslash is an
  escape character.
- **Which `ssh.exe` git gets.** `C:\Tools\rsync\ssh.exe` — the fast build the
  elevated half unpacks — if it is there, `%WINDIR%/System32/OpenSSH/ssh.exe`
  otherwise. It is the same client with the same `~/.ssh`, agent and
  `known_hosts`; the difference is the stdin pump, and without it anything git
  *pushes* is capped at ~17 MB/s. Candidates are tried by **running** them
  (`ssh -V`), not by `Test-Path`: the fast build needs a `libcrypto.dll` that an
  image without the OpenSSH Client capability does not have, and a client that
  will not start should be found here rather than on the next `git push`.
  This is also why `setup-windows.bat` now runs the elevated half **first** — the
  fast `ssh.exe` has to exist before the git config step can prefer it. The
  non-elevated half still runs even when the elevated one failed; it just falls
  back. Re-run `setup-windows-no-uac.ps1` on its own at any time to re-pick.
- All the scripts are safe to re-run: nothing is reinstalled at the version it
  already has. See [Re-running](#re-running) for how each step decides.
- `setup-windows-no-uac.ps1` runs its steps independently: one failing warns and
  the rest still run, and it exits 1 if any did. The `.bat` reports that and
  carries on. Use `-Only` / `-Skip` to re-run a subset, e.g.
  `.\setup-windows-no-uac.ps1 -Skip BinSkim`.
  Run it **non-elevated**: it writes per-user state (the `HKCU` `PATH`, the
  `.gitconfig` under `%USERPROFILE%`), so an elevated run would configure the
  administrator's profile instead. It warns if you do.
- **Remote access.** OpenSSH Server is installed from the Windows on-demand
  capability (10/1809+), set to start automatically, and given an inbound TCP 22
  firewall rule on *all* profiles — a VM's host-only or bridged adapter is
  routinely classified Public, which is the usual reason a running `sshd` is
  unreachable. Windows ships no `rsync`, so a build of it
  ([nuket/rsync-windows](https://github.com/nuket/rsync-windows)) is installed to
  `C:\Tools\rsync` and added to the **machine** `PATH`. That last detail matters:
  the remote end of an `rsync` runs non-interactively, with no login shell, and
  Win32-OpenSSH builds that environment from the registry `PATH` rather than from
  a profile. Key auth needs `~/.ssh/authorized_keys` ACL'd to just you and
  `SYSTEM`; accounts in the Administrators group use
  `C:\ProgramData\ssh\administrators_authorized_keys` instead.
- **rsync brings its own `ssh.exe`.** That release ships as one zip per
  architecture — `rsync-windows-x86.zip`, `-x64.zip` and `-arm64.zip`, each
  holding `rsync.exe`, an `ssh.exe`, `COPYING.txt` and `NOTICE-ssh.txt` — and the
  elevated half picks the zip matching the host, verifies it against the
  published `.sha256`, unpacks the pair together, then **runs** the unpacked
  `ssh.exe` and removes it if it will not start. Together is the point:
  `rsync.exe` prefers an `ssh.exe` sitting in its own directory, and the release
  builds one because the client Windows ships reads its stdin 3 KB at a time,
  which holds a transfer *from* the box at ~17 MB/s however fast the link is.
  Nothing else about it differs — same `~/.ssh`, same `ssh-agent`, same
  `known_hosts` — and a bare `ssh` still resolves to the in-box client, which
  sits ahead of `C:\Tools\rsync` on the `PATH`. It links against the
  `libcrypto.dll` the **OpenSSH Client** capability puts in `System32` (Windows'
  own LibreSSL, which uses AES-NI) and ships no copy of its own, so the elevated
  half installs that capability first and falls back to `rsync.exe` alone,
  warning, on an image that will not offer it.
- The `rsync` download follows the `releases/latest/download/` redirect rather
  than the GitHub API: unauthenticated API calls are rate-limited to 60/hour per
  IP, which a provisioning run behind a shared NAT can genuinely exhaust. To hold
  a box on a known build, pin the tag in `$RsyncUrl`
  (`.../releases/download/<tag>/<asset>`) instead.
- Visual Studio is installed in three labelled passes (base workload, Clang/LLVM,
  XP toolset) so a failure identifies which component group is responsible. On
  ARM64 only the first runs — the other two are skipped there, each printing why.
  The last two are optional passes: a failure there warns and provisioning continues,
  because neither is needed to build with MSVC and losing the whole toolchain
  over a component you can add later from the installer UI is the worse outcome.
- **Which Visual Studio generation.** `$VsChannel` near the VS step picks it —
  `17` for VS 2022, `18` for VS 2026 — and `$VsEdition` picks Community /
  Professional / Enterprise. It is **architecture-split by default**: 17 on x64,
  where the `v141`/XP toolset in the component list is the reason to pin a
  generation, and 18 on ARM64, where that toolset cannot exist anyway (no
  ARM64-hosted 14.16 compiler), so nothing holds Arm back to the older one.
- **The aka.ms path differs per generation** — VS 2022 is published under
  `/release/`, VS 2026 under `/stable/`, which `$VsChannelPath` derives. This is
  not cosmetic: `https://aka.ms/vs/18/release/vs_community.exe` is *not* a 404,
  it silently redirects to Bing and returns **200 with an HTML body**. A wrong
  guess there downloads a web page, names it `vs_community.exe`, and fails later
  at `Start-Process` with something that looks nothing like a bad URL. The step
  therefore checks the downloaded file starts with an `MZ` header and throws with
  the URL if it does not.
- `Get-VsInstallPath` scopes its `vswhere` query to that generation
  (`-version "[17.0,18.0)"`). That scoping is load-bearing: a bare
  `vswhere -products *` returns **every** Visual Studio on the box, newest
  first, and on a machine that already has VS 2026 the old unscoped lookup handed
  an 18.x install path to a 17.x bootstrapper as `modify --installPath`, so every
  pass targeted the wrong product. The step now also lists any other generations
  it found and states that it left them alone — when none of them matches
  `$VsChannel` the script is about to fetch a second, largely redundant
  toolchain, and that should be a visible decision. On ARM64, where `$VsChannel`
  is 18, an existing VS 2026 **is** the match and gets modified in place rather
  than duplicated.
- **Windows Performance Analyzer is not part of Visual Studio.** VS has its own
  Performance Profiler, which is a different, `.diagsession`-based tool and
  cannot open an `.etl`. WPA ships with `xperf` and `wpr` in the Windows
  Performance Toolkit, which exists in exactly two places: as an optional
  *feature* of the Windows SDK (`OptionId.WindowsPerformanceToolkit`) and inside
  the Windows ADK, which bundles the same toolkit. Whether the SDK install that
  Visual Studio performs selects that feature varies by version, so the elevated
  half **detects first** — `%ProgramFiles(x86)%\Windows Kits\10\Windows
  Performance Toolkit`, its 64-bit twin, and the ADK location — and only falls
  back to `winget install Microsoft.WindowsADK` when nothing is there. It then
  re-asserts that directory on the machine `PATH` (the toolkit's own installer
  usually does this, and the Start Menu gets *Windows Kits > Windows Performance
  Toolkit* shortcuts for WPA and WPR). To install just the toolkit instead of the
  whole ADK, run the standalone SDK setup with
  `winsdksetup.exe /features OptionId.WindowsPerformanceToolkit /q`. A newer WPA
  also exists in the Microsoft Store (`winget install --id 9N0W1B2BXGNZ --source
  msstore`); it is not installed here because the Store source needs an
  interactive, signed-in session, which the unattended elevated half does not
  have.
- **Intel VTune Profiler is reported, not installed.** The elevated half prints
  whether it is on the box, its version, and the path to `vtune.exe`; if it is
  missing it prints the download page instead (and says so if the CPU is not
  Intel). Automating the install is not worth it here: the offline installer is a
  ~750 MB download from a URL carrying a per-release GUID with no "latest"
  redirect behind it, so every new build would mean editing a hard-coded link,
  and it is only worth having on Intel silicon since hardware event-based
  sampling reads Intel PMU counters. It does install unattended if you want it
  scripted elsewhere:

  ```powershell
  intel-vtune-<version>_offline.exe -a --silent --cli --eula accept
  ```

  **Run it from an administrator account, elevated.** Hardware event-based
  sampling (`uarch-exploration`, `memory-access`, `hotspots -knob
  sampling-mode=hw`) requires it, and VTune warns about that at the top of every
  unelevated run. Worth knowing that the failure it gives there is *"cannot
  recognize the processor"*, which reads like a hardware problem and is not one:
  the drivers (`sepdrv5`, `sepdal`, `vtss`) are installed and running, and VTune
  identifies the PMU through them. There is no group to join to get around it —
  the Linux driver can be handed to a `vtune` group, but on Windows the
  documented answer is to run as administrator.

- **Collect traces from an elevated Administrator session. Non-elevated
  collection was tried here and abandoned.** The attempt was to put one ordinary
  account into `BUILTIN\Performance Log Users`, which appears in the default
  security descriptors ETW keeps per provider GUID under
  `HKLM\SYSTEM\CurrentControlSet\Control\WMI\Security`, and collect without a UAC
  prompt. It does not survive contact with the real workflow: `xperf -on base`
  and `wpr -start` drive the *NT Kernel Logger*, reserved for Administrators and
  LocalSystem, and granting the group `SeSystemProfilePrivilege` ("Profile system
  performance") plus an explicit ACE for `TRACELOG_ACCESS_KERNEL_LOGGER` on
  `SystemTraceControlGuid` — all three in place, across a reboot — still answered

  ```text
  xperf: error: NT Kernel Logger: Access is denied. (0x5).
  ```

  It is not a check an ACE overrides, and the same wall turned up often enough
  elsewhere that the whole approach was dropped rather than carried as a
  half-working path. **Sign in to an administrator account and run `xperf`, `wpr`
  and VTune from an elevated prompt.** Analysis is the exception and never needed
  any of this: `wpa.exe` opens an existing `.etl` as a plain user.

  If an earlier revision of these scripts ran on a box, it left that account in
  the group. Take it back out with:

  ```powershell
  net localgroup "Performance Log Users" DOMAIN\user /delete
  ```

  Two revisions also granted the privilege and the ACE. Undo the privilege in
  `secpol.msc` > Local Policies > User Rights Assignment > "Profile system
  performance" by removing Performance Log Users. The ACEs sit in the
  `{9e814aad-3204-11d2-9a82-006008a86939}` value under
  `HKLM\SYSTEM\CurrentControlSet\Control\WMI\Security`: strip the `LU` entries
  from that descriptor rather than deleting the value, which also carries entries
  for SYSTEM, Administrators and two service accounts.

- **Claude Code is not installed through winget.** Recent releases of
  `Anthropic.ClaudeCode` are broken through that route, so the batch file runs
  Anthropic's own installer, `irm https://claude.ai/install.ps1 | iex`: it
  checks the download against the release manifest's SHA-256 and puts `claude`
  in `%USERPROFILE%\.local\bin`, per-user. The `LocalBinPath` step in
  `setup-windows-no-uac.ps1` makes sure that directory is on the user `PATH`
  (creating it if need be); the installer itself only prints a reminder. Two
  things are fixed up around it.
  The script picks its ARM64 or x64 build from `$env:PROCESSOR_ARCHITECTURE`
  alone, which reads `AMD64` in an emulated x64 shell on ARM64 (see
  [Detecting the architecture](#detecting-the-architecture)), so the batch file
  sets that variable from the registry's answer for the installer's process.
  And the script refuses a 32-bit PowerShell, which is what `powershell` is from a
  32-bit `cmd.exe`, so it is run through `%SystemRoot%\Sysnative` when that
  exists. A copy left over from the winget route can shadow the new one on the
  `PATH`; the step warns if it finds one (`winget uninstall
  Anthropic.ClaudeCode` removes it), and the architecture audit shows which
  `claude.exe` wins.
- **Rust.** winget installs rustup (`Rustlang.Rustup`, per-user, under
  `%USERPROFILE%\.cargo` and `.rustup`). Its silent install is
  `rustup-init -y -q`, which already sets up a stable toolchain for whatever
  host rustup detects. The `RustToolchain` step in `setup-windows-no-uac.ps1`
  then pins the answer: `stable-x86_64-pc-windows-msvc` on x64,
  `stable-aarch64-pc-windows-msvc` on ARM64, installed, made the default, and set
  as rustup's default host. That matters on ARM64, where an x64 rustup —
  an older install, or one started from an emulated shell — would otherwise
  quietly set up an emulated compiler. The `-msvc` toolchains link with the
  Visual Studio the elevated half installs, but only need it to *build*:
  installing rustup first is fine, and with `-y` rustup-init just warns that
  the prerequisites are missing rather than installing a Visual Studio of its
  own. Re-running the step updates stable. It also resets the default to
  stable, so leave `RustToolchain` out of the plan if you have chosen another
  default on purpose. The architecture audit reports the compiler *inside* the
  toolchain: `.cargo\bin\rustc.exe` is a rustup proxy, so its architecture is
  rustup's, not the compiler's.
- **`adb` and `fastboot`** come from `Google.PlatformTools`, a portable zip that
  winget unpacks under `%LOCALAPPDATA%\Microsoft\WinGet\Packages` and puts on the
  user `PATH` (`adb.exe` needs the `AdbWinApi` DLLs beside it). The manifest
  calls it x64, but every binary in it is 32-bit **x86** — checked on r37.0.1 —
  and there is no ARM64 build. It runs under WOW64 on x64 and under x86
  emulation on ARM64, which every Windows on Arm has; the audit lists it as
  expected. It stays on ARM64 for the same reason `iperf3` does: it is bound by
  the link to the device, not by the CPU.
- **Android Studio and the Android SDK** are separate steps. Studio
  (`Google.AndroidStudio`) is machine-wide — its installer elevates itself — and
  is installed only when missing, since it updates itself. The SDK is per-user,
  in Studio's default `%LOCALAPPDATA%\Android\Sdk` (or wherever `ANDROID_HOME`
  already points): the command-line tools, platform-tools, and the newest
  stable platform and build-tools from Google's package index, read at run
  time. That is what Studio's first-run wizard would set up, and it is enough
  to build: Gradle fetches whatever else a project asks for. The step sets
  `ANDROID_HOME`, puts the command-line tools on the user `PATH`, and points
  `JAVA_HOME` at Studio's bundled JDK for a command-line `gradlew` when there is
  no `JAVA_HOME` already. The SDK licences are accepted on your behalf — the
  plan says so before anything runs. Both are x64-only: Studio has no ARM64
  build, and the SDK's Windows build tools are x86/x64. Three things about
  the current command-line tools (23.0), found when this step was written:
  - `sdkmanager` is deprecated. It is now a shim over the new **Android CLI**
    (`android.exe`), which on first use installs itself into
    `%USERPROFILE%\.android` — about 90 MB in `bin\`, and a `cli\` folder with
    its own Java runtime. It also keeps a spool of **usage metrics** there and
    uploads them; no opt-out was found. The step calls the CLI directly.
  - **CLI 1.0.16406183 crashes on the way out of every `sdk` command**
    (`0xC0000409`) on this Windows 10, after the work is done. So the step does
    not trust its exit code: each package must be present afterwards, and a
    crash with everything in place is printed as a note, not a failure.
  - Windows PowerShell 5.1's progress bar made the 148 MB command-line tools
    download take about ten minutes; with it off, the whole first install took
    under a minute. The BinSkim download now skips the progress bar for the
    same reason.
- The scripts were extracted from a native Windows project, so the component
  selection is tuned for that: Spectre-mitigated runtimes, the v141/XP toolset,
  and driver-kit headers. Trim the component lists in the `.ps1` if you don't
  need them — each group is a plain array near the top.

## Running on ARM64

All three scripts detect the host architecture and adapt. Nothing needs a flag —
run `setup-windows.bat` exactly as on x64.

**The two architectures deliberately install different things.** x64 is the full
workstation; ARM64 is provisioned as a lean build box with a single C/C++
compiler. See
[ARM64 installs less, on purpose](#arm64-installs-less-on-purpose) below for the
list and the reasoning.

### Detecting the architecture

All three scripts read the **machine-level registry value**, not the environment
and not `RuntimeInformation.OSArchitecture`. Both of those report the *emulated*
architecture inside an emulated x64 process — which is what you get by launching
`powershell` or `cmd` from an x64 shell (Git Bash, for one) on an ARM64 box.
Measured on this machine, from that emulated shell:

| source | reports |
| --- | --- |
| `[RuntimeInformation]::OSArchitecture` | `X64` ✗ |
| `%PROCESSOR_ARCHITECTURE%` | `AMD64` ✗ |
| `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment` | `ARM64` ✓ |

`OSArchitecture` is documented as the *OS's* architecture, and on .NET Core it
is; under .NET Framework on Prism it is not. It is kept only as a fallback. This
used to be a cosmetic mislabel in a log line — now that the architecture decides
which packages are installed at all, reading it wrong provisions the wrong
machine.

> The batch file calls `reg.exe` by full path and parses it **without** piping to
> `find`/`findstr`. Both are shadowable by anything earlier on the `PATH`, and a
> POSIX `find` turns the whole detection into a silent no-op that leaves the
> emulated answer standing. That is not hypothetical; it is how this was found.

**The build toolchain is fully native.** Visual Studio's ARM64 installer and MSVC
are ARM64 binaries, and MSVC cross-compiles every target from an ARM64 host with
no emulation in the compiler:

```bat
cmake -B build -A ARM64   && cmake --build build --config Release   :: native
cmake -B build -A x64     && cmake --build build --config Release   :: cross
cmake -B build -A Win32   && cmake --build build --config Release   :: cross
```

**ARM64 uses Visual Studio 2026** (`$VsChannel = 18`) while x64 stays on VS 2022.
Nothing forces that split — the Arm box simply has no reason to stay on the older
generation, since the `v141`/XP toolset that pins x64 there cannot run on Arm at
all — so Arm takes the newer MSVC. Note this is a *default*, not a limitation:
VS 2026 does still offer `v141` and `WinXP` as components on x64.

The base component group now names `VC.Tools.x86.x64` **and** `VC.Tools.ARM64`
explicitly instead of relying on `--includeRecommended`, which resolves
differently per host: on an ARM64 machine the workload's recommended set is the
ARM64-targeting toolchain, and the x64 cross-compiler is *not* implied. Spectre
runtimes and ATL are likewise requested for both target families
(`VC.ATL.ARM64.Spectre` is a separate component from `VC.ATL.Spectre`).

### ARM64 installs less, on purpose

The ARM64 machine here is a constrained VM, and nearly everything it was
installing without a native build was going to run under Prism emulation anyway.
The exceptions were individually defensible and collectively a VM full of x64
binaries. So the split is now explicit: **ARM64 gets MSVC and nothing that
duplicates it or that exists only as an x64 binary.**

| dropped on ARM64 | where | why |
| --- | --- | --- |
| `Brave.Brave` | `setup-windows.bat` | no ARM64 build; an emulated browser is the slowest thing on the box, and Edge is in-box and native |
| `WinMerge.WinMerge` | `setup-windows.bat` | ARM64 ships as a **machine-scope** installer only, so an unelevated `winget` can install nothing but the emulated x64 build |
| `LLVM.LLVM` | `setup-windows.bat` | second Clang, dropped along with VS's `clang-cl` |
| `NASM.NASM` | `setup-windows.bat` | x86/x86-64 assembler with no ARM64 target; MSVC's `armasm64.exe` is the native one |
| `Google.AndroidGPUInspector` | `setup-windows.bat` | x64-only, and it profiles Android devices rather than anything compiled here |
| `OpenCppCoverage` | `setup-windows.bat` | collects coverage by stepping x86/x64 instructions, so it cannot instrument an ARM64 binary at all |
| VS Clang/LLVM component | `setup-windows-with-uac.ps1` | see below |
| Windows Driver Kit | `setup-windows-with-uac.ps1` | see below |
| BinSkim | `setup-windows-no-uac.ps1` | the NuGet package publishes `win-x64` only |
| Android Studio (`Google.AndroidStudio`) | `setup-windows.bat` | Google publishes no Windows ARM64 build |
| Android SDK | `setup-windows-no-uac.ps1` | its Windows build tools are x86/x64 only, as is Android Studio |

x64 keeps every one of them. The decision is made in one place,
`setup-windows-steps.ps1` (`-X64Only`, with the reason): the plan shows each as
`[-]` with that reason, and the run log repeats it where the step would have
run, rather than leaving a silent gap.

**`clang-cl` is dropped by choice, not by limitation.** A native ARM64 `clang-cl`
*is* offered on Arm and did work here before the split. Two things establish
that: the `VC.Llvm.Clang` VSIX is `productArch=neutral` with no `chip` or
`machineArch` restriction, so the Arm installer offers it; and MSVC's
`VC\Tools\Llvm` tree is partitioned by **host** architecture, with real ARM64
binaries in `ARM64\bin`, which is where `clang-cl.exe` lands:

| directory | host |
| --- | --- |
| `VC\Tools\Llvm\bin` | x86 |
| `VC\Tools\Llvm\x64\bin` | x64 |
| `VC\Tools\Llvm\ARM64\bin` | ARM64 |

> Watch for a false positive when checking by hand: `VC\Tools\Llvm\*\bin` holds
> `clang-format.exe` and `clang-tidy.exe` on **any** host, installed or not —
> those ship with the NativeDesktop workload. Their presence does not mean the
> compiler is there; look for `clang-cl.exe`.

Note that the VS installer never uninstalls a component you simply stopped
asking for, so a box provisioned before this split keeps its `clang-cl` until it
is explicitly removed. The verification step says so and prints the
`--remove` line.

**The WDK is dropped for two reasons, and the second one bites on x64 too.** The
ARM64 box builds user-mode software, so it does not need a driver kit — but this
particular WDK *cannot* install here regardless. The kit requires the **matching
Windows SDK revision**, and revisions are not side-by-side: `Include\10.0.26100.0`
is one directory, whichever revision wrote it. VS 2026 installs SDK
**26100.7705**; `linkid=2335869` is WDK **26100.6584**, the kit paired with VS
2022. `wdksetup.exe /quiet` therefore aborts:

```
WDK installer exit code: 15605
WER: WDK / 10.1.26100.6584 / Install / 0x80070642
```

`0x642` is `1602`, `ERROR_INSTALL_USEREXIT` — a silent install cancelling itself
on a failed prerequisite check. Nothing to do with Arm or emulation; the same
pairing fails on x64. If a driver ever does need building against VS 2026, use
the kit Microsoft's [supported WDK downloads](https://learn.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads)
table pairs with it — the 28000.x one — not this link. x64 with VS 2022 has the
matched pair, so it installs there.

**Compiler diversity now lives on the x64 box**, which has room for three
toolchains: MSVC, VS's `clang-cl`, and **upstream LLVM** (`winget install
LLVM.LLVM`). Upstream runs on its own schedule, is usually several major versions
ahead of the Clang VS bundles, and installs to `C:\Program Files\LLVM` rather
than inside the VS tree, so the two are genuinely independent. Two Clang majors
plus MSVC over the same sources is what catches the bugs a single toolchain
agrees with itself about. Watch the `PATH` there: a bare `clang-cl` may resolve
to upstream while CMake's `-T ClangCL` keeps using VS's, so pass a full
`-DCMAKE_CXX_COMPILER` when it matters.

**Rust is on both boxes, and native on ARM64.** It is a different language
rather than a second C/C++ compiler, so it does not bend the one-compiler rule,
and its `-msvc` toolchain links through MSVC's own `link.exe`. The ARM64 box
gets `stable-aarch64-pc-windows-msvc`; to build x64 Rust code from there, add
the x64 *target* (`rustup target add x86_64-pc-windows-msvc`) rather than an x64
host toolchain, which would run emulated.

What you end up with on ARM64:

| | On ARM64 |
| --- | --- |
| **Native ARM64** | Git, Python, .NET SDK, PowerShell, VS Code, Windows Terminal, Sysinternals, Claude Code, CMake, Ninja, the VS installer, **MSVC**, MSBuild, the SDK tools (`rc`, `signtool`), rustup and **Rust** (`stable-aarch64-pc-windows-msvc`), the in-box OpenSSH client, and the Windows Performance Toolkit. |
| **Emulated** | `iperf3` (x64; network-bound), `adb` and `fastboot` (x86 — Google ships no other Windows build; bound by the USB/TCP link to the device), and the ADK *installer* (x64; the toolkit it lays down is native). |
| **Emulated, minor** | `py.exe` (python.org ships the launcher shim as x86; it execs the native `python.exe`) and `vswhere.exe` (Microsoft ships x86 only; runs once). |
| **Not installed** | Brave, WinMerge, upstream LLVM, NASM, Android GPU Inspector, OpenCppCoverage, BinSkim, VS `clang-cl`, the WDK, and the Android SDK — see the table above. |
| **Unavailable** | VirtualBox, the Windows 7 x86 test VM, Intel VTune, Android Studio, and the `v141` / Windows XP targeting toolset. |

### The architecture audit

`setup-windows-no-uac.ps1` ends with an **`ArchAudit`** step that reads the PE
COFF header of every tool the box provisions and reports what you would actually
run, resolved PATH-first. It reads the file itself rather than trusting package
metadata — a multi-architecture package (Sysinternals) ships every build in one
zip under different names, and an installer's metadata says nothing about which
binary landed. Purely informational; it never fails the run. Skip it with
`-Skip ArchAudit`.

Anything emulated with a listed reason prints as expected. Anything emulated
*without* one is called out, with a remedy where a native build exists — which is
how the `ninja` problem below was found.

### Elevation, and the case where there is no prompt

`setup-windows.bat` works out **once, at the top**, whether this account can
elevate, and reports it as `Elevation: ALREADY | PROMPT | NOLUA`:

| | |
| --- | --- |
| `ALREADY` | Already elevated. The elevated half runs **directly** — no point asking to elevate what already is. |
| `PROMPT` | Not elevated, UAC on. Elevation is requested: an administrator gets a consent prompt, a standard user gets an over-the-shoulder **credential** prompt. |
| `NOLUA` | UAC is off machine-wide (`EnableLUA = 0`) **and** this is not an administrator. Elevation is *impossible*, not merely declined. |

`IsInRole(Administrator)` is false for an admin running unelevated under UAC,
which is what makes `ALREADY` mean *actually elevated* rather than *could be*.

**Why `NOLUA` needs detecting rather than attempting.** `Start-Process -Verb
RunAs` is not honest about it. With UAC disabled the `RunAs` verb is **silently
ignored**: no prompt appears, the child starts with the caller's own unelevated
token, and `Start-Process` reports **exit code 0** as though it had worked. The
elevated script then refuses itself on its `#Requires -RunAsAdministrator` line,
exits 1, and never reaches its `Start-Transcript` — so there is no log either.
Read naively that is indistinguishable from a cancelled UAC prompt, which is
exactly what this script used to report, sending you to look for a prompt that
could never have appeared.

Measured on such a box: `Start-Process -Verb RunAs` returned exit 0 while the
child reported itself as the *unelevated* calling user.

**What is skipped when elevation is impossible.** The elevated half, plus four
packages that sit in the "per-user" section but are machine-wide installers.
They used to fail on every run with opaque codes — `exit 5`
(`ERROR_ACCESS_DENIED`) for the .NET SDK, MSI `1603` for CMake and Android GPU
Inspector, `exit 1` for OpenCppCoverage, whose installer self-elevates. They are
now shown as unavailable in the plan, with the reason, and skipped with one
clear line each. None blocks a build: the .NET SDK is
only there for the WiX MSI tooling, CMake also ships inside Visual Studio, AGI
profiles Android devices, and OpenCppCoverage cannot instrument ARM64 binaries
anyway.

A `NOLUA` run is a **success** (exit 0), not a failure — the per-user half did
its job. To finish the box, run it from an administrator account, then re-run
`setup-windows-no-uac.ps1` as yourself so the per-user `PATH` and `.gitconfig`
land in *your* profile rather than the administrator's.

Two consequences worth knowing rather than rediscovering:

- **LLVM does not fail — it relocates.** Its NSIS installer targets
  `%ProgramFiles%\LLVM`, and when it cannot write there it silently falls back to
  a per-user directory (observed: `%USERPROFILE%\Documents\LLVM`) while winget
  still reports *Successfully installed*. The compiler is genuinely there and
  native; nothing can find it. The `LlvmPath` step looks in that fallback, puts
  the directory on the user `PATH`, and says so.
- **WinMerge silently downgrades to x64.** Upstream publishes ARM64 as a
  **machine-scope** installer and x64 as a **per-user** one, so an unelevated
  winget lets its scope preference beat its architecture preference. The batch
  now asks for `--architecture arm64` first and falls back, so an admin run gets
  the native build and a standard-user run still gets a working one.

### Two gotchas the audit surfaces

- **Visual Studio bundles an x64 `ninja.exe` even on ARM64.** It matters more
  than a one-off tool would, because ninja is re-invoked for every edge in the
  build graph — it is the one place emulation is paid over and over rather than
  once. `winget install Ninja-build.Ninja` gets the native `ninja-winarm64`
  build, and the `NinjaPath` step pins its directory to the **front** of the user
  `PATH`. VS's bundled `cmake.exe` *is* ARM64, so only ninja has this problem.

  On which copy wins inside a Developer Command Prompt: the native one. VS adds
  its ninja from `Common7\Tools\vsdevcmd\ext\cmake.bat`, which does
  `set "PATH=%PATH%;...\CMake\bin;...\CMake\Ninja"` — an **append**, so the VS
  directories land at the very end of the composed `PATH`, behind every machine
  and user entry. A native ninja anywhere on the user `PATH` already beats it,
  measured on an ARM64 box. The `NinjaPath` step is therefore insurance rather
  than the load-bearing fix: winget *appends* its package directory to the user
  `PATH`, so without it the margin rests on two append orders staying as they
  are, one of them in a file Microsoft owns and revises.
- **Sysinternals ships every architecture in one zip**, and the ARM64 build is
  not the default-named exe. `ProcessExplorer.zip` contains `procexp.exe` (x86),
  `procexp64.exe` (x64) and `procexp64a.exe` (**ARM64**) — so run the `*64a.exe`
  variants; plain `procexp.exe` runs emulated. (`Microsoft.Sysinternals.Suite`
  has a dedicated `SysinternalsSuite-ARM64.zip` if you prefer the whole set.)

- **x64 emulation is checked, not assumed.** Everything in the "emulated" row
  needs Prism, which is present on Windows 11 on Arm but absent on Windows 10 on
  Arm (x86-only there) and on some Server images. The elevated half tests for
  `System32\xtajit64.dll` up front and warns, rather than letting the failure
  surface much later as a binary that will not start.
- **VirtualBox is skipped.** There is no ARM64 Windows host build, and the x64
  one cannot be rescued by emulation: a hypervisor is kernel-mode, and its x64
  driver will not load on an ARM64 kernel. This is also what makes
  `setup-windows-7-test-env.bat` unreachable from an ARM64 host — it prepares a
  Windows 7 *x86* guest, which neither VirtualBox nor Hyper-V on ARM64 can run.
  (That script itself is unchanged; it runs inside the guest, so it never sees
  the host architecture.)
- **VirtualBox is also skipped inside a virtual machine**, on any architecture.
  The planner reads the firmware's SMBIOS manufacturer and model
  (`Win32_ComputerSystem`) and recognises VirtualBox, VMware, Hyper-V (and
  Azure), QEMU/KVM, Parallels, Xen, EC2 and GCE; the plan's `machine:` line
  names what it found. It does not use `HypervisorPresent`, which is also true
  on physical hardware running Hyper-V, WSL2 or VBS. The test VMs belong on the
  physical host.
- **The `v141` / Windows XP toolset is skipped**, and the verification step says
  `n/a` instead of warning about it. The components are still *listed* in the
  catalog on Arm, so this is a deliberate skip rather than a hard unavailability
  — but the 14.16 toolset predates Windows on Arm as a host and ships
  `HostX86`/`HostX64` compilers only, so the best you could get is an
  x86-emulated compiler, and XP targeting is not supported from an Arm host.
  Nothing is lost that this box could have used:
  Windows XP never ran on ARM64, so the only point of an XP-targeting build here
  would be producing x86 binaries, which the current toolset does natively via
  `-A Win32`.
- **OpenCppCoverage is no longer installed on ARM64.** Unlike the rest of the
  emulated row this was a real ceiling rather than a slowdown: it collects
  coverage by debugging the process under test and stepping x86/x64
  instructions, so it can cover cross-compiled x86/x64 binaries but **not** an
  ARM64 one. A coverage tool that cannot cover this machine's own output belongs
  on the x64 box, which is where it still installs. Run coverage there.
- **BinSkim is no longer installed on ARM64 either**, though the reason is
  weaker: the NuGet package publishes `win-x64` only (its other RIDs are
  `linux-x64`, `linux-arm64`, `osx-x64`), but BinSkim *reads* PE headers and load
  configs, so its own architecture is independent of the binaries it analyses —
  an emulated x64 BinSkim checks ARM64 binaries perfectly well. It went with the
  rest of the x64-only set to keep the rule simple, not because it was broken.
  The RID list is still ordered preference on x64, so a future `win-arm64` build
  would be picked up with no further change.
- **`rsync` is native on ARM64 now**, and its `ssh.exe` is still verified by
  running it. The release publishes an `arm64` asset as of `v3.5.0-gdeeda96f`;
  both binaries in it are `0xAA64`, and the `ssh.exe` reports
  `OpenSSH_for_Windows_10.0p2 ... LibreSSL 3.8.2` on this box.

  Before that asset existed, ARM64 took the x64 zip. The `rsync.exe` was fine —
  a transfer is bounded by the socket, not by emulated CPU — but its `ssh.exe`
  links against `System32\libcrypto.dll`, which on ARM64 is an **ARM64** binary
  an x64 process cannot load. It died with `0xC0000135`
  (`STATUS_DLL_NOT_FOUND`) and had to be deleted on every run. That matters more
  than it sounds: `rsync.exe` *prefers* an `ssh.exe` in its own directory, so a
  present-but-broken one does not degrade to the in-box client — it breaks rsync
  outright, with an error naming a dead remote shell rather than `ssh.exe`.

  The elevated half still runs `ssh -V` after unpacking and **deletes** the
  binary if it will not start. The check is kept because it is what found that
  problem, and it still covers a missing or too-old `libcrypto.dll` on any
  architecture. An x64 `rsync.exe` surviving on an ARM64 box now shows up in the
  audit as emulation *without* a listed reason, with a remedy pointing at a
  re-run. The `core.sshCommand` step in the non-elevated half already picked its
  candidate by running it, and is unchanged.
- **Intel VTune reports `n/a`** rather than printing a download link: there is no
  Windows-on-Arm build, and its value is reading Intel PMU counters. Use the
  Windows Performance Toolkit (`wpr`/`xperf` to collect, `wpa` to analyse), or
  Arm Performance Studio / Streamline for Arm PMU sampling.
- **NASM is not installed on ARM64.** It assembles x86/x86-64 only — there is no
  ARM64 target in it and no ARM64 build of it — so it went into the x64-only set
  with the rest. The ARM64 assembler is `armasm64.exe`, which ships with MSVC.
  Its installer is also one of the two here that fall back to a per-user
  directory it never registers (`%LOCALAPPDATA%\bin\NASM`), so `winget uninstall`
  cannot find it afterwards; the `Uninstall.exe` in that directory is the way out.
- **`vswhere` stays under the 32-bit Program Files** on ARM64 too
  (`%ProgramFiles(x86)%\Microsoft Visual Studio\Installer`), so that path is
  unchanged. The VS Installer is x86-registered there by contract even though the
  installer binaries themselves are native.
- **The WDK registry probe reads both hives.** `wdksetup.exe` is 32-bit and
  writes under `WOW6432Node` on x64, but which hive a kit lands in has varied
  across versions and architectures, and reading only one made an installed WDK
  look absent — costing a needless multi-GB reinstall on every run.