bind-cpp

Binding C++ with mirror_bridge

mirror_bridge auto-discovers every struct/class in a directory of C++ headers and compiles a binding module. Nobody writes binding code: not the user, not you.

Procedure

1. Locate the toolchain. Try in order:

   • mirror_bridge version (pip install: pip install mirror-bridge)
   • The mirror_bridge MCP tools, if connected (generate_bindings, doctor, check_binding_drift)
   • docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/franciscothiesen/mirror_bridge:latest bash tools/mirror_bridge ... (inside a mirror_bridge checkout)

   If none works, suggest pip install mirror-bridge (requires Docker) and stop.

2. Generate. Always use --json and parse stdout (it is exactly one JSON object; progress goes to stderr):

   mirror_bridge generate <header_dir> --module <name> --lang python --json
   

   --lang choices: python, lua, js, all. Extra include roots: -I <dir>.

3. On failure, read errors[].suggestion — it names the fix. The common loop:

   • "member type has no converter": open the named header, find the offending member (handles, mutexes, raw pointers to user types, function pointers), and annotate it:

     #include "python/mirror_bridge_annotations.hpp"
     using mirror_bridge::exclude;
     
     struct Engine {
         double speed;                      // bound
         [[=exclude{}]] void* impl_handle;  // skipped
     };
     

     Use // MIRROR_BRIDGE_SKIP on the line directly above a class to skip the whole class, or // MIRROR_BRIDGE_SKIP_FILE to skip a file. Re-run generate. Repeat until "status": "ok".

   • Environment problems (compiler, headers): run mirror_bridge doctor --json and apply the hint of each failed check.

4. Verify. Import and exercise the module; the .so/.node is listed in the JSON outputs:

   PYTHONPATH=build python3 -c "import <name>; print(dir(<name>))"