Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (59 loc) · 4.81 KB

CLAUDE.md

File metadata and controls

87 lines (59 loc) · 4.81 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build library
cargo build
cargo build --release

# Build eq CLI
cargo build --bin eq --features cli --release

# Test
cargo test
cargo test test_detect_v          # Run a single test by name

# Lint / Format — always run cargo fmt before committing
cargo fmt                         # Auto-fix formatting
cargo fmt -- --check              # Check formatting (CI gate)
cargo clippy -- -D warnings       # Lint (warnings as errors)

# Docs
cargo doc --all-features --no-deps

# Run example
cargo run --example using_equilibrium

# Polyglot demo (TUI works everywhere; GUI needs GPU)
cd examples/polyglot-gui
cargo build --bin polyglot-tui
cargo build --bin polyglot-gui

Architecture

Equilibrium is a Rust library that auto-generates C FFI bindings for foreign-language source files. It implements a three-stage pipeline:

  1. Language Detection (src/detector.rs) — Maps file extensions to one of 10 supported languages (V, Zig, C, C++, C#, Rust, D, Nim, Odin, Hare). find_compiler() uses which to locate installed compiler binaries. Each Language variant knows its extensions, primary/fallback compiler commands, and the CLI flags needed to emit C-compatible output.

  2. Compilation to C (src/compiler.rs) — Invokes the detected compiler with the appropriate flags to produce a .c or preprocessed intermediate file plus an optional .h header. compile_to_c() auto-detects the language; compile_batch() handles multiple files; generate_header() produces headers for languages with cbindgen/native support (Rust, V).

  3. Binding Generation (src/bindings.rs) — Parses a C header (functions, typedefs, structs) and emits Rust extern "C" declarations. BindingOptions controls the module name, include paths, symbol allowlists, and #[derive] attributes. c_type_to_rust() handles the type mapping (e.g. int → c_int, char* → *mut c_char).

src/lib.rs re-exports the public surface: detect_language, compile_to_c, generate_bindings, find_compiler.

eq CLI (src/bin/eq.rs)

The eq binary (feature-gated behind cli) provides four subcommands:

  • eq check — detects all supported compilers and shows versions/paths
  • eq install [names…] — installs missing compilers via the best available package manager; multiple compilers install in parallel. Install order: wax → brew/linuxbrew → apt/dnf/pacman on Linux/macOS, wax → winget → scoop on Windows.
  • eq build [args…] — runs cargo build with all known compiler bin dirs prepended to PATH (linuxbrew, homebrew, /usr/local/sbin, etc.)
  • eq generate <header> [-o file] — emits Rust extern "C" bindings from a C header via equilibrium_ffi::generate_bindings

Helper Libraries

Language-specific ergonomic crates live in sibling directories:

  • equilibrium-rust/ — proc macro #[ffi] attribute
  • equilibrium-nim/ — Nim type conversion helpers
  • equilibrium-d/ — D @ffi UDA and extern(C) helpers
  • equilibrium-zig/ — Zig comptime FFI helpers

Examples

  • examples/using_equilibrium.rs — demonstrates all three pipeline stages (detect, compile, generate bindings, scan_directory)
  • equilibrium::load() is the primary one-call entry point; prefer it in docs and demos when the goal is to load a single C source and use generated bindings
  • examples/demo-app/ — minimal end-to-end demo: build.rs compiles math.c via cc and generates bindings with equilibrium-ffi; main.rs calls C functions through the generated include!()d bindings
  • examples/full-demo/ — full demo calling a C calculator library from Rust
  • examples/polyglot-gui/ — interactive polyglot dashboard with a ratatui TUI (polyglot-tui) and a GPUI GUI (polyglot-gui). Calls live FFI into C, C++, Zig, Nim, V, D, Odin, and Rust. build.rs uses find_bin() with hardcoded linuxbrew fallbacks so compilers are found regardless of the shell PATH that cargo inherits.

Zig FFI notes

Zig objects must be compiled with -fPIC -OReleaseFast to link cleanly into Rust's PIE binary. ReleaseFast removes safety checks that otherwise pull in Zig's stdlib panic infrastructure, which conflicts with the linker. See examples/polyglot-gui/build.rs.

V FFI on Linux

V's runtime cannot link directly into Rust's PIE binary. The polyglot-gui uses a C shim (v_module_shim.c) that implements the same exported symbols with identical semantics.

Windows build notes

The polyglot-gui binary targets D3D11 (no Vulkan needed). Build from Windows PowerShell:

cargo build --release --bin polyglot-gui

The TUI binary works cross-platform. The eq CLI on Windows uses %TEMP% as the working directory when invoking winget/scoop to avoid UNC path errors from WSL2 filesystem paths.