1 files changed, 109 insertions, 0 deletions
diff --git a/docs/WindowsOnLinux.md b/docs/WindowsOnLinux.md
new file mode 100644
index 000000000..540447cb2
--- /dev/null
+++ b/docs/WindowsOnLinux.md
@@ -0,0 +1,109 @@
+# Cross-Compiling Windows Binaries on Linux
+
+This document describes how to build `zenserver.exe` and `zen.exe` for Windows
+from a Linux host using clang-cl, lld-link, and the Windows SDK fetched via
+[xwin](https://github.com/Jake-Shadle/xwin).
+
+## Prerequisites
+
+- **LLVM/Clang 17+** with the following tools (typically in `/usr/lib/llvm-<ver>/bin/`):
+  - `clang` (used as `clang-cl` via `--driver-mode=cl`)
+  - `lld-link`
+  - `llvm-lib`
+  - `llvm-rc`
+  - `llvm-ml`
+  - `llvm-mt`
+
+  On Ubuntu/Debian:
+  ```bash
+  sudo apt install clang-18 lld-18 llvm-18
+  ```
+
+- **xmake** (build system) — see [xmake.io](https://xmake.io) for installation.
+
+## Step 1: Fetch the Windows SDK
+
+Run the provided script to download the Windows SDK and MSVC CRT headers/libs:
+
+```bash
+./scripts/win_cross/get_win_sdk.sh
+```
+
+This downloads the SDK to `~/.xwin-sdk` by default. Override the location with
+an argument or the `$XWIN_SDK_DIR` environment variable:
+
+```bash
+./scripts/win_cross/get_win_sdk.sh /path/to/sdk
+```
+
+The script also creates:
+- Tool wrapper scripts (clang-cl, lld-link, llvm-lib, etc.) in the SDK `bin/` directory
+- An MSVC-compatible directory layout that xmake's built-in clang-cl toolchain can discover
+- Debug CRT lib symlinks so cmake package builds succeed
+
+## Step 2: Configure and Build
+
+```bash
+xmake config -y -p windows -a x64 \
+  --toolchain=clang-cl \
+  --sdk=$HOME/.xwin-sdk \
+  --mrc=$HOME/.xwin-sdk/bin/x64/rc.exe \
+  -m release \
+  --zensentry=n \
+  --zenmimalloc=n
+
+xmake
+```
+
+### Notes
+
+- **`--sdk` must use an absolute path** — `$HOME/.xwin-sdk` works, but
+  `~/.xwin-sdk` does not (xmake doesn't expand `~`).
+- **`--mrc`** points to the resource compiler wrapper. Without it, xmake can't
+  auto-detect `llvm-rc` (it doesn't support `--version`).
+- **`--zensentry=no`** is recommended — crashpad (used by sentry-native) is
+  difficult to cross-compile.
+- **`--zenmimalloc=no`** is recommended initially to reduce the package surface.
+- **LTO is automatically disabled** for cross-compilation builds.
+
+## Step 3: Verify
+
+```bash
+file build/windows/x64/release/zenserver.exe
+# PE32+ executable (console) x86-64, for MS Windows, 12 sections
+
+file build/windows/x64/release/zen.exe
+# PE32+ executable (console) x86-64, for MS Windows, 12 sections
+```
+
+## Running with Wine (optional)
+
+The resulting binaries can be run under Wine for testing:
+
+```bash
+wine build/windows/x64/release/zenserver.exe --help
+```
+
+## Troubleshooting
+
+### Library not found (case sensitivity)
+
+The Windows SDK ships headers and libs with specific casing (e.g. `DbgHelp.h`,
+`ws2_32.lib`). Linux filesystems are case-sensitive, so `#include <Dbghelp.h>`
+won't find `DbgHelp.h`. The codebase uses lowercase includes where possible. If
+you encounter a missing header/lib, check the actual casing in the SDK directory.
+
+### `add_ldflags(...) is ignored`
+
+xmake's auto flag checker may reject MSVC linker flags when using clang-cl. Add
+`{force = true}` to the `add_ldflags()` call.
+
+### Stale build state
+
+If you hit unexpected errors after changing toolchain settings, clean everything:
+
+```bash
+rm -rf .xmake build ~/.xmake
+```
+
+Then reconfigure and rebuild.