# 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-12

## Categories & Tags

**Categories**: Uncategorized

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

## README

# Rprocps-ng

Rprocps-ng 是对原生 procps-ng 工具集的 Rust 语言重构项目，目标是在保持与上游完全一致的命令行接口、输出格式与行为的前提下，引入 Rust 的内存安全与现代工程实践。

## 项目目标
- 兼容性优先：命令行参数、输出内容、退出码与错误信息与原生 procps-ng 完全一致。
- 代码忠实重构：遵循原生 C 代码的数据结构、算法逻辑与系统调用，不改变既有行为。
- 命名规范：各子工具以原生命令命名：`free`、`uptime`、`ps`、`top`。
- 渐进式重构：先完成核心工具，再扩展到完整工具集。

## 工具优先级
- 核心工具：`free`、`uptime`、`ps`、`top`
- 系统监控：`vmstat`、`slabtop`、`w`
- 进程管理：`kill`、`pgrep`、`pidof`

## 兼容性与行为约束
- 参数解析：支持并严格对齐上游所有选项、短/长参数、互斥与默认值。
- 输出格式：列名、列宽、单位、舍入/对齐、颜色与本地化行为严格一致。
- 退出码：错误分类与退出码与上游一致；错误信息文本对齐原生实现。
- 信号处理：遵循上游对于 `SIGINT`、`SIGTERM`、`SIGWINCH` 等的处理逻辑与交互行为（尤其是 `top-rs`）。
- IPC/环境：遵循上游对环境变量、终端能力与 `/proc`、`sysfs` 的访问策略。
- 平台范围：以 Linux 为主，依赖 `/proc` 文件系统；非 Linux 平台不承诺兼容。

## 代码组织（计划）
本项目将以 Rust workspace 组织，每个工具为独立二进制 crate，共享基础库以统一访问 `/proc`、格式化与兼容逻辑。

```
Rprocps-ng/
  Cargo.toml                  # workspace 声明（后续添加）
  crates/
    libproc/                 # 公共库：procfs 读取、解析与兼容层
      src/
    free/
      src/main.rs            # 对应原生 free.c 的实现
    uptime/
      src/main.rs            # 对应原生 uptime.c 的实现
    ps/
      src/main.rs            # 对应原生 ps/* 的实现（按模块拆分）
    top/
      src/main.rs            # 对应原生 top/* 的实现（交互/渲染/采样）
    vmstat/
      src/main.rs
    slabtop/
      src/main.rs
    w/
      src/main.rs
    kill/
      src/main.rs
    pgrep/
      src/main.rs
    pidof/
      src/main.rs
```

## 与原生 C 代码的对应关系
- 源码映射：
  - `free` ↔ `free.c`
  - `uptime` ↔ `uptime.c`
  - `ps` ↔ `ps/` 下的 C 模块（选项解析、列定义、排序/过滤等）
  - `top` ↔ `top/` 下的 C 模块（采样、统计、排序、交互/渲染）
  - `vmstat` ↔ `vmstat.c`，`slabtop` ↔ `slabtop.c`，`w` ↔ `w.c`
  - `kill` ↔ `kill.c`，`pgrep` ↔ `pgrep.c`，`pidof` ↔ `pidof.c`
- 数据结构映射：尽量保持与原生 `struct`/`enum` 同构；在 Rust 中以 `struct`/`enum` 表达，必要时以 `#[repr(C)]` 保持布局。
- 系统调用与 `/proc` 读取：优先直接文件 I/O 与标准库封装，必要时使用 `libc` 绑定，严格遵循原生访问路径与字段解析规则。

## 构建与运行
- 系统要求：Linux（启用 `/proc`），Rust stable（建议安装 `rustup`）。
- 获取代码：
  - `git clone <repo-url>`
- 构建（在 workspace 就绪后）：
  - `cargo build --workspace --release`
- 运行示例（与原生保持一致的参数）：
  - `target/release/free -h`
  - `target/release/uptime`
  - `target/release/ps aux`
  - `target/release/top`（交互式）

## 兼容性验证

### 自动化测试框架

本项目实现了全面的测试验证框架，用于确保 Rust 实现与原生 procps-ng 的输出**完全一致**。

**快速开始**：
```bash
# 编译工具
cargo build

# 运行所有兼容性测试
cargo test test_all_commands_compatibility --test compatibility_tests -- --ignored --nocapture

# 查看 HTML 报告
firefox test-results/*.html
```

**主要特性**：
- ✅ 多种验证策略（字节级、行级、正则表达式）
- ✅ 智能处理动态数据（时间戳、PID）
- ✅ 详细的差异分析和可视化报告
- ✅ 预定义的测试套件（free、uptime、ps、pidof、pwdx）

详细文档请参考：
- [测试框架详细文档](tests/framework/README.md) - 框架API说明

### 传统验证方法

- 快速对比：
  - `diff -u <(free) <(target/release/free)`
  - `diff -u <(uptime) <(target/release/uptime)`
  - `ps aux | diff -u - <(target/release/ps aux)`
- Golden 测试：对标准输入参数组合生成上游输出快照，作为回归基准。
- 区域设置验证：在不同 `LC_ALL`/`LANG` 下验证格式与单位一致性。
- 退出码验证：构造错误场景（无权限/无进程/非法参数）比对退出码与错误文案。

## 📚 文档

- **[文档中心](docs/README.md)** - 文档导航入口
- **[架构文档](docs/ARCHITECTURE.md)** - 项目整体架构和各工具设计
- **[各工具架构设计](docs/architecture/)** - 详细的架构文档

## 开发指南

**快速概览**：
- 模块划分：`cli`（参数解析）、`procfs`（数据采集）、`format`（格式化）、`sysinfo`（统计/单位换算）、`signals`、`compat`（兼容层）。
- 错误处理：统一使用 `Result`，细分为 I/O、解析、格式化、终端等错误域；所有错误文案对齐上游。
- 性能优化：避免重复系统调用，合理缓存，控制分配，使用切片与零拷贝；保持输出兼容为前提。
- 日志与调试：调试日志默认关闭；任何日志不得污染标准输出（以免影响兼容性）。
- 代码风格：遵循 `rustfmt` 与静态检查（如使用 `clippy`）；风格检查不改变输出行为。

## 测试与基准（计划）
- 单元测试：格式化函数、选项解析、字段计算。
- 端到端测试：对主工具的典型参数组合建立 Golden 快照。
- 基准测试：采样周期、排序与渲染性能，避免 UI 卡顿（`top-rs`）。

## 平台与限制
- 仅支持 Linux；强依赖 `/proc` 与若干 `sysfs` 条目。
- 在容器/最小系统上，根据可用的 `/proc` 字段自动降级但保持输出结构一致。

## 迭代路线图
1. 完成 `free` 的核心功能与兼容测试
2. 完成 `uptime` 并建立基础公共库 `libproc`
3. 推进 `ps`（列定义、排序、过滤、输出布局）
4. 实现 `top` 的采样、渲染与交互循环
5. 扩展到 `vmstat`、`slabtop`、`w`
6. 完成 `kill`、`pgrep`、`pidof` 并进行整体验证

## 贡献指南
- 提交流程：Fork → 创建分支 → 开发与测试 → 发起 Pull Request。
- 代码要求：保证与上游兼容；附带必要测试与验证说明；不得引入影响输出的非必要变更。
- 讨论与评审：以兼容性与忠实重构为最高优先级。

## 许可证
许可证将与上游保持兼容（具体细则将在初始化代码与依赖明确后补充说明）。

## 致谢
感谢原生 [procps-ng](https://gitlab.com/procps-ng/procps) 项目与其维护者及贡献者。