Make the build standard the default

.cargo/config.toml

@@ -0,0 +1,33 @@
+# Repository-wide Cargo defaults for the development build standard.
+#
+# The mold linker and the parallel `rustc` frontend are the defaults for every
+# development, test, lint and typecheck build. Cargo auto-discovers this file,
+# so a bare `cargo build` gets them too; there is no opt-in path and no slower
+# alternative to choose.
+#
+# Release and coverage builds are excluded. Both are held out by assigning
+# `RUSTFLAGS`, which displaces every `rustflags` table below; see "The build
+# standard" in docs/developers-guide.md for the mechanism and the contracts.
+#
+# No codegen backend is named here, and none may be. A panic compiled by the
+# Cranelift backend does not find the unwind handler it should: `catch_unwind`
+# fails to catch and a panic on a spawned thread aborts the process, while a
+# bare `#[should_panic]` still passes. That makes the backend unusable for a
+# profile any test or binary runs on. The guide records the measurement and the
+# command; a contract refuses a backend key so that re-adding one has to go
+# through that evidence first.
+
+# Cargo selects a single rustflags source rather than merging them: a matching
+# `[target.*]` table replaces `[build] rustflags` outright, and an externally
+# set `RUSTFLAGS` replaces both. Every flag that must survive therefore has to
+# be repeated in each source, including the `RUSTFLAGS` the Makefile composes
+# for the gate targets. tests/build_tools_cargo_config_tests.rs and
+# tests/makefile_test_target/rustflags.rs hold the sources equal.
+[build]
+rustflags = ["-Zthreads=8"]
+
+# mold ships for Linux only, so the linker flag is gated behind a target `cfg`.
+# macOS and Windows fall through to `[build] rustflags` above and use their
+# platform default linker.
+[target.'cfg(target_os = "linux")']
+rustflags = ["-Zthreads=8", "-Clink-arg=-fuse-ld=mold"]

.github/workflows/ci-windows.yml

@@ -176,7 +176,13 @@ jobs:
         run: |
           $profileHome = [Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile)
           $whitaker = Join-Path $profileHome '.local\bin\whitaker.ps1'
