The `cfire` Language & Systems Programming Guide

A deep dive into writing safe, high-velocity systems software in cfire with 1-to-1 ISO C++23 lowering.

1. Philosophy & Architecture

cfire ("Sapphire on Fire") is designed for engineers who want the fast, readable iteration loop of Go and Odin without sacrificing the raw performance or ecosystem of C++23. Every construct in cfire maps predictably to modern C++23 types—meaning zero FFI marshaling, zero hidden garbage collection, and full compatibility with lldb, gdb, Instruments, and Clang sanitizers.

2. Tour of the Toolchain

./cfire run examples/01-hello-core/main.cf
./cfire run --sanitize examples/09-stdlib-test-pointers/main.cf
./cfire build examples/07-types-match-map/main.cf
./cfire test --sanitize examples/09-stdlib-test-pointers/main.cf
./cfire fmt --check examples/
./cfire lsp
./cfire doc --check
./cfire eject examples/08-multi-pkg-cc-build/main.cf ./standalone_cpp

3. Values, Ownership, Parameter Intents & Smart Pointers

Bindings declared with := are const by default. Function parameters default to zero-copy read-only borrows (in), while mut, out, and move parameters require matching call-site annotations and enforce the Law of Exclusivity at call sites (cfire/MUT-ALIAS):

fn compute_fixed_sum(arr: [4]i32, out total: i32) {
    total = arr[0] + arr[1] + arr[2] + arr[3]
}

fn main() {
    owned_box := make(own[Box], Box{Value: 42})
    shared_box := make(shared[Box], Box{Value: 58})
    fixed_arr: [4]i32 = [10, 20, 30, 40]
    mut sum_out: i32 = 0
    compute_fixed_sum(fixed_arr, out sum_out)
}

4. Algebraic Data Types, Struct Tags & Exhaustive `match`

Struct tags (`json:"..."`, `sql:"..."`, `cli:"..."`) drive compile-time code generation for core:json, core:db/sqlite, and core:cli. Algebraic enum types lower to std::variant and enforce exhaustive match checking (cfire/NON-EXHAUSTIVE-MATCH).

5. Fearless Error Handling & `defer`

Fallible functions return T! (std::expected<T, cfire::Error>). Callers propagate errors with try, provide defaults with or val, or recover inline with or err { ... }. Deterministic cleanup is handled via defer.

6. Structured Concurrency & Typed Channels

Use async.scope(workers: N) |scope| { ... } for structured parallel task execution and sync.make_channel[T]() from core:sync for thread-safe typed message passing.

7. Zero-Friction C & C++ Interop

When you write import "c:fast_hash.h" as fh or import "cpp:...", cfire invokes Clang's JSON AST dump, caches the header index in .cfire/cache/ast/, and automatically inserts cfire::c_str(...) at const char* boundaries.

8. Unified Build System (`build.cf`) & CMake Ejection

Add a build.cf file to compile companion C/C++ sources (build.CC), CMake subprojects (build.CMake), or system packages (build.SystemLib). Run ./cfire eject at any time to generate a standalone C++23 + CMakeLists.txt project.

9. Comparisons & Honest Design Trade-Offs

Vs. Cppfront & Carbon: Rather than reskinning all of C++'s accidental complexity, cfire provides a smaller Go/Odin-inspired language with call-site mutation/move visibility, 13 built-in core:* modules, a unified build system, and cfire eject.

Vs. Rust, Zig & Odin: Unlike Zig and Odin (which target the C ABI), cfire natively speaks the ISO C++23 ABI (std::string, std::span, std::expected). Unlike Rust, cfire enforces call-site mutation exclusivity (cfire/MUT-ALIAS) and move tracking (cfire/USE-AFTER-MOVE) without lifetime annotations ('a), paired with first-class Clang sanitizer support (--sanitize) and automatic precompiled header (.pch) acceleration.