Skip to content

Commit 4a720e4

Browse files
Charliechen114514Charliechen114514
committed
next step: files ready
1 parent 858dcd8 commit 4a720e4

20 files changed

Lines changed: 6790 additions & 349 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
build*/
44
out/
55

6+
# Compare And Check
7+
competition/
8+
69
# CMake
710
CMakeCache.txt
811
CMakeFiles/

‎README.en.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ echo "Hello, World!" # now calls cfbox via symlink
104104
| Document | Description |
105105
|----------|-------------|
106106
| [Architecture & Design](document/architecture.md) | Dispatch mechanism, core infrastructure, error handling, testing |
107-
| [Roadmap](Roadmap.md) | 7-phase development plan, current progress, architecture decisions |
107+
| [Production Roadmap](document/todo/README.md) | Production roadmap docs for Phase 4.5 to v1.0; currently maintained in Chinese |
108108
| [Cross-Compilation & Embedded](document/cross-compilation.md) | Toolchains, CMake options, build examples, binary sizes |
109109
| [QEMU Testing](document/qemu-testing.md) | User-mode / system-mode testing, init applet, kernel config |
110110
| [Continuous Integration](document/ci.md) | CI pipeline overview |
@@ -144,6 +144,29 @@ cfbox/
144144
└── scripts/ # Build, test, install scripts
145145
```
146146

147+
## Next Steps
148+
149+
Current release: v0.1.0. Upcoming work, in priority order:
150+
151+
### Phase 0: Production Pre-gates (In Progress)
152+
153+
Before adding new applets, the following quality foundations must be completed:
154+
155+
| Phase | Scope | Status |
156+
|-------|-------|--------|
157+
| **0A** Baseline Inventory | 109-applet catalog, maturity labels, profile assignments, doc drift fixes | Pending |
158+
| **0B** Perf Baseline | Core benchmarks (cat/grep/sed/sort/find/tar/gzip/cp/tail), RSS regression thresholds | Pending |
159+
| **0C** Size Budget | Per-profile size caps, new rescue/container profiles, per-applet delta tracking | Pending |
160+
| **0D** IO Policy | Streaming audit (head/tail/sed/tr/md5sum etc.), large file/pipe/broken pipe tests | Pending |
161+
| **0E** Safety Hardening | Unified numeric parsers, parser fuzz smoke, privileged command isolation tests | Pending |
162+
| **0F** CI & Release | Tiered CI (sanitizer/benchmark/differential/cross/QEMU), reproducible builds, error format spec | Pending |
163+
164+
### Phase 1: Core System (After Phase 0)
165+
166+
New system-level applets: `chmod`, `chown`, `chgrp`, `mount`, `umount`, `chroot`, `dd`, `stty`, plus deepening existing core commands.
167+
168+
> See [document/todo/README.md](document/todo/README.md) for the full roadmap.
169+
147170
## Contributing
148171

149172
See [CONTRIBUTING.md](CONTRIBUTING.md).

‎README.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ echo "Hello, World!" # 通过符号链接调用 cfbox
104104
| 文档 | 说明 |
105105
|------|------|
106106
| [架构与设计](document/architecture.md) | 分发机制、核心基础设施、错误处理、测试体系 |
107-
| [路线图](Roadmap.md) | 7 阶段开发计划、当前进度、架构决策 |
107+
| [生产化升级路线图](document/todo/README.md) | Phase 4.5 到 v1.0 的生产化治理文档集、优先级、发布标准 |
108108
| [交叉编译与嵌入式](document/cross-compilation.md) | 工具链、CMake 选项、构建示例、二进制大小对比 |
109109
| [QEMU 测试](document/qemu-testing.md) | 用户模式 / 系统模式测试、init applet、内核配置 |
110110
| [持续集成](document/ci.md) | CI 流水线阶段说明 |
@@ -144,6 +144,29 @@ cfbox/
144144
└── scripts/ # 构建、测试、安装脚本
145145
```
146146

147+
## 下一步计划
148+
149+
当前版本 v0.1.0，下一阶段工作按优先级排列：
150+
151+
### Phase 0：生产化前置门禁（进行中）
152+
153+
在新增 applet 之前，必须完成以下质量地基：
154+
155+
| 阶段 | 内容 | 状态 |
156+
|------|------|------|
157+
| **0A** 基线盘点 | 109 个 applet 清单、成熟度标注、profile 归属、文档漂移修复 | 待开始 |
158+
| **0B** 性能基线 | 核心命令 benchmark（cat/grep/sed/sort/find/tar/gzip/cp/tail）、RSS 回归阈值 | 待开始 |
159+
| **0C** 体积预算 | 按 profile 设定体积上限、新增 rescue/container profile、每 applet 增量追踪 | 待开始 |
160+
| **0D** IO 策略 | 流式处理审计（head/tail/sed/tr/md5sum 等整改为流式）、大文件/管道/broken pipe 测试 | 待开始 |
161+
| **0E** 安全加固 | 数值解析统一 helper、parser fuzz smoke、特权命令隔离测试 | 待开始 |
162+
| **0F** CI 与发布 | 分层 CI（sanitizer/benchmark/differential/cross/QEMU）、可复现构建、错误格式规范 | 待开始 |
163+
164+
### Phase 1：核心系统（Phase 0 完成后）
165+
166+
新增 `chmod`、`chown`、`chgrp`、`mount`、`umount`、`chroot`、`dd`、`stty` 等系统级 applet，深化核心命令功能。
167+
168+
> 详细路线图见 [document/todo/README.md](document/todo/README.md)。
169+
147170
## 贡献
148171

