# sysinfo

**Repository Path**: gycherish/sysinfo

## Basic Information

- **Project Name**: sysinfo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sysinfo

A small cross-platform C++23 library (plus a command-line tool) for collecting
host system information: memory, CPU topology, hostname, operating system,
network interfaces and baseboard.

- Synchronous API: each category is one plain function call
- Best-effort semantics: values that cannot be determined keep their defaults
  (`E::unknown` for enums, empty for strings, zero for numbers) instead of
  raising errors
- Built-in JSON serialization in both directions ([nlohmann_json](https://github.com/nlohmann/json)
  is the library's one required dependency; camelCase keys, versioned schema)
- Linux (primary) and Windows backends; the MinGW build still runs on
  Windows XP / Server 2003

## What it collects

| Category | Details |
|----------|---------|
| Memory | Kernel-usable total and physically installed size (the latter includes firmware/kernel-reserved regions, no root needed) |
| CPU | Logical processors, sockets, cores per socket, threads per core, model name, architecture |
| Hostname | `gethostname` |
| OS | Distribution / product name and version (os-release, kernel release, Windows build) |
| NICs | Name, MAC, type (`ethernet`/`wifi`/`loopback`/`bond`/`bridge`), operational state, link speed, IPv4/IPv6 addresses with CIDR prefix and reachability scope (`loopback`/`link_local`/`private`/`global`) |
| Board | Baseboard vendor / name / version / serial (DMI; falls back to the system/product table on VMs) |

## Requirements

- C++23 compiler (GCC 14+, Clang 18+, MSVC 17.10+).
- [xmake](https://xmake.io/) ≥ 3.0.0.
- nlohmann_json — pulled automatically via xmake / xrepo.

## Build

```sh
xmake f -m release                               # configure (use -m debug while developing)
xmake build                                      # build everything
xmake test                                       # run the catch2 test suite
xmake project -k compile_commands build          # export compile_commands.json
```

Build with MinGW on Windows:

```sh
xmake f -m release -p mingw --sdk=/path/to/mingw
```

## Library usage

```cpp
#include "sysinfo/sysinfo.hpp"
#include <nlohmann/json.hpp>

int main() {
    // Everything at once...
    const sysinfo::system_info info = sysinfo::collect_all();

    // ...or one category at a time.
    const sysinfo::cpu_info cpu = sysinfo::collect_cpu();

    // Serialization is attached to the types as hidden friends: any
    // nlohmann_json conversion just works, in both directions.
    const nlohmann::json j = info;
    const auto back = j.get<sysinfo::system_info>();
}
```

The enum string forms (`to_string`) are a stable contract used by the JSON
output; `from_string(to_string(x)) == x` holds for every enumerator and
unrecognised text parses to `E::unknown`.

## Tools

### sysinfo-dump

Prints host information; category flags select what to collect (everything by
default), `--json` switches the format.

```
Usage: sysinfo-dump [--mem] [--cpu] [--hostname] [--os] [--net] [--board] [--json]
```

```text
$ sysinfo-dump
hostname: devbox
os: Fedora Linux 43 (Workstation Edition) (6.17.1-300.fc43.x86_64)
memory: 17179869184 installed (16.0 GiB), 16777195520 usable (15.6 GiB)
cpu: Intel(R) Xeon(R) CPU E5-2698 v3 @ 2.30GHz [x86_64]
  16 logical (2 sockets x 8 cores/socket x 1 threads/core)
board: vendor="QEMU" name="Standard PC (i440FX + PIIX, 1996)" version="pc-i440fx-6.2" serial=""
nics:
  lo [loopback] state=unknown speed=unknown mac=00:00:00:00:00:00
    ipv4: 127.0.0.1/8 (loopback)
    ipv6: ::1/128 (loopback)
  ens18 [ethernet] state=up speed=1000 Mbps mac=52:54:00:12:34:56
    ipv4: 192.168.1.100/24 (private)
    ipv6: fe80::5054:ff:fe12:3456/64 (link_local)
```

```text
$ sysinfo-dump --cpu --mem --json
{
  "cpu": {
    "arch": "x86_64",
    "coresPerSocket": 8,
    "logical": 16,
    "model": "Intel(R) Xeon(R) CPU E5-2698 v3 @ 2.30GHz",
    "sockets": 2,
    "threadsPerCore": 1
  },
  "mem": {
    "installed": 17179869184,
    "total": 16777195520
  },
  "version": "0.1.0"
}
```

The top-level `version` field is the JSON schema version (SemVer): minor bumps
add fields, major bumps change or remove them. Deserialization is lenient --
fields missing from the input keep their defaults.

## Platform notes

- **Linux** is the primary target. All probes go through cheap syscalls and
  sysfs/procfs reads; nothing requires root (DMI serial numbers are the
  exception -- they read as empty without privileges).
- **Windows** uses Win32/IpHlpApi plus raw SMBIOS parsing for the baseboard.
  APIs newer than XP/Server 2003 are resolved at run time and degrade
  gracefully, so the MinGW binary still runs there. NIC teaming and bridges
  currently surface as `ethernet`.

## License

[MIT](LICENSE)