mirror_bridge: Instructions file for Codex

AGENTS.md

mirror_bridge is a C++26 reflection-based binding generator: it inspects C++ structs/classes at compile time (via P2996 reflection) and emits zero-overhead Python, Lua, JavaScript and C# bindings — no hand-written binding code. The one critical constraint: it requires a C++26 reflection compiler — either stock GCC 16+ (g++ -std=c++26 -freflection) or Bloomberg's clang-p2996 (with libc++ and the <meta> header). A pre-reflection distro compiler will fail with "no member named 'meta'" or an unknown -freflection flag. Unless your host already has GCC 16+ or clang-p2996, compile inside the project's Docker container (or a GitHub Codespace). The CLI auto-detects whichever compiler is present; override with MB_CXX. Editing, searching, and reading code on the host is always fine.

Note: P3394 field annotations ([[=exclude{}]], [[=readonly{}]]) work under both compilers, in the Python backend. The Lua and JavaScript backends do not read them yet: they enumerate every named member, so an annotated field is still bound there.

Environment setup

The reflection compiler lives in the Docker image. Prefer pulling the pre-built image over building from source (~45–90 min).

# Pull + tag the pre-built image (interactive helper, choose option 1)
./start_dev_container.sh

# Or pull directly
docker pull ghcr.io/franciscothiesen/mirror_bridge:latest
docker tag  ghcr.io/franciscothiesen/mirror_bridge:latest mirror_bridge:latest

start_dev_container.sh creates a persistent container named mirror_bridge_dev with the repo mounted at /workspace (host edits are immediately visible inside, and vice versa).

To run a command inside the container non-interactively (scriptable for an agent):

# One-off, throwaway container with the repo mounted:
docker run --rm -v "$(pwd):/workspace" -w /workspace mirror_bridge:latest \
    bash -lc './tests/run_all_tests.sh'

# Or exec into the long-lived dev container if it's already running:
docker exec -w /workspace mirror_bridge_dev bash -lc 'tools/mirror_bridge version'