attempt 3

BUILD.md

@@ -0,0 +1,114 @@
+# Building qroissant wheels
+
+This project ships as a [maturin](https://www.maturin.rs/) / PyO3 mixed
+Rust+Python package. The native extension uses `#![feature(portable_simd)]` so
+**nightly Rust is required**, pinned via `rust-toolchain.toml`.
+
+All builds run inside a Docker image (`scripts/Dockerfile.build`) so the host
+needs only Docker and Python 3 — no Rust, no MSVC SDK, no mingw to install.
+
+## Prerequisites
+
+- Docker (tested with 29.x)
+- Python 3.11+ on the host, **only** if you want to install/test the produced
+  Linux wheel locally via `scripts/build.sh check`.
+
+## One-time setup
+
+```sh
+scripts/build.sh image
+```
+
+Builds `qroissant-build:latest`. Pulls `ghcr.io/rust-cross/cargo-xwin`,
+installs the nightly toolchain + `x86_64-pc-windows-msvc` target + maturin.
+~5 min on a cold cache, then it's a no-op.
+
+## Build commands
+
+```sh
+scripts/build.sh linux      # -> dist-linux/qroissant-*-manylinux_*_x86_64.whl
+scripts/build.sh windows    # -> dist-windows/qroissant-*-win_amd64.whl
+scripts/build.sh all        # image + linux + windows
+scripts/build.sh check      # install latest linux wheel into .venv, import-smoke,
+                            # then `zipfile -l` the windows wheel
+scripts/build.sh clean      # rm dist-linux dist-windows
+scripts/build.sh clean-cache  # also drop the cargo/target/xwin Docker volumes
+```
+
+The wheels target **abi3-py311**, so a single artifact per platform covers
+CPython 3.11, 3.12, 3.13, and onward.
+
+## What lives where
+
+| Artifact | Path |
+| --- | --- |
+| Build image definition | `scripts/Dockerfile.build` |
+| Wrapper script | `scripts/build.sh` |
+| Toolchain pin | `rust-toolchain.toml` |
+| Linux wheels | `dist-linux/` (gitignored) |
+| Windows wheels | `dist-windows/` (gitignored) |
+| Cargo registry cache | Docker volume `qroissant-cargo-registry` |
+| Cargo target dir | Docker volume `qroissant-target` |
+| cargo-xwin MSVC cache | Docker volume `qroissant-xwin` |
+
+The three Docker volumes persist between runs so reruns only rebuild changed
+crates; nuke them with `scripts/build.sh clean-cache` if anything looks stale.
+
+## Debug symbols on Windows
+
+The release profile sets `debug = "line-tables-only"`, so a `_native.pdb` is
+produced alongside the wheel. `scripts/build.sh windows` copies it into
+`dist-windows/`. To get resolved frames in a Rust panic backtrace on a Windows
+machine:
+
+1. `pip install qroissant-*-win_amd64.whl`
+2. Locate the installed extension, e.g.
+   `Lib\site-packages\qroissant\_native.pyd`
+3. Drop `_native.pdb` next to it (same directory, same basename).
+
+Symbol info is line-tables-only, so frames resolve to `file:line` but local
+variables and types aren't included. That's enough for backtraces and is
+~30 MB; full debug info would be much larger.
+
+## How Windows cross-compile works
+
+The Windows path uses [cargo-xwin](https://github.com/rust-cross/cargo-xwin),
+which downloads the Microsoft CRT + Windows SDK headers (cached in the xwin
+volume; license auto-accepted via `XWIN_ACCEPT_LICENSE=1`). PyO3's
+`generate-import-lib` feature — enabled in
+`crates/qroissant-python/Cargo.toml` — lets us produce the `python3.dll`
+import library at build time, so no Windows Python install is required on the
+host.
+
+## Quick wheel sanity checks
+
+```sh
+# Listing
+python3 -m zipfile -l dist-windows/qroissant-*-win_amd64.whl
+
+# Validate the dist-info
+pipx run twine check dist-linux/*.whl dist-windows/*.whl
+```
+
+## Iterating on Python code
+
+For Python-side changes (no Rust touched), the fastest loop is still
+`maturin develop` against a local rustup install. The Docker flow above is
+optimized for producing wheels, not for inner-loop iteration. If you have a
+nightly rustup toolchain on the host, you can do:
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install 'maturin>=1.8,<2.0'
+.venv/bin/maturin develop --release
+.venv/bin/python -c 'import qroissant'
+```
+
+## Troubleshooting
+
+- **"manylinux_2_34" wheel won't install on old distros** — the image base is
+  Debian 13 (glibc 2.38). For broader compatibility, build inside a
+  manylinux2014 image or run `auditwheel repair` against the produced wheel.
+- **"failed to generate python3.dll import library"** — means `llvm-dlltool`
+  is missing inside the image. Rebuild it with `scripts/build.sh image`.
+- **xwin download is slow / fails** — Microsoft's CDN occasionally rate-limits.
+  Drop the cache (`docker volume rm qroissant-xwin`) and retry.