docs: add end-to-end local-setup guide for wire-test-cluster#1
Conversation
End-to-end guide covering prereqs, the WIRE_ROOT sibling-repo layout, the OPP feature branches required across wire-sysio / wire-ethereum / wire-solana, per-repo build steps (wire-cdt, wire-sysio, OPP bundle generation, Anchor build of opp-outpost), the run command, and the gotchas hit along the way (pkg-fetch race, pnpm global bin, protoc-gen-ts, zpp proto ordering, POST_BUILD fish step PATH, pkill self-term). README now links to it from Prerequisites.
jglanz
left a comment
jglanz
left a comment
There was a problem hiding this comment.
Read the comments before merging please, but more than any THANK YOU for taking the time - many of the comments are reminders to myself to fix/tweak things - but please read them all
| ├── wire-ethereum/ | ||
| ├── wire-solana/ | ||
| ├── wire-e2e-tests/ | ||
| ├── wire-opp/ # GENERATED by generate-opp-bundles.fish, not cloned |
There was a problem hiding this comment.
Needs to exist, but can be empty
There was a problem hiding this comment.
Good catch — fixed in 04eda04. Added a mkdir -p "$WIRE_ROOT/wire-opp" step in §1.3 with a one-liner explaining that generate-opp-bundles.fish only writes there when the dir already exists.
| > **GOTCHA — first-build race on the zpp-generated contract headers.** The | ||
| > `contracts_project` external target depends on `opp_cdt_models.protos` | ||
| > (which runs `cdt::protoc-gen-zpp` to generate `sysio/opp/**/*.pb.hpp` in | ||
| > `build/debug/libraries/opp/generated-cdt/`). With Ninja, that dependency | ||
| > doesn't reliably fire on a cold build — the contracts build runs before | ||
| > the `.pb.hpp` files exist and blows up with | ||
| > `fatal error: 'sysio/opp/types/types.pb.hpp' file not found`. Running | ||
| > `ninja opp_cdt_models.protos` explicitly before the full build generates | ||
| > the headers, after which the main `cmake --build` proceeds cleanly. |
There was a problem hiding this comment.
Is this really the case? I can tweak it if the latest commits didn't resolve it
There was a problem hiding this comment.
Good question — turns out wire-sysio commit 1015c98d3 (your "Refactor OPP bundle generation… add target dependencies in CMake") already wired add_dependencies(contracts_project opp_cdt_models.protos). I did hit the cold-build race despite that on feature/intrinsic-span-cleanup, but it may have been a transient ordering thing. Softened in 04eda04 to a "if you still hit it, run ninja opp_cdt_models.protos first" note, and dropped the obligatory pre-step from the main build commands. §6.4 troubleshooting entry rewritten to match.
| (cd "$WIRE_ROOT/wire-opp/solidity" && npm link) | ||
| (cd "$WIRE_ROOT/wire-opp/typescript" && npm link) |
There was a problem hiding this comment.
pnpm link --global is required as well
There was a problem hiding this comment.
Done in 04eda04 — both npm link and pnpm link --global now run for wire-opp/solidity and wire-opp/typescript in §3.5. Also updated the §5 Dockerfile-diffs entry so it lists wire-opp/{solidity,typescript} as packages that still need a global link (alongside the three CLI binaries).
| **Fix:** pre-populate the cache once before `pnpm install`: | ||
|
|
||
| ```bash | ||
| npx --yes @yao-pkg/pkg-fetch node22 linux x64 # fills ~/.pkg-cache/v3.5/ |
There was a problem hiding this comment.
Confirmed and fixed in 04eda04. protoc-gen-solidity, protoc-gen-solana, and protobuf-bundler all declare "engines": { "node": ">=24" }, and @yao-pkg/pkg fetches a v24 runtime to bundle. Bumped §1.2 install + verify step (nvm install 24), the §6.1 pkg-fetch line (node22 → node24), and removed the now-stale "Node 22 works fine" entry from §5.
| Fresh pnpm installs don't pick up a global bin dir. Set it once: | ||
|
|
||
| ```bash | ||
| pnpm config set global-bin-dir /home/<you>/.local/share/pnpm | ||
| pnpm config set global-dir /home/<you>/.local/share/pnpm/global | ||
| # and add PNPM_HOME to your shell rc: | ||
| export PNPM_HOME="$HOME/.local/share/pnpm" | ||
| export PATH="$PNPM_HOME:$PATH" |
There was a problem hiding this comment.
run pnpm setup - it does this for you
There was a problem hiding this comment.
Good call — replaced the manual pnpm config set block in §6.2 with pnpm setup in 04eda04. Much cleaner.
- Note wire-opp/ must exist (mkdir -p) before the wire-sysio build
- Bump Node.js requirement to 24 (protoc-gen-* declare engines.node>=24)
- Add pnpm link --global alongside npm link for wire-opp/{solidity,typescript}
- Replace manual PNPM_HOME config with pnpm setup
- Soften OPP cold-build gotcha — wire-sysio 1015c98d3 wired the dep,
ninja opp_cdt_models.protos pre-step is now a fallback only
- Credit b66eea7243 for the find_program cache-reuse fix (§6.5)
- Fix duplicate §6.5 numbering (cascades to §6.6–§6.8)
2 participants
Summary
docs/local-setup.md— step-by-step for building and runningwire-test-clusterfrom source, without Docker, across all five sibling repos.wire-sysio/wire-ethereum/wire-solana, plus the gotchas hit during the walkthrough:@yao-pkg/pkg-fetchrace, pnpm global-bin setup, missingprotoc-gen-ts,opp_cdt_models.protosnot built beforecontracts_project,libopp.aPOST_BUILD fish step requiring pnpm bin on PATH,pkill -fself-terminating the shell,wire-solanamaster being the liqSol repo (not opp-outpost), and ~5 places the reference Dockerfile has drifted.