Shared script libraries (linux/scripts/lib/)#
Sourceable, project-agnostic cores. Nothing about a specific project is hard-coded in any of them. The contract is always the same:
A thin wrapper script sets that library’s
*_DEFAULT_*/*_*variables — its project defaults.It optionally declares hook functions.
It sources the library and calls the library’s
*_main.
None of them set -e/-u/-o pipefail: sourcing must not change the caller’s
shell options, and wrappers are expected to run under set -euo pipefail
themselves. Anything the wrapper does not provide is discovered from the
environment — logging from 01-core/logging.sh (or minimal fallbacks), job
computation from 01-core/parallelism.sh, tool presence and the Vulkan
environment from the caller’s own has_tool/require_tools/source_vulkan_env
when it declares them.
Three have their own pages, because their topic is bigger than the library:
code-quality.sh,
slang-compile.sh, and the agentic-loop.sh +
agentic-engines.sh pair, one executable loop in two files
(agentic-loop-build-matrix.md).
The tree, as AGENTS.md drew it#
Moved out of AGENTS.md on 2026-09-15 (owner decision D10), and edited since
only to keep it current. AGENTS.md keeps one line per top-level directory; the
per-file detail, the deletion history and the consumer-surface notes are here.
linux/scripts/
├── 01-core/ shared utilities (62 as of 2026-09-01 — `ls linux/scripts/01-core/*.sh | wc -l`; the literal said 48 for long enough that README repeated it, so treat any count here as indicative: versions.env, logging, platform, cross-env, cross-gcc, cross-meson, cross-apt, compiler-resolution, tag-naming, stage-defs, digest-pinning, ancestry, build-helpers, cli-parsers, …)
├── 02-toolchain/ GCC, LLVM, Rust, Python, CMake, Vulkan builds
├── 03-media/ media library build scripts
│ ├── core/common.sh single DRY bootstrap — sourced by every media script
│ ├── build/ per-library build scripts
│ │ ├── onnxruntime/ ONNX Runtime + GenAI (build/ steps, runtime/ pkgconfig, android/)
│ │ ├── litert/ LiteRT + TFLite C API (Critical Fix #2: abseil span.h copy in build-litert.sh)
│ │ ├── opencv/ OpenCV 5.x
│ │ ├── ffmpeg/ FFmpeg (build-ffmpeg.sh has fixed host compiler wrapper)
│ │ ├── gstreamer/ GStreamer monorepo (common/ has patch-gstreamer-sources.sh — Critical Fix #5)
│ │ ├── libcamera/ libcamera
│ │ ├── pyav/ PyAV wheel (`import av`), built in a stage layered on the FFmpeg it links against (Dockerfile.media `FROM ffmpeg AS pyav`); versions.env pinned PYAV_VERSION while nothing built it until 2026-08
│ │ ├── armnn/ Arm NN + Arm Compute Library — arm64 ONLY; other arches get empty /opt/armnn + /opt/acl
│ │ ├── hailo/ HailoRT + hailortcli + the hailonet element, built in the wrapper image (Dockerfile.torch); riscv64 skips
│ │ └── iree/ android/ ONLY (dispatched via android-dispatch.sh); the Linux-lane IREE is built by 05-frameworks/torch/build-app-wheelhouse.sh
│ └── runtime/ artifact collection, runtime config, wheel repair, verification, media-env.sh (canonical ENV)
├── 04-runtime/ entrypoint + env scripts (gstreamer-env.sh, etc.)
├── 05-frameworks/ TVM, Torch, Flutter
└── 06-packaging/ assembly + smoke tests (smoke-media.sh, smoke-common.sh)
Top-level orchestrators: build-cross-chain.sh, build-cross-compiler.sh, build-cross-stage.sh, build-runtime-manifest.sh, build-runtime-artifacts.sh. Verification: verify-cross-chain.sh, verify-critical-fixes.sh, verify-artifact-copy-parity.sh.
Beyond linux/scripts/:
linux/scripts/lib/ consumer-facing bash libraries: agentic-loop.sh +
agentic-engines.sh (one loop in two files),
app-packaging.sh (tar/deb/AppImage/Flatpak),
app-runner.sh (generic app launcher: arg parse, exe
discovery, LD_LIBRARY_PATH, per-profile hooks),
cmake-build.sh, code-quality.sh, coverage.sh,
compiler-llvm-tools.sh (a build tree's own LLVM
tools, first on PATH), dartdoc-build.sh (+
dartdoc-guides.py), linker-select.sh (opt-in
KATAGLYPHIS_LINKER=lld|mold), log-bootstrap.sh (the
logging block the others source), slang-compile.sh,
wasm-opt.sh, ctest-run.sh (ctest runner),
docs-build.sh (Sphinx build helper),
rust-toolchain.sh — the last three had NO doc entry
anywhere until the 2026-08-08 orphan sweep. A
consumer surface, reached through the consumer's
third_party/ANTfrastructure checkout: no image
ships lib/, and in-repo only preflight.sh and
05-frameworks/flutter/flutter_checks.sh source it
(code-quality.sh)
linux/scripts/02-toolchain/rust/ cargo_* helpers (test/bench/debug/
fmt+clippy/security/coverage/release/doc; test,
bench and debug run through _cargo_wrapper.sh) —
consumer surface COPY'd into the
toolchain/sdk/package images; nothing in-repo calls
them (the redundant zero-ref Build-Linux.sh duplicate
was deleted 2026-08-08)
linux/scripts/02-toolchain/python/ci_*.sh Python CI helpers (tests, static
analysis, packaging, docs) — same consumer-surface
status as rust/
linux/scripts/01-core/setup-host-deps.sh hand-run developer-onboarding
helper (host toolchains, compiler caches, analysis
and coverage tools); intentionally not wired into CI
or builds
linux/scripts/06-packaging/package_archive.sh tar/deb/AppImage/Flatpak
assembly — consumer surface. Called from
OxidANT's reusable-linux.yml, which its Linux
lanes (linux-x64.yml, linux-arm64.yml) call;
rust_ubuntu26_04.yml until the 2026-09-24 rename.
Deleted by the 2026-08-08 orphan sweep as
"zero-reference" and restored 2026-08-11: the sweep
searched only THIS repo, so a consumer's CI lane was
broken silently. Grep the consumer repos before
deleting anything under lib/, rust/, python/ or
06-packaging/.
windows/scripts/ Windows lane, GROUPED since #108 (2026-08-20):
build/ (chain components: Build-*FromSource.ps1,
Build-*All.ps1 wrappers, Test-Container.ps1,
Import-Versions.ps1), host/ (Install-*/Set-*/
Repair-*/Reset-* + elevated maintenance),
diagnostics/ (Test-*/Get-*/Invoke-*/Measure-* probes
+ the Invoke-DiagnosticProbe.ps1 runner). A settled
one-shot is DELETED, not archived: git history is the
record, and the diagnostics/archive/ facility that
used to hold them never worked as advertised —
`**/archive/` in .dockerignore strips it from every
build context, so the -ProbeScript archive/<name>.ps1
it promised could not solve. Container mounts
stay FLAT (C:\bkmnt, C:\temp\scripts) — the
$scriptAssetRoot resolver bridges both layouts and
is gated by ScriptAssetRoot.Parity.Tests.
Ungrouped residents BY DECISION (#131):
Invoke-Lint.ps1, entrypoint.cmd, cargo-retry.cmd
(consumer-CI suspect — never delete unverified),
certificates/ (MSIX cert generation + WebDAV
download_webdav_files.py — see its README.md),
python/ + rust/ (consumer CI-lane drivers).
Also ungrouped: patches/ (the static source-build
patches, catalogued in its README.md).
modules/*.psm1 (reusable PS modules: SourceBuild,
Build.Common, ContainerBuild.Reuse, AgenticLoop,
CMake, Config, Formatting, Msix.{Common,Signing},
WebDav, Uv, Scripts.Shared, Toolchain, CodeQL,
ContainerImage, CrossBundle, Flutter, Installer,
HostMaintenance, SmokeTest, GstPlugins, …),
tests/ (harness + suites), shims/
windows/upstream/ prepared upstream submissions (not build inputs), one
directory per submission = format-patch + PR.md. See
its README.md for the index, and
docs/upstream-windows-patches.md for the graded
register of EVERY local third-party change.
hcsshim-teardown-timeout/ is the one already FILED
(microsoft/hcsshim#2855) and also carries ISSUE.md,
the deployed 45min local patch and the rebuild
recipe; the other 14 are prepared and UNSENT - do
not post without the owner saying so.
shared/agentic-loop/ cross-platform data: prompts/*.md — the single source
for the default planner/refactor-planner/executor task
prompts read by BOTH WindowsAgenticLoop.Common.psm1
and linux/scripts/lib/agentic-loop.sh;
system-prompts/*.md, the role prompts both halves
compose (agentic-engines.sh on Linux); templates/,
the consumer config and runner wrappers
.github/actions/ 12 composite actions consumers call @develop, incl.
cleanup-disk-space (Windows runners),
run-in-linux-container, run-in-windows-container;
full list in .github/actions/README.md
out/: generated build artifacts (OCI layouts, rootfs exports). Excluded from Docker context via .dockerignore.
Module loading order, as AGENTS.md carried it#
Moved out of AGENTS.md on 2026-09-15 (owner decision D10), and edited since only to keep it current. The RULES stayed there; this is the reference behind them.
artifact-common.sh sources 01-core modules in dependency order:
common.sh2.tag-naming.sh3.stage-defs.sh4.digest-pinning.sh5.chain-verify.sh6.ancestry.sh7.build-helpers.sh8.cross-stage-build.sh9.context-management.sh10.version-forwarding.sh11.cli-parsers.sh12.runtime-build-fns.sh13.compiler-resolution.sh14.parallel-loop.sh15.path-helpers.sh.abseil-headers.shis deliberately NOT in this loop (backlog A3, 2026-08-12): it has no host-side caller, and its in-image consumers load it viasource_module.
runtime-flow-common.sh is sourced by lib-orchestrator.sh inside runtime_flow_preamble(); build-runtime-artifacts.sh and build-runtime-manifest.sh reach it by sourcing lib-orchestrator.sh.
lib-runtime-wheels.sh (RUNTIME_WHEELS_SOURCE) is sourced by lib-orchestrator.sh at top level, right after artifact-common.sh. It sits beside 01-core, not in it, because 01-core is in the compiler image’s closure and this file is host-only. append_wrapper_build_args calls into it only while RUNTIME_WHEELS_EXPORT_ROOT is set, which only its own runtime_wheels_setup does (both deliveries).
03-media/build/hailo/hailo-build-lib.sh is sourced there too, right after it, for one function: hailo_validate_knobs, which the chain and both runtime orchestrators call before they build anything. The same file is the Hailo build’s own library inside the wrapper image, so it sets no shell options and runs nothing at load, and a change to it re-keys only the wrapper’s Hailo RUN (two switches).
Which loader a NEW script should use (the dual-loader rule): scripts that
also execute INSIDE containers (bind-mounted or COPY’d — base-image, 02-toolchain,
03-media, 06-packaging) load via modules.sh / source_module, which resolves
both the repo layout and the /opt/scripts container layout. Host-only
orchestration (build-cross-*.sh, runtime flows) sources artifact-common.sh
directly. Do not mix: a container-capable script hard-sourcing repo paths breaks
at /opt/scripts. (Known wart: modules.sh hardcodes a ../02-toolchain
search path — a 01-core file encoding stage-2 layout; fold a fix into any
future modules.sh touch. The layer order itself is frozen by
tests/test-layer-order.sh.)
What holds the standalone contract#
Two suites, and they split the work. tests/test-lib-smoke.sh is the cheap half
over every lib/*.sh: the module parses (bash -n), it sources cleanly under
set -euo pipefail — a strict-mode consumer must not be killed by an unbound
variable or a failing top-level command — and sourcing it defines at least one
function, counted as a delta inside one shell so functions exported into the
test environment cannot fake the number. A module that exports nothing is a
gutted or early-returning copy, not a library. It also parses
cmake_build_parse_args in isolation. No network, no cmake run.
tests/test-lib-modules.sh is the strict half described under
The logging bootstrap: double-source safety, and that
info/warn/err arrive from the real 01-core/logging.sh rather than a
private fallback copy. It skips the agentic-*.sh pair, one executable loop split
over two files rather than a source-library.
The logging bootstrap#
log-bootstrap.sh is the one owner of the block every other library needs
before it can say anything: resolve ../01-core/logging.sh if the caller has
not already defined info, and otherwise define the minimal info/warn/err
that let the library run standalone. Each library sources it on the line after
its own re-source guard; only cmake-build.sh and wasm-opt.sh keep a
_*_CORE_DIR of their own, because they reach into 01-core for
parallelism.sh, load-versions-env.sh and downloads.sh as well.
It is a separate file, and not an idiom pasted into each library, because nine
hand-kept copies had already drifted twice, and both drifts were defects
(complexity audit F-A): app-runner.sh carried no re-source guard and never
attempted the real 01-core/logging.sh, so standalone consumers silently got
the minimal fallbacks — no log, no die, different formatting — forever;
rust-toolchain.sh had no guard either and defined no err, so an err call
would have inherited whatever the caller happened to have, or exploded. No
duplication gate could catch that: at nine owners every shingle of the block
lands in verify_code_dupes’ suppressed as idiom at >6 owners bucket
(MAX_OWNERS = 6), which is why the copies were free to rot.
Sourcing a sibling to get logging is not the bootstrap paradox it looks like.
The block it replaced already sourced a file — ../01-core/logging.sh, one
directory further away — and every consumer vendors the whole ANTfrastructure
checkout (third_party/ANTfrastructure/linux/scripts/lib/<lib>.sh), so
a missing file next to the library it serves is a broken checkout, not a
supported state. tests/test-lib-modules.sh holds that line: every lib/*.sh
must source cleanly standalone, define info/warn/err, survive a double
source, and end up with the real logging module rather than the fallbacks.
cmake-build.sh — configure + build a CMake project in a container#
Variable |
Meaning |
Default |
|---|---|---|
|
CMake preset name |
— |
|
build directory |
|
|
|
|
|
|
|
|
|
— |
|
peak RAM per compile job |
|
|
|
|
|
bash ARRAY of extra configure-step arguments |
empty |
|
path registered as a git |
|
|
label logged around the pre-build hook |
— |
|
one-line description shown in |
— |
Vulkan selection — _cmake_build_resolve_vulkan. Three sources can name a
Vulkan SDK, and they are resolved in one place: an explicit --vulkan-version /
--vulkan-setup-script / --vulkan-sdk flag overwrites whatever the image
exported, and CMAKE_BUILD_DEFAULT_VULKAN_SETUP_SCRIPT is consulted last — only
when nothing else set VULKAN_SETUP_SCRIPT and the file it names exists.
That -f test is the load-bearing half: cmake_build_prepare_env sources
VULKAN_SETUP_SCRIPT unconditionally once it is set, so adopting a default that
is not on disk turns a missing SDK into a sourcing error much later.
tests/test-lib-smoke.sh pins all four cases.
Extra configure arguments — --configure-arg. Repeatable, and the only way
to put a -D on the configure command line. Each occurrence appends one
argument, in order, to CMAKE_BUILD_CONFIGURE_ARGS; the list is reset per
cmake_build_parse_args call and seeded from CMAKE_BUILD_DEFAULT_CONFIGURE_ARGS
(an array, not an environment string — splitting one would break the first -D
whose value contains a space, and --configure-arg '-DCMAKE_CXX_FLAGS=-O2 -g'
must stay one argument). They reach the configure step only, never
cmake --build. An empty value is fatal rather than dropped: cmake "" fails
with a message about the source directory, nowhere near the caller. Without
this, a wrapper that needed one -D had to run --skip-configure true and
issue its own cmake -B … --preset …, i.e. call three library entry points
where cmake_build_main would do.
Hook — cmake_build_prebuild_hook. Called only when the wrapper declares it.
Runs after configure, immediately before cmake --build; use it for code or
asset generation the build or the runtime depends on (shader precompilation,
codegen). A non-zero return is fatal by default — see cmake_build_run()
for why.
app-packaging.sh — the two flatpak entry points#
Every packager in the file obeys three rules. Staging trees are container-native,
never inside the mounted workspace: a bind-mounted host drive refuses chmod/fchmod
for the container uid, so dpkg-deb, appimagetool and flatpak-builder fail there,
and only finished artifacts are copied into out/. flatpak-builder’s exit code is
reported but never the verdict; ostree --repo=<repo> refs decides whether the app
is committed. And nothing prints Created: without app_packaging_assert_artifact. Two entry
points were added on 2026-09-15 for a consumer that packages a CMake install
tree rather than a Flutter bundle; the finish-args block and the CON2 probe
landed on 2026-09-17:
app_packaging_ensure_flatpak_runtime [arch] [runtime] [sdk] [version]— flathub plus the runtime/SDK pair, for a run that is not inside the family CI image. Deliberately notapp_packaging_setup_dependencies_for_container: that one assumes the image already ships flatpak, installs missing packages through a privilege helper and installs underdbus-run-session. This one installs nothing with apt and asks first, so a warm dev box is a no-op. User installation first, system as the fallback, for the remote and for both refs — an unprivileged user cannot write the system installation, and pulling a second copy of a ref the machine already has system-wide costs 1-2 GB.app_packaging_setup_dependencies_for_containernow probes both scopes before installing too (CON2, 2026-09-17): the CI image installs the pair system-wide as root while the container runs as uid 1001, so its unconditional--user installwas pulling that second copy on every flatpak-packaging run.app_packaging_flatpak_finish_args_block— the manifest’sfinish-argslist: the four generated entries (network, the two display sockets, DRI) plus whateverKATAGLYPHIS_FLATPAK_FINISH_ARGSadds, space-separated. Appended, never replaced (CON6, 2026-09-17). V4L2 capture needs--device=all(there is no per-device video grant in flatpak) and a user-chosen model path needs a--filesystem=; the knob exists because the omission is invisible to every gate — the bundle ships, the window opens, and only the camera stays silent.app_packaging_package_cmake_install_flatpak <build_dir> <out_dir> <app_id> <project_name> <version_suffix> [runtime] [sdk] [version] [branch] [arch]—cmake --installinto a container-native staging prefix, rename the PROJECT-named.desktop/.png/.appdata.xmlto the APP ID, write the manifest, build, and copy only the finished bundle into<out_dir>.<out_dir>is routinely the build directory on a mounted workspace, which is exactly why nothing but the bundle is written there.
app_packaging_require_flatpak_tools, which both packagers call first, requires
three binaries: flatpak, flatpak-builder and — since 2026-09-15 —
ostree. The verdict above is ostree refs, but Debian’s and Ubuntu’s flatpak
package depends on libostree and not on the ostree CLI, so a box with the two
obvious tools installed passed the check and then reported is not in <repo>
over an export that had succeeded. Each missing tool is reported with what the
packaging step wanted it for, and all of them at once: one apt-get installs the
set.
tests/test-app-packaging-flatpak.sh pins all of them against stubbed
flatpak/flatpak-builder/ostree/cmake, including the two cases the exit code
cannot see: a non-zero flatpak-builder whose app is committed still ships,
and a zero exit with an empty repo fails.
06-packaging/package_archive.sh — one binary, four formats#
One release binary, a tar always, and by --package-types a deb, an AppImage and
a flatpak. The types are comma- or space-separated, in any case. Its consumer is
OxidANT’s Linux lane. Until 2026-10-06 it wrote the tar and stopped: its
create_deb() was deleted on 2026-08-08 as unreachable, and --flatpak-manifest,
--desktop-file and --appdata-file were checked for existence and then never
read.
After the tar it stages the binary alone, under its package name, in
${KATAGLYPHIS_PACKAGING_WORKDIR:-/tmp/packaging-work}/bundle. It hands that tree to
the three bundle packagers above, the ones a Flutter lane calls, through seven
knobs. Unset, each keeps the Flutter default, so a Flutter lane packs what it did
before:
Knob |
Flutter default |
|
|---|---|---|
|
|
the staged tree |
|
|
|
|
a generated entry |
|
|
|
|
|
|
|
|
|
|
|
|
|
Three details each format depends on:
The desktop entry is the project’s own.
app_packaging_adapt_desktop_filekeeps every line butExecandIcon, and sets those two right after[Desktop Entry]for the format: the package name for the deb and the flatpak,AppRunfor the AppImage.The icon goes where its real size says.
app_packaging_icon_sizereadsWxHfrom the PNG header, so a 128×128 logo lands inhicolor/128x128/apps. A file that is no PNG falls back to512x512, the directory every icon used to go to.The flatpak copies
lib/anddata/only when they exist. A Flutter bundle has both, a single binary has neither.
--flatpak-manifest and --appdata-file now stop the run with an error that says
why, instead of being accepted and ignored. The flatpak manifest is generated from
the staged bundle. An unknown package type stops the run before anything is built,
and the three bundle formats need --arch.
tests/test-package-archive.sh pins the wiring against stubbed packagers. It also
packs one real deb through the real library and checks its contents, Depends and
desktop entry. Measured 2026-10-06 in :latest, OxidANT’s release kataglyphis_cli
(1.9 MB; it links libc, libm and libgcc_s) gave:
a tar of 885 KB;
a deb of 732 KB, whose binary runs;
an AppImage of 1.7 MB, which runs with
APPIMAGE_EXTRACT_AND_RUN=1;a flatpak of 684 KB, which
flatpak install --system --bundleinstalls andflatpak run --command=oxidantruns, with its desktop entry and 128×128 icon exported.
ctest-run.sh — run a CMake project’s test suite in a container#
The twin of cmake-build.sh for the test phase, and deliberately a separate
library rather than another entry point inside it: CI configures and builds
once, then runs ctest several times over different build trees (plain, ASan,
TSan…). Sourcing the build driver for that would drag in its cargo/ccache/sccache
writability fallbacks and its pre-build hook machinery, none of which a ctest run
uses.
Variable |
Meaning |
Default |
|---|---|---|
|
build tree to |
|
|
value for |
|
|
default |
none |
|
ctest flags when the caller does not override them |
maximally loud on purpose — a container test run is only debuggable through its log |
|
git |
|
|
one-line description shown in |
— |
A GPU test suite needs the loader and the layers on the same terms the build had, which is why the Vulkan environment is resolved here too.
compiler-llvm-tools.sh — the LLVM tools of the compiler that built a tree#
Anything that reads clang’s output has to come from the same LLVM. That covers
llvm-profdata and llvm-cov on a raw profile, and clang-tidy on module PCMs. The
images put a source-built clang behind clang/clang++, while the bare tools on
PATH can be an older distro LLVM, so the pairing fails with “no profile can be
merged” or “uses a newer format that cannot be read”. The image after CON11 links
clang’s own copies into /usr/local/bin (BACKLOG CON15); keep the helper for older
images and for a tree another compiler configured.
compiler_llvm_tool <build-dir> <tool>prints the tool beside the compiler that configured the tree (CMAKE_CXX_COMPILERin itsCMakeCache.txt, elseclang++). It asks that compiler’s-print-prog-name, and fails when the answer is the bare name, which is clang’s way of saying it has none.use_compiler_llvm_tools <build-dir> <tool>...puts that directory first on PATH, but only when it holds every named tool. A half set would mix two LLVMs in one report, so it warns and leaves PATH alone instead. Call it in a subshell when the directory holds a tool the caller must not swap, such asclang-format.
It came up from AccelerANTgine’s ci-common.sh once BeschleunigerBallett’s coverage
lane hit the same “no profile can be merged” (2026-09-24).
linux/scripts/tests/test-compiler-llvm-tools.sh pins it with two fake LLVM
installs.
linker-select.sh — an opt-in linker#
KATAGLYPHIS_LINKER=default|lld|mold picks the linker for one build. Unset, or
default, changes nothing: clang keeps GNU ld 2.46 and x64 Rust keeps rustc’s
own rust-lld. linker_select_env applies it, and cmake_build_prepare_env and the
cargo_test/cargo_bench/cargo_debug wrappers call it. A Flutter lane calls it
itself, after it has set CC.
C/C++: it appends
-fuse-ld=<x>toLDFLAGS. CMake folds that into everyCMAKE_*_LINKER_FLAGS, but only at the first configure, so a reused build tree keeps its old linker. For mold under clang it also passes-Wl,-plugin,<clang prefix>/lib/LLVMgold.so. Without it mold stops on LTO bitcode archive members (“the -plugin option was not provided”). GCC’s collect2 passes its own plugin.Rust: for the host triple only, it sets
CARGO_TARGET_<HOST>_LINKER=$CCand appends-C link-arg=-fuse-ld=<x>toCARGO_TARGET_<HOST>_RUSTFLAGS. wasm32 and the Android targets keep their own linkers. Changing the value recompiles every crate, and sccache misses with it.Loud, never a fallback. An unknown value returns 2. Three things return 1: a set
RUSTFLAGSorCARGO_ENCODED_RUSTFLAGS(cargo would take either over the per-target flags without a word), a driver that cannot link a one-line probe with-fuse-ld=<x>, and a mold that cannot be had.USE_LLDincompiler-cache.shfalls back silently; this switch exists to measure, and a fallback would make the measurement lie.mold comes from PATH, else the pinned release. No image ships it yet.
linker_select_ensure_molddownloads theMOLD_LINUX_*pin intool-pins.env(SHA256 per arch: x86_64, aarch64, riscv64) into a version-keyed cache (LINKER_SELECT_CACHE_DIR, default$TMPDIR). An unpinned architecture fails.
Which one to pick. Measured 2026-10-05 in :latest on 32 cores, across OxidANT,
AccelerANTgine and the OmniAccelerANT Flutter app, and BeschleunigerBallett on 2026-10-06:
Build |
GNU ld |
lld 23 |
mold 3.0.0 |
|---|---|---|---|
AccelerANTgine Debug (ASan, UBSan), relink all 5 binaries |
1.70 s |
0.35 s |
0.56 s |
AccelerANTgine release, |
0.97 s |
0.85 s |
0.82 s |
|
49.3 / 3.9 s |
47.6 / 3.8 s |
49.5 / 4.3 s |
Rust dev link, |
0.87 s |
0.14 s |
0.33 s |
BeschleunigerBallett |
1.55 s |
0.20 s |
0.32 s |
Linking is about 2% of these builds, so lld is the useful value. It is already
in the image, and it is the one real gain on Debug relinks. mold 3.0.0 links
correctly, with the same exported symbols and passing tests, but is never faster
than lld here. mold 2.x (Ubuntu’s 2.40.4, the last C++ release 2.42.1) does not
link AccelerANTgine. It stops on its non-PIC spdlog (R_X86_64_PC32 … recompile with -fPIC). With spdlog made PIC it exports 619 extra symbols, and two Debug
suites abort on an ASan odr-violation. That is why the pin is 3.x and why no apt
package is used.
linux/scripts/tests/test-linker-select.sh pins it with stub drivers and a stubbed
download.
riscv64-cross.sh — cross-build for riscv64, test under QEMU#
riscv64_cross_env turns the amd64 image into a riscv64 cross environment over a
sysroot built from the image’s riscv64 child (RISCV64_SYSROOT, default
/opt/riscv64-sysroot). It writes triple-named clang wrappers, exports the cc-rs, Cargo
and pkg-config variables for riscv64gc-unknown-linux-gnu, names the CMake toolchain in
RISCV64_CMAKE_TOOLCHAIN_FILE, sets the QEMU CPU model, and fails when a riscv64 binary
does not execute. Why each piece is there, and what it was measured against:
riscv64-cross-test-lanes.md.
linux/scripts/tests/test-riscv64-cross.sh pins it.
docs-build.sh — build a Sphinx documentation tree#
Every project in this family builds its docs the same way: get a virtualenv with
the docs requirements, pull whatever the C++/Doxygen side generated into
_static, optionally run a diagram generator, then make html and
make linkcheck with warnings promoted to errors.
Not 02-toolchain/python/ci_build_docs.sh, which is the docs step for
pure-Python repositories (uv_sync_project over a pyproject, pytest/coverage
report staging, no linkcheck). This one is for projects whose docs sit next to a
C++/Rust build.
Variable |
Meaning |
Default |
|---|---|---|
|
project root |
cwd |
|
directory holding the Sphinx Makefile |
|
|
Sphinx source dir |
|
|
static asset dir |
|
|
virtualenv to activate |
|
|
script that creates the venv |
— |
|
script that installs its requirements |
— |
|
directory whose |
— |
|
Python script run with the source dir as cwd before Sphinx; empty skips |
— |
|
interpreter for that script |
|
|
|
|
|
array of make targets |
|
Both UV_* scripts run with the project root as cwd — the same contract as
code-quality.sh’s pair, and both defer to 01-core/python_uv.sh. Unlike that
pair, which falls back to the hub’s own bootstrap since 2026-09-15, both are
required here: an unset one is fatal.
A missing SVG is fatal on purpose. An empty diagram set means the generating build did not run, and shipping docs with holes in them is worse than failing here.
dartdoc-build.sh — theme and enrich a dart doc site#
The Dart/Flutter counterpart of docs-build.sh. dart doc has no theme and no
navigation hook, so the library works the only two seams it leaves: the
generated doc/api/static-assets/styles.css, and the emitted HTML.
The theme sheet is generated, never hand-written. DARTDOC_BUILD_THEME_CSS
points at style/dartdoc.css, which DocumANTation’s style/generate_style.py
renders from style/brand.json — the same single source of truth the LaTeX,
Pandoc and Sphinx consumers read. That file exists because the hand-written
predecessor had drifted onto a Tailwind slate/sky palette (#0284c7 links,
#22c55e hover) while the brand’s link colour was #0e7490, so one site in the
family rendered a different brand from every other. Its two marker lines are
load-bearing: dartdoc_build_apply_theme truncates a previous append at the
first line, so rebuilding cannot stack copies of the sheet.
dartdoc-guides.py next to it renders the configured Markdown into dartdoc’s
own index.html shell, so a guide page carries the same header, sidebars and
theme as an API page, and rewrites every relative *.md link onto the guide
page rendered from that file.
dartdoc emits TWO page shapes, and a third kind of file. Some pages carry a
static left sidebar with a bare <ol>; the rest carry
<div id="dartdoc-sidebar-left-content"></div>, filled at runtime from a
*-sidebar.html fragment — measured on one consumer, 1030 of 1459 pages were the
second kind. Those fragments are not documents at all: no <html, no </body>.
So the renderer skips a page it cannot hang navigation on and skips a fragment it
cannot attach a footer to, rather than aborting the run on the first one, and the
END of the run is where vacuity is caught instead: a run that navigated no page,
or that configured a footer and footered no page, fails. It prints both numbers
(navigated X/N and footered Y/N) so “it worked” is a measurement.
Variable |
Meaning |
Default |
|---|---|---|
|
project root |
cwd |
|
directory |
|
|
array run before generation; unset skips |
— |
|
array that generates the site |
|
|
generated brand sheet appended to dartdoc’s stylesheet |
— (required) |
|
directory copied to |
— |
|
array of |
— |
|
array of |
— |
|
bold name in front of those links |
— |
|
appended to each guide page’s |
— |
|
venv for the renderer |
|
|
its requirements file |
|
|
interpreter for the renderer |
the venv’s, created on demand |
A configured input that is missing is fatal. An absent
DARTDOC_BUILD_IMAGES_DIR, guide source or theme sheet fails the build instead
of being skipped: a docs site quietly missing its theme and half its pages is
worse than a build that stops and says so. The same rule governs the CI
ownership fix — the container writes doc/ as root over a bind mount, and a
chown that fails leaves a tree the host user cannot rebuild.
The rustdoc theme sheet#
02-toolchain/rust/cargo_build_doc.sh styles cargo doc output with the same
generated brand sheet the Sphinx and dartdoc builds use: DocumANTation’s
style/generate_style.py renders it from style/brand.json and ships it inside
the sphinx_kataglyphis package.
It did not always find it. Both probes that stood in that script named a hub path
that resolves to nothing — the hub’s own docs/_static/css/custom.css was dropped
in 28425115 (2026-07-15) as a stale fork of that very sheet, and the fallback
pointed one level short, at linux/docs/_static/, which has never existed in this
repository. The block therefore produced an empty EXT_CSS on every run and
rustdoc got no theme at all, silently.
The path is now resolved from SCRIPT_DIR rather than the working directory, so
it answers the same inside a consumer’s third_party/ANTfrastructure checkout —
which is the case the cwd-relative probe existed for in the first place.
Consumer entry points that are not libraries#
The things below are executables a consumer runs, not cores it sources. They
share one rule, and it is the rule the lint-secrets.sh and lint-workflows.sh
repairs were both about: the consumer repo root is an explicit argument, never
inferred from BASH_SOURCE. A consumer checks this repo out at
third_party/ANTfrastructure/, so a self-derived root resolves to ANTfrastructure and
the tool operates on the wrong tree — reporting green, having looked at nothing.
Gate aggregation (01-core/gates.sh)#
run_gate / gate_skip / assert_gates, the shell half of the fleet’s
“run every gate, then fail once” idiom (the PowerShell half is
Invoke-BuildGate / Add-BuildGateSkip / Assert-BuildGates in
WindowsBuild.Common.psm1).
source "${CORE_DIR}/gates.sh"
gate_reset "static analysis"
run_gate "ruff check" ruff check --no-fix src
run_gate "ty" ty check
if has_tool clang-tidy; then
run_gate "clang-tidy" clang-tidy src
else
gate_skip "clang-tidy" "not installed in this image"
fi
assert_gates # 0 when all passed; 1 naming every failure or skip
Every gate RUNS even after an earlier one fails, so one push names every finding
instead of one per round trip. run_gate returns 0 for a failing gate — that
is deliberate and it is only safe because assert_gates re-raises: a run_gate
batch with no closing assert_gates is suppression, not aggregation. It is
compatible with set -e (the command runs inside a || list). assert_gates
also fails when no gate ran, because an aggregator whose list came out empty
reporting success is the failure this mechanism exists to prevent.
The third bucket: a gate that could not RUN#
A gate can also be neither a pass nor a failure: its tool is not installed. Both
ways of forcing that into the other two buckets are lies — counted as a pass it
is the suppression this file exists to prevent, counted as a failure it is a red
nobody can act on — so gate_skip <name> [why] records it as its own thing. The
reason is part of the record on purpose: “skipped” without one reads exactly like
a gate somebody quietly deleted.
Bucket |
Recorded by |
Counts as “a gate ran”? |
Verdict |
|---|---|---|---|
pass |
|
yes |
green |
failure |
|
yes |
red, and named |
skip |
|
no |
red, unless |
A skip is RED BY DEFAULT, and that default is the inverse of the first cut.
The earlier spelling was assert_gates --fail-on-skip: tolerance was what you
got for free and strictness was the thing you had to remember, which is exactly
the “allowed to fail” shape the fleet rule forbids. A driver that forgot the flag
reported green over a tool that never ran, and nothing in the tree recorded which
drivers those were. Inverted, tolerance is an explicit --tolerate-skips at a
call site, so one grep -rn -- --tolerate-skips enumerates every place in the
fleet where a missing tool is currently allowed to pass and the audit is finite.
assert_gates returns 2 for any other argument, so a stale --fail-on-skip
is a caller bug rather than a silently re-armed default.
A skip does not count towards _GATE_RAN, so a batch of nothing but skips is
red even with --tolerate-skips: nothing was graded, so there is no result to
tolerate. That is the no-gate-ran rule above, and it outranks the flag — as does
a real failure sharing the batch.
run_gate runs its command in a SUBSHELL#
( "$@" ), not a bare "$@". Upstream check helpers report failure with err()
(01-core/logging.sh), which ends in exit 1. Called directly that exit
unwinds the driver, not just the gate: the findings already recorded are lost,
the gates after it never run, and the batch never reaches assert_gates — “stop
at the first failure” arriving through the back door, in the one file whose whole
job is to prevent it. || does not catch exit; only a subshell does. The cost
is that a gate can no longer export state back to the driver, which no caller
wanted. linux/scripts/tests/test-lint-gates.sh grades this by running one
driver against the shipped file and against a copy with the subshell removed: the
copy has to die mid-batch, or the shipped file passing proves nothing.
Windows parity, and the one place the halves differ#
The third bucket is mirrored exactly — Add-BuildGateSkip -Context -Name [-Reason] and Assert-BuildGates [-TolerateSkips], where a [switch] is false
unless passed, so the inverted default is the same fact on both halves.
The subshell is not mirrored, and that was measured rather than assumed:
exit inside a gate scriptblock terminates the whole PowerShell driver through
both & $Script and $Script.Invoke(), and the only containment left is a child
runspace, which breaks the closures a gate scriptblock is written with. The
hazard also does not arise there for the reason it does in bash.
Invoke-BuildGate’s contract is that a gate fails by throwing, or by a
non-zero exit propagated through Invoke-BuildExternal, and its try/catch
already contains both; PowerShell has no equivalent of the fleet-wide err()
helper that makes exit the normal way to report a failure.
windows/scripts/tests/BuildGates.ThirdBucket.Tests.ps1 pins both halves of that
paragraph, the child-pwsh measurement included, so the day PowerShell contains
an exit this section goes red instead of quietly aging into a false claim.
Tool presence (01-core/tool-checks.sh)#
has_tool <cmd> and require_tools <cmd>..., the latter naming every missing
tool rather than the first. Each is defined only when the caller has not already
defined it, so a project common.sh still wins — that conditional shape is what
the inline fallbacks in lib/code-quality.sh and lib/coverage.sh were, and
those two now source this instead of carrying a copy each.
Python interpreter probe (01-core/python-probe.sh)#
preflight_python_require <caller> returns 0 with PREFLIGHT_PYTHON exported
when that value (or, unset, python3) runs -c pass, and 1 naming the caller
and the knob otherwise. Plain python3 is not trusted because on Windows Git
Bash it is the Microsoft Store stub, which prints an install hint and exits
non-zero. preflight.sh probes a candidate list and exports the winner; a gate
run standalone inherits nothing, so lint-workflows.sh and run-lint-gates.sh
call this before their Python steps instead of each carrying the check inline,
which is where the second copy sat until 2026-09-14. lint-python.sh and this
repo’s own pre-commit/pre-push hooks joined them on 2026-09-15. Expand the value
unquoted, as preflight.sh does: it may be a command line such as
uv run --no-project python, the very hint the failure message gives.
run-in-ci-image.sh — run a command in the CI image#
bash third_party/ANTfrastructure/linux/scripts/run-in-ci-image.sh . -- bash scripts/linux/build.sh
<repo-root> [--engine docker|nerdctl] [--platform ...] [--workdir ...] [--mount-hub-scripts] [--name N] [--keep] -- <command...>.
Every consumer README, every “reproducing CI locally” section and half the agent
prompts carried the same hand-typed docker run, and they had all drifted: a
different tag, a forgotten MSYS_NO_PATHCONV, a mount at a different path, no
safe.directory. This is that line once. The image comes from
ci-image-ref.sh, the root is mounted at /workspace and registered as a git
safe.directory before the command runs (without it every git ls-files inside
fails as “dubious ownership”, which breaks a format gate long before anything
builds), and the engine defaults to nerdctl when present, else docker — the
local box runs Rancher Desktop and CI runs docker, and neither should have to
say so.
MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*' are exported by the script rather
than documented for the reader: from Git Bash, MSYS rewrites anything that looks
like a POSIX path into a Windows one, destroys every -v/-w argument, and
fails with “expected an absolute path”. A note nobody reads is how that keeps
being rediscovered.
CI workflow steps keep using the run-in-linux-container composite action; this
is for everything that is not a workflow step.
ci-image-ref.sh — the family CI image reference#
Prints ${IMAGE_REGISTRY_PREFIX}:${CI_IMAGE_LINUX_TAG} (or …_WINDOWS_TAG with
--windows, …_WINDOWS_ARM64_TAG with --windows-arm64 for the arm64 cross
bundle) on stdout and nothing else, so it is safe in a command substitution.
docker run --rm -v "$PWD:/workspace" -w /workspace \
"$(third_party/ANTfrastructure/linux/scripts/ci-image-ref.sh)" <cmd>
Workflow steps do not need it: the four container composite actions carry the
same value as their image: input default. It is for the callers that cannot omit
an input because they are not calling an action — a raw docker run, a local
repro, a lane driver. It is the one entry point here that takes no consumer
root, because the only file it reads is this repo’s versions.env whatever tree
is being built; a root parameter would imply a per-consumer answer and there is
none. Its PowerShell twin is Get-CiImageReference
(WindowsContainerImage.Common.psm1). tests/test-ci-image-ref.sh holds the
script to the same strings as verify_ci_image_refs.py, which grades the four
action defaults (and the Windows pair’s image-arm64);
ContainerImage.CiRef.Tests.ps1 holds the twin to versions.env.
The empty-scope rule#
_lint_gates_scope builds a gate’s file list from git ls-files under the graded
root, minus the excluded top-level directories. Its third argument decides what an
empty result means, and the two callers genuinely differ:
Mode |
Meaning |
Who uses it |
|---|---|---|
|
a BROKEN SCOPE. |
the shell gate |
|
a FACT about the repo. |
the python gate |
The python gate can allow it because it passes explicit absolute paths: with no
paths there is no argument list to fall back from, so there is nothing to run and
nothing to mis-grade. That distinction is not cosmetic — ANThology is a pure Dart
package and OxidANT a Rust crate, neither has a single .py, and refusing an empty
Python scope made both lanes exit 1 on every push for a reason nothing in either tree
could change. A permanently red lane is a tolerated failure by construction.
run-lint-gates.sh — six gates over a consumer tree, plus the opt-in ratchets#
bash third_party/ANTfrastructure/linux/scripts/run-lint-gates.sh "$PWD"
bash third_party/ANTfrastructure/linux/scripts/run-lint-gates.sh "$PWD" --exclude vendor
shellcheck, actionlint (+ the CI image-ref check), gitleaks, ruff (error tier),
the shared-config drift check and the consumer pin-forwarding check, in one
command, every gate running even after one fails. Three consumers had grown their own copy
— two of them as run: blocks inside a workflow, so the gate blocking their
deploy could not be reproduced locally at all.
What the copies carried and this keeps: the git ls-files scope (a **/*.sh
glob does not recurse without globstar, so it graded the directories somebody
remembered), the empty-list guards (lint-shell.sh with zero file arguments
falls back to ANTfrastructure’s own tree and exits 0), and the gitleaks
self-test — a clean-tree positive control plus a planted-PAT canary matched by
path, which is what tells “the gate ran and found nothing” from “the gate never
started” and proves the scan root was honoured.
--exclude <dir> (default third_party) drops a vendored top-level directory
from every scope while KEEPING the tracked plain files directly inside it: those
are the consumer’s own, and dropping the whole prefix excluded them silently.
The pin preconditions the copies carried (“does the pinned lint-secrets.sh
understand a scan root yet?”) are gone by construction: this script ships in the
same commit as the gates it calls.
--ratchets (opt-in, 2026-09-14) adds the eight measurement gates that take
--root — verify_code_size, verify_code_complexity, verify_dead_functions,
verify_comment_size, verify_stdout_returns, verify_masked_assignments,
verify_trailing_conditional and verify_shellcheck_warnings — over the
consumer tree, exactly as the scan-root contract
describes: the freeze files are read from <consumer-root>/<gate>.allow
(function-size.allow, file-size.allow, code-complexity.allow,
dead-functions.allow, comment-size.allow, masked-assignments.allow,
trailing-conditional.allow, shellcheck-warnings.allow; verify_stdout_returns
has none). It is opt-in because a tree with no freeze files is red on its first
run — that first report is what seeds them. Seed, commit, then keep the flag on
in the wrapper and the workflow.
The step also runs docs/scripts/verify_doc_links.py --root (2026-09-15),
which is the ninth gate and the odd one out: it has no freeze file, so there is
nothing to seed and it is safe the very first time the flag goes on. It grades
every tracked Markdown page in the consumer — which is what puts a consumer’s
own README.md into the cross-reference graph at all — and it runs even when
the tree carries no shell, because a Dart or Python repo still has pages.
A consumer with no tracked shell at all — a pure Dart or Python repo — may
still pass the flag: the step asks gate_scope.assert_non_empty once with
on_empty="allow", prints ratchets: no tracked *.sh outside third_party under <root> - nothing to grade. and returns green. That decision belongs to the
aggregator, not to the gates: rule 2 of the scan-root contract says an empty scan
is a decision and never a default, and who pointed the gate at this tree is the
only thing that knows which answer is right. Pointed at a tree by hand, a gate
still refuses. A root that is not a usable checkout fails the step outright, with
gate_scope’s own message.
The Python gates run under PREFLIGHT_PYTHON when it is set (the same contract
preflight.sh and lint-workflows.sh document) and probe the interpreter first:
on a Windows host plain python3 is the Microsoft Store stub, and the probe
names the fix instead of letting a gate die inside its Python step.
05-frameworks/flutter/setup-sqlite3-wasm.sh#
Fetches the pinned sqlite3.wasm into <consumer-root>/web/, SHA256-verified
through download_verified_file. Two consumers had copied the same unverified
curl and had already drifted to different versions; the version and its digest
now live in 01-core/versions.env (SQLITE3_WASM_VERSION /
SQLITE3_WASM_SHA256). There is deliberately no version argument — the pin is
the point.
05-frameworks/flutter/lane-prologue.sh#
flutter_lane_prepare_env [flutter_dir] is the Flutter twin of
cmake-build.sh’s cmake_build_prepare_env, and exists for the same reason:
two consumers had each grown their own prologue, they had drifted, and the
differences were all work the IMAGE already does.
It asserts ${FLUTTER_DIR:-/opt/flutter}/bin/flutter, puts its bin/ on PATH
once, registers a git safe.directory for the repo root only, defaults
PUB_CACHE to <repo>/.pub-cache, and prints flutter --version — the tag is
unpinned, so the version is a measurement rather than a constant.
Because that cache lands inside the repository, a consumer that also runs a
tree-walking gate must keep it out of the walk: every dependency ships its own
example/ sources, and a gate that grades them fails on code the repository
neither owns nor can format. OmniAccelerANT measured 28 such CMake files —
fl_chart’s example/linux/CMakeLists.txt among them — after one pub get.
code_quality_find_cmake_files therefore excludes */.pub-cache/* by default
(CODE_QUALITY_CMAKE_DEFAULT_EXCLUDES, added to whatever
CODE_QUALITY_CMAKE_EXCLUDE_PATHS a consumer sets, never replacing it): the hub
created the directory, so the hub excludes it. Any OTHER tree-walking gate a
consumer runs — clang-format, a licence sweep, a secret scan over sources — has
to exclude it in that gate’s own list.
Three things it does not do, and must not gain: a safe.directory for the SDK
(setup-package-image.sh:556 registers /opt/flutter at --system level, so a
--global copy is a no-op that reads like a requirement), sourcing ~/.bashrc
to find flutter (Dockerfile.package’s ENV PATH already carries it, and a stock
non-interactive .bashrc returns early with a meaningless status while hiding a
broken rc file), and installing an SDK — a lane that installs one is testing a
different toolchain from the one it ships.
flutter_build_web [--wasm] [--no-tree-shake-icons] [args...] is the optional
second half: flutter build web --release with the two flags every consumer
passes named rather than re-spelled, everything else forwarded untouched.
01-core/webdav-download.sh#
webdav_download_tree <remote> <local> [extension|all] pulls a WebDAV tree into
a directory. Credentials come from WEBDAV_HOSTNAME / WEBDAV_USERNAME /
WEBDAV_PASSWORD and are never arguments — a password on a command line is in
every ps listing and in every CI log line that echoes the command.
It installs the client at WEBDAVCLIENT_REF from
01-core/versions.env, which is the
point of the pin: the PowerShell twin (WindowsWebDav.Common.psm1) installs the
same ref, so “which WebDavClient did this run use” has one answer instead of
“whatever the default branch was that day”. The --python in the install is
load-bearing — the image bakes a root-owned /opt/venv and exports UV_PYTHON
at it, so a plain uv pip install inside an activated .venv still targets
/opt/venv and dies with “Permission denied (os error 13)” as the uid-1001
build user.
The script it runs is 01-core/download-webdav-files.py. With no --extension
(or all) it hands the whole walk to the client’s own
download_all_files_iterative; a 140-line hand-rolled traversal used to live in
its place, with its own URL joining, sub-path sanitising and streaming download,
each a second implementation of something the client already did. The
extension-filtered path stays for the early .pfx certificate fetch, which
genuinely wants one file type out of a shared folder. A one-line shim remains at
windows/scripts/certificates/download_webdav_files.py, because the PowerShell
module resolves that path relative to itself.
01-core/http-readiness.sh#
wait_for_http <url> <who> [attempts] [sleep] polls until an endpoint answers.
Three consumers had written this loop and every difference between them was an
accident — attempt count, sleep length, and the one that matters: whether
failure kills the caller. It returns non-zero rather than exiting, because
the nginx caller has to dump docker logs before it dies and a helper that
calls exit takes that away. Probes that fail while the server is still
starting are the expected case and stay silent; only the verdict is printed, and
it names who — a bare URL never told anyone which server failed to come up.
Defaults are 50 attempts at 0.2s, the ten seconds the consumers converged on.
01-core/bind-mount-ownership.sh#
fix_bind_mount_ownership <target> <reference> hands a tree a container wrote
back to whoever owns the bind mount. <reference> is a path the host user owns
— normally the workspace root — and its uid:gid is what <target> is handed
back to; nothing takes a uid as an argument, because a number typed at a call
site is the thing that goes stale.
The three decisions around the chown are the whole reason this is shared:
Only the paths that actually differ, never a blanket
chown -R. On a tree that is mostly already correct, recursing over it asks the kernel for a chown it refuses for a non-owner and turns a no-op into an error.-hso a symlink is retargeted rather than its destination, which may be outside the tree.A failure as a non-root uid is explained and tolerated. Giving a file to a different uid needs
CAP_CHOWN; as an unprivileged container user that is arithmetic, not a defect, and it was measured red on a Windows host with nothing an operator could do about it.The same failure as root is fatal. There it means a read-only or broken mount, and the tree really is left in the state this step exists to prevent.
A missing <target> is not an error: a docs step that produced nothing has
nothing to hand back. lib/dartdoc-build.sh’s dartdoc_build_fix_ownership is
the older blanket chown -R form over one fixed tree and predates this;
tests/test-bind-mount-ownership.sh pins all three decisions.