fix(builder): build times measured on nightly-56: the docs, the Builders' estimates and when to measure again #175

Merged

HumanBean merged 3 commits from HumanBean/Longshot:docs/build-times into main 2026-11-13 10:55:45 +00:00

Conversation 1 Commits 3 Files changed 13 +97 -31

HumanBean commented 2026-11-13 10:43:24 +00:00

Owner

• Copy link
• Copy Markdown

Why

The docs told players a build takes "10 to 45 minutes" (README, getting started, common problems), "about 40 minutes" (CONTRIBUTING) or 25 and 43 minutes (design notes). A player's build of the current nightly takes about 14 minutes on a 12-core desktop, and nothing told developers to keep these numbers current.

What changed

• docs/development.md: a new Build times section with:
  • the phase table from two clean player builds of nightly-56;
  • which docs quote the numbers;
  • how to measure again (a player's build in new folders with an empty NVIDIA cache, then how to read each phase from the log);
  • when to measure again: after a change to the lift, the compile flags, the shader preparation or the toolchain (tools.lock), and before each release candidate.
• README ("Install and play"), docs/getting-started.md, docs/common-issues.md and CONTRIBUTING.md ("Building"): "about 15 minutes on a 12-core desktop, longer on a slower PC", linking the section.
• The estimates players see (fix(builder) commit):
  • The Builders said "About 45 min" in all 13 languages (Strings.cs, MainWindow.xaml, MainWindow.xaml.cs, the Linux Builder). They now say 15 to 30 minutes; the top of the range is for slower PCs.
  • recomplauncher.json's step said "10 to 45 minutes" and now says "15 to 30 minutes".
  • The progress bar's step shares are now the measured ones. The Windows Builder's WithShaders gave the shaders 8% of the bar; they are 37% on Most. make_game.py's STAGE_SPAN gets the same change.
  • tests/test_make_game_prepare.py follows the new shares.
• The launcher's estimates are in MagicBeanDev/LongshotLauncher#28:
  • its "About 45 min" becomes this PC's own estimate, scaled by its CPU threads;
  • the time left starts from that estimate and corrects itself as each step finishes.
• docs/design.md: the old 25, 43 and 79 minute findings stay as history, each with a dated note giving today's number. Also noted: a release ships no hot list, so a player's build compiles every lifted file at -O1.

Flags and settings

None

Measurements

Baseline: nightly-56 @ e7ed2f7a, run 1. This is a docs-only change, so there is no main and PR pair: both columns measure the nightly the docs describe (e7ed2f7a65), the newest when measured (nightly-58 has been tagged since).
Hardware: Ryzen 9 7900X (12 cores, 24 threads), 30 GB, RTX 3090 (NVIDIA 620.70.06), Samsung 980 PRO NVMe, Linux (CachyOS, kernel 7.3.3).
Method:

• A player's build, from nothing: download the AppImage, verify SHA256SUMS and its signature, unpack, then run the Builder's own make_game.py command line (24 jobs, Compile shaders Most).
• New data, cache and work folders for each run. Every line of the log is timestamped, and the phases are read from the @@stage lines.
• Run 2 started with an empty NVIDIA shader cache, as a player's first build does.
• Two runs, one after the other.

Step	nightly-56 @ e7ed2f7a, run 1	nightly-56 @ e7ed2f7a, run 2 (empty NVIDIA cache)
Download (100 MB) and verify	3 s	4 s
Unpack, install the build tools	6 s	7 s
Read the game files	64 s	89 s
Translate (the lift)	56 s	58 s
Compile (274 files, -O1) and link	5 min 11 s	4 min 59 s
Finish the game folder	67 s	65 s
Prepare shaders, Most	5 min 0 s	5 min 22 s
In all	13 min 30 s	14 min 7 s
Peak memory above the idle PC	~15 GB	~14 GB

Run 2's read was slower because other work was running on the PC at the time (load average 20-23, against 5-10 in run 1).

run 1:   9.0 @@stage read | 73.2 @@stage lift | 129.4 @@stage compile | 442.8 @@stage finish | 509.8 the build took 0:08:21, compiled in 0:05:13 | 510.1 @@stage shaders | 643.3 prepared 38809 shader programs ... in 133.2 s | 810.0 @@mark build-end exit 0
run 2: the build took 0:08:34; prepare 322.5 s (programs 124.2 s, pipelines 198.3 s); 846.9 s end to end

Testing

Tested:

• The two builds above, both exit 0.
• Every link to development.md#build-times resolves to the new heading.
• tests/run_all.py at the last commit: 465 passed, 2 failed, 69 skipped. The two failures are this PC's Python, not this change:
  • test_bake_portability.py: no module named zstandard;
  • test_builder_log_read_only.py: no libtk8.6.so.

Not tested:

• Windows (the Builder runs the same make_game.py).
• A PC with fewer cores: the "longer on a slower PC" wording rests on the compile and the preparation using every thread, not on a measurement.
• An update (relift), which keeps its objects.

Needs other testers:

• Windows, and a 6- or 8-core PC: one player build of a current nightly with the steps in the new section, expecting the same phases and a time to add to the table (T-KQH4).

Screenshots

Nothing on screen

Risk and rollback

Docs, the Builders' text and the progress bar's shares; the build itself does not change. Reverting the commits is enough.

Reviewer notes

The old 25, 43 and 79 minute figures in design.md are dated findings, so they are kept and annotated rather than rewritten.

Issues

None

Checklist

For everyone

• One topic.
• The title is a Conventional Commit (type(scope): description).
• Rebased on current main.
• python -I -B tests/run_all.py run and passing (any failure that also fails on main is named above). The two failures are named under Testing; both come from missing local Python packages.
• Tested in the game, or what wasn't is named under Testing.
• Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests).
• Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. Two builds of the named nightly. There is no main/PR comparison, since the change is docs only.
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

