sys_lib/lib.rs
1//! # sys_lib
2//!
3//! System facts for Rust services: operating system, CPU, memory, disks,
4//! network, host, this process, virtualization, power, and device identity,
5//! container-aware by default, plus the boot kit every long-running service
6//! needs (build info, instance info, and a process guard).
7//!
8//! Every reading is a file read or a system call. sys-lib never starts a
9//! thread or a timer, never runs another program, and has no third-party
10//! runtime dependencies.
11//!
12//! ## Tier 1
13//!
14//! Add it with Cargo's rename, `sys = { package = "sys-lib", version = "0.2" }`,
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//!
18//! ```
19//! use sys_lib as sys;
20//!
21//! println!("sys-lib {}", sys::VERSION);
22//! ```
23//!
24//! The Tier 1 functions arrive from `0.3.0` on, one plain call each:
25//!
26//! ```text
27//! sys::os::name() // "Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"
28//! sys::os::distro() // "Ubuntu"; "Windows", "macOS" elsewhere
29//! sys::cpu::name() // "AMD Ryzen 9 7950X"
30//! sys::cpu::physical() // cores
31//! sys::cpu::available() // what this process may use (affinity, cpuset, quota)
32//! sys::mem::total()? // the container's limit inside a container
33//! sys::mem::used_percent()? // "32.8%"
34//! sys::cpu::used()? // blocks for 100 ms
35//! sys::net::traffic()? // download and upload; blocks for 1 s
36//! sys::disk::space(path)? // the filesystem holding `path`
37//! sys::process::guard("site")? // single-instance lock, umask, open-file limit
38//! ```
39//!
40//! ## Status
41//!
42//! Design locked (`0.2.0`). The complete API is in `docs/API.md`, the design
43//! in `dev/PLAN.md`, and the schedule in `dev/ROADMAP.md` (all in the
44//! [repository](https://github.com/jamesgober/sys-lib)); the boot kit ships in
45//! `0.3.0`.
46
47#![doc(html_root_url = "https://docs.rs/sys-lib")]
48#![cfg_attr(docsrs, feature(doc_cfg))]
49// `deny`, not `forbid`: the per-platform `sys` modules lift it locally to call
50// the OS where std has no API. Nowhere else.
51#![deny(unsafe_code)]
52#![deny(unsafe_op_in_unsafe_fn)]
53#![deny(missing_docs)]
54#![deny(
55 clippy::undocumented_unsafe_blocks,
56 clippy::multiple_unsafe_ops_per_block,
57 clippy::ptr_as_ptr,
58 clippy::cast_ptr_alignment
59)]
60#![cfg_attr(
61 not(test),
62 deny(
63 clippy::unwrap_used,
64 clippy::expect_used,
65 clippy::panic,
66 clippy::todo,
67 clippy::unimplemented,
68 clippy::unreachable,
69 clippy::dbg_macro
70 )
71)]
72
73/// Crate version string, populated by Cargo at build time.
74pub const VERSION: &str = env!("CARGO_PKG_VERSION");
75
76mod sys;
77
78#[cfg(test)]
79mod tests {
80 use super::VERSION;
81
82 #[test]
83 fn test_version_matches_manifest() {
84 assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
85 // Pre-release and build metadata (`1.0.0-rc.1`, `+build`) follow the core.
86 let core = VERSION.split(['-', '+']).next().unwrap_or_default();
87 assert_eq!(core.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
88 assert!(
89 core.split('.').all(|part| part.parse::<u64>().is_ok()),
90 "every version component is a number"
91 );
92 }
93}