Using Native Rust Crates

Flame’s philosophy is: “Don’t reinvent the wheel; just use Rust’s.”

Best Practice

While you can import crates directly, Flame highly recommends creating a custom native plugin and using complex native Rust crates within that plugin instead. This allows you to encapsulate complex generics, lifetimes, and wrapper types entirely inside Rust, exposing a clean, simple API to Flame.

Flame treats Rust crates as a first-class source language. When you build a Flame project, the compiler resolves Rust dependencies, generates static bridges, and statically compiles them directly into your final executable binary.

---

1. Adding a Crate (flame.toml)

Add any public crate from crates.io under [native-dependencies]:

[package]
name = "my_app"
version = "0.1.0"

[native-dependencies]
uuid = "1.0"
axum = "0.7"
regex = "1.10"
chrono = "0.4"

---

2. Importing the Crate

In your Flame .fm files, import the crate using the native. prefix:

import native.uuid
import native.chrono

fn main() {
    let id = uuid.new_v4()
    print($"Generated UUID: {id}")
}

---

3. Discovering APIs: docs.rs & .fmi Intellisense

Because Flame links directly with Rust, the API you call in Flame is identical to the Rust crate API:

1. Docs on docs.rs: You can look up any crate on docs.rs to see its functions, structs, and methods.
2. VS Code Intellisense (.fmi): When you run flame build or flame run, the compiler runs cargo rustdoc to generate .fmi (Flame Meta Interface) files.
3. Editor Autocomplete: In VS Code, typing uuid. immediately displays completion items, argument signatures, and original crate docstrings!

---

4. Reproducible Builds (flame.lock)

When you build a Flame project with native dependencies, the underlying Cargo lockfile is automatically hoisted to the root of your project as flame.lock.

You should commit flame.lock to your version control system. This ensures that every developer and CI pipeline builds against the exact same versions of native dependencies, guaranteeing reproducible builds and heavily reducing compilation time.

---

Under the Hood: The Application-Specific Native Runtime Pipeline

Flame ensures that native crates are incorporated only when required by the application’s dependency graph:

[ flame.toml ] ──► [ flame install ] ──► [ .fmi Interface Metadata ]
                                                │
[ Flame Source ] ──► [ Dependency Analysis ] ───┴──► [ Application-Specific Runtime ]
                                                               │
                                                          Rust / Cargo
                                                               │
                                                             LLVM
                                                               │
                                                               ▼
                                                        [ Native Binary ]

1. Interface Resolution: flame install resolves dependencies and caches .fmi interface files.
2. Selective Inclusion: If a crate listed in flame.toml is not actually imported or referenced by the code, it is excluded from the specialized runtime.
3. Native Compilation: The specialized runtime is compiled with LLVM optimizations into an optimized machine code binary.
4. Clean Filesystem Access: Standard builds interact directly with the real host filesystem without VFS overhead.