Skip to main content

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.3" }`,
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//! ```
28//!
29//! The boot kit:
30//!
31//! ```no_run
32//! # #[cfg(all(feature = "instance", feature = "guard"))]
33//! # fn main() -> Result<(), sys_lib::Error> {
34//! use sys_lib as sys;
35//!
36//! let _guard = sys::process::guard("site")?;   // single-instance lock, umask, open-file limit
37//! let build = sys::build_info!();              // with `sys::build::emit()` in build.rs
38//! let instance = sys::Instance::start();
39//! println!("{build}\n{instance}");
40//! # Ok(())
41//! # }
42//! # #[cfg(not(all(feature = "instance", feature = "guard")))]
43//! # fn main() {}
44//! ```
45//!
46//! ## Status
47//!
48//! `0.3.0`, the boot kit: [`os`], [`cpu`], [`host`], [`process`], [`build`],
49//! and instance info. Memory, disks, network, virtualization,
50//! power, and device identity arrive through `0.6`; the complete approved API,
51//! each item with the version it arrives in, is `docs/API.md` in the
52//! [repository](https://github.com/jamesgober/sys-lib).
53
54#![doc(html_root_url = "https://docs.rs/sys-lib")]
55#![cfg_attr(docsrs, feature(doc_cfg))]
56// `deny`, not `forbid`: the per-platform `sys` modules lift it locally to call
57// the OS where std has no API. Nowhere else.
58#![deny(unsafe_code)]
59#![deny(unsafe_op_in_unsafe_fn)]
60#![deny(missing_docs)]
61#![deny(
62    clippy::undocumented_unsafe_blocks,
63    clippy::multiple_unsafe_ops_per_block,
64    clippy::ptr_as_ptr,
65    clippy::cast_ptr_alignment
66)]
67#![cfg_attr(
68    not(test),
69    deny(
70        clippy::unwrap_used,
71        clippy::expect_used,
72        clippy::panic,
73        clippy::todo,
74        clippy::unimplemented,
75        clippy::unreachable,
76        clippy::dbg_macro
77    )
78)]
79
80/// Crate version string, populated by Cargo at build time.
81pub const VERSION: &str = env!("CARGO_PKG_VERSION");
82
83pub mod build;
84pub mod cpu;
85pub mod host;
86#[cfg(feature = "instance")]
87#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
88pub mod instance;
89pub mod os;
90pub mod process;
91
92mod error;
93mod fmt;
94#[cfg(fuzzing)]
95#[doc(hidden)]
96pub mod __fuzz {
97    //! Parser entry points for `fuzz/`; not part of the API.
98    pub use crate::fuzz::*;
99}
100#[cfg(fuzzing)]
101mod fuzz;
102#[cfg(any(target_os = "linux", target_os = "android", test))]
103mod linux;
104mod parse;
105mod sys;
106mod units;
107
108pub use build::{BuildInfo, PublicBuild};
109pub use error::{Error, Result};
110#[cfg(feature = "instance")]
111#[cfg_attr(docsrs, doc(cfg(feature = "instance")))]
112pub use instance::{Instance, InstanceId};
113pub use units::{Bytes, Percent, Units};
114
115#[cfg(test)]
116mod tests {
117    use super::VERSION;
118
119    #[test]
120    fn test_version_matches_manifest() {
121        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
122        // Pre-release and build metadata (`1.0.0-rc.1`, `+build`) follow the core.
123        let core = VERSION.split(['-', '+']).next().unwrap_or_default();
124        assert_eq!(core.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
125        assert!(
126            core.split('.').all(|part| part.parse::<u64>().is_ok()),
127            "every version component is a number"
128        );
129    }
130}