Skip to content
Merged
16 changes: 16 additions & 0 deletions bench/profile.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import signal
import struct
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
Expand Down Expand Up @@ -171,13 +172,27 @@ def test_profile_rejects_invalid_selection_before_building(self):
self.assertEqual(result.returncode, 1, result.stdout)
self.assertIn(diagnostic, result.stderr)

@unittest.skipIf(sys.platform == "linux", "Linux can profile")
def test_profile_refuses_off_linux_before_evidence(self):
root = Path(__file__).resolve().parent.parent
result = subprocess.run(
["bash", str(root / "bench/run.sh"), "--profile"],
env=dict(os.environ, BENCH_PROFILE_MODES="cpu"),
capture_output=True,
text=True,
)
self.assertEqual(result.returncode, 1, result.stdout)
self.assertEqual(result.stderr, "relay profiling needs Linux for perf and /proc\n")
self.assertNotIn("Benchmark evidence", result.stdout)


FIXTURE = Path(__file__).with_name("profile.test.txt").read_text()
IDLE, MUTEX, ALLOCATOR = "2152705", "2152709", "2152707"
# Every fixture wait closes, so the window end only has to follow the last event.
END = 271707 * 1_000_000_000


@unittest.skipUnless(sys.platform == "linux", "relay profiling needs Linux for perf and /proc")
class Orchestration(unittest.TestCase):
def harness(self, directory, sampler_binary):
"""A checkout whose committed revision has the old harness and, when
Expand Down Expand Up @@ -493,6 +508,7 @@ def test_lost_samples_refused(self):


class Heap(unittest.TestCase):
@unittest.skipUnless(sys.platform == "linux", "reads /proc")
def test_usr1_handler_detected(self):
previous = signal.signal(signal.SIGUSR1, signal.SIG_DFL)
try:
Expand Down
9 changes: 5 additions & 4 deletions bench/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,11 @@ case $MODE in
exit 1
fi
done
# Refuse at setup, after validating the selection but before creating evidence.
if [[ $(uname -s) != Linux ]]; then
printf 'relay profiling needs Linux for perf and /proc\n' >&2
exit 1
fi
# Without frame pointers, perf's DWARF unwinder stops at the first relay frame,
# and CPU stacks unwind by frame pointer alone.
export RUSTFLAGS="${RUSTFLAGS:+$RUSTFLAGS }-C force-frame-pointers=yes"
Expand Down Expand Up @@ -965,10 +970,6 @@ run_shard_sweep() {
}

run_profiles() {
if [[ $(uname -s) != Linux ]]; then
printf 'relay profiling needs Linux for perf and /proc\n' >&2
return 1
fi
# Refuse before the build when the host would refuse a capture.
local mode
for mode in $PROFILE_MODES; do
Expand Down
7 changes: 7 additions & 0 deletions demo/carla/bridge/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,13 @@
//! The worker protocol is [`protocol`].
//!
//! Linux only; the crate is empty elsewhere.
#![cfg_attr(
not(target_os = "linux"),
allow(
rustdoc::broken_intra_doc_links,
reason = "the items these docs link to are Linux-only"
)
)]
#![cfg(target_os = "linux")]

mod ffi;
Expand Down
5 changes: 4 additions & 1 deletion doc/.vitepress/api/index.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Renders the JS API reference from the TSDoc in every published `@moq/*` package's source:
// one TypeDoc run over all of them, written as VitePress markdown with a sidebar.
import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
import { dirname, join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { Application, type Reflection, type ReflectionGroup, ReflectionKind, type TypeDocOptions } from "typedoc";
Expand All @@ -23,6 +23,9 @@ export interface Reference {

/** Render the reference, throwing on any TypeDoc warning, such as an unresolved link or an unexported type an export names. */
export async function generate({ root, packages, out, docs }: Reference) {
// TypeScript reports sources by real path, so compare against real paths, such as macOS's `/var` -> `/private/var`.
root = realpathSync(root);
packages = packages.map((dir) => realpathSync(dir));
const plugin = (name: string) => fileURLToPath(import.meta.resolve(name));
// typedoc-vitepress-theme declares `docsRoot` without typing it.
const options: TypeDocOptions & PluginOptions & { docsRoot: string } = {
Expand Down
4 changes: 2 additions & 2 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,8 @@
cargo-mutants
cargo-nextest
cargo-codspeed
# Sets versions for a release cut; `sh/version.py` needs 0.4.1 or newer.
release-plz
# Source-based test coverage (`just rs coverage`).
# Its LLVM test helpers must read the compiler's profile format.
(cargo-llvm-cov.override {
Expand All @@ -175,8 +177,6 @@
]
++ gstreamerDeps
++ pkgs.lib.optionals (!pkgs.stdenv.hostPlatform.isDarwin) [
# Marked broken on Darwin in nixpkgs, but builds fine on Linux.
pkgs.release-plz
# cpal's `alsa-sys` (moq-audio `capture` / `playback` features) links
# libasound on Linux via pkg-config; macOS uses CoreAudio, so no dep
# there. See `alsaPlugins` below for reaching the default device at
Expand Down
2 changes: 1 addition & 1 deletion quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ edge, which embeds moq-relay; it moved there on 2026-09-28.
- [Publish the release line's drain() wrappers](/quest/m0/ffi-shutdown-backport.md) - Dart `moq` 0.1.1 reaches pub.dev from `release`
- [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in GitHub's merge queue, one tested entry at a time, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last
- [More tests under load](/quest/m0/test-flakes-2/README.md) - load-only and queue failures, one quest per flake, fixed at the cause, since each one drops a queued PR
- [just check passes on macOS](/quest/m0/macos-check.md) - the version test, the doc re-export link test, and the carla bridge docs pass on a macOS host
- [just check passes on macOS](/quest/m0/macos-check.md) - `check cpp` and `check py`, the last two macOS failures, pass on a macOS host
- [Agent build output can't fill the desktop's disk](/quest/m0/agent-disk-budget.md) - finished agent checkouts reclaim their mbx targets automatically, so parallel agent builds stop filling the root disk
- [MoQ builds against rind 0.4 and its corrected adapters](/quest/m0/rind-adapters.md) - the calls rind 0.4 and its adapter patch releases change, adapted the day they publish
- [moq-transport stops sending our max age as MAX_CACHE_DURATION](/quest/m0/ietf-max-age.md) - a late joiner reads the newest catalog through any draft-18 relay, fixing the regression from moq-dev/moq#7729 before the cut ships it
69 changes: 28 additions & 41 deletions quest/m0/macos-check.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,53 +3,40 @@
## Goal

`just check` on a clean `main` checkout passes on a macOS host inside the Nix
dev shell, as it already does on Linux. Three failures block it today, all
reproduced on `origin/main` by
[moq-dev/moq#8392](https://github.com/moq-dev/moq/pull/8392) and
[moq-dev/moq#8394](https://github.com/moq-dev/moq/pull/8394):

- `test gh`: `sh/version.test.py`'s
`test_cut_promotes_only_published_library_dependencies_and_preserves_exemptions`
(`'0.0.1' != '0.22.0'`) and `test_release_plz_keeps_manual_cut_despite_breaking_commits`,
with release-plz 0.3.149.
- `check js`: `doc/.vitepress/api/index.test.ts`, "a re-export from another
workspace package links to its owner"; the rendered link holds
`/private/var/folders/...`.
- `check rs`: `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p moq-carla-bridge`
reports unresolved links to `Bridge`, `Source`, and `protocol`.
dev shell, as it already does on Linux.
[moq-dev/moq#8426](https://github.com/moq-dev/moq/pull/8426) fixed the
failures in scripts, tests, and Linux-only crate docs; two remain, both seen
on the maintainer's aarch64-darwin host on 2026-11-10 with
`quest gate nix develop --command just check` selecting the whole tree:

- `check cpp`: the build stops at
`clang++: error: -Wl,-lintl: 'linker' input unused [-Werror,-Wunused-command-line-argument]`,
after the `probe` builds pass, in a CMake build under
`cpp/moq/build/test-*` whose compiler is the mbx `clang++` shim.
- `check py`: Sphinx, which treats warnings as errors, stops with
`py/moq-rs/docs/index.md:147: WARNING: autosummary: stub file not found 'moq.media.catalog'. Check your autosummary_generate setting.`

Non-goal: a macOS runner on the PR gate (rejected in
[macos.md](/quest/m0/nightly/macos.md)).

## Plan

Planned 2026-11-09 (maintainer, /quest-complete follow-up of #8392 and #8394).
Milestone: ✅ m0 (rejected: a later milestone).

Causes, read from source on Linux (no macOS host was available):

- carla bridge, **confirmed**: `demo/carla/bridge/src/lib.rs` puts
`#![cfg(target_os = "linux")]` after its `//!` docs, so on macOS the crate is
empty and the intra-doc links dangle. Either gate the links too or build the
crate (and its docs) only on Linux, e.g. by keeping it out of the macOS doc
selection.
- doc re-export link, **guess**: `tmpdir()` is `/var/folders/...` on macOS,
a symlink to `/private/var/...`. `index.ts` computes package paths with
`relative(root, dir)`; if one side is resolved through the symlink (by
TypeScript or the workspace scan) and the other is not, the link becomes a
`../../private/var/...` path. Confirm by checking which side resolves, then
realpath both sides in `index.ts` (production paths can be symlinked too),
not only in the test.
- `sh/version.test.py`, **guess**: the Linux dev shell provides release-plz
0.4.1 (`pkgs.release-plz` in `flake.nix`), while the failing host ran
0.3.149, so it likely picked up a non-Nix `release-plz` (e.g. from
`~/.cargo/bin`) ahead of the dev shell. The flake uses one nixpkgs for both
systems, so a different darwin build is less likely. If it is PATH, the
test should fail loud on a release-plz older than it supports instead of
asserting wrong versions; if the dev shell's darwin release-plz really is
0.3.149, align it.

Verify each fix on a macOS host (a maintainer machine or a manual Platform
dispatch), and on Linux.
Milestone: ✅ m0 (rejected: a later milestone). Narrowed 2026-11-10
(maintainer): ✅ land #8426 and keep this quest for what remains (rejected:
widen #8426 again).

Causes are not yet diagnosed:

- `check cpp`: `-lintl` is gettext's library, which the Nix darwin stdenv
adds to link flags; it likely reaches a compile-only clang++ step through
`NIX_LDFLAGS` or the CMake flags `cpp/` passes. Find which step gets it and
keep link flags off compile steps rather than dropping `-Werror`.
- `check py`: check whether `moq.media.catalog` exists in the built module on
macOS (a cfg-gated or feature-gated binding would explain a missing stub),
then align the docs index with what the module exports there.

Verify on a macOS host (a maintainer machine or a manual Platform dispatch),
and on Linux.

Public API: none. Wire: none.
5 changes: 2 additions & 3 deletions quest/m1/carla-workspace.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ The bridge is the root `Cargo.toml`'s first `members` entry. Give it its own
workspace and lock file, keep its check in the dispatch for `demo/carla/**`
changes, and keep the files where they are: moq.pro reads
`demo/carla/sim/trucks.json` from its pin. Check the GPU end-to-end test in
[vendor-free CARLA bridge](/quest/m5/carla-bridge.md) and
[macOS check](/quest/m0/macos-check.md), which touch the bridge, still find
it.
[vendor-free CARLA bridge](/quest/m5/carla-bridge.md), which touches the
bridge, still finds it.

Public API: none. Wire: none.
7 changes: 7 additions & 0 deletions rs/moq-vaapi/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,13 @@
)]
// VA-API and DMA-BUF are Linux-only, so elsewhere the crate is an empty stub and
// moq-video only depends on it there.
#![cfg_attr(
not(target_os = "linux"),
allow(
rustdoc::broken_intra_doc_links,
reason = "the items these docs link to are Linux-only"
)
)]
#![cfg(target_os = "linux")]

mod bindings;
Expand Down
3 changes: 2 additions & 1 deletion sh/gh/gst-formula.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ def test_other_target_refused_before_brew(self):

def test_failed_test_cleans_only_created_tap_and_install(self):
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
# Real path, as the formula records it; macOS's temp dir sits behind a symlink.
root = Path(tmp).resolve()
(root / "Formula").mkdir()

def brew(command, **kwargs):
Expand Down
2 changes: 2 additions & 0 deletions sh/js/coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ def report(root, directories):
found = lines.setdefault(source, {})
found[int(number)] = found.get(int(number), False) or int(count) > 0
summary = {}
# Sources above are real paths; a symlinked root (macOS /var) must match them.
root = root.resolve()
manifest = json.loads((root / "package.json").read_text())
for directory in [root / "js/common", *(root / path for path in manifest["workspaces"] if path.startswith("js/"))]:
sources = [
Expand Down
42 changes: 42 additions & 0 deletions sh/local.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,55 @@ const child = Bun.spawn(command, {
stderr: "inherit",
env: { ...process.env, LOCAL_SUPERVISED: "1" },
});
// Each process's parent and start time; the start time tells a live process from a
// later one that reused its PID.
function table(): Map<number, { ppid: number; start: string }> {
const found = new Map<number, { ppid: number; start: string }>();
for (const line of Bun.spawnSync(["ps", "-A", "-o", "pid=,ppid=,lstart="]).stdout.toString().split("\n")) {
const [pid, ppid, ...start] = line.trim().split(/\s+/);
if (pid && ppid && start.length) found.set(Number(pid), { ppid: Number(ppid), start: start.join(" ") });
}
return found;
}

// Every process below `root` with its start time, from one snapshot.
function descendants(root: number): Map<number, string> {
const processes = table();
const found = new Map<number, string>();
for (let queue = [root]; queue.length; ) {
const parent = queue.pop() as number;
for (const [pid, { ppid, start }] of processes) {
if (ppid !== parent || found.has(pid)) continue;
found.set(pid, start);
queue.push(pid);
}
}
return found;
}

// Forward cancellation and let the child clean up; once it exits, every survivor is ours.
// Without a subreaper (macOS), a descendant whose parent dies leaves the tree before
// --no-orphans sweeps it, so record the tree when cancellation arrives.
let signaled: number | undefined;
const tree = new Map<number, string>();
for (const name of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
process.on(name, () => {
signaled ??= 128 + constants.signals[name];
if (process.platform !== "linux") for (const [pid, start] of descendants(process.pid)) tree.set(pid, start);
child.kill(name);
});
}
const code = await child.exited;
if (tree.size) {
// Kill only a recorded process that keeps its start time, never a PID's new owner.
const now = table();
for (const [pid, start] of tree) {
if (now.get(pid)?.start !== start) continue;
try {
process.kill(pid, "SIGKILL");
} catch {
// Exited since the check.
}
}
}
process.exit(signaled ?? code);
4 changes: 4 additions & 0 deletions sh/version.py
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,10 @@ def bump(root, config, target):
sections.append(f'[[package]]\nname = "{p.name}"\nchangelog_path = {json.dumps(str(changelog))}\n')
config_path.write_text("\n".join(sections))
if rust:
# Older release-plz, such as a non-Nix one ahead on PATH, leaves versions unset without failing.
found = run(root, "release-plz", "--version").split()[-1]
if version(found) < (0, 4, 1):
raise ValueError(f"release-plz {found} is older than 0.4.1; use the Nix dev shell's")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The floor itself ships untested, and the existing fake release-plz in sh/version.test.py:258 (a shell script that corrupts Cargo.toml/Cargo.lock and exits 1 on any argument) now fails on this --version probe rather than inside set-version, so the test no longer exercises what its comment claims. Since CONTRIBUTING.md leans on that fixture to catch release-plz behavior changes, give the fake a --version answer of release-plz 0.4.1 and add a case with an older one asserting this refusal.

Technical details
# The release-plz floor has no test, and the restore fixture moved its failure point

## Affected sites
- `sh/version.py:248-251` — the new probe and refusal.
- `sh/version.test.py:258` — fake binary is argument-blind; the `--version` probe trips it first.
- `CONTRIBUTING.md:137` — states the fixture catches release-plz upgrades that break the cut.

## Required outcome
- A test proves an older release-plz fails the cut loudly with the versions untouched.
- `test_cut_refuses_bad_targets_and_restores_partial_external_failure` still fails *inside*
  `set-version`, after release-plz has edited manifests.

## Suggested approach (optional)
- Make the fake print `release-plz 0.4.1` when `$1 == --version` and keep the corrupting failure
  otherwise; add a sibling fake printing `0.3.149` to cover the refusal.
- The error text reads truncated at `use the Nix dev shell's`; name the binary, e.g.
  `release-plz {found} is older than 0.4.1; run the cut inside `nix develop``.

run(
root,
"release-plz",
Expand Down
Loading