If applicable

• AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
• Docs updated.
• A check under tests/ that reads changed source updated in this PR, not weakened.

## Why The docs told players a build takes "10 to 45 minutes" (README, getting started, common problems), "about 40 minutes" (CONTRIBUTING) or 25 and 43 minutes (design notes). A player's build of the current nightly takes about 14 minutes on a 12-core desktop, and nothing told developers to keep these numbers current. ## What changed - docs/development.md: a new **Build times** section with: - the phase table from two clean player builds of nightly-56; - which docs quote the numbers; - **how to measure again** (a player's build in new folders with an empty NVIDIA cache, then how to read each phase from the log); - **when to measure again**: after a change to the lift, the compile flags, the shader preparation or the toolchain (`tools.lock`), and before each release candidate. - README ("Install and play"), docs/getting-started.md, docs/common-issues.md and CONTRIBUTING.md ("Building"): "about 15 minutes on a 12-core desktop, longer on a slower PC", linking the section. - **The estimates players see** (`fix(builder)` commit): - The Builders said "About 45 min" in all 13 languages (`Strings.cs`, `MainWindow.xaml`, `MainWindow.xaml.cs`, the Linux Builder). They now say 15 to 30 minutes; the top of the range is for slower PCs. - `recomplauncher.json`'s step said "10 to 45 minutes" and now says "15 to 30 minutes". - The progress bar's step shares are now the measured ones. The Windows Builder's `WithShaders` gave the shaders 8% of the bar; they are 37% on Most. `make_game.py`'s `STAGE_SPAN` gets the same change. - `tests/test_make_game_prepare.py` follows the new shares. - **The launcher's estimates** are in MagicBeanDev/LongshotLauncher#28: - its "About 45 min" becomes this PC's own estimate, scaled by its CPU threads; - the time left starts from that estimate and corrects itself as each step finishes. - docs/design.md: the old 25, 43 and 79 minute findings stay as history, each with a dated note giving today's number. Also noted: a release ships no hot list, so a player's build compiles every lifted file at `-O1`. ## Flags and settings None ## Measurements Baseline: nightly-56 @ e7ed2f7a, run 1. This is a docs-only change, so there is no main and PR pair: both columns measure the nightly the docs describe (e7ed2f7a6526), the newest when measured (nightly-58 has been tagged since). Hardware: Ryzen 9 7900X (12 cores, 24 threads), 30 GB, RTX 3090 (NVIDIA 620.70.06), Samsung 980 PRO NVMe, Linux (CachyOS, kernel 7.3.3). Method: - A player's build, from nothing: download the AppImage, verify `SHA256SUMS` and its signature, unpack, then run the Builder's own `make_game.py` command line (24 jobs, Compile shaders Most). - New data, cache and work folders for each run. Every line of the log is timestamped, and the phases are read from the `@@stage` lines. - Run 2 started with an empty NVIDIA shader cache, as a player's first build does. - Two runs, one after the other. | Step | nightly-56 @ e7ed2f7a, run 1 | nightly-56 @ e7ed2f7a, run 2 (empty NVIDIA cache) | |---|---|---| | Download (100 MB) and verify | 3 s | 4 s | | Unpack, install the build tools | 6 s | 7 s | | Read the game files | 64 s | 89 s | | Translate (the lift) | 56 s | 58 s | | Compile (274 files, `-O1`) and link | 5 min 11 s | 4 min 59 s | | Finish the game folder | 67 s | 65 s | | Prepare shaders, Most | 5 min 0 s | 5 min 22 s | | **In all** | **13 min 30 s** | **14 min 7 s** | | Peak memory above the idle PC | ~15 GB | ~14 GB | Run 2's read was slower because other work was running on the PC at the time (load average 20-23, against 5-10 in run 1). ``` run 1: 9.0 @@stage read | 73.2 @@stage lift | 129.4 @@stage compile | 442.8 @@stage finish | 509.8 the build took 0:08:21, compiled in 0:05:13 | 510.1 @@stage shaders | 643.3 prepared 38809 shader programs ... in 133.2 s | 810.0 @@mark build-end exit 0 run 2: the build took 0:08:34; prepare 322.5 s (programs 124.2 s, pipelines 198.3 s); 846.9 s end to end ``` ## Testing **Tested:** - The two builds above, both exit 0. - Every link to `development.md#build-times` resolves to the new heading. - `tests/run_all.py` at the last commit: 465 passed, 2 failed, 69 skipped. The two failures are this PC's Python, not this change: - `test_bake_portability.py`: no module named `zstandard`; - `test_builder_log_read_only.py`: no `libtk8.6.so`. **Not tested:** - Windows (the Builder runs the same `make_game.py`). - A PC with fewer cores: the "longer on a slower PC" wording rests on the compile and the preparation using every thread, not on a measurement. - An update (relift), which keeps its objects. **Needs other testers:** - Windows, and a 6- or 8-core PC: one player build of a current nightly with the steps in the new section, expecting the same phases and a time to add to the table (T-KQH4). ## Screenshots Nothing on screen ## Risk and rollback Docs, the Builders' text and the progress bar's shares; the build itself does not change. Reverting the commits is enough. ## Reviewer notes The old 25, 43 and 79 minute figures in design.md are dated findings, so they are kept and annotated rather than rewritten. ## Issues None ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` run and passing (any failure that also fails on `main` is named above). The two failures are named under Testing; both come from missing local Python packages. - [x] Tested in the game, or what wasn't is named under Testing. - [x] Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests). - [x] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. Two builds of the named nightly. There is no main/PR comparison, since the change is docs only. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### If applicable - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Docs updated. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened.

