From 71f5f83adb1f390addc489ac9d9a40ac62c05986 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Tue, 21 Apr 2026 21:29:59 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20#153=20=E2=80=94=20add=20post-build=20b?= =?UTF-8?q?inary=20location=20and=20verification=20guide=20to=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem Users frequently ask after building: - "Where is the claw binary?" - "Did the build actually work?" - "Why can't I run \`claw\` from anywhere?" This happens because \`cargo build\` puts the binary in \`rust/target/debug/claw\` (or \`rust/target/release/claw\`), and new users don't know: 1. Where to find it 2. How to test it 3. How to add it to PATH (optional but common follow-up) ## Fix Added new section "Post-build: locate the binary and verify" to README covering: 1. **Binary location table:** debug vs. release, macOS/Linux vs. Windows paths 2. **Verification commands:** Test the binary with \`--help\` and \`doctor\` 3. **Three ways to add to PATH:** - Symlink (macOS/Linux): \`ln -s ... /usr/local/bin/claw\` - cargo install: \`cargo install --path . --force\` - Shell profile update: add rust/target/debug to \$PATH 4. **Troubleshooting:** Common errors ("command not found", "permission denied", debug vs. release build speed) ## Impact New users can now: - Find the binary immediately after build - Run it and verify with \`claw doctor\` - Know their options for system-wide access Also filed ROADMAP #153 documenting the gap. Closes ROADMAP #153. --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++- ROADMAP.md | 29 ++++++++++++++++++++ 2 files changed, 107 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dcf4038..0b09007 100644 --- a/README.md +++ b/README.md @@ -98,10 +98,87 @@ export ANTHROPIC_API_KEY="sk-ant-..." **Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install. +## Post-build: locate the binary and verify + +After running `cargo build --workspace`, the `claw` binary is built but **not** automatically installed to your system. Here's where to find it and how to verify the build succeeded. + +### Binary location + +After `cargo build --workspace` in `claw-code/rust/`: + +**Debug build (default, faster compile):** +- **macOS/Linux:** `rust/target/debug/claw` +- **Windows:** `rust/target/debug/claw.exe` + +**Release build (optimized, slower compile):** +- **macOS/Linux:** `rust/target/release/claw` +- **Windows:** `rust/target/release/claw.exe` + +If you ran `cargo build` without `--release`, the binary is in the `debug/` folder. + +### Verify the build succeeded + +Test the binary directly using its path: + +```bash +# macOS/Linux (debug build) +./rust/target/debug/claw --help +./rust/target/debug/claw doctor + +# Windows PowerShell (debug build) +.\rust\target\debug\claw.exe --help +.\rust\target\debug\claw.exe doctor +``` + +If these commands succeed, the build is working. `claw doctor` is your first health check — it validates your API key, model access, and tool configuration. + +### Optional: Add to PATH + +If you want to run `claw` from any directory without the full path, choose one of these approaches: + +**Option 1: Symlink (macOS/Linux)** +```bash +ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw +``` +Then reload your shell and test: +```bash +claw --help +``` + +**Option 2: Use `cargo install` (all platforms)** + +Build and install to Cargo's default location (`~/.cargo/bin/`, which is usually on PATH): +```bash +# From the claw-code/rust/ directory +cargo install --path . --force + +# Then from anywhere +claw --help +``` + +**Option 3: Update shell profile (bash/zsh)** + +Add this line to `~/.bashrc` or `~/.zshrc`: +```bash +export PATH="$(pwd)/rust/target/debug:$PATH" +``` + +Reload your shell: +```bash +source ~/.bashrc # or source ~/.zshrc +claw --help +``` + +### Troubleshooting + +- **"command not found: claw"** — The binary is in `rust/target/debug/claw`, but it's not on your PATH. Use the full path `./rust/target/debug/claw` or symlink/install as above. +- **"permission denied"** — On macOS/Linux, you may need `chmod +x rust/target/debug/claw` if the executable bit isn't set (rare). +- **Debug vs. release** — If the build is slow, you're in debug mode (default). Add `--release` to `cargo build` for faster runtime, but the build itself will take 5–10 minutes. + > [!NOTE] > **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path. -Run the workspace test suite: +Run the workspace test suite after verifying the binary works: ```bash cd rust diff --git a/ROADMAP.md b/ROADMAP.md index 842f51d..2e9af1c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5905,3 +5905,32 @@ pub fn from_cwd(cwd: impl AsRef) -> Result { **Blocker.** None. Implementation exists on worktree `jobdori-127-verb-suffix` but needs rebase against main (conflicts with #141 which already shipped). **Source.** Clawhip nudge 2026-04-21 21:17 KST — "no excuses, always find something to ship" directive. Session tally: ROADMAP #152. + +## Pinpoint #153. README/USAGE missing "add binary to PATH" and "verify install" bridge + +**Gap.** After `cargo build --workspace`, new users don't know: +1. Where the binary actually ends up (e.g., `rust/target/debug/claw` vs. expecting it in `/usr/local/bin`) +2. How to verify the build succeeded (e.g., `claw --help`, `which claw`, `claw doctor`) +3. How to add it to PATH for shell integration (optional but common follow-up) + +This creates a confusing gap: users build successfully but then get "command not found: claw" and assume the build failed, or they immediately ask "how do I install this properly?" + +**Real examples from #claw-code:** +- "claw not found — did the build fail?" +- "do I need to `cargo install` this?" +- "why is the binary at `rust/target/debug/claw` and not just `claw`?" + +**Fix shape (~50 lines).** Add a new "Post-build verification and PATH" section in README (after Quick start) covering: +1. **Where the binary lives:** `rust/target/debug/claw` (debug build) or `rust/target/release/claw` (release) +2. **Verify it works:** Run `./rust/target/debug/claw --help` and `./rust/target/debug/claw doctor` +3. **Optional: Add to PATH** — three approaches: + - symlink: `ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw` + - `cargo install --path ./rust` (builds and installs to `~/.cargo/bin/`) + - update shell profile to export PATH +4. **Windows equivalent:** Point to `rust\target\debug\claw.exe` and `cargo install --path .\rust` + +**Acceptance:** New users can find the binary location, run it directly, and know their first verification step is `claw doctor`. + +**Blocker:** None. Pure documentation. + +**Source:** Clawhip nudge 2026-04-21 21:27 KST — onboarding gap from #claw-code observations earlier this month.