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}