reflaxe.rust

Haxe 4.3.7 -> Rust target built on Reflaxe.

This project lets you write Haxe and ship native Rust binaries, with a path for both Haxe-first and Rust-first teams.

Start Here

• New here: Start Here guide
• Building async apps: Async/Await preview guide
• Production rollout: Production Readiness guide
• HXRT overhead visibility: HXRT overhead benchmarks
• Post-1.0 quality cadence: Weekly CI Evidence runbook
• Cross-platform sys risk tracking: Sys Regression Watchlist
• Fast edit-compile-run loop: Dev Watcher guide
• Full docs map: Documentation Index
• Profile/scenario examples map: Examples Matrix

Scaffold A New Project (Generator)

Generate a ready-to-run Haxe.rust project:

npm run dev:new-project -- ./my_haxe_rust_app
cd my_haxe_rust_app

The generated project includes the full task plumbing:

• cargo hx --action run (compile Haxe->Rust, then run)
• cargo hx --action test (compile Haxe->Rust, then test)
• cargo hx --action build --release (production build)
• bash scripts/dev/watch-haxe-rust.sh --hxml compile.hxml (watch loop)
• bash scripts/dev/check-guards.sh (local-path + security wiring checks; gitleaks scan when installed)
• bash scripts/install-git-hooks.sh (installs pre-commit local-path + staged gitleaks checks)

Quick Start (First Successful Run)

1. Install dependencies (toolchain is pinned via lix):

npm install

2. Compile and run the hello example:

cd examples/hello
npx haxe compile.hxml
(cd out && cargo run -q)

3. Run snapshot tests:

npm test

4. Run the CI-style local harness (snapshots + examples):

npm run test:all

Fast Dev Loop (Watcher)

Install watcher engine once:

• Homebrew: brew install watchexec
• Cargo: cargo install watchexec-cli

Then run:

npm run dev:watch -- --hxml examples/hello/compile.hxml

Watch mode uses a session-owned Haxe compile server by default, so compiles are faster after warm-up. Use --no-haxe-server if you want direct compile-only behavior.

More usage options: Dev Watcher guide.

Pick Your Profile

Use -D reflaxe_rust_profile=portable|idiomatic|rusty|metal.

Profile	Best for	What you get
portable (default)	Haxe-first teams	Stable Haxe semantics and portability-first behavior (largest intentional UX/semantic tradeoff envelope vs pure Rust)
idiomatic	Teams that want cleaner Rust output without semantic shifts	Same behavior as portable, cleaner emitted Rust
rusty	Rust-aware teams	Rust-first APIs and borrow/ownership-oriented surface
metal (experimental)	Rust-heavy teams that need typed low-level interop	Rusty+ profile with typed metal injection façade, stricter app-side injection boundaries, and the primary near-pure-Rust hot-path performance objective

Read more: Profiles guide, Rusty profile details, Metal profile details, HXRT overhead benchmarks, and Lifetime encoding design.

Examples

• chat_loopback (cross-profile flagship: portable/idiomatic/rusty/metal)
• profile_storyboard (cross-profile micro-app focused on profile-specific coding style + @:rustTest)
• hello
• async_retry_pipeline
• classes
• serde_json
• sys_file_io
• sys_net_loopback
• sys_process
• sys_thread_smoke
• thread_pool_smoke
• tui_todo

Coverage map: docs/examples-matrix.md.

Most Useful Commands

• Watch mode for local development: npm run dev:watch -- --hxml examples/hello/compile.hxml
• Scaffold a new starter project: npm run dev:new-project -- ./my_haxe_rust_app
• Refresh tracker-backed status docs: npm run docs:sync:progress
• Verify tracker-backed status docs are in sync: npm run docs:check:progress
• Snapshot tests: bash test/run-snapshots.sh
• Upstream stdlib sweep: bash test/run-upstream-stdlib-sweep.sh
• Template task-matrix smoke: bash scripts/ci/template-smoke.sh
• Windows-safe smoke subset: bash scripts/ci/windows-smoke.sh
• HXRT overhead benchmark + soft-budget warnings: bash scripts/ci/perf-hxrt-overhead.sh
• Full local CI equivalent: bash scripts/ci/local.sh
• Clean generated artifacts: npm run clean:artifacts:all

1.0 Status and Roadmap

• Live tracker: Compiler Progress Tracker
• Vision vs implementation: Reality check
• Execution playbook: Road to 1.0
• Weekly post-1.0 operations: Weekly CI Evidence
• Sys regression intake: Cross-Platform Watchlist
• Technical support matrix: v1 scope

Defines (Common)

• -D rust_output=out - output directory for the generated Cargo project
• -D rust_no_build / -D rust_codegen_only - codegen only, skip Cargo build
• -D rust_build_release / -D rust_release - release build mode
• -D rust_target=<triple> - pass target triple to Cargo
• -D rust_idiomatic - alias for -D reflaxe_rust_profile=idiomatic
• -D rust_metal - alias for -D reflaxe_rust_profile=metal
• -D reflaxe_rust_profile=rusty|metal - enable Rust-first profile surfaces
• -D rust_async_preview - enable Rust-first async/await preview (docs/async-await.md)
• -D rustfmt - run cargo fmt on generated output (best effort)

Full list: Defines reference.

Rust Interop

Preferred order:

1. Pure Haxe + runtime/std APIs
2. Typed externs and metadata (@:native, @:rustCargo, @:rustExtraSrc)
3. Framework wrappers around hand-written Rust modules
4. Raw __rust__ only when necessary

Read: Interop guide and Workflow guide.

Installation and Release Docs

• Toolchain install details: Install via lix
• Release process: Release docs