Development and Testing

Development & Testing

Columbus is Go (1.26+) with cgo and the fts5 build tag always on (tree-sitter and SQLite are C). The Makefile pins both — go through it, or remember -tags fts5 CGO_ENABLED=1.

Setup

git clone https://github.com/orafaelfragoso/columbus
cd columbus
brew install zig goreleaser ripgrep ast-grep   # toolchain (macOS)
make setup       # fetch model weights + libtokenizers.a + onnxruntime -> ~/.columbus/libs
make build       # -> dist/columbus
make install     # -> ~/.local/bin/columbus (override with PREFIX=/usr/local/bin)
export COLUMBUS_ORT_LIB="$HOME/.columbus/libs/libonnxruntime.dylib"  # .so on linux

The embedding engine needs two native libs: libtokenizers.a (linked at build time — point the linker at it with CGO_LDFLAGS=-L$HOME/.columbus/libs, which the Makefile exports by default) and an onnxruntime shared library (loaded at runtime via COLUMBUS_ORT_LIB). make setup fetches both plus the model. Without them the build still works but search falls back to keyword.

Make targets

Target	What it does
make setup	Fetch model + libtokenizers.a + onnxruntime into ~/.columbus/libs
make build	Build dist/columbus (-tags fts5, version stamped)
make install	Build into $PREFIX (default ~/.local/bin)
make test	go test -tags fts5 ./...
make test-short	go test -tags fts5 -short ./...
make vet	go vet -tags fts5 ./...
make fmt	gofmt -w .
make cover	Coverage profile + summary
make clean	Remove dist/ and coverage files

Linting

golangci-lint run ./...

CI runs four jobs on every PR — test, lint, govulncheck, and smoke (build the full semantic binary, onboard a fixture repo, assert search returns a vector-backed hit) — and they are required to pass before merge. Each job prefetches the native deps so the cgo packages link.

Version stamping

make and goreleaser both stamp main.version, main.commit, and main.date via -ldflags, so columbus version reports real build metadata in releases.

Project layout

The CLI entry point is cmd/columbus; everything else is under internal/ (index, search, show, embed, knowledge, memory, work, store, extract, live, render, tui, …). Columbus itself is a great way to explore it:

columbus reindex && columbus graphs

Related

Releasing · Contributing · Installation