From 3bdab3306691a70cb44e282b2159a67da0452f93 Mon Sep 17 00:00:00 2001
From: Lukasz Klimek <842586+lklimek@users.noreply.github.com>
Date: Tue, 17 Nov 2026 08:12:00 +0000
Subject: [PATCH] docs(agents): document running targeted tests with BLS cgo
flags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
A bare `go test` fails with `dashbls/bls.hpp: No such file or directory`
because only Makefile targets pass the BLS cgo flags. Document the flags,
worktree/macOS/CI hints, and correct the make target descriptions.
CLAUDE.md now imports AGENTS.md with `@AGENTS.md`; a plain-text reference
does not load the file into Claude Code's context.
🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent
Co-Authored-By: Claude Opus 5.5
---
AGENTS.md | 51 ++++++++++++++++++++++++++++++++++++++++++++-------
CLAUDE.md | 8 +++++---
2 files changed, 49 insertions(+), 10 deletions(-)
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.