WIP: docs(build): the lifted-chunk -O2 budget: costs, coverage and a LONGSHOT_CHUNK_OPT patch #1180

Draft
Marcuss2 wants to merge 1 commit from Marcuss2/Longshot:perf/build-opt-budget into main
Contributor

Type: docs · Risk: low · Tested on: Linux, build-time only (no game run — nothing here changes the game) · Needs: an in-game A/B decision by the Lead (commands in Testing)

Why

The hot-giant split (task-1) made a build that carries a hot list cost the same as a no-list build (7:13 -> 3:17). Task-2 asked the follow-up with numbers: what does it cost to compile more of the lift at -O2, and is any of it worth recommending? This PR answers with from-scratch builds and proposes the switch that would ship such an experiment — as a patch in the report, not applied: nx2/build.py is untouched here (task-1 is landing lines in it).

What changed

Nothing in code. Two hand-written measurement files under the git-ignored build folder, force-added on purpose so the numbers travel with the branch:

  • build-linux/opt-budget.md — the report: the table, the budget answer, the recommendation, the patch, reproduction commands.
  • build-linux/chunk_opt.patch — the proposed LONGSHOT_CHUNK_OPT env switch next to OPT in nx2/build.py (default = today's behaviour; all or a file of code_*.c/f_ names sends those chunks to -O2 with the light flags off). It is also embedded in the report.

Measurements

Verdict: more -O2 is not worth recommending by default — the report's honest answer. All chunks at -O2 costs 23:25 wall / 1,345 s compile (9.6x chunk CPU) vs 3:29 / 139.5 s for the baseline list build, and the exe shrinks 19.1 MB (546,891,360 -> 527,756,744 B), so there is no size trade either. The sample mass outside the hot list sits in the 25 MB chunks (code_000.c holds 927 of 5,218 innermost samples); each costs +610..745 s CPU at -O2 — the split's ~240 s buys none of them whole. The only sane chunk-level A/B is the efficient-3 selection (code_002_1.c, code_002.c, code_014_1.c: +201 s CPU, ~+20-35 s wall, +6.8% sample coverage). Cheaper still: extend the hot list (+25 functions ≈ +18.7% coverage ≈ +10-40 s wall) — the split made hot pieces cost ~4-25 s each.

Baseline: main @ 71b1edd8 + split line, hot list After: this branch @ cc757427, LONGSHOT_CHUNK_OPT=all
build wall (from scratch) 3:29 (209.4 s) 23:25 (1,405.0 s)
compile phase 139.5 s 1,345.2 s
chunk CPU sum (per-object seconds) 3,489 s 30,851 s
exe (longshot) 546,891,360 B 527,756,744 B (-3.5%)
lifted C at -O2 24.3 MB of 1,492 MB (1.6%, the code_hot pieces) 1,492 MB (100%)
objects compiled 412 411 (0 failed)

Hardware: Linux, Ryzen ZNVER5 32-thread, 62 GB. Method: rm -rf build-linux then python3 -I scripts/dev_build.py build through scripts/job_queue.py (mode build), one build at a time, LONGSHOT_OBJ_STORE=0 LONGSHOT_LIFT_STORE=0, no shader preparation; per-chunk times from build_times.json; samples counted as scripts/hotlist.py counts (innermost f_ frame) over the Market profile. The report also keeps the first all-O2 attempt as the artifact it was — a scoping bug in the patch (local vs global CHUNK_OPT_O2) left the -O2 flag off the chunks: same 62-light-chunks line, byte-identical exe; the rerun shows 0 light chunks, 4-9x per-chunk times, a different exe.

build: 0 lifted chunks without -O1's module passes (LONGSHOT_LIGHT_PASSES, functions under 1024 KB):
object keys: game-code headers 0f5eb61fcb, flags 4e370948b8, hot flags 3d90a888ed, lifted code 37630d47a6 (96 files)
compiled in 1341s, 0 failed
the build took 0:23:25, compiled in 0:22:25

Flags and settings

One switch is proposed (not shipped here): LONGSHOT_CHUNK_OPT — see build-linux/chunk_opt.patch. Default (unset) is exactly today's behaviour; all lifts every lifted chunk to -O2 (light flags off); a file of code_*.c names or f_ names lifts the named chunks / the chunks defining the named functions. Verified in the rerun: the light-chunk line 62 -> 0, per-chunk times 4-9x (hand-checked by the Lead: code_022.c -O1 light 55.0 s / -O1 all passes 73.4 s / -O2 223.6 s), exe bytes change. Recommendation: keep it unset by default; use it for targeted experiments (the efficient-3 set is the one worth an A/B).

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
LONGSHOT_CHUNK_OPT (proposed) which lifted chunks compile at -O2 unset (-O1 chunks, light passes) unset by default; the patch adds the values above build time vs -O2 coverage of the lift helps targeted sets only; all costs 9.6x chunk CPU stay unset unless experimenting

Testing

Tested: python -I -B tests/run_all.py on this branch (report-only change): no new failures; the 17 known environmental failures also fail on main 71b1edd8 (test_audio_output_devices, test_bug_report, test_bug_report_defaults, test_crt_options, test_dlss_feature_size, test_failed_compile_keeps_objects, test_guest_imported, test_hardware_report, test_linux_preflight, test_linux_update, test_make_game_cache, test_missing_nup, test_mods_size_table, test_pending_guest_import, test_run_all_changed, test_vk_occlusion_queries, test_walk_key). Both measured builds compiled the whole game with 0 failed compiles. The patch's flag path is verified by the builds themselves (the light-chunk line, per-chunk times, exe bytes).

Not tested: no game run — this PR changes no code the game runs, and task-2 says the Lead does the fps A/B.

Must be tested:

  • This PC (Linux, any GPU), by the Lead, if the recommendation is pursued: the efficient-3 A/B — printf 'code_002_1.c\ncode_002.c\ncode_014_1.c\n' > /tmp/chunk_opt3.txt, apply build-linux/chunk_opt.patch, then a from-scratch list build with LONGSHOT_CHUNK_OPT=/tmp/chunk_opt3.txt (expected ~3:40-4:00), and the in-game comparison against the current config in the Market area. Expected result: only build time changes unless fps moves; the report says what to conclude either way.

Risks

What could break: nothing here — no code change lands. If the patch were landed later, its default (env unset) compiles exactly as today, and a wrong LONGSHOT_CHUNK_OPT value only changes which chunks compile at -O2 (slower builds, no behaviour change; object keys name the flags).

Turning it off: unset the env var; or revert the commit.

Compatibility: nothing changes for a player; no shader or pipeline cache effects (no game code change).

Issues

See the team board task-2 (opt budget); no tracker issue.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (docs(build): ...).
  • Why gives the reason plainly and links the issues that fit (board task-2; no tracker issue).
  • Measurements has a verdict.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main (branch is 71b1edd8 = origin/main, no other commits).
  • python -I -B tests/run_all.py passes (the 17 known environmental failures are named; they fail on main too).
  • No game files, dumps, build output or generated files (the two files are hand-written reports; the build folder is git-ignored and they are force-added deliberately, as the task asked the report live at build-linux/opt-budget.md).
  • third_party/ untouched.
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: trailer (the commit).
  • Numbers from the same PC, scene and settings — build-time numbers from identical from-scratch builds, one at a time; no game fps numbers (none claimed; the Lead runs the A/B).
  • Switches documented — N/A: the switch is proposed, not shipped; its row is above and the full story is in the report. When it lands, docs/development.md gets the row.
  • Screenshots — N/A (nothing shows on screen).
  • A file in docs/tested/ — N/A: these are build-time measurements, not game runs; the report under build-linux/ is the record the task asked for.
  • MKWVK_API_VERSION — N/A (renderer untouched).
  • SPIR-V headers — N/A (no shader change).
  • A game-free test added for the fix — N/A (no fix; the measurement is its own evidence).
  • A check under tests/ updated — N/A (no source changed).
  • Host code builds on both platforms — N/A (no host code change).
  • Docs updated — the report is the deliverable; no repo docs claim anything new yet.
**Type:** docs · **Risk:** low · **Tested on:** Linux, build-time only (no game run — nothing here changes the game) · **Needs:** an in-game A/B decision by the Lead (commands in Testing) ## Why The hot-giant split (task-1) made a build that carries a hot list cost the same as a no-list build (7:13 -> 3:17). Task-2 asked the follow-up with numbers: what does it cost to compile **more** of the lift at -O2, and is any of it worth recommending? This PR answers with from-scratch builds and proposes the switch that would ship such an experiment — as a patch in the report, **not applied**: `nx2/build.py` is untouched here (task-1 is landing lines in it). ## What changed Nothing in code. Two hand-written measurement files under the git-ignored build folder, force-added on purpose so the numbers travel with the branch: - `build-linux/opt-budget.md` — the report: the table, the budget answer, the recommendation, the patch, reproduction commands. - `build-linux/chunk_opt.patch` — the proposed `LONGSHOT_CHUNK_OPT` env switch next to `OPT` in `nx2/build.py` (default = today's behaviour; `all` or a file of `code_*.c`/`f_` names sends those chunks to -O2 with the light flags off). It is also embedded in the report. ## Measurements **Verdict:** more -O2 is not worth recommending by default — the report's honest answer. All chunks at -O2 costs **23:25 wall / 1,345 s compile (9.6x chunk CPU) vs 3:29 / 139.5 s** for the baseline list build, and the exe **shrinks** 19.1 MB (546,891,360 -> 527,756,744 B), so there is no size trade either. The sample mass outside the hot list sits in the 25 MB chunks (code_000.c holds 927 of 5,218 innermost samples); each costs **+610..745 s CPU** at -O2 — the split's ~240 s buys none of them whole. The only sane chunk-level A/B is the efficient-3 selection (code_002_1.c, code_002.c, code_014_1.c: +201 s CPU, ~+20-35 s wall, +6.8% sample coverage). Cheaper still: extend the hot list (+25 functions ≈ +18.7% coverage ≈ +10-40 s wall) — the split made hot pieces cost ~4-25 s each. | | Baseline: main @ 71b1edd8 + split line, hot list | After: this branch @ cc757427, `LONGSHOT_CHUNK_OPT=all` | |---|---|---| | build wall (from scratch) | 3:29 (209.4 s) | 23:25 (1,405.0 s) | | compile phase | 139.5 s | 1,345.2 s | | chunk CPU sum (per-object seconds) | 3,489 s | 30,851 s | | exe (longshot) | 546,891,360 B | 527,756,744 B (-3.5%) | | lifted C at -O2 | 24.3 MB of 1,492 MB (1.6%, the code_hot pieces) | 1,492 MB (100%) | | objects compiled | 412 | 411 (0 failed) | Hardware: Linux, Ryzen ZNVER5 32-thread, 62 GB. Method: `rm -rf build-linux` then `python3 -I scripts/dev_build.py build` through `scripts/job_queue.py` (mode build), one build at a time, `LONGSHOT_OBJ_STORE=0 LONGSHOT_LIFT_STORE=0`, no shader preparation; per-chunk times from `build_times.json`; samples counted as `scripts/hotlist.py` counts (innermost `f_` frame) over the Market profile. The report also keeps the first all-O2 attempt as the artifact it was — a scoping bug in the patch (local vs global `CHUNK_OPT_O2`) left the -O2 flag off the chunks: same 62-light-chunks line, byte-identical exe; the rerun shows 0 light chunks, 4-9x per-chunk times, a different exe. ``` build: 0 lifted chunks without -O1's module passes (LONGSHOT_LIGHT_PASSES, functions under 1024 KB): object keys: game-code headers 0f5eb61fcb, flags 4e370948b8, hot flags 3d90a888ed, lifted code 37630d47a6 (96 files) compiled in 1341s, 0 failed the build took 0:23:25, compiled in 0:22:25 ``` ### Flags and settings One switch is **proposed** (not shipped here): `LONGSHOT_CHUNK_OPT` — see `build-linux/chunk_opt.patch`. Default (unset) is exactly today's behaviour; `all` lifts every lifted chunk to -O2 (light flags off); a file of `code_*.c` names or `f_` names lifts the named chunks / the chunks defining the named functions. Verified in the rerun: the light-chunk line 62 -> 0, per-chunk times 4-9x (hand-checked by the Lead: code_022.c -O1 light 55.0 s / -O1 all passes 73.4 s / -O2 223.6 s), exe bytes change. Recommendation: keep it unset by default; use it for targeted experiments (the efficient-3 set is the one worth an A/B). | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `LONGSHOT_CHUNK_OPT` (proposed) | which lifted chunks compile at -O2 | unset (-O1 chunks, light passes) | unset by default; the patch adds the values above | build time vs -O2 coverage of the lift | helps targeted sets only; `all` costs 9.6x chunk CPU | stay unset unless experimenting | ## Testing **Tested:** `python -I -B tests/run_all.py` on this branch (report-only change): no new failures; the 17 known environmental failures also fail on main `71b1edd8` (test_audio_output_devices, test_bug_report, test_bug_report_defaults, test_crt_options, test_dlss_feature_size, test_failed_compile_keeps_objects, test_guest_imported, test_hardware_report, test_linux_preflight, test_linux_update, test_make_game_cache, test_missing_nup, test_mods_size_table, test_pending_guest_import, test_run_all_changed, test_vk_occlusion_queries, test_walk_key). Both measured builds compiled the whole game with 0 failed compiles. The patch's flag path is verified by the builds themselves (the light-chunk line, per-chunk times, exe bytes). **Not tested:** no game run — this PR changes no code the game runs, and task-2 says the Lead does the fps A/B. **Must be tested:** - This PC (Linux, any GPU), by the Lead, if the recommendation is pursued: the efficient-3 A/B — `printf 'code_002_1.c\ncode_002.c\ncode_014_1.c\n' > /tmp/chunk_opt3.txt`, apply `build-linux/chunk_opt.patch`, then a from-scratch list build with `LONGSHOT_CHUNK_OPT=/tmp/chunk_opt3.txt` (expected ~3:40-4:00), and the in-game comparison against the current config in the Market area. Expected result: only build time changes unless fps moves; the report says what to conclude either way. ## Risks **What could break:** nothing here — no code change lands. If the patch were landed later, its default (env unset) compiles exactly as today, and a wrong `LONGSHOT_CHUNK_OPT` value only changes which chunks compile at -O2 (slower builds, no behaviour change; object keys name the flags). **Turning it off:** unset the env var; or revert the commit. **Compatibility:** nothing changes for a player; no shader or pipeline cache effects (no game code change). ## Issues See the team board task-2 (opt budget); no tracker issue. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`docs(build): ...`). - [x] Why gives the reason plainly and links the issues that fit (board task-2; no tracker issue). - [x] Measurements has a verdict. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main` (branch is `71b1edd8` = origin/main, no other commits). - [x] `python -I -B tests/run_all.py` passes (the 17 known environmental failures are named; they fail on main too). - [x] No game files, dumps, build output or generated files (the two files are hand-written reports; the build folder is git-ignored and they are force-added deliberately, as the task asked the report live at `build-linux/opt-budget.md`). - [x] `third_party/` untouched. - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` trailer (the commit). - [x] Numbers from the same PC, scene and settings — build-time numbers from identical from-scratch builds, one at a time; no game fps numbers (none claimed; the Lead runs the A/B). - [ ] Switches documented — N/A: the switch is proposed, not shipped; its row is above and the full story is in the report. When it lands, `docs/development.md` gets the row. - [ ] Screenshots — N/A (nothing shows on screen). - [ ] A file in `docs/tested/` — N/A: these are build-time measurements, not game runs; the report under `build-linux/` is the record the task asked for. - [ ] `MKWVK_API_VERSION` — N/A (renderer untouched). - [ ] SPIR-V headers — N/A (no shader change). - [ ] A game-free test added for the fix — N/A (no fix; the measurement is its own evidence). - [ ] A check under `tests/` updated — N/A (no source changed). - [x] Host code builds on both platforms — N/A (no host code change). - [x] Docs updated — the report is the deliverable; no repo docs claim anything new yet.
docs(build): the lifted-chunk -O2 budget: costs, coverage and a LONGSHOT_CHUNK_OPT patch
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
cc75742748
Task-2 (opt budget): what does it cost to compile more of the lift at -O2 now
that the hot-giant split made a list build as cheap as a no-list one. Measured
from scratch on main 71b1edd8 (plus task-1's hot_fl split line, applied
locally), one build at a time through the job queue, stores off:

- baseline (hot list, chunks -O1 light/26 full, code_hot -O2): 3:29 wall,
  139.5 s compile, exe 546,891,360 B
- LONGSHOT_CHUNK_OPT=all (every chunk -O2, light flags off): 23:25 wall,
  1345.2 s compile (9.6x the chunk CPU), exe 527,756,744 B (-19.1 MB)

The first all-O2 attempt printed the old numbers with a byte-identical exe: a
scoping bug in the patch (CHUNK_OPT_O2 assigned a local in main(), read as the
global in lifted_flags) kept -O2 off the chunks; the report keeps that attempt
as the artifact it was, with the tells (62 vs 0 light chunks, exe bytes).

Recommendation: ship nothing by default. The hottest chunks (code_000.c holds
927 of 5,218 innermost samples) cost +610..745 s CPU each at -O2, so the
split's ~240 s buys none of them whole; the report gives the per-chunk deltas,
the efficient-3 selection worth an in-game A/B (+201 s CPU, +6.8% sample
coverage), and the cheaper direction (extend the hot list: the split made hot
pieces cost ~4-25 s each). The env switch defaults to today's behaviour;
nx2/build.py is untouched in this branch (task-1 lands lines there).

Assisted-by: DeepSeek Harness
Collaborator

Possibly related, for context:

  • PR #1146 perf(build): the hot pieces compile with their giant functions split — Hot-giant split measurements this report builds on
Possibly related, for context: - PR #1146 perf(build): the hot pieces compile with their giant functions split — Hot-giant split measurements this report builds on
Author
Contributor

Note: This is marked WIP as this shows what is possible. Compiling everything at -O2 is something worth considering for major releases.

Note: This is marked WIP as this shows what is possible. Compiling everything at -O2 is something worth considering for major releases.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/build-opt-budget:Marcuss2-perf/build-opt-budget'
git switch 'Marcuss2-perf/build-opt-budget'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1180
No description provided.