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.5" }`,
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 build;
89pub mod cpu;
90#[cfg(feature = "device-id")]
91#[cfg_attr(docsrs, doc(cfg(feature = "device-id")))]
92pub mod device;
93pub mod disk;
94pub mod host;
95#[cfg(feature = "instance")]
96#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
97pub mod instance;
98pub mod mem;
99pub mod net;
100pub mod os;
101pub mod power;
102pub mod process;
103pub mod virt;
104
105mod error;
106mod fmt;
107#[cfg(fuzzing)]
108#[doc(hidden)]
109pub mod __fuzz {
110 //! Parser entry points for `fuzz/`; not part of the API.
111 pub use crate::fuzz::*;
112}
113#[cfg(fuzzing)]
114mod fuzz;
115#[cfg(any(target_os = "linux", target_os = "android", test))]
116mod linux;
117mod parse;
118mod pressure;
119mod summary;
120mod sys;
121mod units;
122
123pub use build::{BuildInfo, PublicBuild};
124pub use error::{Error, Result};
125#[cfg(feature = "instance")]
126#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
127pub use instance::{Instance, InstanceId};
128pub use pressure::{Pressure, PressureLevel, Stall};
129pub use summary::{Summary, summary};
130pub use units::{Bytes, Mhz, Percent, Rate, Units};
131
132#[cfg(test)]
133mod tests {
134 use super::VERSION;
135
136 #[test]
137 fn test_version_matches_manifest() {
138 assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
139 // Pre-release and build metadata (`1.0.0-rc.1`, `+build`) follow the core.
140 let core = VERSION.split(['-', '+']).next().unwrap_or_default();
141 assert_eq!(core.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
142 assert!(
143 core.split('.').all(|part| part.parse::<u64>().is_ok()),
144 "every version component is a number"
145 );
146 }
147}