sys_lib/lib.rs
1//! # sys_lib
2//!
3//! System facts for Rust services, container-aware by default, plus the boot
4//! kit every long-running service needs in its first milliseconds: build info,
5//! instance info, and a process guard.
6//!
7//! Every reading is a file read or a system call. sys-lib never starts a
8//! thread or a timer, never runs another program, and has no third-party
9//! runtime dependencies by default (the `device-id` feature brings crypt-io's
10//! BLAKE3 stack).
11//!
12//! ## Tier 1
13//!
14//! Add it with Cargo's rename, `sys = { package = "sys-lib", version = "0.7" }`,
15//! and every file writes `sys::`; without the rename, `use sys_lib as sys;`
16//! does the same (the examples use that form so they compile either way).
17//! One plain call per fact; static facts are read once and cached:
18//!
19//! ```
20//! use sys_lib as sys;
21//!
22//! println!("{}", sys::os::name()); // "Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"
23//! println!("{}", sys::os::distro()); // "Ubuntu"; "Windows", "macOS" elsewhere
24//! println!("{}", sys::cpu::name()); // "AMD Ryzen 9 7950X"
25//! println!("{} cores, {} threads", sys::cpu::physical(), sys::cpu::logical());
26//! let workers = sys::cpu::available(); // what this process may use: affinity, cpuset, quota
27//! # assert!(workers >= 1);
28//! println!("{} of {} used", sys::mem::used()?, sys::mem::total()?); // the container's limit inside one
29//! println!("{} free here", sys::disk::space(".")?.available);
30//! # Ok::<(), sys_lib::Error>(())
31//! ```
32//!
33//! The boot kit:
34//!
35//! ```no_run
36//! # #[cfg(all(feature = "instance", feature = "guard"))]
37//! # fn main() -> Result<(), sys_lib::Error> {
38//! use sys_lib as sys;
39//!
40//! let _guard = sys::process::guard("site")?; // single-instance lock, umask, open-file limit
41//! let build = sys::build_info!(); // with `sys::build::emit()` in build.rs
42//! let instance = sys::Instance::start();
43//! println!("{build}\n{instance}");
44//! # Ok(())
45//! # }
46//! # #[cfg(not(all(feature = "instance", feature = "guard")))]
47//! # fn main() {}
48//! ```
49//!
50//! ## Status
51//!
52//! `0.7.0`, optimisation: every reading measured against the crates people
53//! use for it, with the numbers in `docs/PERFORMANCE.md`. Feature complete
54//! since `0.6`: the boot kit ([`os`], [`cpu`], [`host`], [`process`],
55//! [`build`], and instance info), the live readings ([`mem`], [`disk`],
56//! [`net`]), [`virt`], [`power`], [`summary()`], the environment reports,
57//! device identity behind the `device-id` feature, on Linux (64- and 32-bit),
58//! macOS, Windows, and FreeBSD. The complete API is `docs/API.md` in the
59//! [repository](https://github.com/jamesgober/sys-lib).
60
61#![doc(html_root_url = "https://docs.rs/sys-lib")]
62#![cfg_attr(docsrs, feature(doc_cfg))]
63// `deny`, not `forbid`: the per-platform `sys` modules lift it locally to call
64// the OS where std has no API. Nowhere else.
65#![deny(unsafe_code)]
66#![deny(unsafe_op_in_unsafe_fn)]
67#![deny(missing_docs)]
68#![deny(
69 clippy::undocumented_unsafe_blocks,
70 clippy::multiple_unsafe_ops_per_block,
71 clippy::ptr_as_ptr,
72 clippy::cast_ptr_alignment
73)]
74#![cfg_attr(
75 not(test),
76 deny(
77 clippy::unwrap_used,
78 clippy::expect_used,
79 clippy::panic,
80 clippy::todo,
81 clippy::unimplemented,
82 clippy::unreachable,
83 clippy::dbg_macro
84 )
85)]
86
87/// Crate version string, populated by Cargo at build time.
88pub const VERSION: &str = env!("CARGO_PKG_VERSION");
89
90pub mod bench;
91pub mod build;
92pub mod cpu;
93#[cfg(feature = "device-id")]
94#[cfg_attr(docsrs, doc(cfg(feature = "device-id")))]
95pub mod device;
96pub mod disk;
97pub mod gpu;
98pub mod host;
99#[cfg(feature = "instance")]
100#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
101pub mod instance;
102pub mod mem;
103pub mod net;
104pub mod os;
105pub mod power;
106#[cfg(target_os = "linux")]
107#[cfg_attr(docsrs, doc(cfg(target_os = "linux")))]
108pub mod probe;
109pub mod process;
110pub mod readiness;
111pub mod security;
112pub mod sensors;
113pub mod virt;
114
115mod error;
116mod fmt;
117#[cfg(fuzzing)]
118#[doc(hidden)]
119pub mod __fuzz {
120 //! Parser entry points for `fuzz/`; not part of the API.
121 pub use crate::fuzz::*;
122}
123#[cfg(fuzzing)]
124mod fuzz;
125#[cfg(any(target_os = "linux", target_os = "android", test))]
126mod linux;
127mod origin;
128mod parse;
129mod pressure;
130mod summary;
131mod sys;
132mod units;
133
134pub use build::{BuildInfo, PublicBuild};
135pub use error::{Error, Result};
136#[cfg(feature = "instance")]
137#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
138pub use instance::{Instance, InstanceId};
139pub use pressure::{Pressure, PressureLevel, Stall};
140pub use summary::{Summary, summary};
141pub use units::{Bytes, Mhz, Percent, Rate, Units};
142
143#[cfg(test)]
144mod tests {
145 use super::VERSION;
146
147 #[test]
148 fn test_version_matches_manifest() {
149 assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
150 // Pre-release and build metadata (`1.0.0-rc.1`, `+build`) follow the core.
151 let core = VERSION.split(['-', '+']).next().unwrap_or_default();
152 assert_eq!(core.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
153 assert!(
154 core.split('.').all(|part| part.parse::<u64>().is_ok()),
155 "every version component is a number"
156 );
157 }
158}