build: cap per-link LTO parallelism at four partitions (ADR-1172)

[lusoris]

Summary

core/meson.build enables LTO for every build (b_lto=true), and GCC's plain -flto means -flto=auto: one lto1-ltrans job per core per link, with no jobserver under Ninja. ninja -j 8 overlaps several of the project's dozens of link targets, so each link spawned 32 partitions. Measured today while three agent builds linked at once: 1-minute load 190 on the 32-core workstation, nine lto1-ltrans processes above 700 % CPU.

ADR-1172: keep LTO on, add b_lto_threads=4 to default_options → -flto=4 (GCC) / -flto-jobs=4 (Clang). A build is now bounded at 4 × ninja -j. Overridable per build dir (-Db_lto_threads=0 = compiler default). docs/development/build-flags.md claimed b_lto defaults to false; corrected, and the new option is documented with its override.

Verified: meson setup core/build core -Denable_cuda=false -Denable_sycl=false → b_lto=True b_lto_threads=4; ninja -t commands | grep -o '\-flto[^ ]*' | sort | uniq -c → 1278 -flto=4, nothing else.

Type

• build — Meson default option

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (pre-commit on every touched file).
• Unit tests — n/a: build option only; the option value is asserted from meson introspect in the reproducer.
• Docs in the same PR: docs/development/build-flags.md.
• ADR: docs/adr/1172-bound-lto-link-parallelism.md + index row.
• SIMD/GPU, twins, new C sources, breaking change, ffmpeg-patches — n/a (libvmaf build flag only).

Bug-status hygiene (ADR-0165)

• docs/state.md — no row: build-experience change, no functional defect.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: trivial. The mechanism is GCC's documented -flto=auto default and Meson's b_lto_threads mapping, both quoted in the ADR.
• Decision matrix — ADR-1172 ## Alternatives considered (LTO off / tell every agent / Ninja jobserver / chosen).
• AGENTS.md invariant note — no rebase-sensitive invariants: the rebase note below carries the one coupling (b_lto_threads exists because b_lto is on).
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/changed/bound-lto-link-parallelism.md.
• Rebase note — docs/rebase-notes.md entry (fork-edited hunk of the upstream meson.build).

Reproducer

meson setup core/build core -Denable_cuda=false -Denable_sycl=false
meson introspect core/build --buildoptions | jq -r '.[] | select(.name=="b_lto" or .name=="b_lto_threads") | "\(.name)=\(.value)"'
ninja -C core/build -t commands | grep -oE -- '-flto[=a-z0-9-]*' | sort | uniq -c     # only -flto=4
# before this PR, during `ninja -C core/build -j 8`: ps -eo pcpu,comm --sort=-pcpu | head  → lto1-ltrans ×(cores) per link

🤖 Generated with Claude Code