empyrean-sys 0.10.0

//! Raw FFI bindings to `libempyrean`, the C shared library for empyrean's
//! astrodynamics engine.
//!
//! Prefer the safe wrapper crate [`empyrean`](https://docs.rs/empyrean)
//! unless you need direct access to the C ABI.
//!
//! # How `libempyrean` is loaded
//!
//! The library is opened at run time with [`libloading`] — there is **no**
//! link-time native dependency and no `install_name_tool` / `patchelf` / rpath /
//! `LD_LIBRARY_PATH` setup. Its path is resolved on first use, in order:
//!
//! 1. `EMPYREAN_LIB` — an explicit path to the library, passed straight to
//!    `dlopen` (override / offline use / a locally built engine). A bare name
//!    defers to the OS loader search; pass a full path for an exact file.
//! 2. A `libempyrean.{dylib,so}` sitting next to the **currently loaded module**
//!    — the `.so`/`.dylib`/executable that statically links this crate — located
//!    via `dladdr`. This makes prebuilt, relocatable artifacts self-contained:
//!    a Python wheel can bundle the engine beside its extension and it is found
//!    with no build-machine path baked in.
//! 3. The absolute path recorded at build time (`LIB_PATH`): a sibling
//!    `../target/release` build, an `EMPYREAN_LIB_DIR` override, or a
//!    version-matched, checksum-pinned prebuilt downloaded (in pure Rust — no
//!    `curl`/`tar`) into `~/.cache/empyrean`. This covers `cargo add empyrean`,
//!    where the build script runs on the consumer's own machine.
//!
//! The bindings are pre-generated and committed, so building needs no C header
//! and no `libclang` / `bindgen`. Callers use the free `empyrean_*` functions
//! exactly as with a statically linked library; each delegates to the loaded
//! [`EmpyreanLib`].
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(dead_code)]
// The generated dynamic-loading methods call the loaded fn pointers directly in
// their (unsafe) bodies; this is generated FFI, so allow the 2024 granularity lint.
#![allow(unsafe_op_in_unsafe_fn)]
// The generated bindings and the free-function shims are `pub unsafe fn`s without
// per-function `# Safety` sections, and mirror the C ABI's wide argument lists;
// they are generated FFI, not hand-authored API.
#![allow(clippy::missing_safety_doc)]
#![allow(clippy::too_many_arguments)]

use std::path::{Path, PathBuf};
use std::sync::OnceLock;

// Dynamic-loading bindings: `struct EmpyreanLib` + per-function methods + the
// shared type/const definitions.
include!("bindings.rs");

// Absolute path to libempyrean recorded by the build script — resolution
// fallback #3 (see the module docs).
include!(concat!(env!("OUT_DIR"), "/lib_path.rs"));

static LIB: OnceLock<EmpyreanLib> = OnceLock::new();

/// Platform file name of the engine library.
const LIB_FILENAME: &str = if cfg!(target_os = "macos") {
    "libempyrean.dylib"
} else if cfg!(target_os = "windows") {
    "empyrean.dll"
} else {
    "libempyrean.so"
};

// A data symbol whose address lands in *this* module, so `dladdr` reports the
// shared object / executable that statically links empyrean-sys.
#[cfg(unix)]
static SELF_MARKER: u8 = 0;

/// Directory of the currently loaded module — the `.so`/`.dylib`/executable that
/// links this crate — via `dladdr`. `None` if it cannot be determined.
#[cfg(unix)]
fn self_module_dir() -> Option<PathBuf> {
    use std::ffi::CStr;
    use std::os::raw::c_void;

    let mut info: libc::Dl_info = unsafe { std::mem::zeroed() };
    let addr = &SELF_MARKER as *const u8 as *const c_void;
    // SAFETY: `info` is a valid out-pointer; `dli_fname` is a loader-owned C
    // string we only dereference when dladdr reports success (non-zero).
    if unsafe { libc::dladdr(addr, &mut info) } == 0 || info.dli_fname.is_null() {
        return None;
    }
    let cstr = unsafe { CStr::from_ptr(info.dli_fname) };
    let dir = Path::new(cstr.to_str().ok()?).parent()?;
    // Only trust an ABSOLUTE module directory. `dladdr` may report a relative or
    // bare path (e.g. glibc echoes a relative `argv[0]` for the main executable),
    // whose `parent()` can be `""`; joining the library name onto that would
    // resolve against the current working directory and let a cwd-planted
    // `libempyrean` load ahead of the checksum-pinned build-time path. Treat that
    // as "cannot determine" so resolution falls through to the absolute LIB_PATH.
    dir.is_absolute().then(|| dir.to_path_buf())
}