-          $env:RUSTFLAGS = "$env:RUSTFLAGS -D warnings"
+          # Assigning RUSTFLAGS displaces every `rustflags` table in
+          # `.cargo/config.toml`, so the value has to carry the standard's
+          # flags as well as the deny. Name `-Zthreads=8` explicitly: mold is
+          # Linux-only so its flag is absent here, but the parallel frontend is
+          # not, and dropping it would lint a differently compiled tree from the
+          # one the other lanes measure.
+          $env:RUSTFLAGS = "$env:RUSTFLAGS -D warnings -Zthreads=8"
           $env:DYLINT_TOML = Get-Content dylint.toml -Raw
           & $whitaker --all --no-deps --package netsuke-build '--' --all-targets --all-features
           if ($LASTEXITCODE -ne 0) {
@@ -320,6 +326,15 @@ jobs:
         # been made.
         shell: pwsh
         run: |
+          # The `setup-rust` action exports its `rustflags` input as
+          # `RUSTFLAGS`, and an externally set `RUSTFLAGS` displaces every
+          # `rustflags` table in `.cargo/config.toml`. This step invokes Cargo
+          # directly rather than through the Makefile, so nothing composes the
+          # standard back in: without this line the binary users get would be
+          # the one build here not compiled with the parallel frontend. mold is
+          # Linux-only, so its flag stays absent. Same assignment, and same
+          # reason, as `Lint (Whitaker)` above.
+          $env:RUSTFLAGS = "$env:RUSTFLAGS -Zthreads=8"
           cargo build --locked --bin netsuke
           if ($LASTEXITCODE -ne 0) {
             exit $LASTEXITCODE

.github/workflows/ci.yml

@@ -145,6 +145,11 @@ jobs:
           tool: nextest@${{ env.NEXTEST_VERSION }}
       - name: Reset sccache statistics
         run: sccache --zero-stats
+      - name: Install the build standard
+        # The pinned `mold` is the repository's default linker and
+        # `check-build-tools` gates every build target on it, so this runs
+        # before the first compile rather than as a convenience.
+        run: make install-build-tools
       - name: Show rustc version
         run: |
           rustup show
@@ -257,6 +262,15 @@ jobs:
         # `rustflags` input. Pull requests only; on the trunk
         # `coverage-upload` runs the same set over the same commit.
         if: github.event_name == 'pull_request'
+        env:
+          # One of the two exclusions from the build standard. A build whose
+          # output is a measurement is a reproducibility claim, so it takes
+          # neither the parallel frontend nor the linker change. Assigning
+          # RUSTFLAGS is the whole mechanism: it displaces every `rustflags`
+          # table in `.cargo/config.toml`. Stated here rather than inherited
+          # from `setup-rust`, so the exclusion is visible at the step it
+          # applies to and a contract has something to read.
+          RUSTFLAGS: -D warnings
         uses: leynos/shared-actions/.github/actions/generate-coverage@a5765019912a8ab6882b12db049c7cde635f3a85
         with:
           language: rust

.github/workflows/coverage-main.yml

@@ -213,6 +213,15 @@ jobs:
       - name: Reset sccache statistics
         run: sccache --zero-stats
       - name: Test and Measure Coverage
+        env:
+          # One of the two exclusions from the build standard. A build whose
+          # output is a measurement is a reproducibility claim, so it takes
+          # neither the parallel frontend nor the linker change. Assigning
+          # RUSTFLAGS is the whole mechanism: it displaces every `rustflags`
+          # table in `.cargo/config.toml`. Stated here rather than inherited
+          # from `setup-rust`, so the exclusion is visible at the step it
+          # applies to and a contract has something to read.
+          RUSTFLAGS: -D warnings
         uses: leynos/shared-actions/.github/actions/generate-coverage@a5765019912a8ab6882b12db049c7cde635f3a85
         with:
           language: rust

.github/workflows/netsukefile-test.yml

@@ -107,6 +107,11 @@ jobs:
         uses: seanmiddleditch/gha-setup-ninja@3b1f8f94a2f8254bd26914c4ab9474d4f0015f67  # v6
       - name: Reset sccache statistics
         run: sccache --zero-stats
+      - name: Install the build standard
+        # `make build` below is gated on `check-build-tools` and links with the
+        # pinned `mold`, so it must be present before the first compile rather
+        # than installed on demand.
+        run: make install-build-tools
       - name: Show rustc version
         run: |
           rustup show

AGENTS.md

@@ -190,18 +190,28 @@ directive anywhere.
     CI-pinned version. `--git --include-untracked` selects the tracked and
     untracked Markdown files Git does not ignore, and `--check` exits `1` when
     any of them would be reformatted.
-  - `make lint` executes:
+  - On Linux, `make lint` executes:
 
     ```sh
-    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings" \
+    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings -Zthreads=8 -Clink-arg=-fuse-ld=mold" \
     RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo doc --workspace --no-deps
-    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings" \
+    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings -Zthreads=8 -Clink-arg=-fuse-ld=mold" \
     cargo clippy --workspace --all-targets --all-features -- -D warnings
+    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings -Zthreads=8 -Clink-arg=-fuse-ld=mold" \
     whitaker --all -- --all-targets --all-features
     yamllint --config-file .yamllint.yml .github/workflows
     actionlint
     ```
 
+    The Makefile composes that `RUSTFLAGS` value from one variable.
+    `-Clink-arg=-fuse-ld=mold` is Linux-only, so every sample in this section
+    drops it elsewhere — macOS and Windows use their platform linker and the
+    value ends `-D warnings -Zthreads=8`. Only that one flag is platform-gated;
+    `-Zthreads=8` and `-D warnings` apply everywhere. The flags are restated in
+    the Makefile rather than left to `.cargo/config.toml` because an assigned
+    `RUSTFLAGS` replaces every `rustflags` table in that file; see *Build
+    standard* below.
+
     linting every target with all features enabled, denying all Clippy
     warnings, running the Whitaker Dylint suite (see
     `docs/whitaker-users-guide.md`; install via `cargo install
@@ -226,15 +236,18 @@ directive anywhere.
     otherwise `$HOME/go/bin`; override `GO_BIN` to point at a different
     directory, or pass `ACTIONLINT=/path/to/actionlint` to name the binary
     directly, as CI does.
-  - `make test` executes:
+  - On Linux, `make test` executes:
 
     ```sh
-    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings" \
+    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings -Zthreads=8 -Clink-arg=-fuse-ld=mold" \
     cargo nextest run --workspace --all-targets --all-features
-    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings" \
+    RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-D warnings -Zthreads=8 -Clink-arg=-fuse-ld=mold" \
     cargo test --workspace --doc --all-features
     ```
 
+    The platform caveat stated under `make lint` applies unchanged: the linker
+    flag is Linux-only and the rest of the value is not.
+
     running every unit, integration, and behavioural test through
     [cargo-nextest](https://nexte.st/), then the doctests separately because
     nextest cannot execute them. Both passes deny warnings, and `make test`
@@ -551,14 +564,40 @@ The following tooling is available in this environment:
 These practices help maintain a high-quality codebase and facilitate
 collaboration.
 
-## Fast development builds
-
-`make dev-build` and `make dev-test` compile with the opt-in Cranelift backend
-and the mold linker configured in `tools/dev-fast/config.toml`. Run
-`make install-dev-fast` to install the pinned nightly's
-`rustc-codegen-cranelift-preview` component and, on Linux, the pinned `mold`
-release. `make dev-fast-check` preflights those prerequisites before Cargo is
-invoked. Linux `x86_64` and `aarch64` hosts use `mold`; macOS and Windows use
-their platform linker instead. The fragment is passed explicitly with
-`--config`, so release, coverage, and verification builds are unaffected; never
-copy its contents into `.cargo/config.toml`, which Cargo applies to every build.
+## Build standard
+
+The `mold` linker and the parallel `rustc` frontend (`-Zthreads=8`) are the
+**defaults** for development, test, lint, and typecheck builds. They are
+committed to `.cargo/config.toml`, which Cargo auto-discovers, so a bare
+`cargo build` gets them too. The Cranelift codegen backend is deliberately not
+part of the standard and a contract refuses one; the developers' guide records
+why.
+
+Run `make install-build-tools` to install the pinned nightly and, on Linux, the
+pinned `mold` release. `make check-build-tools` preflights those prerequisites,
+and is a prerequisite of `make build`, `make test`, `make lint`, and
+`make typecheck`, so a missing tool reports an installation hint before Cargo
+runs. Linux hosts use `mold`; macOS and Windows keep their platform linker,
+which the `cfg(target_os = "linux")` gate in the configuration expresses.
+
+Two build shapes are excluded and must stay excluded:
+
+- **Release and packaging.** The release recipe assigns `RUSTFLAGS` so the
+  configuration's `rustflags` tables do not apply. A shipped artefact is built
+  on the platform linker and a single-threaded frontend.
+- **Coverage.** A build whose output is a measurement is a reproducibility
+  claim. The coverage steps assign `RUSTFLAGS` at the step itself and carry
+  neither `-Zthreads` nor the linker flag.
+
+Cargo picks a single `rustflags` source rather than merging them: a matching
+`[target.*]` table replaces `[build] rustflags`, and an externally set
+`RUSTFLAGS` replaces both. Every gate recipe assigns `RUSTFLAGS` to deny
+warnings, so the standard's flags are restated in the Makefile and composed
+into that value. Changing one source without the other fails a contract test;
+do not "simplify" by deleting a restatement.
+
+There is no separate accelerated target. `make build`, `make test`,
+`make lint`, and `make typecheck` are the build targets, and they all run on
+the standard. See "The build standard" in
+[developers' guide](docs/developers-guide.md) for the full ownership boundary,
+the benchmark, and the fallback behaviour.