diff --git a/AGENTS.md b/AGENTS.md index 1710114bb..2f9e0cc8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,22 +42,58 @@ and regenerate with `make proto-gen`. ## Building, Testing, and Linting ```bash -# Build (includes BLS native dependency) -make build +# Build the BLS native library: inits the submodule, needs cmake, a C++ +# compiler and libgmp-dev. Once per checkout or worktree. +make build-bls -# Run all unit tests with race detector (matches CI: CGO, BLS, -tags=deadlock, -p 1) -make test_race +# Build (includes build-bls) +make build -# Run all unit tests without race detector (matches CI configuration) +# Run all unit tests (-p 1, -tags deadlock) make test -# Lint +# Run all unit tests with race detector (-p 1) +make test_race + +# Lint lines changed vs origin/dev (what CI enforces); +# stacked PRs: make lint LINT_BASE=origin/ make lint # Format make format ``` +### Running targeted tests + +Most packages link BLS through cgo. The Makefile passes the cgo flags only to +its own targets, so a bare `go test`, `go vet` or `go build` fails with: + +```text +blschia.cpp:17:10: fatal error: dashbls/bls.hpp: No such file or directory +``` + +Export the Makefile's flags once per shell, then run `go` directly: + +```bash +BLS_DIR="$(git rev-parse --show-toplevel)/third_party/bls-signatures" +export CGO_ENABLED=1 +export CGO_CXXFLAGS="-I$BLS_DIR/build/depends/relic/include -I$BLS_DIR/src/depends/mimalloc/include -I$BLS_DIR/src/depends/relic/include -I$BLS_DIR/src/include" +export CGO_LDFLAGS="-L$BLS_DIR/build/depends/mimalloc -L$BLS_DIR/build/depends/relic/lib -L$BLS_DIR/build/src -ldashbls -lrelic_s -lmimalloc-secure -lgmp" + +go test -race -count=1 -run 'TestName' ./internal/p2p/ +``` + +- `third_party/bls-signatures/build/` exists only where `make build-bls` ran. + In a fresh clone or a new `git worktree`, run it there, or set `BLS_DIR` to + another checkout that already built the same BLS revision. +- macOS: append `-L$(brew --prefix gmp)/lib` to `CGO_LDFLAGS` and + `-I$(brew --prefix gmp)/include` to `CGO_CXXFLAGS`, as the Makefile does. +- CI (`.github/workflows/tests.yml`) installs BLS into `/usr/local` and runs + `go test -race -timeout=5m` over package groups (`make test-group-N + NUM_SPLIT=6`). +- `cmd/abcidump` needs `libpcap-dev`. +- `-count=1` bypasses the Go test cache when re-running unchanged tests. + ## Working with Dependencies and Tools (Go modules, Buf, etc.) - Go dependencies are managed via Go Modules. Only update required modules. @@ -99,7 +135,8 @@ make format ## Common Pitfalls - BLS native dependency must be built before Go binaries (`make build` handles - this; standalone `go build` may fail). + this); standalone `go` commands need the cgo flags from + [Running targeted tests](#running-targeted-tests). - `*.pb.go` files are generated — never edit them by hand. - `gogoproto` extensions (e.g., `nullable`, `customtype`) can produce unexpected Go types; always check the generated code after proto changes. diff --git a/CLAUDE.md b/CLAUDE.md index 048912153..0b92a3a4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,10 @@ # Claude Code Instructions -Follow all rules defined in `AGENTS.md` — it is the single source of truth -for code conventions, repo structure, build/test commands, security policy, -and common pitfalls. +@AGENTS.md + +`AGENTS.md` (imported above) is the single source of truth for code +conventions, repo structure, build/test commands, security policy, and common +pitfalls. Do not manually edit or generate `CHANGELOG.md` for development changes; the release script generates it as part of the release process.