1# rust-frontier — self-hosting the builder's rust toolchain
2
3The last frontier of `selfhost-verify` variante (b): replace the Alpine
4`rustc/cargo 1.91.1` in `/toolchain` with a hammer-built rust, via the **purist
5mrustc chain** (no prebuilt rustc binary). Path:
6
7    mrustc → rustc 1.90.0 (builds bundled LLVM) → 1.91.0 → 1.91.1
8
9These scripts + patch are the working artifacts. The mrustc tree itself lives in
10`.scratch/mrustc` (gitignored — it's a large third-party clone, upstream master
11`be69c74`); only our deltas are tracked here.
12
13## Files
14
15- **`run_rustc.patch`** — patch against mrustc `be69c74` for `run_rustc/Makefile`
16  and `run_rustc/rustc_proxy.sh`. Apply from the mrustc root:
17  `git -C .scratch/mrustc apply /path/to/run_rustc.patch`
18- **`build-stage0-musl.sh`** — rebuild the mrustc stage0 `rustc`+`cargo` with a
19  **musl host triple** (`output-1.90.0-x86_64-unknown-linux-musl/`). Run inside
20  the Alpine devfs sandbox (gcc, MRUSTC_TARGET_VER=1.90). Reuses the already-built
21  LLVM and `bin/mrustc`.
22- **`run-runrustc.sh`** — run a `run_rustc` make target inside the devfs sandbox,
23  pointed at the musl-host stage0.
24
25> Both runners hardcode `/home/sergio/hammer` and assume the prepared devfs at
26> `.dev-fs/alpine` (256-TLS-key musl loader + g++; see the bootstrap-devfs notes).
27
28## Why the patches exist (the snags)
29
30The lab is **musl-only** (Alpine devfs); the 4/4 inputs (arje-zero/hammerd) are
31built `--target x86_64-unknown-linux-musl`. Three coupled problems had to be fixed
32to bootstrap a usable rust there:
33
341. **stage-1 std built for gnu** (`mmap64`/`open64` undefined at link).
35   `minicargo` was invoked without `--target`, so it used mrustc's default **gnu**
36   triple — and gnu std references glibc's LFS64 symbols that musl 1.2.5 doesn't
37   export. Fix: pass `--target $(RUSTC_TARGET)` to minicargo (Makefile:162) and to
38   the stage-1 smoke-test (Makefile:172). A correct musl std uses the **base** libc
39   symbols (`open`/`mmap`/…), matching Alpine's reference std.
40
412. **self-contained CRT absent.** musl's default link is `-static-pie` against a
42   `lib/rustlib/<t>/lib/self-contained/` CRT dir that the mrustc sysroot never
43   populates (also needs static `-lunwind`). Fix: `-C target-feature=-crt-static
44   -C link-self-contained=no` so the Alpine gcc supplies crt1/crti/crtn +
45   crtbeginS/crtendS and links dynamically against the system musl (RUSTFLAGS in
46   Makefile:111, plus **both** hello_world smoke-test rules: the stage-1 one at
47   Makefile:172 *and* the final fully-bootstrapped one at Makefile:262 — the latter
48   only surfaces once stage-2/3 actually completes, i.e. after snag #3 is fixed).
49
503. **host-triple = gnu on a musl system** (the deep one). cargo compiles
51   build-scripts and **proc-macros** for the *host*; mrustc's stage0 rustc has its
52   host triple baked as `x86_64-unknown-linux-gnu` (not runtime-overridable). A
53   proxy `--target musl` inject fixes build-script *bins*, but **proc-macros are
54   dlopen'd and must match the host triple structurally** — injection makes them
55   target artifacts that rustc rejects. Aliasing musl rlibs as gnu also fails:
56   rustc reads the triple from rlib *metadata* (`E0461`), not the path.
57
58   **The only fix is a stage0 rustc whose host triple is musl** — that's what
59   `build-stage0-musl.sh` produces (`CFG_COMPILER_HOST_TRIPLE` via `RUSTC_TARGET`,
60   `--target` via `MRUSTC_TARGET`). Then host==target==musl: cargo doesn't
61   cross-compile, proc-macros load natively, and `rustc_proxy.sh` only needs the
62   CRT flags (no `--target` inject).
63
64   Gotcha: do **not** pass `OUTDIR_SUF` on make's command line — a command-line var
65   can't be reassigned by the makefile, so the `-musl` suffix append is skipped and
66   the build contaminates the gnu output dir. Let it default.
67
684. **final cargo needs vendored OpenSSL.** The fully-bootstrapped `prefix/bin/cargo`
69   rule (Makefile:235) builds cargo with default features, so `openssl-sys` looks
70   for a system OpenSSL via pkg-config and fails (the hermetic musl devfs has none,
71   and no `openssl.pc`). Fix: add `--features vendored-openssl` to that cargo build
72   so `openssl-src` compiles OpenSSL from source — same approach the stage0 cargo
73   build uses. Real cargo (unlike minicargo) handles the OUT_DIR fine, so snag #4
74   doesn't recur here. Only surfaces after the final hello_world (snag #2/262) passes.
75
765. **minicargo OUT_DIR host/target split** (only when building the musl stage0's
77   cargo). With `RUSTC_TARGET` set, minicargo runs each cargo build-script under
78   `cargo-build/host/build_X/`, but the *target* crate's `include!` /
79   `include_bytes!(concat!(env!("OUT_DIR"), "/.."))` resolves `OUT_DIR` to
80   `cargo-build/build_X/` (no `host/`, empty) → mrustc aborts with signal 6. Hit
81   `libsqlite3-sys` (`bindgen.rs`) and the `cargo` binary (`man.tgz`). The gnu
82   build never split (single triple → single dir). Since host==target the script
83   outputs are bit-identical, so `build-stage0-musl.sh` symlinks the target dir to
84   the host dir (`symlink_outdirs`). Late sys-crates (cargo, curl, openssl,
85   libgit2-sys, libssh2-sys) run their scripts near the end, so it's applied in a
86   retry loop around the incremental cargo build.
87
88## Workflow
89
90```sh
91# 1. apply the run_rustc patch into the mrustc clone
92git -C .scratch/mrustc apply scripts/rust-frontier/run_rustc.patch
93
94# 2. rebuild stage0 rustc+cargo with a musl host triple (~hours, reuses LLVM)
95.scratch/build-stage0-musl.sh            # -> output-1.90.0-x86_64-unknown-linux-musl/
96
97# 3. build the optimised rustc + cargo via run_rustc (stage 1/2/3)
98.scratch/run-runrustc.sh all
99
100# 4. (next) climb 1.90.0 → 1.91.0 → 1.91.1, then swap rust into /toolchain
101```
102
103Full diagnostic history is in the `selfhost-verify-rust-frontier` memory.