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