docs: explain host-wide build bounding - #89
Merged
Conversation
Adds docs/concurrent-dev-cache.md: what bounds concurrent builds on one host, and what is deliberately left unbounded. Rust builds are held by a memory semaphore, the artefact pool by a ceiling derived from the disk, and the compiler caches by fixed byte ceilings. The file existed untracked as a pre-work design note whose opening said none of the work was built. Four of the five things it scoped had shipped, so it is restructured rather than patched: the gap numbering and the sections addressed to one reader are gone, and the unbuilt work is stated as limitations. Linked from the role README, which is where its sibling is linked from. Corrects three errors in tracked files that the rewrite surfaced. developer-rust/README.md said sccache passes incremental calls through. It does not cache them, which is what the sentence meant, but setting CARGO_INCREMENTAL=1 by hand makes sccache refuse the build outright. Both cases are now stated. That README and rust-build-governor.md both claimed every build lands in rust-build.slice. The shim reaches the slice only on Linux with a live user manager, and otherwise falls back to a QoS clamp on macOS or to nice, where the semaphore and the job cap are the bounds. All three files now carry the same qualifier. rust-build-governor.md gave HYPERI_RUST_GOVERN_NO_INCREMENTAL=0 as the hand override. That is a no-op where the role leaves the setting off, which is the default. Both directions are now stated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/concurrent-dev-cache.mdand corrects three factual errors itsurfaced in tracked files.
The new document
What bounds concurrent builds on one host, and what is deliberately left
unbounded. Rust builds are held by a memory semaphore, the artefact pool by a
ceiling derived from the disk, and the compiler caches by fixed byte ceilings.
It existed untracked as a pre-work design note whose opening line said none of
the work was built. Four of the five things it scoped had shipped, so it is
restructured rather than patched: the
Gap 1..5numbering is gone, so are thesections addressed to one reader (
Decisions for Derek,Not verified, anopen question that was answered), and the unbuilt work is stated as limitations
rather than as a task list. 11 sections became 7, and the slot/memory model is a
diagram instead of three paragraphs.
Nothing linked to it, so it is now linked from the role README, beside its
sibling.
The three corrections
developer-rust/README.mdsaid sccache "passes those through" forincremental compilation. It does not cache them, which is what the sentence
meant, but setting
CARGO_INCREMENTAL=1by hand makes sccache refuse thebuild outright. Both cases are now stated. Checked against
mozilla/sccache,
not decided by preference.
rust-build-governor.mdboth claimed every build lands inrust-build.slice. The shim reaches the slice only on Linux with a liveuser manager, and otherwise falls back to a QoS clamp on macOS or to
nice.All three files now carry the same qualifier.
rust-build-governor.mdgaveHYPERI_RUST_GOVERN_NO_INCREMENTAL=0as thehand override. That is a no-op where the role leaves the setting off, which is
the default. Both directions are now stated.
Gates
hyperi-ai docs lintclean on all three but for two soft-ceiling findings(
concurrent-dev-cache.md4 words over, the role README 12).maidreportsValid on both files under
docs/.Two adversarial review rounds, fresh context each, defaulting to FAIL. The first
failed on five confirmed contradictions. The second caught a regression the
first remediation introduced into a tracked file, which is why there was a
third pass. Every claim in the new document is traced to the role source, the
shim, or the prune tooling.
Known, not fixed here
ansible/roles/developer-rust/README.mdcarries a## SSoTsection of datedhistory about a script that no longer exists, which is the class
documentation-structure.mdkeeps out of docs. Cutting it would also take thefile under the word ceiling. Left alone deliberately: it is 180 words of why an
earlier approach was rejected, and removing it is a separate call from this
change.