samiandClaude Opus 5
9624e685af
CI / clang-format (push) Canceled after 0s
CI / testserver (push) Canceled after 0s
CI / bootstrap-script (push) Canceled after 0s
CI / bootstrap-script-2604 (push) Canceled after 0s
CI / extension-lint (push) Canceled after 0s
CI / build (clang) (push) Canceled after 0s
CI / build (gcc) (push) Canceled after 0s
CI / sanitizers (dev) (push) Canceled after 0s
CI / sanitizers (tsan) (push) Canceled after 0s
CI / clang-tidy (push) Canceled after 0s
CI / conformance (push) Canceled after 0s
CI / nightly-integration (push) Canceled after 0s
CI / gui-dod (push) Canceled after 0s
CI / gui-dod-nightly (push) Canceled after 0s
As written, ADR 0020 gave PORT ownership of cmake/platform*.cmake while also making PORT wait for Phase 0 — but Phase 0's seams are exactly what needs velox_platform_sources() to select platform/linux/*.cpp. PORT cannot start until Phase 0 lands, and Phase 0 cannot land without the file PORT owns. PKG/QA caught the circularity before writing anything, which was the right call. Central OS detection is root build infrastructure, so it stays with PKG/QA and lands during Phase 0. PORT keeps the per-OS backend directories and the macOS and Windows packaging, and owns no part of cmake/. Also drops a hardcoded test count from the PORT definition of done; the suite number moves every round and the gate is that it stays green. Co-Authored-By: Claude Opus 5 <[email protected]>
52 lines
2.7 KiB
Markdown
52 lines
2.7 KiB
Markdown
# Agent brief — PORT (per-OS backends)
|
||
|
||
**Starts after Phase 0: CORE and DAEMON have landed the seams on Ubuntu.**
|
||
|
||
## You own
|
||
```
|
||
core/src/**/platform/<os>/** daemon/src/**/platform/<os>/**
|
||
packaging/macos/** packaging/windows/**
|
||
```
|
||
You may read everything. **You never write logic** — not in `core/src/io/*.cpp`, not in
|
||
`daemon/src/rpc/*.cpp`, not in `gui/`, never in `contracts/`.
|
||
|
||
## Read first
|
||
`docs/adr/0020-cross-platform-strategy.md`, then `docs/08-porting.md` — it has the seam
|
||
list, the API mapping and the dependency table. Then `CLAUDE.md`.
|
||
|
||
## The one rule that matters
|
||
**Linux behaviour never changes.** If your port needs a seam that doesn't exist, or a seam
|
||
whose shape is wrong, you do not widen it yourself — you file a request with the owning
|
||
lane (CORE for `core/`, DAEMON for `daemon/`) exactly as every other lane does. A port that
|
||
quietly edits shared logic is how one tree becomes two.
|
||
|
||
## Build order (macOS)
|
||
1. **Configure at all.** The root `CMakeLists.txt` requires `libsecret-1` unconditionally;
|
||
that must be Linux-gated before anything else compiles. PKG/QA owns that, and also owns
|
||
`cmake/platform.cmake` (the `VELOX_OS_*` detection and `velox_platform_sources()`); both
|
||
land in Phase 0, before you start. File anything else you need with them.
|
||
2. `core/` — `preallocate`, `advise_dontneed`, `flush_durable`. Use `F_FULLFSYNC`, not
|
||
`fsync`: `.veloxpart` resume correctness depends on a real flush.
|
||
3. `daemon/` — `Wakeup` (self-pipe), `peer_of` (`getpeereid`), `instance_lock` (socket file
|
||
+ `flock`, with stale-socket cleanup), `runtime_dir` (`$TMPDIR`, `~/Library/Application
|
||
Support/Velox`).
|
||
4. Unit tests green for both lanes.
|
||
5. `tools/testserver` (stdlib Python) and conformance (Node) — expected to run unchanged.
|
||
If they don't, that's a bug worth reporting, not patching around.
|
||
6. GUI against Qt 6 for macOS.
|
||
7. Packaging — `.dmg`/Homebrew, `launchd`, native-messaging manifest locations. Last.
|
||
|
||
## Definition of done (Phase 1–2)
|
||
- macOS builds `libveloxcore`, `veloxd` and `velox` with `-Wall -Wextra -Werror`.
|
||
- Core and daemon unit tests pass on macOS.
|
||
- One real download completes on macOS against `tools/testserver` with a SHA-256 that
|
||
matches the server's reference — the same gate the Linux vertical slice passed.
|
||
- `kill -9` mid-download, restart, resume completes and the checksum still matches.
|
||
- The Ubuntu suite is **still** green from the same commit.
|
||
|
||
## Do not
|
||
- Do not add `#ifdef` outside a `platform/<os>/` file.
|
||
- Do not change a fixture, a schema or a hostile-mode expectation to make macOS pass.
|
||
- Do not substitute `F_NOCACHE` for `posix_fadvise(DONTNEED)` — see `docs/08` for why.
|
||
- Do not start with packaging.
|