149172
见 [CONTRIBUTING.md](CONTRIBUTING.md)。

‎Roadmap.md‎

Lines changed: 0 additions & 347 deletions
This file was deleted.

‎document/todo/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# CFBox 生产化升级路线图
2+
3+
本文档集用于承接 CFBox 从 v0.1.0 走向 v1.0 生产可用的升级路线。它取代根目录旧路线图，作为后续 Phase 0 到 v1.0 的执行入口。
4+
5+
## 当前状态
6+
7+
| 项目 | 状态 |
8+
|------|------|
9+
| 版本 | v0.1.0 |
10+
| Applet | 109 个 |
11+
| 体积 | 约 446 KB（size-opt, LTO + strip） |
12+
| 测试 | 331 个 GTest 单元测试 + 56 个集成脚本 |
13+
| 已完成阶段 | 历史 Phase 0-4：构建、POSIX-like shell、coreutils、归档压缩、文本处理、procps、init |
14+
| 主要缺口 | 权限/挂载/`dd`、网络、登录管理、系统日志、核心命令功能深度、生产发布工程 |
15+
16+
## 文档索引
17+
18+
| 文档 | 用途 |
19+
|------|------|
20+
| [生产化路线图](production-roadmap.md) | **全局总纲**：Phase 0-5 阶段顺序、核心 Applet 优先级、质量工程策略、发布与分发规范 |
21+
| [v1.0 生产可用标准](v1-production-criteria.md) | v1.0 发布门槛：profile 标准、成熟度、测试、发布矩阵、体积预算 |
22+
| [兼容性策略](compatibility-policy.md) | POSIX/BusyBox/GNU 行为冲突的裁决原则、退出码策略 |
23+
| [VitePress 文档站](documentation-site.md) | 文档站信息架构、applet reference、cookbook |
24+
| [Phase 0A-0F 前置门禁](phases/phase-0a-baseline-inventory.md) | 进入 Phase 1 前必须完成的质量、体积、IO、安全和工程地基 |
25+
| [Phase 1 核心系统](phases/phase-1-core-system.md) | 权限、挂载、dd、stty、核心命令深化 |
26+
| [Phase 2 网络](phases/phase-2-network.md) | 基础网络配置、诊断、下载 |
27+
| [Phase 3 质量](phases/phase-3-quality.md) | fuzzing、benchmark、POSIX 子集、release 工程 |
28+
| [Phase 4 多用户](phases/phase-4-multiuser.md) | login/getty/syslog/mdev/storage |
29+
| [Phase 5 长尾](phases/phase-5-longtail.md) | vi、额外压缩格式、硬件工具 |
30+
31+
## 推荐阅读顺序
32+
33+
1. 先读 [v1.0 生产可用标准](v1-production-criteria.md)，明确最终验收边界。
34+
2. 再读 [生产化路线图](production-roadmap.md)，确认阶段顺序、优先级和全局策略。
35+
3. 进入任何新增 applet 工作前，完成 [Phase 0A-0F 前置门禁](phases/phase-0a-baseline-inventory.md)。
36+
4. 实现 applet 前读对应 Phase 文档。
37+
5. 改动兼容性相关行为前读 [兼容性策略](compatibility-policy.md)。
38+
6. 编写用户文档前读 [VitePress 文档站](documentation-site.md)。
39+
40+
## 路线原则
41+
42+
- 场景闭环优先于 applet 数量。
43+
- 核心命令功能深度优先于长尾命令覆盖率。
44+
- 默认零运行时依赖，可选依赖必须通过构建开关隔离。
45+
- 兼容性要可说明、可测试、可接受；不支持项必须公开记录。
46+
- 每个阶段都必须同时交付实现、测试、文档和体积报告。
47+
- Phase 0A-0F 是硬门禁；未达成确定指标时，不继续扩展 applet 数量。

