Feature Request

Provide a comprehensive design for a Rust build plugin/integration that invokes the Fory foryc compiler during cargo build, with multi-platform foryc binaries distributed similarly to the Java/Maven plugin proposal.

Is your feature request related to a problem? Please describe

Rust users must manually install Python + fory-compiler or run foryc out-of-band. This makes builds non-reproducible and harder to set up in CI, especially across macOS/Linux/Windows and x86_64/aarch64.

Describe the solution you'd like

Below is a detailed design/requirements proposal for Rust build integration and the expected packaging of foryc binaries. This is a design-only request (not implementation).

Goals

• Provide first-class Rust build integration that runs foryc during cargo build.
• Support multi-platform foryc binaries:
  • OS: macOS, Linux, Windows
  • Arch: x86_64, aarch64 (arm64)
• Keep the workflow cargo-native, requiring no Python installation on end-user machines.

Non-Goals

• Re-implementing foryc in Rust
• Replacing the PyPI distribution
• Supporting OS/arch beyond macOS/Linux/Windows and x86_64/aarch64

1) Rust build integration approach

Recommended shape

Provide a small Rust helper crate, e.g. foryc-build, used from build.rs:

// build.rs
fn main() {
    foryc_build::compile(&foryc_build::Config {
        schema_dir: "src/fdl".into(),
        includes: vec!["**/*.fdl".into()],
        out_dir: "${OUT_DIR}/fory".into(),
        lang: "rust".into(),
        import_paths: vec!["src/fdl".into()],
        extra_args: vec![],
        foryc_path: None,
    }).expect("foryc failed");
}

Behavior

• Resolve platform (OS/arch) at build time.
• Locate the correct embedded foryc binary (see section 2).
• Extract to OUT_DIR/foryc/{version}/{os}-{arch}/foryc[.exe].
• Execute foryc with config arguments.
• Emit cargo:rerun-if-changed for the schema directory and import paths.

Alternative: procedural macro

A proc-macro is possible but not ideal because it runs after codegen and complicates incremental builds. build.rs is the standard approach for code generation.

2) foryc binary distribution

Use the same PyInstaller-built binaries as the Maven plugin proposal:

• foryc-macos-x86_64
• foryc-macos-aarch64
• foryc-linux-x86_64
• foryc-linux-aarch64
• foryc-windows-x86_64.exe
• foryc-windows-aarch64.exe

Packaging in Rust

Option A (preferred):

• Publish a Rust crate foryc-bin that embeds the binaries as crate resources.
• foryc-build depends on foryc-bin and performs runtime selection.

Option B:

• foryc-build directly embeds the binaries to avoid two crates.

3) Runtime selection logic

OS/arch normalization

• OS detection: cfg!(target_os = "windows"|"macos"|"linux")
• Arch detection: cfg!(target_arch = "x86_64"|"aarch64")
• Fallback: explicit error message for unsupported platforms

Resolution order

1. If FORYC_PATH env var is set, use it.
2. Else use embedded binary for OS/arch.
3. Extract if missing and set executable bit (unix).

4) Cargo integration details

Emitted build outputs

• cargo:rerun-if-changed for schema files
• cargo:rerun-if-env-changed=FORYC_PATH

Output locations

• OUT_DIR/foryc/... for the extracted binary
• OUT_DIR/fory/... for generated Rust code

Module integration

• Support writing to src/generated for non-OUT_DIR workflows
• Example: include the generated module via include!(concat!(env!("OUT_DIR"), "/fory/mod.rs"));

5) GitHub Actions workflow

A shared workflow (similar to the Java/Maven one) should:

1. Build PyInstaller binaries for macOS/Linux/Windows x86_64 + aarch64
2. Upload artifacts
3. Package binaries into the Rust crate(s)
4. Publish crates on tagged releases

6) Documentation updates

Update docs/compiler/compiler-guide.md with a new section:

• “Rust (build.rs + foryc-build)”
• Include build.rs example
• Explain how to override FORYC_PATH
• Document supported OS/arch and expected artifacts

7) Acceptance Criteria

• cargo build runs foryc automatically without Python installed.
• Correct foryc binary is selected on macOS/Linux/Windows, x86_64/aarch64.
• GitHub Actions builds and packages binaries for all targets.
• Documentation updated with Rust build integration steps.

Describe alternatives you've considered

• Manual foryc invocation before cargo build (manual and error-prone).
• Docker-based codegen (extra dependency and slower builds).
• Rewriting foryc in Rust (out of scope).

Additional context

This can be implemented in phases:

1. CI workflow to build foryc binaries
2. foryc-build Rust crate
3. Documentation updates