Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 44 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<base-branch>
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.
Expand Down Expand Up @@ -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.
Expand Down
8 changes: 5 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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.
Loading