skills/gastownhall__beads
1
0
Fork 0
mirror of https://github.com/gastownhall/beads.git synced 2026-09-14 20:17:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document supported go install modes (bd-o5a) (#3480)

Browse Source 
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
This commit is contained in:
matt wilkie
2026-04-25 11:30:19 -07:00
committed by GitHub
parent 1b2dd2cb56
commit e2e4975044
28 changed files with 214 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
+1
View File
@@ -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:
README.md
+1 -1
View File
@@ -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.
SECURITY.md
+1 -1
View File
@@ -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
claude-plugin/skills/beads/resources/TROUBLESHOOTING.md
+2 -2
View File
@@ -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
cmd/bd/doctor/agent.go
+2 -2
View File
@@ -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"},
}
}
default.nix
+1 -5
View File
@@ -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 ];
docs/AIDER_INTEGRATION.md
+1 -1
View File
@@ -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
docs/GETTING_STARTED_ANALYSIS.md
+8 -5
View File
@@ -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)
docs/ICU-POLICY.md
+1 -1
View File
@@ -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
docs/INSTALLING.md
+11 -21
View File
@@ -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/
```
docs/PLUGIN.md
+5 -2
View File
@@ -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
docs/RELEASING.md
+3 -3
View File
@@ -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
```
docs/TROUBLESHOOTING.md
+5 -5
View File
@@ -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/
```
examples/bash-agent/README.md
+1 -1
View File
@@ -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`
examples/bash-agent/agent.sh
+1 -1
View File
@@ -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
examples/python-agent/README.md
+1 -1
View File
@@ -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
examples/python-agent/agent.py
+1 -1
View File
@@ -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")
npm-package/CLAUDE_CODE_WEB.md
+6 -6
View File
@@ -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
scripts/check-go-install-guidance.sh
Executable
+37
View File
@@ -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"
scripts/install.sh
+1 -1
View File
@@ -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
}
tests/integration/README.md
+1 -1
View File
@@ -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
website/docs/getting-started/installation.md
+40 -34
View File
@@ -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).
website/docs/getting-started/upgrading.md
+9 -4
View File
@@ -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/
```
website/docs/reference/troubleshooting.md
+3 -3
View File
@@ -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
website/static/llms-full.txt
+52 -41
View File
@@ -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
website/versioned_docs/version-1.0.0/getting-started/installation.md
+14 -6
View File
@@ -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.
website/versioned_docs/version-1.0.0/getting-started/upgrading.md
+2 -1
View File
@@ -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
website/versioned_docs/version-1.0.0/reference/troubleshooting.md
+3 -3
View File
@@ -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