# Runbook - building the stallion Dialer on a Windows 11 PC (WSL2)

The WSL2-specific delta only. Everything about the AOSP build itself (sync, adevtool, lunch, `m`) is
identical to Linux - see [graphene-build.md](graphene-build.md) and don't duplicate its judgement
here. This file exists because the one-time WSL2 environment is where every Windows AOSP build goes
wrong.

Device is `stallion` (Pixel 10a); pick the current Stable tag per graphene-build.md. The AOSP tree is
synced fresh on the Windows machine - never copied from another box.

## Why WSL2 needs special care

AOSP will silently produce a broken tree or fail cryptically if any of these are wrong:

1. The source tree MUST live on the WSL2 native ext4 filesystem (under `~`), NOT under `/mnt/c` or any
   Windows mount. The Windows filesystem is case-insensitive and slow over the 9P bridge; AOSP needs
   case-sensitive and will corrupt or fail. This is the number one WSL2 AOSP failure.
2. Give WSL2 enough RAM. The LTO+CFI link step peaks over 32 GiB and WSL2 defaults to about half of
   host RAM. Too little means an OOM kill hours into the build.
3. ~350 GiB free on the Windows drive backing the WSL2 vhdx (source + build output + headroom). The
   vhdx grows on demand, so the host drive must actually have the space.
4. `git config --global core.autocrlf false` inside WSL2 - CRLF rewriting breaks patches and shell
   scripts.

If the host doesn't have about 64 GiB RAM and 350 GiB free, stop: a cold AOSP build under those
constraints is slower and more fragile than using the existing Linux build box.

## One-time Windows-side setup

In an elevated PowerShell:

```powershell
wsl --install -d Ubuntu-24.04
wsl --set-default-version 2
wsl --status
```

Create `C:\Users\<you>\.wslconfig` (the RAM cap is the part that matters):

```ini
[wsl2]
memory=48GB           # >=32GB required; ~75% of host RAM
processors=16
swap=16GB
```

Apply with `wsl --shutdown`, reopen Ubuntu, confirm with `free -h` and `nproc`.

## Inside WSL2 Ubuntu

```bash
sudo apt update
sudo apt install repo yarnpkg zip rsync git python3 gnupg openssh-client curl
sudo dpkg --add-architecture i386 && sudo apt update
sudo apt install libc6:i386 lib32stdc++6 lib32gcc-s1
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt install nodejs

git config --global core.autocrlf false     # WSL2-critical
git config --global user.name  "<you>"
git config --global user.email "<you@…>"
```

Clone the Helpdesk repo. vmin git is SSH-only, so you need your SSH key added to GitLab first (see
`docs/onboarding.md`):

```bash
cd ~ && git clone git@gitlab.vmin.cz:vm/helpdesk.git Helpdesk
```

## Sync AOSP and build

Follow graphene-build.md verbatim, inside the Ubuntu shell and under `~`:

```bash
mkdir ~/grapheneos-<tag> && cd ~/grapheneos-<tag>
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/<tag>
# verify the manifest tag, then:
repo sync -j"$(nproc)"                        # ~100-200 GB download; re-run to resume

source build/envsetup.sh
yarnpkg --cwd vendor/adevtool/ install
adevtool generate-all -d stallion
```

Apply both Helpdesk patch sets (paths default to the Linux build box, so override them):

```bash
cd ~/Helpdesk
DIALER_TREE=~/grapheneos-<tag>/packages/apps/Dialer   bash components/dialer-patch/apply.sh
SEPOLICY_TREE=~/grapheneos-<tag>/system/sepolicy      bash components/sepolicy-patch/apply.sh
# expect: overlay copied + patches 0001…0009 applied (or "already applied" on a re-run)
```

Build the same variant the office device runs (userdebug, test keys, unlocked - no signing keys, no
relock):

```bash
cd ~/grapheneos-<tag>
source build/envsetup.sh
lunch stallion-cur-userdebug
m Dialer                         # quick compile check of the patch first
m target-files-package
m otatools-package
```

A cold build is hours even on fast hardware; incremental Dialer rebuilds after that are minutes.

## Flash from Windows

Procedure and brick-safety rules: [pixel10a-flash-manual.md](pixel10a-flash-manual.md). For a reflash
of an already-unlocked phone, use `fastboot flashall` without `-w`.

WSL2 has no native USB, so either flash from the Windows side (the build output is reachable at
`\\wsl$\Ubuntu-24.04\home\<you>\grapheneos-<tag>\out\…`, use Google's Windows platform-tools
`fastboot.exe`) or pass the phone into WSL2 with `usbipd-win` and use the build-matched Linux
fastboot. Then run the on-device acceptance from graphene-build.md.

## What is not in the repo

Secrets (`.claude/env.local`, mTLS p12 files, API keys) are gitignored by design, and the device
credentials/backend URL are runtime properties, not build artifacts - set them per
`docs/phone-connectivity.md` after flashing.