How cryspen/hax works
Project Type and Purpose
• Hax is a compiler-style tool (a Cargo subcommand) that takes Rust crates (restricted to a functional subset called “hacspec”) and translates them into formal back-end languages (F*, Coq, EasyCrypt, ProVerif). It consists of:
• A Rust-based CLI front end that hooks into rustc and/or uses a standalone “exporter” crate to extract the typed Rust THIR AST as JSON.
• An OCaml-based engine that ingests the JSON AST, runs a pipeline of simplification and elaboration phases, and dispatches to language-specific back ends.
• Auxiliary components: a JS driver + web playground, a Rust test harness for snapshot testing, examples, docs, and CI/deployment tooling (Nix, Docker, GitHub Actions).
High-Level Directory Structure
• Top-level crates:
• cli/driver, cli/subcommands: Rust code implementing cargo hax, orchestrating the workflow.
• frontend/exporter: Rust library/crate to extract the THIR AST to JSON.
• engine/: OCaml code organized as a library (engine/lib/…), a binary driver (engine/bin/…), and a set of back ends (engine/backends/{coq,fstar,easycrypt,proverif}).
• test-harness/: Rust crate for snapshot testing of cargo hax invocations.
• cli/subcommands/engine_debug_webapp: small web app (HTML+JS) for engine debugging in the browser.
• docs/, examples/: documentation and sample Rust crates.
• Build and deployment: Nix (flake.nix, default.nix), Docker (.docker/), GitHub workflows (.github/workflows/), justfile, etc.
Core System Components
A. Input Layer (Rust crate under test)
B. CLI Orchestration (Rust)
– “cargo hax” driver (uses cli/driver)
– Invokes the Rust exporter plugin (frontend/exporter) or calls into rustc to produce JSON AST
C. Exporter / Frontend (Rust)
– Parses/modifies THIR, outputs typed AST JSON
D. Engine Core (OCaml library)
– Pipeline of phases (engine/lib/phases/*.ml), AST utilities, analyses
E. Back End Plugins (OCaml modules under engine/backends/)
– Coq, F*, EasyCrypt, ProVerif, etc.
F. Output Layer
– Generated code/artifacts for the chosen backend
G. Test Harness & QA (Rust test-harness), Examples, Docs
H. Web Playground (JS driver + static site)
Architectural Patterns and Principles
• Pipeline architecture in the engine: discrete, named phases that successively transform the AST
• Plugin-style back ends: each target language is a separate module with a common interface
• Clear separation of concerns:
• Frontend (AST extraction)
• Core transformations (OCaml engine)
• Backend code generation
• Orchestration (Rust CLI)
• Cross-language FFI/IPC boundary between Rust and OCaml (via JSON + command-line invocation)
• Use of Nix/Docker/CI for reproducible builds and multi-platform support
Technologies, Frameworks, Libraries
• Rust crates: cli/driver, frontend/exporter, test-harness, examples, hax-types, hax-lib, etc.
• OCaml ecosystem: Dune build, engine/lib/*, engine/backends/*
• JavaScript: engine/bin/js_driver.ml → JS via js_of_ocaml, web static files under cli/subcommands/engine_debug_webapp
• Build and deployment: Nix Flakes, Docker, just command runner, GitHub Actions workflows