reflaxe.go

Haxe 4.3.7 -> Go compiler target built on Reflaxe.

Write Haxe, generate readable Go, and choose between:

• the default product path (portable) for normal Haxe code that should still generate good Go, or
• an explicit Go-native authoring contract (metal) for stricter native lanes.

metal is not required for good Go output. Use it when you intentionally want Go-native APIs, stricter boundaries, and fail-fast checks around native lanes.

Start here

If you are new, read these first:

1. docs/start-here.md
2. docs/index.md
3. docs/glossary.md

Terms

• profile: build contract that controls semantics and policy defaults.
• portable: portability-first profile contract.
• metal: Go-first profile contract with stricter defaults.
• Go-native: APIs or behavior tied specifically to Go.
• hxrt: runtime support package copied into generated Go output.

Quick start

npm install
npm run hooks:install
npm run dev:hx -- --project examples/tui_todo --profile portable --action run

That gets a fresh checkout to a running generated-Go example. Use portable first unless you specifically need Go-native authoring constraints from metal.

Validation commands

After the first example runs, use these commands to validate changes:

# full snapshot suite
npm test

# examples matrix
python3 test/run-examples.py

# full local CI harness
python3 test/run-ci.py

Which profile should I choose?

Choose one profile per build. You can still design one codebase with mostly portable modules plus explicit Go-native adapters or @:goMetal lanes.

If most of this build wants...	Choose
Normal Haxe authoring, cross-target-friendly code, and safe Go output	portable
Explicit Go-native APIs, stricter policy, and fail-fast native-lane checks	metal

Can I mix portable and metal-style code?

Yes, with one important distinction:

• A single compiler invocation selects one profile: portable or metal.
• A codebase can mix layers. Keep shared/domain code portable, then isolate Go-specific code behind typed adapters, go.* APIs, or @:goMetal lanes.
• In a portable build, those native islands can be warned about or rejected by policy. The compiler can also lower portable code to metal-like Go when it can prove the faster lowering preserves portable semantics.
• In a metal build, the whole build opts into stricter Go-native defaults and fail-fast checks for supported native surfaces.

So portable is the default for most projects, including projects that contain small Go-specific islands. Use metal when the build itself is intentionally a Go-first artifact.

Detailed behavior and policy knobs: docs/profiles.md

Example apps

Example	Profile support	Why run it
examples/tui_todo	portable only	Portable CLI baseline and deterministic output contract.
examples/profile_storyboard	portable only	Portable dashboard/reporting baseline.
examples/interop_smoke	portable + metal	Typed interop patterns (@:go.import, receiver/name metadata).
examples/worker_pool_select	portable + metal	Go channel/select usage and profile comparison.
examples/pulseforge	portable + metal	Flagship app with core and go_native variants.
examples/fluxproxy	portable + metal	Flagship proxy app with core and go_native variants.

Full matrix: docs/examples-matrix.md

Most useful commands

• Snapshots: python3 test/run-snapshots.py
• Semantic diff: python3 test/run-semantic-diff.py
• Examples matrix: python3 test/run-examples.py
• Full CI harness: python3 test/run-ci.py
• Profile perf harness: npm run test:perf:go
• App perf harness: npm run test:perf:apps
• New project: npm run dev:new-project -- ./my_haxe_go_app
• Compile/run wrapper: npm run dev:hx -- --project <dir> --profile <portable|metal> --action <compile|run|build|test|vet|fmt>

Output model

The generated Go directory is controlled by -D go_output=<dir> in the selected .hxml file. Example projects usually write to out_<profile> or out_<profile>_ci so portable and metal builds do not overwrite each other.

The quick-start command above uses the portable TUI todo config, so it emits:

examples/tui_todo/out_portable/
  go.mod
  main.go
  module_<haxe_module>.go
  hxrt/
    *.go

Generated output directories are safe to delete. They are regenerated on the next compile or run.

You can override the generated output directory through the dev wrapper:

npm run dev:hx -- --project examples/tui_todo --profile portable --out /tmp/tui_todo_go --action run

By default the backend runs go build after codegen. Use -D go_no_build for codegen-only workflows.

Related docs

• Docs map: docs/index.md
• Glossary: docs/glossary.md
• Start guide: docs/start-here.md
• Profiles and policy: docs/profiles.md
• Profile semantics guide: docs/profile-semantics-guide.md
• Portable contract: docs/portable-canonical-contract.md
• Versioned semantics: docs/portable-semantics-v1.md
• hxrt runtime: docs/hxrt-runtime.md
• Feature support matrix: docs/feature-support-matrix.md
• Defines reference: docs/defines-reference.md
• Semantic diff guide: docs/semantic-diff-guide.md
• Release readiness checklist: docs/release-readiness-checklist.md