llama_cpp_sys/

lib.rs

//! Raw FFI bindings to [llama.cpp](https://github.com/ggml-org/llama.cpp),
//! plus the first-party C++ shim (`wrapper.cpp`) that exposes the `_c`-suffixed
//! symbols our Rust callers consume.
//!
//! # Activation
//!
//! The real bindings are hidden behind the `bindings` cargo feature. A default
//! build (`cargo build -p llama-cpp-sys`) compiles this crate to an empty
//! shell on every target — this keeps the workspace-wide `cargo clippy` /
//! `cargo check` on Linux CI runners green, because llama.cpp's cmake build
//! requires a C++ toolchain and pulls in ~180 MB of source.
//!
//! To get the actual FFI surface, build with `--features bindings`. The
//! build script will use the in-tree `vendor/llama-cpp` directory if
//! present, and otherwise clone the pinned commit
//! `b46812de78f8fbcb6cf0154947e8633ebc78d9ac` from GitHub into `$OUT_DIR`.
//!
//! # Safety and stability
//!
//! This is a `-sys` crate: every item under [`bindings`] is `unsafe extern "C"`
//! and mirrors the upstream C ABI (after the `_c` suffix introduced by
//! `wrapper.cpp`) one-to-one. It is not meant to be consumed directly outside
//! the workspace. The safe wrapper crate `xybrid-llama` owns the RAII, typed
//! error mapping, and streaming-trampoline concerns.
//!
//! The generated bindings are intentionally *not* re-exported transitively:
//! downstream crates opt in explicitly by depending on `llama-cpp-sys` with
//! the `bindings` feature and using the items behind [`bindings`].
//!
//! # Phase note (epic: `llamacpp-crate-split`)
//!
//! The extern declarations in [`bindings`] are generated by bindgen from
//! `wrapper.h`, which declares the first-party `_c` shim surface consumed by
//! `xybrid-llama`.

#![allow(non_camel_case_types, non_snake_case, non_upper_case_globals)]

#[cfg(feature = "bindings")]
pub mod bindings {
    //! Generated FFI bindings emitted by `bindgen` against [`wrapper.h`].
    //!
    //! Phase 5 of the `llamacpp-crate-split` epic — replaces the
    //! prior 26-symbol hand-written `extern "C" {}` block. Bindgen
    //! processes `wrapper.h` (which both #includes `<llama.h>` and
    //! declares the first-party `_c` shim functions) and emits one
    //! generated `bindings.rs` file consumed via `include!` below.
    //!
    //! The allowlist in `build.rs` keeps the surface focused on
    //! `llama_.*` (functions, types, and `LLAMA_.*` constants);
    //! `ggml_.*` is intentionally NOT allowlisted because no
    //! `xybrid-llama` / `xybrid-core` consumer references a `ggml_*`
    //! symbol directly — wrapper.cpp handles all ggml interop.
    //!
    //! See `.notes/bindgen-symbol-diff.md` for the symbol-by-symbol
    //! diff against the pre-Phase-5 hand-written list.

    // Mirror `mlx-c-sys::bindings`'s lint allowances. Bindgen output
    // routinely trips dead_code, improper_ctypes, and the broader
    // clippy lints; the wide allowances keep the generated module
    // lint-free without needing to post-process bindings.rs.
    #![allow(
        non_camel_case_types,
        non_snake_case,
        non_upper_case_globals,
        dead_code,
        improper_ctypes,
        clippy::all,
        clippy::pedantic,
        clippy::nursery,
        clippy::cargo
    )]

    use std::os::raw::{c_char, c_int, c_void};

    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

    /// Convenience alias for the bindgen-generated streaming callback
    /// typedef. Bindgen emits `llama_token_callback_c` as
    /// `Option<unsafe extern "C" fn(...)>` (Option already wrapping the
    /// function pointer); `TokenCallback` here is the inner `unsafe
    /// extern "C" fn(...)` so `xybrid-llama` can construct
    /// `Some(streaming_trampoline::<F>)` against an
    /// `Option<TokenCallback>`-shaped FFI argument.
    pub type TokenCallback = unsafe extern "C" fn(
        token_id: c_int,
        token_text: *const c_char,
        user_data: *mut c_void,
    ) -> c_int;
}

/// Initialize the llama.cpp backend. Idempotent across calls thanks to the
/// internal [`std::sync::Once`] guard, so safe to invoke from every
/// backend-construction call site — only the first invocation actually runs
/// `llama_backend_init_c()`.
///
/// We intentionally never call `llama_backend_free_c()`. The `Once` guard
/// cannot be re-armed, so if we freed the backend when the last instance
/// drops and then created a new instance (e.g., during model swap), the
/// backend would NOT be re-initialized — causing undefined behavior. Since
/// `llama_backend_free_c()` only cleans up NUMA info (a no-op on most
/// platforms), skipping it is safe. The OS reclaims all resources at
/// process exit.
///
/// This `-sys` crate deliberately does not read Xybrid-specific environment
/// variables. Higher-level crates that need policy during backend startup
/// should call [`backend_init_with_configure`] and keep their configuration
/// hook in the same one-time init closure.
#[cfg(feature = "bindings")]
pub fn backend_init() {
    backend_init_with_configure(|| {});
}

/// Initialize the llama.cpp backend once, running `configure` immediately
/// after `llama_backend_init_c()` during the same one-time initialization.
///
/// This preserves the historical timing for higher-level policies such as
/// log-verbosity setup while keeping this `-sys` crate free of product-level
/// environment-variable contracts.
#[cfg(feature = "bindings")]
pub fn backend_init_with_configure(configure: impl FnOnce()) {
    use std::sync::Once;
    static BACKEND_INIT: Once = Once::new();
    BACKEND_INIT.call_once(|| {
        unsafe { bindings::llama_backend_init_c() };
        configure();
    });
}

/// No-op stub when the `bindings` feature is disabled. Lets the wrapper
/// crate's `LlamaCppBackend::new()` constructor call `backend_init()`
/// unconditionally without a `#[cfg]` branch.
#[cfg(not(feature = "bindings"))]
pub fn backend_init() {}

/// No-op stub when the `bindings` feature is disabled.
#[cfg(not(feature = "bindings"))]
pub fn backend_init_with_configure(_configure: impl FnOnce()) {}