Sam & Claude
4d8ce07fa7
Normalize markdown formatting after the latest main updates.\n\nChecks: python3 scripts/layered_soul.py validate .; npx --yes prettier@3 --check '**/*.md'; git diff --check.
83 lines
2.3 KiB
Markdown
83 lines
2.3 KiB
Markdown
# Herdr Build Pitfalls
|
|
|
|
## Zig version: exact 0.15.2 required
|
|
|
|
Herdr vendors `libghostty-vt` which is compiled via `zig build` during
|
|
`cargo build`. The vendored library has an exact Zig version check.
|
|
|
|
**Wrong version → build error:**
|
|
|
|
```
|
|
error: Your Zig version v0.17.0-dev does not meet the required build version of v0.15.2
|
|
|
|
# Also breaks with:
|
|
error: invalid builtin function: '@cImport' # removed in 0.17
|
|
error: member function expected 4 argument(s), found 3 # readFileAlloc changed
|
|
```
|
|
|
|
**Fix:** Download Zig 0.15.2 from ziglang.org, extract to `~/.local/`,
|
|
symlink `zig` into `~/.local/bin/`:
|
|
|
|
```bash
|
|
# Remove wrong version
|
|
rm -f ~/.local/bin/zig
|
|
|
|
# Download and install
|
|
wget https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
|
|
tar -xf zig-linux-x86_64-0.15.2.tar.xz -C ~/.local/
|
|
ln -s ~/.local/zig-linux-x86_64-0.15.2/zig ~/.local/bin/zig
|
|
|
|
# Verify
|
|
zig version # must print "0.15.2"
|
|
```
|
|
|
|
## Debian apt does not have Zig
|
|
|
|
`apt search zig` finds no matching package. Manual download from
|
|
ziglang.org is the only reliable path.
|
|
|
|
## `herdr --remote` requires interactive terminal for first install
|
|
|
|
The remote mode prompts for install confirmation via stdin. Running
|
|
non-interactively fails with:
|
|
|
|
```
|
|
Error: "matching remote herdr 0.6.2 is not installed at $HOME/.local/bin/herdr;
|
|
run from an interactive terminal to approve installation"
|
|
```
|
|
|
|
**Workarounds (pick one):**
|
|
|
|
1. Run from user's terminal:
|
|
|
|
```bash
|
|
export PATH="/path/to/herdr/target/release:$PATH"
|
|
herdr --remote <host>-ts-herdr
|
|
```
|
|
|
|
Approve the prompt, TUI opens, quit with `q`.
|
|
|
|
2. Pre-install upstream binary on remote:
|
|
|
|
```bash
|
|
ssh <host>-ts-herdr 'mkdir -p ~/.local/bin'
|
|
ssh <host>-ts-herdr 'curl -L <release-url> -o ~/.local/bin/herdr && chmod +x ~/.local/bin/herdr'
|
|
```
|
|
|
|
Then `herdr --remote` detects the existing binary and skips the prompt.
|
|
|
|
3. Use `HERDR_REMOTE_BINARY` env var to ship a local build:
|
|
```bash
|
|
HERDR_REMOTE_BINARY=/path/to/herdr/target/release/herdr herdr --remote <host>-ts-herdr
|
|
```
|
|
|
|
## FreeBSD is not a supported remote platform
|
|
|
|
`RemotePlatform::from_uname()` in `remote.rs` only matches `"Linux"` and
|
|
`"Darwin"`. FreeBSD returns `"FreeBSD"` which causes:
|
|
|
|
```
|
|
Error: unsupported remote platform: FreeBSD amd64
|
|
```
|
|
|
|
Do not use `herdr --remote` against osa or any FreeBSD host.
|