empyrean-sys 0.8.0

Low-level FFI bindings to the libempyrean astrodynamics C ABI. For an ergonomic Rust API, use the empyrean crate.
Documentation

empyrean-sys

Low-level FFI bindings to the libempyrean astrodynamics C ABI

empyrean-sys exposes the C ABI of libempyrean to Rust as raw, unsafe, bindgen-generated declarations. It does not attempt to wrap, type-check, or RAII-manage the underlying handles.

[dependencies]
empyrean-sys = "0.8"

use empyrean_sys::*;

// All entry points are unsafe; pointer ownership and lifetime are the
// caller's responsibility. See include/empyrean.h at the repository
// root for the authoritative C ABI documentation.
unsafe {
    // Null data_dir = the platform default data directory; downloads
    // any missing kernels. Returns null on error (see empyrean_last_error).
    let ctx: *mut EmpyreanContext = empyrean_context_from_data_dir(std::ptr::null());
    assert!(!ctx.is_null());
    empyrean_context_free(ctx);
}

Most users want the safe wrapper instead — see the empyrean crate, which builds on empyrean-sys to provide typed handles, Result-returning entry points, and Rust-native lifetime management.

Runtime requirement

empyrean-sys opens libempyrean.{dylib,so} at run time via libloading (dlopen). The library is distributed separately as a binary release on GitHub and inside the published Python wheel. The path is resolved from the EMPYREAN_LIB environment variable if set, else a libempyrean.* sitting next to the loaded module, else a build-time location — an EMPYREAN_LIB_DIR override, a sibling ../target/release build, or a checksum-pinned download from the GitHub release (in that order). The FFI bindings are pre-generated and committed, so no C header, libclang, or bindgen is needed to build.

Prebuilt engine binaries are currently published for four targets: macOS arm64 (macos-aarch64), macOS x86_64 (macos-x86_64), Linux x86_64 (linux-x86_64), and Linux aarch64 (linux-aarch64). On other targets the build stops with an error unless EMPYREAN_LIB_DIR points at an engine build.

License

Source code in this crate is licensed under the BSD 3-Clause License. The closed-source libempyrean runtime it loads at runtime is governed by a separate proprietary binary license; see the main repository for the dual-license breakdown.

Copyright © 2024–2026 Joachim Moeyens. All rights reserved.