# Rprocps-ng

**Repository Path**: openeuler/Rprocps-ng

## Basic Information

- **Project Name**: Rprocps-ng
- **Description**: Redesigning and refactoring system components with Rust to establish a new foundation for operating system security.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2025-11-12
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: sig-MCP-Tools-Ecosystem

## README

# Rprocps-ng

Rprocps-ng is a Rust-based refactor of the native procps-ng toolset. The goal is to introduce Rust’s memory safety and modern engineering practices while keeping command-line interfaces, output formats, and behaviors fully identical to upstream.

## Project Goals
- Compatibility first: CLI options, outputs, exit codes, and error messages exactly match upstream procps-ng.
- Faithful refactor: follow the original C code’s data structures, algorithms, and syscalls without changing behavior.
- Naming convention: tools use native names: `free`, `uptime`, `ps`, `top`.
- Progressive refactor: finish the core tools first, then expand to the full suite.

## Tool Priority
- Core tools: `free`, `uptime`, `ps`, `top`
- System monitoring: `vmstat`, `slabtop`, `w`
- Process management: `kill`, `pgrep`, `pidof`

## Compatibility and Behavior Constraints
- Option parsing: support and strictly align with all upstream flags, short/long options, mutual exclusions, and defaults.
- Output format: column names, widths, units, rounding/alignment, colors, and localization behaviors strictly match upstream.
- Exit codes: error categories and exit codes align with upstream; error text matches the native implementation.
- Signal handling: follow upstream handling of `SIGINT`, `SIGTERM`, `SIGWINCH`, etc. (especially for `top-rs`).
- IPC/environment: comply with upstream behaviors for environment variables, terminal capabilities, and access to `/proc` and `sysfs`.
- Platform scope: Linux-focused, relying on the `/proc` filesystem; non-Linux platforms are not guaranteed.

## Code Organization (Planned)
This project will be organized as a Rust workspace. Each tool is an independent binary crate. A shared base library provides `/proc` access, formatting, and compatibility logic.

```
Rprocps-ng/
  Cargo.toml                  # workspace declaration (to be added)
  crates/
    libproc/                 # shared lib: procfs reading, parsing, compatibility 
      src/
    free/
      src/main.rs            # implementation corresponding to upstream free.c
    uptime/
      src/main.rs            # corresponding to upstream uptime.c
    ps/
      src/main.rs            # corresponding to upstream ps/* (modularized)
    top/
      src/main.rs            # corresponding to upstream top/* (UI/renderer/sampling)
    vmstat/
      src/main.rs
    slabtop/
      src/main.rs
    w/
      src/main.rs
    kill/
      src/main.rs
    pgrep/
      src/main.rs
    pidof/
      src/main.rs
```

## Mapping to Upstream C Code
- Source mapping:
  - `free` ↔ `free.c`
  - `uptime` ↔ `uptime.c`
  - `ps` ↔ modules under `ps/` (option parsing, column definitions, sorting/filtering, etc.)
  - `top` ↔ modules under `top/` (sampling, statistics, sorting, interactive rendering)
  - `vmstat` ↔ `vmstat.c`, `slabtop` ↔ `slabtop.c`, `w` ↔ `w.c`
  - `kill` ↔ `kill.c`, `pgrep` ↔ `pgrep.c`, `pidof` ↔ `pidof.c`
- Data structures: keep the Rust `struct`/`enum` closely isomorphic to upstream; use `#[repr(C)]` when layout compatibility is required.
- Syscalls and `/proc` reads: prefer direct file I/O and Rust stdlib; use `libc` bindings when necessary and strictly follow upstream file paths and field parsing rules.

## Build and Run
- Requirements: Linux (with `/proc`), Rust stable (install via `rustup`).
- Fetch the code:
  - `git clone <repo-url>`
- Build (once the workspace is ready):
  - `cargo build --workspace --release`
- Run examples (with options identical to upstream):
  - `target/release/free -h`
  - `target/release/uptime`
  - `target/release/ps aux`
  - `target/release/top` (interactive)

## Compatibility Verification
- Quick diffs:
  - `diff -u <(free) <(target/release/free)`
  - `diff -u <(uptime) <(target/release/uptime)`
  - `ps aux | diff -u - <(target/release/ps aux)`
- Golden tests: generate upstream outputs for standard argument sets as regression baselines.
- Locale checks: verify consistency under different `LC_ALL`/`LANG` settings.
- Exit code checks: construct failure scenarios (permission denied/no process/invalid args) and compare exit codes and error texts.

## Development Guide
- Modules: `cli` (argument parsing), `procfs` (data collection), `format` (formatting), `sysinfo` (statistics/unit conversions), `signals`, `compat` (compatibility layer).
- Error handling: unified `Result` with clear domains (I/O, parsing, formatting, terminal); align error texts with upstream.
- Performance: avoid redundant syscalls, cache appropriately, control allocations, use slices and zero-copy; compatibility takes priority.
- Logging/debugging: disabled by default; never pollute stdout to preserve output compatibility.
- Code style: follow `rustfmt` and static checks (e.g., `clippy`); style must not alter outputs.

## Tests and Benchmarks (Planned)
- Unit tests: formatting functions, option parsing, field computations.
- End-to-end tests: golden snapshots for typical argument combinations of main tools.
- Benchmarks: sampling intervals, sorting, and rendering performance to avoid UI stalls (`top-rs`).

## Platform and Limitations
- Linux only; relies on `/proc` and some `sysfs` entries.
- In containers/minimal systems, degrade gracefully based on available `/proc` fields while keeping the output structure consistent.

## Roadmap
1. Implement `free` core features and compatibility tests
2. Implement `uptime` and establish shared library `libproc`
3. Advance `ps` (column definitions, sorting, filtering, output layouts)
4. Implement `top` sampling, rendering, and interactive loop
5. Extend to `vmstat`, `slabtop`, `w`
6. Complete `kill`, `pgrep`, `pidof` and perform suite-wide validation

## Contribution Guide
- Workflow: Fork → create branch → develop and test → open Pull Request.
- Code requirements: maintain upstream compatibility; include necessary tests and verification notes; avoid changes that alter outputs.
- Discussion and review: compatibility and faithful refactor take highest priority.

## License
The license will remain compatible with upstream (details will be clarified once the initial code and dependencies are established).

## Acknowledgments
Thanks to the upstream [procps-ng](https://gitlab.com/procps-ng/procps) project, its maintainers, and contributors.