tools/cl: builds through CL_LAUNCHER, test binaries and renders through CL_RUNNER

cl test builds with cargo test --no-run and runs each test binary itself, as
cargo would, through CL_RUNNER. A wrapper that limits how many test binaries
run at once then holds its limit only for the run; held for the build, it
queued every build behind the slowest one while the job pool already shares
the cores between builds.
This commit is contained in:
aiongg
2026-11-12 14:32:42 +00:00
parent 4c80ffcd7a
commit a12625ddfc
2 changed files with 80 additions and 13 deletions
+4 -2
View File
@@ -9,8 +9,8 @@ How to build, test and look at this workspace without waiting for it. The rules
| What | Command | Builds |
|---|---|---|
| check the crate you changed | `cl check <crate>` | `cargo check` of the crate's lib, bins and tests |
| build its tests | `cl test <crate> --no-run` | `cargo test -p <crate> --tests` |
| run some trials | `cl test <crate> -- <filter> --test-threads 4` | nothing new when warm |
| build its tests | `cl test <crate> --no-run` | `cargo test -p <crate> --tests --no-run`; prints each test binary's path |
| run some trials | `cl test <crate> -- <filter> --test-threads 4` | nothing new when warm; then runs each test binary with the filter |
| the debug gallery | `cl build gallery` | the `craft-ui-gallery` binary only |
| one component's stories as PNGs | `cl render <crate\|ui> <Component> [--story <name>] [--out <dir>]` | the `story-render` binary with that crate's feature |
| anything else | `cl cargo <args>` | what you asked for, through the job pool, nothing added |
@@ -60,6 +60,8 @@ Frame-time numbers come from the gallery profile, the build the owner runs: `cl
cargo gives each build a jobserver with one token per core, so a build alone uses the whole machine, but several builds at once (worktrees, agents) each take every core and slow each other down. To share one job pool between them, set `CL_LAUNCHER` to a command that runs its arguments with a shared jobserver in `MAKEFLAGS` (cargo joins a jobserver it finds there). `cl` runs every cargo command through that command; without `CL_LAUNCHER` it runs cargo directly.
Test binaries take no tokens: each starts its own test threads, and screen tests a software renderer's threads as well. `cl test` therefore builds with `cargo test --no-run` through `CL_LAUNCHER` and then runs each test binary itself, as cargo would (from its package's directory, the lib's unit tests first, stopping at the first that fails), through `CL_RUNNER` when it is set: a command that limits how many test binaries run at once. `cl render` runs the story renderer through `CL_RUNNER` too. Keep the two apart: a limit held for a whole build only queues the builds behind it, and the job pool already shares the cores between builds.
## A new worktree's first build
A new target directory builds the dependencies once (about 240 crates, 2–3 minutes with 16 cores) and then the framework for the first crate you work on (contract, widgets, panels, canvas, patterns, shell: another 1–2 minutes). After that, a one-line edit in a framework crate rebuilds that crate (seconds) and its test binary; a domain crate's test binary after a framework edit takes about 25 s (the chain above the edit at opt-level 0).
+76 -11
View File
@@ -2,7 +2,7 @@
"""The craft-libs build loop: cargo with one resolution of features, so every local build shares one build of each crate.
cl check <crate> [cargo args] cargo check of the crate's lib, bins and tests
cl test <crate> [cargo args] [-- test args] cargo test -p <crate> --tests
cl test <crate> [cargo args] [-- test args] build the crate's tests (cargo test --no-run), then run each test binary
cl build gallery [cargo args] the debug gallery binary (target/debug/craft-ui-gallery)
cl build <crate> [cargo args] cargo build of the crate's lib and bins
cl render <crate|ui> <Component> [--card] [--story <name>] [--out <dir>] [--threads N]
@@ -12,8 +12,10 @@
cl cargo <args...> cargo through the job pool, nothing added
Every cargo command runs through the command in CL_LAUNCHER when it is set (for example a wrapper that gives several
builds on one machine a shared jobserver; docs/development.md "The job pool"), else plain cargo. CARGO_TARGET_DIR
defaults to <worktree>-target when that directory exists beside the worktree.
builds on one machine a shared jobserver; docs/development.md "The job pool"), else plain cargo. The binaries cl runs
after a build (test binaries, the story renderer) run through the command in CL_RUNNER when it is set (for example a
wrapper that limits how many run at once), else directly; a test binary runs from its package's directory, as cargo
runs it. CARGO_TARGET_DIR defaults to <worktree>-target when that directory exists beside the worktree.
Why one resolution: cargo builds a crate once per distinct feature set, and everything above it again, and it unifies
features only over the packages a command selects. A framework crate's tests, a domain crate's tests, the gallery and
@@ -210,24 +212,86 @@ def report_new_variants(before, after):
file=sys.stderr)
def run(top, cargo_args, then=None):
"""Runs cargo through the launcher and reports new framework builds; `then` (a command) runs after a successful
cargo, through the launcher too. Exits with the last return code."""
def cargo(top, cargo_args, json_out=False):
"""Runs cargo through CL_LAUNCHER and reports new framework builds. Returns (return code, target dir, the JSON
messages cargo printed on stdout when `json_out`)."""
# cargo fmt builds nothing, so its `--all` is the usual whole-workspace format.
for arg in ([] if cargo_args[:1] == ["fmt"] else cargo_args):
if arg in REFUSED:
fail(f"{arg} refused: {REFUSED[arg]}")
env = dict(os.environ)
target = target_dir(top, env)
launcher = shlex.split(env.get("CL_LAUNCHER", ""))
cmd = launcher + ["cargo"] + cargo_args
cmd = shlex.split(env.get("CL_LAUNCHER", "")) + ["cargo"] + cargo_args
print("cl: " + " ".join(cmd) + f" (target {target})", file=sys.stderr)
sys.stdout.flush()
before = variants(target)
rc = subprocess.run(cmd, cwd=top, env=env).returncode
messages = []
if json_out:
proc = subprocess.Popen(cmd, cwd=top, env=env, stdout=subprocess.PIPE, text=True)
for line in proc.stdout:
try:
messages.append(json.loads(line))
except ValueError:
sys.stdout.write(line)
rc = proc.wait()
else:
rc = subprocess.run(cmd, cwd=top, env=env).returncode
report_new_variants(before, variants(target))
return rc, target, messages
def run_binary(cmd, cwd, env=None):
"""Runs a built binary through CL_RUNNER."""
sys.stdout.flush()
return subprocess.run(shlex.split(os.environ.get("CL_RUNNER", "")) + cmd, cwd=cwd, env=env).returncode
def shown(path, top):
"""A path as cargo shows it: relative to the worktree when inside it."""
return os.path.relpath(path, top) if path.startswith(top + os.sep) else path
def test(top, packages, cargo_args, test_args):
"""Builds the tests with `cargo test --no-run`, then runs each test binary as cargo would: from its package's
directory, the lib's unit tests first, stopping at the first that fails."""
no_run = "--no-run" in cargo_args
quiet = "-q" in cargo_args or "--quiet" in cargo_args
cargo_args = [a for a in cargo_args if a != "--no-run"]
rc, target, messages = cargo(top, cargo_args[:1] + ["--no-run", "--message-format=json-render-diagnostics"] + cargo_args[1:], json_out=True)
if rc != 0:
sys.exit(rc)
by_manifest = {p["manifest_path"]: p for p in packages.values()}
tests = []
for m in messages:
if m.get("reason") != "compiler-artifact" or not m.get("executable") or not m["profile"]["test"]:
continue
root = os.path.dirname(m["manifest_path"])
source = os.path.relpath(m["target"]["src_path"], root)
lib = any(k in ("lib", "rlib", "proc-macro") for k in m["target"]["kind"])
tests.append((not lib, m["target"]["name"], "unittests " + source if lib else source, m["executable"], m["manifest_path"]))
tests.sort()
for _, _, source, exe, manifest in tests:
print(f"{'Executable':>12} {source} ({shown(exe, top)})", file=sys.stderr)
if no_run:
sys.exit(0)
for _, _, source, exe, manifest in tests:
if not quiet:
print(f"{'Running':>12} {source} ({shown(exe, top)})", file=sys.stderr)
package = by_manifest.get(manifest, {})
env = dict(os.environ, CARGO_MANIFEST_DIR=os.path.dirname(manifest), CARGO_PKG_NAME=package.get("name", ""))
rc = run_binary([exe] + test_args + (["--quiet"] if quiet else []), os.path.dirname(manifest), env)
if rc != 0:
print(f"cl: test failed: {source} ({shown(exe, top)}) exited with {rc}", file=sys.stderr)
sys.exit(rc)
sys.exit(0)
def run(top, cargo_args, then=None):
"""Runs cargo; `then` (a binary in the target's debug dir and its arguments) runs after a successful cargo. Exits
with the last return code."""
rc, target, _ = cargo(top, cargo_args)
if rc == 0 and then:
rc = subprocess.run(launcher + [os.path.join(target, "debug", then[0])] + then[1:], cwd=top, env=env).returncode
rc = run_binary([os.path.join(target, "debug", then[0])] + then[1:], top)
sys.exit(rc)
@@ -266,7 +330,8 @@ def main():
if command == "check":
run(top, with_features(["check"] + selected(pkg) + ["--tests"] + own_targets(packages[pkg]), features) + args)
if command == "test":
run(top, with_features(["test"] + selected(pkg) + ["--tests"], features) + args)
mine, theirs = (args[:args.index("--")], args[args.index("--") + 1:]) if "--" in args else (args, [])
test(top, packages, with_features(["test"] + selected(pkg) + ["--tests"], features) + mine, theirs)
run(top, with_features(["build"] + selected(pkg) + own_targets(packages[pkg]), features) + args)
if command == "render":
if len(rest) < 2: