Module user_guides

ocaml-interop: OCaml and Rust Integration

Zinc-iron alloy coating is used in parts that need very good corrosion protection.

Important Notices:

• API IS CONSIDERED UNSTABLE AT THE MOMENT AND IS LIKELY TO CHANGE IN THE FUTURE.
• Starting with version 0.11.0, only OCaml 5.x is supported.

This library facilitates interoperability between OCaml and Rust.

This document provides a structured guide to using ocaml-interop, covering fundamental Foreign Function Interface (FFI) calls and progressing to more advanced concepts.

Table of Contents

• Part 1: Initial Usage - A Brief Overview
  • 1.1 Exporting Rust Functions to OCaml: An Introduction
  • 1.2 Invoking OCaml Functions from Rust: An Introduction
  • 1.3 The OCaml Runtime Handle: OCamlRuntime
• Part 2: Fundamental Concepts
  • 2.1 Representing OCaml Values within Rust
  • 2.2 Converting Data Between Rust and OCaml
• Part 3: Exporting Rust Functions to OCaml
  • 3.1 The #[ocaml_interop::export] Macro
  • 3.2 Argument Types and Rooting Considerations
  • 3.3 Return Types
  • 3.4 Panic Handling Mechanisms
  • 3.5 Bytecode Function Generation
  • 3.6 The noalloc Attribute
  • 3.7 Direct Primitive Type Mapping
• Part 4: Invoking OCaml Functions from Rust
  • 4.1 The ocaml! Macro
  • 4.2 Passing Arguments to OCaml
  • 4.3 Receiving Return Values from OCaml
  • 4.4 Handling OCaml Exceptions from Rust
• Part 5: Managing the OCaml Runtime (for Rust-driven programs)
  • 5.1 Runtime Initialization
  • 5.2 Acquiring the Domain Lock
• Part 6: Advanced Topics
  • 6.1 In-depth Examination of Lifetimes and GC Interaction
  • 6.2 OCamlRef<'a, T> Detailed Explanation
  • 6.3 Interacting with OCaml Closures
  • 6.4 Tuples
  • 6.5 Records
  • 6.6 Variants and Enums
  • 6.7 Polymorphic Variants
  • 6.8 Bigarrays (Placeholder)
  • 6.9 Threading Considerations (Placeholder)
• Part 7: Build and Link Instructions
  • 7.1 OCaml Programs Calling Rust Code
  • 7.2 Rust Programs Calling OCaml Code

References and Further Reading

• OCaml Manual: Chapter 20 Interfacing C with OCaml
• Safely Mixing OCaml and Rust paper by Stephen Dolan.
• Safely Mixing OCaml and Rust talk by Stephen Dolan.
• CAMLroot: revisiting the OCaml FFI.
• caml-oxide, the code from that paper.
• ocaml-rs, another OCaml<->Rust FFI library.

Modules

part1_initial_usage_a_brief_overview

Part 1: Initial Usage - A Brief Overview

part2_fundamental_concepts

Part 2: Fundamental Concepts

part3_exporting_rust_functions_to_ocaml

Part 3: Exporting Rust Functions to OCaml

part4_invoking_ocaml_functions_from_rust

Part 4: Invoking OCaml Functions from Rust

part5_managing_the_ocaml_runtime_for_rust_driven_programs

Part 5: Managing the OCaml Runtime (for Rust-driven programs)

part6_advanced_topics

Part 6: Advanced Topics

part7_build_and_link_instructions

Part 7: Build and Link Instructions