Skip to main content

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}