Development Guide¶

This guide is for both humans and agents.

Development environment¶

We use dev container for both local development and CI.

Prerequisites¶

Docker
Dev Container CLI
(Optional) An IDE with dev container support, e.g. VS Code with the Dev Containers extension
All other dependencies are installed in the dev container.

Dev container setup¶

No separate setup is needed. The ./dev.sh script calls devcontainer up automatically, which builds the container image on first run.

Commands¶

The ./dev.sh script runs commands inside the dev container from the host. Omit it if you're already inside.

Bazel¶

Build¶

./dev.sh bazel build //...

Test¶

./dev.sh bazel test //...

CMake¶

Configure¶

./dev.sh cmake -B build

Build¶

./dev.sh cmake --build build

Test¶

./dev.sh ctest --test-dir build --output-on-failure

Format¶

./dev.sh ./tools/format.sh

To check without modifying (used in CI):

./dev.sh ./tools/format.sh --check

Lint¶

./dev.sh ./tools/lint.sh

Docs¶

Build¶

./dev.sh ./tools/docs.sh

Serve¶

./dev.sh ./tools/docs.sh serve

Code style¶

C++¶

Follow Google C++ Style Guide.
Follow Google Abseil C++ Tips of the Week.
Naming deviations:
- Free functions and member methods use snake_case (e.g., to_symbolic, safe_cast, shl, value(), expr()), not PascalCase. This aligns with Z3 and other SMT/hardware libraries in the ecosystem, and reads more naturally for hardware primitives. Static factory methods use PascalCase (e.g., Literal, FromValue, True, False).
- Type traits use snake_case with a _v helper (e.g., is_concrete, is_symbolic_v), following std:: conventions rather than Google's PascalCase.

Bazel¶

Follow BUILD Style Guide.

Doc style¶

Follow Google Markdown Style Guide.
For titles, use Title Case.
For non-title section headings, use Sentence case.
Use plain hyphens (-) instead of em dashes.

Quality checks¶

Before commit, ALWAYS run the following commands and fix any issues you see:

./dev.sh bazel build //...
./dev.sh bazel test //...

./dev.sh ./tools/lint.sh
./dev.sh ./tools/docs.sh

# Run format last so no subsequent edits undo it.
./dev.sh ./tools/format.sh

Commit style¶

Keep the subject line under 72 characters.
Explain why the change is being made.
Describe what has changed at a high level. Don't repeat what's obvious in the change itself.
Prefer one commit per logical change. Don't split into too many tiny commits when they form a single unit of work.
For agents: credit yourself (e.g. using Co-authored-by:) for commits you made.