HumanBean added 1 commit 2026-11-13 10:43:25 +00:00

docs: build times measured on nightly-56, and when to measure them again ... 36e6dcacc4

A player's build of nightly-56-e7ed2f7a on a Ryzen 9 7900X: 13 min 30 s and
14 min 7 s end to end (the build 8.5 min, of it the compile 5 min; the shader
preparation on Most 5 to 5.5 min). The README, getting started, common problems,
CONTRIBUTING and the design notes said 10 to 45, 40, 43 or 25 minutes.

docs/development.md gets a Build times section: the phase table, the docs that
quote it, and how and when to measure again.

Co-Authored-By: Claude Fable 5.2 <[email protected]>

HumanBean changed title from WIP: docs: build times measured on nightly-56, and when to measure them again to docs: build times measured on nightly-56, and when to measure them again 2026-11-13 10:43:51 +00:00

HumanBean added 1 commit 2026-11-13 10:49:55 +00:00

fix(builder): the Builders' time estimates and step weights measured on nightly-56 ... 00e60a7bfb

The Builders said "About 45 min" (in every language) and gave the shaders 8% of
the bar; RecompLauncher's step said 10 to 45 minutes. A player's build of
nightly-56 takes 13.5-14 min on a 12-core desktop, a third of it the shaders on
Most (docs/development.md, Build times). The estimates now say 15 to 30
minutes, the top for slower PCs, and the bar's weights (the Windows Builder's
WithShaders and WithoutShaders, make_game.py's STAGE_SPAN) are the measured
shares.

