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.

Current posture:

• architecture and contract model: strong
• validated implementation baseline: broad and evidence-backed
• public release posture: stable 1.x, with explicit documented caveats and proof-depth limits (docs/semver-release-posture.md)

Why reflaxe.rust

• portable contract (default): Haxe-first semantics with portability-oriented behavior and predictable stdlib/runtime integration.
• metal contract: Rust-first boundary rules, typed interop surfaces, and performance-focused paths.
• Portable abstractions do not have to mean wrapper tax: when semantics line up, shared portable surfaces can lower directly to native Rust representations (for example reflaxe.std.Option/Result -> Rust Option/Result).
• reflaxe.std is the start of a broader portable idiom layer, not a Rust-only wrapper module. V1 is intentionally narrow (Option / Result) so semantics and migration stay stable before the portable API surface grows.
• Portable lowering can still target native Rust representations when semantics match, but that is an implementation win inside the portable contract, not a silent switch into native-lane code. See Portable near-native guidance.
• CI evidence: snapshots, negative policy fixtures, runtime/optimizer plan reports, and HXRT overhead tracking are all part of the default workflow.

Start Here

• New here: Start Here guide
• Portable-first path: Profiles, Portable near-native guidance, Examples Matrix
• Metal-first path: Metal profile, Portable near-native guidance, profile_storyboard / metal examples
• Release / operations path: Production Readiness guide, Semver and release posture, Weekly CI Evidence runbook
• Tooling / workflow: Dev Watcher guide, Async/Await guide, Documentation Index

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|metal.

Profile	Best for	What you get
portable (default)	Haxe-first teams	Stable Haxe semantics and portability-first behavior
metal	Rust-aware teams and performance-critical paths	Rust-first APIs, stricter app-side injection boundaries, and primary near-pure-Rust hot-path performance objective

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

Examples

• chat_loopback (cross-profile flagship: portable/metal)
• profile_storyboard (cross-profile micro-app focused on profile-specific coding style + @:rustTest)
• metal_first_dataflow (dedicated metal-style reference: Result/Option/Vec with strict-boundary-safe app code)
• hello (portable sanity check)
• 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

Status and Readiness

• Current release posture: Semver and release posture
• Production rollout guidance: Production Readiness
• Current readiness tracker: Compiler Progress Tracker
• Ongoing validation cadence: Weekly CI Evidence
• Technical support matrix: feature support matrix
• Sys regression intake: Cross-Platform Watchlist

Historical closeout records:

• GA decision record
• GA caveat classification
• Road to 1.0

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 reflaxe_rust_profile=portable|metal - select profile contract
• -D rust_async - enable Rust-first async/await support (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