Headstart: Afhankelijke crates starten voordat hun dependencies klaar zijn met type-checking

Headstart zorgt ervoor dat rustc een vroegtijdig metadata-bestand (early metadata file) schrijft zodra de interface is gecontroleerd, waardoor cargo afhankelijke crates alvast kan starten. De functielichamen van elke crate worden vervolgens gecontroleerd terwijl de downstream-crates al aan het compileren zijn.

Werking en impact

De werking verschilt per commando:

  • cargo check: Afhankelijke crates worden volledig uitgevoerd op basis van de early metadata.
  • cargo build: Afhankelijke crates voeren al hun analyses uit op basis van de early metadata, maar wachten op de volledige metadata van de dependency voordat de uiteindelijke codegeneratie plaatsvindt. Tijdens dit wachten geven ze hun job slot terug.

Indien een functielichaam een fout bevat, faalt de build nog steeds met die fout, met dezelfde diagnostiek en exitstatus als gebruikelijk. De enige verschillen zijn de voortgangsregels en de volgorde van JSON-berichten over crates heen. cargo rapporteert de output van een crate pas wanneer alle dependencies succesvol zijn afgerond, en gooit de output weg als een dependency faalt.

De kosten van deze aanpak zijn:

  • Downstream werk dat weggegooid moet worden bij fouten.
  • Fouten die iets later worden gerapporteerd.
  • Een hoger direct geheugengebruik (zie docs/design.md).

Technische componenten

Het project bestaat uit de volgende onderdelen:

rustc (-Zearly-metadata, 6 patches)

  • Een nieuwe analysis_interfaces query splitst de analyse in item-interfaces en functielichamen.
  • De driver schrijft een .early-rmeta bestand tussen deze twee fasen in.
  • Het laden van crates accepteert early metadata en vervangt deze door volledige metadata vóór de codegeneratie. Indien nodig wordt er gewacht op een lock die de producent vasthoudt tot het bestand is geschreven.

cargo (-Zheadstart, 3 patches)

  • Geeft de vlag -Zearly-metadata mee aan elke compilatie.
  • Start afhankelijke crates zodra de melding voor early metadata binnenkomt, zowel bij check als bij build.
  • Geeft het job slot van een gepauzeerde compilatie vrij voor ander werk.
  • Rapporteert de output van een crate pas wanneer de dependencies succesvol zijn.

De patches zijn opgezet als een commit-serie, inclusief commit-berichten en tests, bedoeld om als upstream pull requests te dienen (zie patches/README.md).

Prestaties

Bij gebruik van de standaard front-end van rustc versnelt headstart clean builds van 13 echte projecten (waaronder rust-analyzer, zed, bevy, lemmy, polars en anderen):

  • cargo check: tot 54% sneller.
  • cargo build: tot 42% sneller.

Met de parallelle front-end (-Zthreads=8) wordt er tot 25% snelheid gewonnen. Deze cijfers zijn gebaseerd op machines met 16 cores. Omdat de winst voortkomt uit het benutten van cores die anders onbenut zouden blijven, is het effect kleiner op kleinere machines. Op 4 cores is de check van rust-analyzer 24% sneller en de build 13–15% sneller; bij codex-rs is de check 14% sneller, terwijl wide builds gelijk blijven.

Bij een clean cargo build van codex-rs op 16 cores (gemeten met cratebank) compileerden de crates van de workspace zonder headstart één na de ander, terwijl de machine grotendeels inactief bleef. Met headstart start elke crate zodra de early metadata van de vorige beschikbaar is, wat resulteert in een build die 37% sneller is.

Installatie en gebruik

Setup

Gebruik het volgende script om rustc en cargo uit te checken, de patches toe te passen en beide te bouwen:

scripts/setup.sh

Uitvoeren

In elk Rust-project kan headstart als volgt worden gebruikt:

RUSTC=/path/to/headstart/rustc/build/host/stage1/bin/rustc \
/path/to/headstart/cargo/target/release/cargo check -Zheadstart

(Vervang check door build indien nodig).

Alternatief kan de functie worden geactiveerd via:

  • De omgevingsvariabele CARGOUNSTABLEHEADSTART=true.
  • De configuratie [unstable] headstart = true in .cargo/config.toml.

Zonder deze instellingen gedraagt de gepatchte cargo zich als de upstream versie, wat een eerlijke baseline voor vergelijkingen mogelijk maakt.

Testen en verificatie

Het project bevat diverse scripts om de correctheid te waarborgen:

  • tests/smoke: Een workspace met twee crates. De langzame library duurt enkele seconden om te checken (voornamelijk in functielichamen). Met headstart start de app na ongeveer 0,2 s in plaats van te wachten tot de library klaar is.
  • scripts/check-errors.sh: Controleert de afhandeling van fouten in tests/errors via drie scenario's (clean build, fout in dependency, fout in binary) voor zowel cargo check als cargo build.
  • scripts/check-incremental.sh [check|build]: Test incrementele wijzigingen, zoals het toevoegen van een impl Fn of het breken en herstellen van een interface.
  • scripts/check-swap.sh: Verifieert dat een library kan starten op early metadata en deze kan vervangen door volledige metadata terwijl hij gepauzeerd is, over alle optimalisatieniveaus heen.
  • scripts/sweep.sh: Bouwt alle 53 rustc-perf compile benchmarks met en zonder headstart, inclusief -Zearly-metadata-verify.

Benchmarks

Voor het meten van prestaties zijn de volgende scripts beschikbaar:

  • scripts/bench.sh -n 5 [-c build] path/to/project ...: Meet clean cargo check of cargo build builds en print de medianen.
  • scripts/real-projects.sh: Cloneert de 13 gemeten projecten.
  • scripts/setup-codex.sh <dir>: Richt codex-rs in (vereist een gepatchte dependency en prebuilt V8).
  • scripts/bench-suite.sh <out-dir>: Voert de volledige suite uit (rust-analyzer, 21 rustc-perf benchmarks, overige projecten en codex-rs).
  • scripts/bench-mem.sh: Samplet het totale geheugengebruik van alle rustc processen tijdens een build.
  • scripts/bench-incremental.sh: Meet de tijd van incrementele re-checks na het bewerken van één functielichaam.
  • scripts/log-rustc: Registreert de start- en eindtijden van elke rustc run om de planning inzichtelijk te maken.

Documentatie

Voor meer details over de werking, de risico's en de meetresultaten, zie:

  • docs/design.md (Ontwerp en risico's)
  • docs/results.md (Metingen)
  • docs/readiness.md (Status van gereedheid voor upstream integratie)