Co-Authored-By: Claude Fable 5.2 <[email protected]>

HumanBean added 1 commit 2026-11-13 10:54:23 +00:00

test(make_game): the prepare's progress lines at the measured stage shares ... 9695c828f2

Co-Authored-By: Claude Fable 5.2 <[email protected]>

HumanBean referenced this pull request from MagicBeanDev/LongshotLauncher 2026-11-13 10:54:38 +00:00

feat(build): this PC's build estimate, and a time left that learns its pace #28

HumanBean changed title from docs: build times measured on nightly-56, and when to measure them again to fix(builder): build times measured on nightly-56: the docs, the Builders' estimates and when to measure again 2026-11-13 10:54:47 +00:00

HumanBean commented 2026-11-13 10:54:53 +00:00

Author

Owner

• Copy link
• Copy Markdown

New commits:

• 00e60a7b: the Builders' "About 45 min" (all 13 languages) and recomplauncher.json's "10 to 45 minutes" now say 15 to 30 minutes. The progress bar's step shares are now measured: the shaders take 37% of the bar on Most, not 8%.
• 9695c828: test_make_game_prepare follows the new shares.

The launcher's own estimate, scaled to the PC and corrected as the build runs, is in MagicBeanDev/LongshotLauncher#28.

New commits: - 00e60a7b: the Builders' "About 45 min" (all 13 languages) and recomplauncher.json's "10 to 45 minutes" now say 15 to 30 minutes. The progress bar's step shares are now measured: the shaders take 37% of the bar on Most, not 8%. - 9695c828: test_make_game_prepare follows the new shares. The launcher's own estimate, scaled to the PC and corrected as the build runs, is in MagicBeanDev/LongshotLauncher#28.

HumanBean referenced this pull request from a commit 2026-11-13 10:55:16 +00:00

feat(build): this PC's build estimate, and a time left that learns its pace (#28)

HumanBean merged commit c67cd4a05b into main 2026-11-13 10:55:45 +00:00

HumanBean referenced this pull request from a commit 2026-11-13 10:55:45 +00:00

fix(builder): build times measured on nightly-56: the docs, the Builders' estimates and when to measure again (#175)

HumanBean deleted branch docs/build-times 2026-11-13 10:55:45 +00:00

HumanBean referenced this pull request 2026-11-13 11:17:09 +00:00

chore(builder): the Builder is command-line only; the launcher is the app #181

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Linux only

  

platform/steam-deck

Steam Deck

  

platform/windows

Windows only

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

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!175

No description provided.