binit

Monorepo for generating x86 instruction test cases, storing them in PostgreSQL, running them against Aegis, and browsing the results locally.

Python setup

Install the base Python project:

uv sync

Install workflow-specific extras when needed. The generator, web UI, and lifter comparison backends have separate dependency sets.

The shared PostgreSQL DSN defaults to:

postgresql://x86db:x86db@localhost:5432/x86db

Override it with X86DB_DSN when needed. Keep local overrides in .env; .env.example documents the expected variable.

Database

Start PostgreSQL and the read-only visualizer:

docker compose up --build -d

Open http://127.0.0.1:5000. PostgreSQL listens only on 127.0.0.1:5432. See db/README.md for initialization, reset, and validation details.

Generate test shapes

Additional test shapes can be written to generator/data/insn.json

Generate test cases

Populate a running local database from the test shapes using :

uv run --extra generator python generator/make_test_cases.py

The generator will clear the db!

Generating test results

Convert test cases to test results with aegis:

cd aegis && just run

Compare lifters

Install one comparison backend and replay Aegis results against it:

uv sync --extra lifter-unicorn
uv run lifter-compare --tool unicorn --sample-states-per-case 10

Run the standalone B2R2 comparison tool with:

dotnet run --project tests/fsharp/b2r2_compare -- --sample-states-per-case 10

Run the standalone Binsec comparison tool after creating its project-local opam switch as described in tests/README.md:

opam exec --switch ./tests/ocaml/binsec_compare -- \
  dune exec --root tests/ocaml/binsec_compare ./main.exe -- --sample-states-per-case 10

See tests/README.md for the supported tools, generated CSV output, and backend-specific requirements.