fun/docs/rust.md

#endif

case OP_RADD: {
#ifdef FUN_WITH_RUST
    (void)fun_op_radd(vm);
#else
    vm_raise_error(vm, "RADD requires FUN_WITH_RUST=ON at build time");
    push_value(vm, make_nil()); // or follow your opcode’s error convention
#endif
    break;
}

Notes:

• Follow the existing opcode conventions for your module (core, math, strings, etc.).
• If your build puts the Rust symbol into a static library, make sure the VM target links it when FUN_WITH_RUST is ON (the top-level CMake already does this for the examples provided).

Using Rust-backed opcodes from Fun

Once wired, expose the opcode via a builtin function or directly in bytecode. The repository includes a demo builtin rust_hello() that returns a Rust-generated string.

Run the example:

1. Build with Rust enabled (Debug): cmake -S . -B build_debug -DFUN_WITH_RUST=ON cmake --build build_debug --target fun

2. Execute the script: build_debug/fun examples/rust_hello.fun

Expected output: Hello from Rust ops!

If you build without Rust, calling rust_hello() raises a runtime error indicating that Rust integration is disabled.

Stack discipline and error handling

• Always pop exactly the arguments you expect and push exactly the results your opcode promises. Mismatch leads to stack corruption and hard-to-debug failures.
• Return an int status to the VM (0 for success). If your project uses a different convention for some opcodes, match it consistently.
• Validate types where appropriate (e.g., ensure values are integers before arithmetic). If a check fails, use the VM’s error mechanism (e.g., vm_raise_error) and follow the module’s convention on what to push after errors.

Data types and FFI surface

The minimal helpers shown cover 64-bit integers and simple strings. Extending the Rust<->C bridge usually involves:

• Declaring additional extern "C" functions in Rust that the C VM implements (to read/write values on the stack, construct arrays/maps/strings, etc.).
• Ensuring all pointers and lifetimes are well-defined: strings pushed to the VM should be copied or allocated using VM facilities so they remain valid after the call.
• Keeping Rust no_std unless you add an allocator and link setup to support std.

Troubleshooting

• Link errors: Make sure FUN_WITH_RUST=ON for your build directory and that the Rust library is compiled before linking the VM. Use the rust_ops_build target if provided by your profile.
• Missing symbol at runtime: Confirm #[no_mangle] and extern "C" on the Rust function and that C sees the correct prototype.
• Wrong or garbled values: Double-check stack order (Fun uses a stack VM; many ops pop in reverse order: first b, then a).
• No output from rust_hello(): Ensure you run a binary built with FUN_WITH_RUST=ON; otherwise the VM deliberately raises an error and returns Nil for that call.

Small end-to-end checklist

1. Write the Rust function in src/rust/src/lib.rs with extern "C", #[no_mangle].
2. Use FFI helpers to pop arguments and push results.
3. Add a C-side case under src/vm/... (or src/vm/rust/...) that calls your Rust function when the opcode executes.
4. Ensure the build links Rust code when FUN_WITH_RUST=ON.
5. Add or reuse a builtin in the parser/runtime to surface your opcode to Fun code.
6. Build and run a small .fun example to validate behavior.

References in this repo

• Rust lib with examples: src/rust/src/lib.rs
• C-side hello wiring: src/vm/rust/hello.c
• Demo script: examples/rust_hello.fun
• General opcode reference: docs/opcodes.md

Links

Authoritative and practical resources on exposing Rust to C (FFI) and maintaining a C-compatible API:

• Rustonomicon: FFI overview and best practices https://doc.rust-lang.org/nomicon/ffi.html
• Rustonomicon: Calling Rust code from C https://doc.rust-lang.org/nomicon/ffi.html#calling-rust-code-from-c
• The Rust Book: Unsafe and FFI (extern, #[no_mangle], calling Rust from other languages) https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html#calling-rust-functions-from-other-languages
• Rust Reference: extern blocks, ABIs, and linkage https://doc.rust-lang.org/reference/items/external-blocks.html
• Rust FFI Omnibus (examples for many patterns, including Rust ↔ C) https://github.com/shepmaster/rust-ffi-omnibus
• cbindgen (generate C headers from Rust libraries) https://cbindgen.github.io/cbindgen/
• bindgen (generate Rust bindings to existing C headers; useful when mixing C and Rust) https://github.com/rust-lang/rust-bindgen

Return-only Rust string helper

Two variants are available for passing a string to Rust and getting output:

• rust_hello_args(msg)
  • Rust side prints the message to stdout; Fun receives Nil. Use when you only want side-effect printing.
• rust_hello_args_return(msg)
  • Rust side does not print; it returns the provided string to Fun (useful for assignment or chaining).

Example:

msg = rust_hello_args_return("Hello back from Rust (no print)!")
print(msg)

See examples/rust_hello_args_return.fun for a complete script.