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//! The convention in every example is `use sys_lib as sys;`:
15//!
16//! ```
17//! use sys_lib as sys;
18//!
19//! println!("sys-lib {}", sys::VERSION);
20//! ```
21//!
22//! The Tier 1 functions arrive from `0.3.0` on, one plain call each:
23//!
24//! ```text
25//! sys::os::name()                // "Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"
26//! sys::cpu::name()               // "AMD Ryzen 9 7950X"
27//! sys::cpu::physical()           // cores
28//! sys::cpu::available()          // what this process may use (affinity, cpuset, quota)
29//! sys::mem::total()?             // the container's limit inside a container
30//! sys::mem::used_percent()?      // "32.8%"
31//! sys::cpu::used()?              // blocks for 100 ms
32//! sys::disk::space(path)?        // the filesystem holding `path`
33//! sys::process::guard("site")?   // single-instance lock, umask, open-file limit
34//! ```
35//!
36//! ## Status
37//!
38//! Scaffold. The design is written down in `dev/PLAN.md` and the milestone
39//! schedule in `dev/ROADMAP.md` (both in the
40//! [repository](https://github.com/jamesgober/sys-lib)); the public API is
41//! locked in `0.2.0` and the boot kit ships in `0.3.0`.
42
43#![doc(html_root_url = "https://docs.rs/sys-lib")]
44#![cfg_attr(docsrs, feature(doc_cfg))]
45// `deny`, not `forbid`: the per-platform `sys` modules lift it locally to call
46// the OS where std has no API. Nowhere else.
47#![deny(unsafe_code)]
48#![deny(unsafe_op_in_unsafe_fn)]
49#![deny(missing_docs)]
50#![deny(
51    clippy::undocumented_unsafe_blocks,
52    clippy::multiple_unsafe_ops_per_block,
53    clippy::ptr_as_ptr,
54    clippy::cast_ptr_alignment
55)]
56#![cfg_attr(
57    not(test),
58    deny(
59        clippy::unwrap_used,
60        clippy::expect_used,
61        clippy::panic,
62        clippy::todo,
63        clippy::unimplemented,
64        clippy::unreachable,
65        clippy::dbg_macro
66    )
67)]
68
69/// Crate version string, populated by Cargo at build time.
70pub const VERSION: &str = env!("CARGO_PKG_VERSION");
71
72#[cfg(test)]
73mod tests {
74    use super::VERSION;
75
76    #[test]
77    fn test_version_matches_manifest() {
78        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
79        // Pre-release and build metadata (`1.0.0-rc.1`, `+build`) follow the core.
80        let core = VERSION.split(['-', '+']).next().unwrap_or_default();
81        assert_eq!(core.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
82        assert!(
83            core.split('.').all(|part| part.parse::<u64>().is_ok()),
84            "every version component is a number"
85        );
86    }
87}