#[cfg(not(unix))]
fn self_module_dir() -> Option<PathBuf> {
    None
}

/// Resolve the engine library path at run time (see the module docs for the
/// full resolution order).
fn resolve_lib_path() -> PathBuf {
    // 1. Explicit override.
    if let Some(p) = std::env::var_os("EMPYREAN_LIB") {
        return PathBuf::from(p);
    }
    // 2. Bundled next to the currently loaded module (relocatable artifacts).
    if let Some(dir) = self_module_dir() {
        let candidate = dir.join(LIB_FILENAME);
        if candidate.exists() {
            return candidate;
        }
    }
    // 3. The absolute path recorded at build time.
    PathBuf::from(LIB_PATH)
}

/// The loaded `libempyrean`, opened lazily on first use.
///
/// Panics if the library cannot be opened, or if the library that opened is
/// built to a different [`EMPYREAN_ABI_VERSION`] than this crate. The path is
/// resolved from the host environment and the build, so a failure here means a
/// broken or incomplete install (e.g. a prebuilt artifact missing its bundled
/// engine, or a stale `libempyrean` picked up from `EMPYREAN_LIB` or a leftover
/// `target/release`) — surfaced loudly rather than papered over.
///
/// # The version handshake
///
/// `dlsym` matches on symbol **name** only, so a mismatched engine resolves
/// every symbol and then reads the caller's arguments through the wrong
/// signature. The check is an equality: [`EMPYREAN_ABI_VERSION`] carries
/// the distribution release that built this crate and advances with every
/// release, so a different value is a different release and nothing about
/// the layouts behind the shared names can be assumed.
///
/// The damage a tolerated mismatch does has grown with the ABI. Under the
/// retired counter, up to its version 2, it could only ever produce wrong
/// values, because every bump appended struct fields; version 3 changed the
/// parameter lists of `empyrean_transform_coordinates` and
/// `empyrean_get_observers` in place, where the same mismatch writes through
/// an integer the caller passed by value; the 0.10.0 ABI shrinks
/// `EmpyreanSolveFor` and shifts the tail of the `EmpyreanODConfig` that
/// embeds it. Checking [`empyrean_abi_version`] the moment the library opens
/// is what that accessor exists for, and it is cheap — one call, once per
/// process.
pub fn lib() -> &'static EmpyreanLib {
    LIB.get_or_init(|| {
        let path = resolve_lib_path();
        // SAFETY: opening a shared library by the path resolved above.
        let lib = unsafe {
            EmpyreanLib::new(&path)
                .unwrap_or_else(|e| panic!("failed to load libempyrean from {path:?}: {e}"))
        };
        // SAFETY: the symbol resolved when the library opened
        // (`--dynamic-link-require-all`), and takes no arguments, so it is
        // safe to call regardless of which ABI version answers it.
        let loaded = unsafe { lib.empyrean_abi_version() };
        assert_eq!(
            loaded, EMPYREAN_ABI_VERSION,
            "libempyrean ABI mismatch: {path:?} reports ABI version {loaded}, but this build of \
             empyrean-sys was compiled against version {EMPYREAN_ABI_VERSION}. Symbol names are \
             shared across versions but signatures and struct layouts are not, so continuing \
             would read arguments through the wrong shape. Point EMPYREAN_LIB at a matching \
             engine, or rebuild it."
        );
        lib
    })
}

mod shims;
pub use shims::*;

// The header/prebuilt pin the build script enforces. Compiled only for
// tests here — at build time `build.rs` pulls the same file in directly,
// so the parse the tests cover is the parse the guard runs.
#[cfg(test)]
mod header_pin;