‎document/todo/compatibility-policy.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# 兼容性策略
2+
3+
CFBox 的目标是成为面向嵌入式、容器和 rescue 场景的 BusyBox 替代品。兼容性策略必须明确，否则每个 applet 都会陷入 POSIX、BusyBox、GNU 行为差异的局部争论。
4+
5+
## 裁决优先级
6+
7+
当 POSIX、BusyBox、GNU 行为冲突时，按以下顺序裁决：
8+
9+
1. **POSIX 语义优先**。
10+
2. **BusyBox 高频行为优先**。
11+
3. **GNU 长选项作为增强**。
12+
4. 体积、复杂度或安全风险过高的扩展可以拒绝。
13+
5. 所有意差异必须文档化。
14+
15+
### 裁决案例
16+
17+
**案例 1：`test -a` / `test -o` 语义**
18+
19+
POSIX 将 `-a`（AND）和 `-o`（OR）标记为 obsolescent。GNU coreutils 和 BusyBox 均支持。裁决：保留支持，因为大量现有脚本依赖此行为；但在文档中标明 POSIX 已弃用。
20+
21+
**案例 2：`sort -h` 人类数字排序**
22+
23+
`-h` 是 GNU 扩展，不在 POSIX 中，BusyBox 支持。裁决：支持，因为它是运维高频需求（`du -h | sort -h`），且实现体积可控。
24+
25+
**案例 3：`echo -n` / `echo -e` 行为**
26+
27+
POSIX 对 `echo` 的 `-n`/`-e` 行为未严格定义，不同实现差异大。裁决：遵循 BusyBox 行为（`-n` 抑制换行，`-e` 解析转义序列），因为这是 BusyBox 替代场景的最高频预期。
28+
29+
## BusyBox 兼容面
30+
31+
CFBox 的直接替代对象是 BusyBox，因此生产 profile 中的高频命令应优先兼容 BusyBox：
32+
33+
- 短选项语义。
34+
- 输出格式。
35+
- 错误信息的关键信息。
36+
- 多文件和部分失败退出码。
37+
- symlink multicall 调用方式。
38+
39+
不要求复制 BusyBox 的历史 bug 或不安全行为。
40+
41+
### 输出格式对齐示例
42+
43+
`ls -l` 输出格式应与 BusyBox 对齐（字段顺序、日期格式、权限字符串），而非 GNU coreutils 的更详细格式。差异应记录在兼容性矩阵中。
44+
45+
## GNU 增强
46+
47+
GNU 长选项和用户体验增强可以加入，但必须满足：
48+
49+
- 不改变 BusyBox 高频短选项行为。
50+
- 可通过 `--help` 清楚展示。
51+
- 不显著增加核心 profile 体积。
52+
- 有测试覆盖。
53+
54+
## POSIX 声明
55+
56+
在通过严肃 POSIX 子集测试前，文档应使用：
57+
58+
- "POSIX-like shell"
59+
- "POSIX-oriented behavior"
60+
- "passes documented POSIX subset"
61+
62+
避免直接声称"POSIX compatible"或"POSIX certified"。
63+
64+
## 不支持项记录
65+
66+
每个 applet 的文档必须列出：
67+
68+
- 已支持选项。
69+
- 不支持的 BusyBox 高频选项。
70+
- 不支持的 GNU 高频选项。
71+
- 已知行为差异。
72+
- 是否属于有意差异。
73+
74+
这比隐性缺口更利于生产用户评估风险。兼容性矩阵的建立和审计流程见 [Phase 0A](phases/phase-0a-baseline-inventory.md)。
75+
76+
## 退出码策略
77+
78+
多目标命令必须统一退出码原则：
79+
80+
- 全部成功：0。
81+
- 部分失败：非 0，并继续处理后续目标，除非命令语义要求立即停止。
82+
- 参数错误：与 BusyBox/POSIX 高频行为对齐。
83+
- 系统调用失败：错误信息包含目标对象和 errno 语义。
84+
85+
### 首批退出码审计对象
86+
87+
| 命令 | 预期退出码语义 | 备注 |
88+
|------|---------------|------|
89+
| `cp` | 0=全部成功，1=部分复制失败 | 继续处理后续文件 |
90+
| `mv` | 0=全部成功，1=部分移动失败 | 跨设备移动时回退到复制+删除 |
91+
| `rm` | 0=全部成功，1=部分删除失败 | `-f` 时不存在文件不报错 |
92+
| `find` | 0=正常，1=遍历错误 | 继续遍历后续目录 |
93+
| `tar` | 0=成功，1=部分失败，2=致命错误 | 区分可恢复和不可恢复 |
94+
| `dd` | 0=成功，1=错误 | 输出传输统计到 stderr |
95+
| `mount` | 0=成功，非 0=各种挂载失败 | 错误信息含设备和挂载点 |
96+
| `umount` | 0=成功，非 0=各种卸载失败 | EBUSY 时建议 `-l` |
97+
98+
## 实验性功能
99+
100+
实验性 applet 或选项必须：
101+
102+
- 不进入 production profile。
103+
- 在文档中标注 maturity level。
104+
- 不作为 v1.0 支持承诺的一部分。
105+
- 在 release notes 中列出行为变化风险。
106+
107+
成熟度分级和升级条件见 [v1.0 生产可用标准](v1-production-criteria.md)。

0 commit comments

Comments
 (0)