coolprop_sys/
lib.rs

1//! [<img alt="GitHub" src="https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="22">](https://github.com/portyanikhin/rfluids)
2//! [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="22">](https://docs.rs/coolprop-sys)
3//! [<img alt="crates.io" src="https://img.shields.io/crates/v/coolprop-sys?style=for-the-badge&logo=rust&labelColor=555555&color=fc8d62" height="22">](https://crates.io/crates/coolprop-sys)
4//! [<img alt="CI" src="https://img.shields.io/github/actions/workflow/status/portyanikhin/rfluids/ci.yml?style=for-the-badge&logo=githubactions&logoColor=ffffff&label=ci&labelColor=555555" height="22">](https://github.com/portyanikhin/rfluids/actions/workflows/ci.yml)
5//!
6//! Raw FFI bindings to [`CoolProp`](https://coolprop.org)
7//!
8//! ## Supported platforms
9//!
10//! - `Linux AArch64`
11//! - `Linux x86-64`
12//! - `macOS AArch64`
13//! - `macOS x86-64`
14//! - `Windows AArch64`
15//! - `Windows x86-64`
16//!
17//! ## MSRV
18//!
19//! `coolprop-sys` requires `rustc` 1.85.0 or later.
20//!
21//! ## How to install
22//!
23//! Add this to your `Cargo.toml`:
24//!
25//! ```toml
26//! [dependencies]
27//! coolprop-sys = "7"
28//! ```
29//!
30//! Or via command line:
31//!
32//! ```shell
33//! cargo add coolprop-sys
34//! ```
35//!
36//! 🎁 It comes with native `CoolProp` dynamic libraries for supported platforms. The library
37//! required for your platform will be automatically copied to the target directory during build.
38//!
39//! It also includes pre-generated FFI bindings, so `libclang` is not required for normal builds.
40//!
41//! ### Regenerating bindings
42//!
43//! If you need to regenerate the FFI bindings (requires `libclang`), enable the
44//! **`regen-bindings`** feature.
45//!
46//! Add this to your `Cargo.toml`:
47//!
48//! ```toml
49//! [dependencies]
50//! coolprop-sys = { version = "7", features = ["regen-bindings"] }
51//! ```
52//!
53//! Or via command line:
54//!
55//! ```shell
56//! cargo add coolprop-sys --features regen-bindings
57//! ```
58//!
59//! #### License
60//!
61//! <sup>
62//! This project is licensed under
63//! <a href="https://github.com/portyanikhin/rfluids/blob/main/LICENSE">MIT License</a>
64//! </sup>
65
66use std::sync::{LazyLock, Mutex};
67
68pub mod bindings;
69
70/// `CoolProp` dynamic library absolute path.
71#[cfg(all(target_os = "linux", target_arch = "aarch64"))]
72pub const COOLPROP_PATH: &str = coolprop_sys_linux_aarch64::COOLPROP_PATH;
73#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
74pub const COOLPROP_PATH: &str = coolprop_sys_linux_x86_64::COOLPROP_PATH;
75#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
76pub const COOLPROP_PATH: &str = coolprop_sys_macos_aarch64::COOLPROP_PATH;
77#[cfg(all(target_os = "macos", target_arch = "x86_64"))]
78pub const COOLPROP_PATH: &str = coolprop_sys_macos_x86_64::COOLPROP_PATH;
79#[cfg(all(target_os = "windows", target_arch = "aarch64"))]
80pub const COOLPROP_PATH: &str = coolprop_sys_windows_aarch64::COOLPROP_PATH;
81#[cfg(all(target_os = "windows", target_arch = "x86_64"))]
82pub const COOLPROP_PATH: &str = coolprop_sys_windows_x86_64::COOLPROP_PATH;
83
84/// Global instance of the `CoolProp` dynamic library.
85///
86/// Provides thread-safe access to a single `CoolProp` instance across the entire application.
87/// The library is loaded lazily on first access using [`LazyLock`].
88///
89/// Access to this shared handle is protected by a [`Mutex`]. This is a conservative boundary
90/// around `CoolProp`'s process-global configuration, debug level, warning, and pending-error
91/// state. It also allows higher-level wrappers to keep calls returning sentinel values and
92/// subsequent pending-error retrieval together.
93///
94/// To use the library, acquire the lock:
95///
96/// ```no_run
97/// use coolprop_sys::COOLPROP;
98///
99/// let coolprop = COOLPROP.lock().unwrap();
100/// // Use CoolProp methods here
101/// ```
102///
103/// # Panics
104///
105/// Panics on initialization if the `CoolProp` dynamic library cannot be loaded
106/// (e.g., if the library file is missing or corrupted).
107///
108/// # Safety
109///
110/// Internally uses `unsafe` to load the dynamic library via FFI.
111/// Safety is ensured because:
112/// - The library is loaded from the verified [`COOLPROP_PATH`]
113/// - Loading occurs once during initialization
114/// - All subsequent accesses work with the already loaded library
115///
116/// # See Also
117///
118/// - [`CoolPropLib.h` Reference](https://coolprop.org/_static/doxygen/html/_cool_prop_lib_8h.html)
119pub static COOLPROP: LazyLock<Mutex<bindings::CoolProp>> = LazyLock::new(|| {
120    Mutex::new(
121        unsafe { bindings::CoolProp::new(COOLPROP_PATH) }
122            .expect("CoolProp dynamic library should load from `COOLPROP_PATH`"),
123    )
124});
coolprop_sys/lib.rs

coolprop_sys/
lib.rs
