diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d0bb89467..a82f3acb7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,6 +39,7 @@ jobs: steps: - uses: actions/checkout@v6 - run: ./scripts/check-build-tags.sh + - run: ./scripts/check-go-install-guidance.sh # Fast check to ensure all version files are in sync check-version-consistency: diff --git a/README.md b/README.md index 971c18ece..10fc03534 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ brew install beads # macOS / Linux (recommended) npm install -g @beads/bd # Node.js users ``` -**Other methods:** [install script](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#quick-install-recommended) | [from source](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux) +**Other methods:** [install script](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#a-note-on-go-install-capability) | [from source](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux) **Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/INSTALLING.md](docs/INSTALLING.md) for complete installation guide. diff --git a/SECURITY.md b/SECURITY.md index 4378b370d..195f49549 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -115,7 +115,7 @@ Once version 1.0 is released, we will support the latest major version and one p 2. **Review before sharing** - Check issue content before sharing project details 3. **Use private repos** - If your issues contain proprietary information, use private git repositories 4. **Validate git hooks** - If using automated export/import hooks, review them for safety -5. **Regular updates** - Keep bd updated to the latest version: `go install github.com/steveyegge/beads/cmd/bd@latest` +5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/INSTALLING.md](docs/INSTALLING.md). ## Known Limitations diff --git a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md index f190e72c3..ba5a2565f 100644 --- a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md +++ b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md @@ -53,8 +53,8 @@ bd version # Via Homebrew (macOS/Linux) brew upgrade beads -# Via go install -go install github.com/steveyegge/beads/cmd/bd@latest +# Via install script +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash # Via package manager # See https://github.com/gastownhall/beads#installing diff --git a/cmd/bd/doctor/agent.go b/cmd/bd/doctor/agent.go index 0c3643b15..d824e3482 100644 --- a/cmd/bd/doctor/agent.go +++ b/cmd/bd/doctor/agent.go @@ -234,7 +234,7 @@ func enrichCLIVersion(dc DoctorCheck) agentEnrichment { explanation: fmt.Sprintf("CLI version check: %s. An outdated CLI may lack bug fixes or schema migrations needed by the current database.", dc.Message), observed: dc.Message, expected: "CLI version matches latest GitHub release", - commands: []string{"go install github.com/steveyegge/beads/cmd/bd@latest"}, + commands: []string{installScriptCommand}, sourceFiles: []string{"cmd/bd/doctor/version.go:CheckCLIVersion"}, } } @@ -582,7 +582,7 @@ func enrichBdInPath(dc DoctorCheck) agentEnrichment { explanation: fmt.Sprintf("bd not in PATH: %s. Claude Code hooks invoke bd commands, but bd is not found in the system PATH. Hooks will fail silently.", dc.Message), observed: dc.Message, expected: "'bd' executable is in PATH and runnable", - commands: []string{"which bd", "go install github.com/steveyegge/beads/cmd/bd@latest"}, + commands: []string{"which bd", installScriptCommand}, sourceFiles: []string{"cmd/bd/doctor/claude.go:CheckBdInPath"}, } } diff --git a/default.nix b/default.nix index 6a89f6fb5..9384f0a9e 100644 --- a/default.nix +++ b/default.nix @@ -3,7 +3,6 @@ self, buildGoModule, git, - icu, ... }: buildGoModule { @@ -14,6 +13,7 @@ buildGoModule { # Point to the main Go package subPackages = [ "cmd/bd" ]; + tags = [ "gms_pure_go" ]; doCheck = false; # Go module dependencies hash - if build fails with hash mismatch, update with the "got:" value @@ -31,10 +31,6 @@ buildGoModule { # Allow patch-level toolchain upgrades when a dependency's minimum Go patch # version is newer than nixpkgs' bundled patch version. env.GOTOOLCHAIN = "auto"; - # Due to https://github.com/dolthub/go-icu-regex, which requires - # separate install of icu headers and library. - env.CGO_CPPFLAGS="-I${icu.dev}/include"; - env.CGO_LDFLAGS="-L${icu}/lib"; # Git is required for tests nativeBuildInputs = [ git ]; diff --git a/docs/AIDER_INTEGRATION.md b/docs/AIDER_INTEGRATION.md index 6e2b71c42..1a7a76da6 100644 --- a/docs/AIDER_INTEGRATION.md +++ b/docs/AIDER_INTEGRATION.md @@ -18,7 +18,7 @@ The beads integration for Aider: ```bash # Install beads CLI -go install github.com/steveyegge/beads/cmd/bd@latest +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash # Initialize in your project cd your-project diff --git a/docs/GETTING_STARTED_ANALYSIS.md b/docs/GETTING_STARTED_ANALYSIS.md index e67444dcd..06e2901fe 100644 --- a/docs/GETTING_STARTED_ANALYSIS.md +++ b/docs/GETTING_STARTED_ANALYSIS.md @@ -86,12 +86,15 @@ CONTRIBUTING.md. The happy path should be `brew install beads` or `npm install **Appears in:** INSTALLING.md (lines 107-130), README.md (lines 75-91), CONTRIBUTING.md -**Root cause:** Users who `go install` need CGO + ICU headers. But prebuilt -binaries don't need any of this. +**Root cause:** Users who run plain CGO-enabled `go install` take the upstream +ICU regex path. Supported `go install` forms avoid ICU by using either +`CGO_ENABLED=0` (server-mode only) or `GOFLAGS=-tags=gms_pure_go` +(embedded-capable). Prebuilt binaries don't need any of this. -**The fix:** Same as above — stop promoting `go install` as a primary install -method. The prebuilt binary path (Homebrew, npm, install script) requires zero -build dependencies. CGO/ICU docs belong in CONTRIBUTING.md only. +**The fix:** Same as above — stop promoting plain `go install` as a primary +install method. The prebuilt binary path (Homebrew, npm, install script) +requires zero build dependencies. The two supported `go install` forms belong +in the full installation docs, not the happy path. ### 2.3 `zsh: killed bd` / macOS crashes (~20 lines, duplicated in 2 files) diff --git a/docs/ICU-POLICY.md b/docs/ICU-POLICY.md index c1510d337..a6a1fd031 100644 --- a/docs/ICU-POLICY.md +++ b/docs/ICU-POLICY.md @@ -21,7 +21,7 @@ creating significant portability problems: | Linux | Binaries dynamically link a specific `libicui18n.so.NN` version; crash on distros with a different ICU version | | macOS | ICU is keg-only in Homebrew; `go install` fails without manual `CGO_CFLAGS`/`CGO_LDFLAGS` | | Windows | ICU C headers (`unicode/uregex.h`) not available; `go install` and CGO builds fail | -| `go install` | Users cannot pass `-tags gms_pure_go` to `go install pkg@latest` | +| `go install` | The module cannot make plain `go install pkg@latest` use `-tags gms_pure_go` automatically | ## How It Works diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index aad75a026..81daf5e40 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -47,29 +47,22 @@ brew install beads ### [Mise-en-place](https://mise.jdx.dev) (macOS/Linux/Windows) -You can install beads using mise in 2 different ways: - -1. Install the latest github release +You can install beads using mise from the latest GitHub release: ```bash mise install github:gastownhall/beads mise use -g github:gastownhall/beads ``` -2. Build the latest code from git using go: - -```bash -mise install go:github.com/steveyegge/beads/cmd/bd@latest -mise use -g go:github.com/steveyegge/beads/cmd/bd -``` - **NOTE**: The `-g` enables beads globally. To enable project-specific versions, omit that. **Why Mise?** - ✅ Same as Homebrew: simple, updates via `mise up`, works without Go, handles PATH - ✅ Supports all platforms - ✅ Always the latest release -- ✅ May optionally use a different version for specific projects +- ✅ May optionally use a different release version for specific projects + +Mise's Go backend follows the same caveats as `go install`; prefer the release backend above. ### Quick Install Script (All Platforms) @@ -80,7 +73,7 @@ curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/inst The installer will: - Detect your platform (macOS/Linux/FreeBSD, amd64/arm64) - Verify downloaded release archives against release `checksums.txt` -- Install via `go install` if Go is available +- Fall back to the supported `go install` modes if Go is available - Fall back to building from source if needed - Guide you through PATH setup if necessary @@ -207,8 +200,7 @@ The script installs a prebuilt Windows release if available and verifies the dow **Via go install** (server-mode only, simplest): ```pwsh -$env:CGO_ENABLED=0 -go install github.com/steveyegge/beads/cmd/bd@latest +$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest # Then: bd init --server (requires a running dolt sql-server) ``` @@ -216,9 +208,7 @@ This produces a server-mode-only binary with no C compiler requirement — the f **Via go install** (embedded-capable, needs MinGW): ```pwsh -$env:CGO_ENABLED=1 -$env:GOFLAGS="-tags=gms_pure_go" -go install github.com/steveyegge/beads/cmd/bd@latest +$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest ``` Requires MinGW-w64 gcc on your PATH. ICU is **not** required — `gms_pure_go` selects Go's stdlib `regexp`. @@ -460,13 +450,13 @@ Some users report crashes when running `bd init` or other commands on macOS. Thi **Workaround:** ```bash -# Build with CGO enabled -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +# Install an embedded-capable build +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest # Or if building from source git clone https://github.com/gastownhall/beads cd beads -CGO_ENABLED=1 go build -o bd ./cmd/bd +CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd sudo mv bd /usr/local/bin/ ``` @@ -557,7 +547,7 @@ CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/c ```bash cd beads git pull -go build -o bd ./cmd/bd +make build sudo mv bd /usr/local/bin/ ``` diff --git a/docs/PLUGIN.md b/docs/PLUGIN.md index 297f58f92..76f3e3915 100644 --- a/docs/PLUGIN.md +++ b/docs/PLUGIN.md @@ -308,8 +308,11 @@ The plugin requires the `bd` CLI to be installed. Update it separately: # Quick update curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash -# Or with go -go install github.com/steveyegge/beads/cmd/bd@latest +# Or with Go (server-mode only) +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Or with Go (embedded-capable) +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### 3. Version Compatibility diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 9ae0ad9ee..101ffceaf 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -39,9 +39,9 @@ If you prefer step-by-step control: 2. **Run tests and build**: ```bash - TMPDIR=/tmp go test ./... + make test golangci-lint run ./... - TMPDIR=/tmp go build -o bd ./cmd/bd + make build ./bd version # Verify it shows new version ``` @@ -82,7 +82,7 @@ This updates: **IMPORTANT**: After version bump, rebuild the local binary: ```bash -go build -o bd ./cmd/bd +make build ./bd version # Should show new version ``` diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 1494a221b..ec89daf7f 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -135,8 +135,8 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" -# Or reinstall -go install github.com/steveyegge/beads/cmd/bd@latest +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### Wrong version of bd running / Multiple bd binaries in PATH @@ -176,13 +176,13 @@ Some users report crashes when running `bd init` or other commands on macOS. Thi **Workaround:** ```bash -# Build with CGO enabled -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +# Install an embedded-capable build +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest # Or if building from source git clone https://github.com/gastownhall/beads cd beads -CGO_ENABLED=1 go build -o bd ./cmd/bd +CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd sudo mv bd /usr/local/bin/ ``` diff --git a/examples/bash-agent/README.md b/examples/bash-agent/README.md index 395cdf0b3..0faf8db29 100644 --- a/examples/bash-agent/README.md +++ b/examples/bash-agent/README.md @@ -14,7 +14,7 @@ A bash script demonstrating how an AI agent can use bd to manage tasks autonomou ## Prerequisites - bash 4.0+ -- bd installed: `go install github.com/steveyegge/beads/cmd/bd@latest` +- bd installed: `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` - jq for JSON parsing: `brew install jq` (macOS) or `apt install jq` (Linux) - A beads database initialized: `bd init` diff --git a/examples/bash-agent/agent.sh b/examples/bash-agent/agent.sh index b9b3caa1a..663f03a50 100755 --- a/examples/bash-agent/agent.sh +++ b/examples/bash-agent/agent.sh @@ -39,7 +39,7 @@ AGENT_NAME="${BEADS_AGENT_NAME:-bash-agent-$$}" # Check if bd is installed if ! command -v bd &> /dev/null; then log_error "bd is not installed" - echo "Install with: go install github.com/steveyegge/beads/cmd/bd@latest" + echo "Install with: curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash" exit 1 fi diff --git a/examples/python-agent/README.md b/examples/python-agent/README.md index 692966d8e..208b18691 100644 --- a/examples/python-agent/README.md +++ b/examples/python-agent/README.md @@ -13,7 +13,7 @@ A simple Python script demonstrating how an AI agent can use bd to manage tasks. ## Prerequisites - Python 3.7+ -- bd installed: `go install github.com/steveyegge/beads/cmd/bd@latest` +- bd installed: `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` - A beads database initialized: `bd init` ## Usage diff --git a/examples/python-agent/agent.py b/examples/python-agent/agent.py index 1d1488732..a61fced71 100755 --- a/examples/python-agent/agent.py +++ b/examples/python-agent/agent.py @@ -139,7 +139,7 @@ def main(): agent.run() except subprocess.CalledProcessError as e: print(f"Error running bd: {e}", file=sys.stderr) - print(f"Make sure bd is installed: go install github.com/steveyegge/beads/cmd/bd@latest") + print("Make sure bd is installed: curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash") sys.exit(1) except KeyboardInterrupt: print("\n\n👋 Agent interrupted by user") diff --git a/npm-package/CLAUDE_CODE_WEB.md b/npm-package/CLAUDE_CODE_WEB.md index ffe75a230..3c024724b 100644 --- a/npm-package/CLAUDE_CODE_WEB.md +++ b/npm-package/CLAUDE_CODE_WEB.md @@ -159,13 +159,13 @@ or curl: (22) The requested URL returned error: 403 ``` -**Workaround: Use go install** +**Workaround: Use a supported go install mode** -If Go is available (it usually is in Claude Code web), use the `go install` fallback: +If Go is available (it usually is in Claude Code web), use the embedded-capable `go install` fallback: ```bash -# Install via go -go install github.com/steveyegge/beads/cmd/bd@latest +# Install via Go without ICU +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest # Add to PATH (required each session) export PATH="$PATH:$HOME/go/bin" @@ -182,13 +182,13 @@ bd version echo "🔗 Setting up bd (beads issue tracker)..." -# Try npm first, fall back to go install +# Try npm first, fall back to a supported Go install if ! command -v bd &> /dev/null; then if npm install -g @beads/bd --quiet 2>/dev/null && command -v bd &> /dev/null; then echo "✓ Installed via npm" elif command -v go &> /dev/null; then echo "npm install failed, trying go install..." - go install github.com/steveyegge/beads/cmd/bd@latest + CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest export PATH="$PATH:$HOME/go/bin" echo "✓ Installed via go install" else diff --git a/scripts/check-go-install-guidance.sh b/scripts/check-go-install-guidance.sh new file mode 100755 index 000000000..bb3656ee2 --- /dev/null +++ b/scripts/check-go-install-guidance.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# Guard user-facing docs and hints against unsupported first-party go install forms. +# +# Plain `go install github.com/.../beads/cmd/bd@latest` takes the CGO+ICU path +# on many hosts. Keep first-party guidance on one of the documented supported +# modes: +# - CGO_ENABLED=0 ... (server-mode only) +# - ... gms_pure_go ... (embedded-capable, no ICU) + +set -euo pipefail + +fail=0 + +while IFS= read -r hit; do + file="${hit%%:*}" + rest="${hit#*:}" + line_no="${rest%%:*}" + line="${rest#*:}" + + case "$file" in + CHANGELOG.md|docs/GETTING_STARTED_ANALYSIS.md) + continue + ;; + esac + + if [[ "$line" == *"CGO_ENABLED=0"* || "$line" == *'CGO_ENABLED="0"'* || "$line" == *"gms_pure_go"* ]]; then + continue + fi + + printf 'error: %s:%s: unsupported first-party bare go install guidance\n' "$file" "$line_no" >&2 + printf ' use CGO_ENABLED=0 for server mode or GOFLAGS=-tags=gms_pure_go for embedded mode\n' >&2 + fail=1 +done < <( + git grep -n -E 'go install github\.com/(steveyegge|gastownhall)/beads/cmd/bd@latest' -- . || true +) + +exit "$fail" diff --git a/scripts/install.sh b/scripts/install.sh index 59b5cc460..67ccf24f3 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -751,7 +751,7 @@ main() { echo "" echo "Or install from source:" echo " 1. Install Go from https://go.dev/dl/" - echo " 2. Run: CGO_ENABLED=1 go install github.com/gastownhall/beads/cmd/bd@latest" + echo " 2. Run: CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/gastownhall/beads/cmd/bd@latest" echo "" exit 1 } diff --git a/tests/integration/README.md b/tests/integration/README.md index 4ebea62ec..8d53ef203 100644 --- a/tests/integration/README.md +++ b/tests/integration/README.md @@ -4,7 +4,7 @@ This directory contains integration tests for bd (beads) that test end-to-end fu ## Prerequisites -- bd installed: `go install github.com/steveyegge/beads/cmd/bd@latest` +- bd installed: `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` - Python 3.7+ for Python-based tests ## Running Tests diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 07fb7dad6..e532f4797 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -30,34 +30,20 @@ curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/inst The installer will: - Detect your platform (macOS/Linux/FreeBSD, amd64/arm64) -- Install via `go install` if Go is available +- Fall back to the supported `go install` modes if Go is available - Fall back to building from source if needed - Guide you through PATH setup if necessary -## Build Dependencies (go install / from source) +## Go Install and Build Dependencies -If you install via `go install` or build from source, you need system dependencies for CGO: +Use Homebrew, npm, or the install script if you do not specifically need `go install`. -macOS (Homebrew): -```bash -brew install icu4c zstd -``` +`go install` has two supported modes: -Linux (Debian/Ubuntu): -```bash -sudo apt-get install -y libicu-dev libzstd-dev -``` +- **Server-mode only:** `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` +- **Embedded-capable:** `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` -Linux (Fedora/RHEL): -```bash -sudo dnf install -y libicu-devel libzstd-devel -``` - -If you see `unicode/uregex.h` missing on macOS, `icu4c` is keg-only. Use: -```bash -ICU_PREFIX="$(brew --prefix icu4c)" -CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest -``` +ICU headers are not required. The embedded-capable command uses `gms_pure_go` so go-mysql-server uses Go's stdlib regexp instead of ICU. ## Platform-Specific Installation @@ -68,16 +54,21 @@ CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_ brew install beads ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest +``` + +**Via go install** (embedded-capable): +```bash +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` **From source**: ```bash git clone https://github.com/gastownhall/beads cd beads -go build -o bd ./cmd/bd +make build sudo mv bd /usr/local/bin/ ``` @@ -96,9 +87,14 @@ yay -S beads-git paru -S beads-git ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest +``` + +**Via go install** (embedded-capable): +```bash +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### FreeBSD @@ -108,9 +104,9 @@ go install github.com/steveyegge/beads/cmd/bd@latest curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest ``` ### Windows 11 @@ -128,12 +124,15 @@ irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source. -**Via go install**: +**Via go install** (server-mode only): ```pwsh -go install github.com/steveyegge/beads/cmd/bd@latest +$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest ``` -If you see `unicode/uregex.h` missing while building, use the PowerShell install script instead. +**Via go install** (embedded-capable): +```pwsh +$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest +``` ## IDE and Editor Integrations @@ -213,6 +212,9 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" + +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### `zsh: killed bd` or crashes on macOS @@ -220,8 +222,8 @@ export PATH="$PATH:$(go env GOPATH)/bin" This is typically caused by CGO/SQLite compatibility issues: ```bash -# Build with CGO enabled -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +# Install an embedded-capable build +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ## Updating bd @@ -247,7 +249,11 @@ brew upgrade beads ### go install ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +# Server-mode only +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Embedded-capable +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading). diff --git a/website/docs/getting-started/upgrading.md b/website/docs/getting-started/upgrading.md index d785214c8..d3cc7de12 100644 --- a/website/docs/getting-started/upgrading.md +++ b/website/docs/getting-started/upgrading.md @@ -28,10 +28,11 @@ Use the command that matches your install method. | Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` | | PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` | | Homebrew | macOS, Linux | `brew upgrade beads` | -| go install | macOS, Linux, FreeBSD, Windows | `go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (server-mode only) | macOS, Linux, FreeBSD, Windows | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (embedded-capable) | macOS, Linux, Windows | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` | | npm | macOS, Linux, Windows | `npm update -g @beads/bd` | | bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` | -| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && go build -o bd ./cmd/bd` | +| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && make build` | ### Quick install script (macOS/Linux/FreeBSD) @@ -54,7 +55,11 @@ brew upgrade beads ### go install ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +# Server-mode only +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Embedded-capable +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### From Source @@ -62,7 +67,7 @@ go install github.com/steveyegge/beads/cmd/bd@latest ```bash cd beads git pull -go build -o bd ./cmd/bd +make build sudo mv bd /usr/local/bin/ ``` diff --git a/website/docs/reference/troubleshooting.md b/website/docs/reference/troubleshooting.md index 99a826196..a7ed8af6c 100644 --- a/website/docs/reference/troubleshooting.md +++ b/website/docs/reference/troubleshooting.md @@ -20,8 +20,8 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH export PATH="$PATH:$(go env GOPATH)/bin" -# Or reinstall -go install github.com/steveyegge/beads/cmd/bd@latest +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### `zsh: killed bd` on macOS @@ -29,7 +29,7 @@ go install github.com/steveyegge/beads/cmd/bd@latest CGO/SQLite compatibility issue: ```bash -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### Permission denied diff --git a/website/static/llms-full.txt b/website/static/llms-full.txt index 94acf9622..1f2354ded 100644 --- a/website/static/llms-full.txt +++ b/website/static/llms-full.txt @@ -327,34 +327,20 @@ curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/inst The installer will: - Detect your platform (macOS/Linux/FreeBSD, amd64/arm64) -- Install via `go install` if Go is available +- Fall back to the supported `go install` modes if Go is available - Fall back to building from source if needed - Guide you through PATH setup if necessary -## Build Dependencies (go install / from source) +## Go Install and Build Dependencies -If you install via `go install` or build from source, you need system dependencies for CGO: +Use Homebrew, npm, or the install script if you do not specifically need `go install`. -macOS (Homebrew): -```bash -brew install icu4c zstd -``` +`go install` has two supported modes: -Linux (Debian/Ubuntu): -```bash -sudo apt-get install -y libicu-dev libzstd-dev -``` +- **Server-mode only:** `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` +- **Embedded-capable:** `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` -Linux (Fedora/RHEL): -```bash -sudo dnf install -y libicu-devel libzstd-devel -``` - -If you see `unicode/uregex.h` missing on macOS, `icu4c` is keg-only. Use: -```bash -ICU_PREFIX="$(brew --prefix icu4c)" -CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest -``` +ICU headers are not required. The embedded-capable command uses `gms_pure_go` so go-mysql-server uses Go's stdlib regexp instead of ICU. ## Platform-Specific Installation @@ -365,16 +351,21 @@ CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_ brew install beads ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest +``` + +**Via go install** (embedded-capable): +```bash +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` **From source**: ```bash git clone https://github.com/gastownhall/beads cd beads -go build -o bd ./cmd/bd +make build sudo mv bd /usr/local/bin/ ``` @@ -393,9 +384,14 @@ yay -S beads-git paru -S beads-git ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest +``` + +**Via go install** (embedded-capable): +```bash +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### FreeBSD @@ -405,9 +401,9 @@ go install github.com/steveyegge/beads/cmd/bd@latest curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` -**Via go install**: +**Via go install** (server-mode only): ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest ``` ### Windows 11 @@ -425,12 +421,15 @@ irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source. -**Via go install**: +**Via go install** (server-mode only): ```pwsh -go install github.com/steveyegge/beads/cmd/bd@latest +$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest ``` -If you see `unicode/uregex.h` missing while building, use the PowerShell install script instead. +**Via go install** (embedded-capable): +```pwsh +$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest +``` ## IDE and Editor Integrations @@ -510,6 +509,9 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" + +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### `zsh: killed bd` or crashes on macOS @@ -517,8 +519,8 @@ export PATH="$PATH:$(go env GOPATH)/bin" This is typically caused by CGO/SQLite compatibility issues: ```bash -# Build with CGO enabled -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +# Install an embedded-capable build +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ## Updating bd @@ -544,7 +546,11 @@ brew upgrade beads ### go install ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +# Server-mode only +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Embedded-capable +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading). @@ -956,10 +962,11 @@ Use the command that matches your install method. | Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` | | PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` | | Homebrew | macOS, Linux | `brew upgrade beads` | -| go install | macOS, Linux, FreeBSD, Windows | `go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (server-mode only) | macOS, Linux, FreeBSD, Windows | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (embedded-capable) | macOS, Linux, Windows | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` | | npm | macOS, Linux, Windows | `npm update -g @beads/bd` | | bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` | -| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && go build -o bd ./cmd/bd` | +| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && make build` | ### Quick install script (macOS/Linux/FreeBSD) @@ -982,7 +989,11 @@ brew upgrade beads ### go install ```bash -go install github.com/steveyegge/beads/cmd/bd@latest +# Server-mode only +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Embedded-capable +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### From Source @@ -990,7 +1001,7 @@ go install github.com/steveyegge/beads/cmd/bd@latest ```bash cd beads git pull -go build -o bd ./cmd/bd +make build sudo mv bd /usr/local/bin/ ``` @@ -6062,8 +6073,8 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH export PATH="$PATH:$(go env GOPATH)/bin" -# Or reinstall -go install github.com/steveyegge/beads/cmd/bd@latest +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### `zsh: killed bd` on macOS @@ -6071,7 +6082,7 @@ go install github.com/steveyegge/beads/cmd/bd@latest CGO/SQLite compatibility issue: ```bash -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### Permission denied diff --git a/website/versioned_docs/version-1.0.0/getting-started/installation.md b/website/versioned_docs/version-1.0.0/getting-started/installation.md index 3dbaab1c4..1febaacc9 100644 --- a/website/versioned_docs/version-1.0.0/getting-started/installation.md +++ b/website/versioned_docs/version-1.0.0/getting-started/installation.md @@ -36,7 +36,15 @@ npm install -g @beads/bd ### macOS -Homebrew is recommended. Alternatively: `go install github.com/steveyegge/beads/cmd/bd@latest` (requires CGO dependencies - see [Building from source](#building-from-source) below). +Homebrew is recommended. If you specifically need `go install`, use one of the supported modes below. + +```bash +# Server-mode only +CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest + +# Embedded-capable +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest +``` ### Linux @@ -57,18 +65,18 @@ If you see `bd: command not found`, ensure your install location is in PATH. For ## Building from Source -Building from source or using `go install` requires CGO dependencies: +Building from source requires Go, git, and a C compiler for embedded Dolt. ICU headers are not required; builds use `gms_pure_go`. | Platform | Command | |----------|---------| -| macOS | `brew install icu4c zstd` | -| Debian/Ubuntu | `sudo apt-get install -y libicu-dev libzstd-dev` | -| Fedora/RHEL | `sudo dnf install -y libicu-devel libzstd-devel` | +| macOS | `brew install zstd` | +| Debian/Ubuntu | `sudo apt-get install -y libzstd-dev` | +| Fedora/RHEL | `sudo dnf install -y libzstd-devel` | ```bash git clone https://github.com/gastownhall/beads cd beads -go build -o bd ./cmd/bd +make build ``` See [CONTRIBUTING.md](https://github.com/gastownhall/beads/blob/main/CONTRIBUTING.md) for full developer setup. diff --git a/website/versioned_docs/version-1.0.0/getting-started/upgrading.md b/website/versioned_docs/version-1.0.0/getting-started/upgrading.md index ec2198169..ccf301883 100644 --- a/website/versioned_docs/version-1.0.0/getting-started/upgrading.md +++ b/website/versioned_docs/version-1.0.0/getting-started/upgrading.md @@ -16,7 +16,8 @@ Use the command that matches your install method: | Install script (macOS/Linux) | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` | | PowerShell (Windows) | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` | | npm | `npm update -g @beads/bd` | -| go install | `go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (server-mode only) | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` | +| go install (embedded-capable) | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` | ## After Upgrading diff --git a/website/versioned_docs/version-1.0.0/reference/troubleshooting.md b/website/versioned_docs/version-1.0.0/reference/troubleshooting.md index 99a826196..a7ed8af6c 100644 --- a/website/versioned_docs/version-1.0.0/reference/troubleshooting.md +++ b/website/versioned_docs/version-1.0.0/reference/troubleshooting.md @@ -20,8 +20,8 @@ go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH export PATH="$PATH:$(go env GOPATH)/bin" -# Or reinstall -go install github.com/steveyegge/beads/cmd/bd@latest +# Or reinstall with the recommended installer +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` ### `zsh: killed bd` on macOS @@ -29,7 +29,7 @@ go install github.com/steveyegge/beads/cmd/bd@latest CGO/SQLite compatibility issue: ```bash -CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest +CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ``` ### Permission denied