doc: improve building and benching docs for rustc

[karolzwolak]

The currently recommended instructions for linking and benchmarking rustc are outdated and don't work.

There isn't any good way of opting out of using lld (so we could symlink default linker to wild) yet in bootstrap.toml.
Instead we can use lld from $PATH using rust.bootstrap-override-lld = true once

• fix: disable self-contained linker when bootstrap-override-lld is set rust-lang/rust#148709 is merged.

We no longer recommend to first build rustc with other linker than wild (see commit c0f337b).

[karolzwolak]

Opening this as draft to get some feedback while waiting for the rust PR to merge.

EDIT: it's merged so I'm marking this as ready for review.

[davidlattimore]

Thanks!

[davidlattimore]

I probably should have tried out the instructions before merging rather than after, but I just tried them and at least on my machine, rustc didn't end up being linked by wild. A bunch of other stuff (build scripts and stuff) did use wild, but not librustc-driver and rustc.

When I switched from setting PATH to setting RUSTFLAGS however, it did link with wild, so I think that's a definite improvement from last time I tried. Perhaps due to your change to rustc bootstrap.

Building with RUSTFLAGS=-Clink-arg=--ld-path=$HOME/work/wild/fakes/ld.lld worked for me.

[karolzwolak]

Are you sure you pulled the latest changes from rust master main? (it was renamed today)

I just did a clean build and it worked fine.

$ readelf -p .comment build/x86_64-unknown-linux-gnu/stage1/bin/rustc | grep -i 'linker:'
  [    4f]  Linker: Wild version 0.7.0 (4ca4d6f45fd89ba38775f89367da2ead9db24b81) (compatible with GNU linkers)

my bootstrap.toml is just:

[rust]
bootstrap-override-lld = true

What my change to bootstrap did is — now setting bootstrap-override-lld = true will opt out of using rusts self-contained lld — and will use the system one — which we have symlinked to wild.

My motivation against setting RUSTFLAGS is the fact that forgetting to set it — will cause a rebuild.

Maybe you need to do a fresh build by running ./x clean first because we use --keep-stage 1.

[davidlattimore]

Thanks for the prompt about the master->main rename. I was still on the former. Although I had checked and confirmed that your change showed up when I ran git log.

I tried again after pulling the latest changes from main and running ./x clean. It still doesn't seem to work for me.

To determine what was going on, I ran the build under strace:

PATH=$HOME/work/wild/fakes:$PATH strace -f --string-limit=1000 -o ~/tmp/strace.out ./x build library --keep-stage 1

It looks like clang is invoked for linking and is passed the argument -fuse-ld=lld. Clang then invokes lld by absolute path rather than by looking for it on $PATH.

grep 'exec.*lld' ~/tmp/strace.out

98617 execve("/usr/bin/clang", ["clang", ... "-fuse-ld=lld"...
98618 execve("/usr/lib/llvm-20/bin/ld.lld", ["/usr/lib/llvm-20/bin/ld.lld"...

My guess is that clang on my system is configured to find lld at that specific path. So perhaps it's an OS difference. I'm testing on Ubuntu 25.10.

[karolzwolak]

Yeah it might be an OS or clang version difference. I'm on arch & clang 21.1.

Anyway, I submitted rust-lang/rust#148795 that will allow putting the rustflags in bootstrap.toml. This will spare us from having to wrap x runs with env variables.

[mati865]

FWIW, relying on PATH is pretty unreliable when it comes to overriding linker. It happens to work well for us on Arch Linux, but for example on openSUSE PATH=<wild_repo>/fakes gcc main.c would still use ld.bfd, and you need to do gcc -B <wild_repo>/fakes main.c. This was found in one of the discussions in this repo, but I don't remember where exactly.

So, a solution that currently works across more distributions would to either use RUSTFLAGS=-Clink-arg=--ld-path=<wild_repo>/ld and Clang, or RUSTFLAGS=-Clink-arg=-B<wild_repo> with any driver.
This might be fragile, because Rust's bootstrap also relies on RUSTFLAGS to build the compiler.

You should also check the tests are using the correct linker (especially run-make tests), because the freshly built compiler can default to LLD built by Rust:

❯ readelf -p .comment build/host/test/run-make/cdylib/rmake_out/libfoo.so | rg Linker
  [    35]  Linker: LLD 21.1.2 (https://github.com/rust-lang/llvm-project.git 8c30b9c5098bdff1d3d9a2d460ee091cd1171e60)

---

For a permanent solution, you can use https://github.com/mati865/wild-proxy, but you will have to remember to rebuilt it for the every change you want to try.

❯ rg '^linker =|^rust.(lld|default-linker)' bootstrap.toml
691:rust.default-linker = "/home/mateusz/Projects/wild-proxy/wild-cc"
775:rust.lld = false
962:linker = "/home/mateusz/Projects/wild-proxy/wild-cc"

[karolzwolak]

Yeah, I now realize this solution is far from ideal.
rust-lang/rust#148795 (WIP) will allow for putting rustflags in the bootstrap.toml config.