Skip to content

README.en.md

Latest commit

 

History

History
169 lines (120 loc) · 7.69 KB

README.en.md

File metadata and controls

169 lines (120 loc) · 7.69 KB

CFBox

中文 | English

A minimalist BusyBox alternative written in modern C++23.

CI License: MIT C++23 CMake Tests Applets

Overview

CFBox is a single-executable Unix utility collection distributed via symbolic links. 115 applets implemented and tested, with a CI pipeline covering native builds, cross-compilation, and QEMU user/system-mode testing. Features configurable CMake builds (per-applet toggles), GNU-style long options, and colored help output.

Design philosophy: Simplicity first — Modern C++ (std::expected) — Embedded-friendly (cross-compilation, static linking)

Size Comparison

Project Language Size Applets Size/Applet
CFBox (size-opt) C++23 406 KB 115 ~3.5 KB
Toybox C ~500 KB 238 ~2.1 KB
BusyBox (full) C ~1.7 MB 274 ~9 KB
uutils/coreutils Rust ~11 MB ~100 ~110 KB

CFBox is 3-4x smaller than BusyBox while providing a complete AWK interpreter, archive suite (tar/cpio/ar/unzip/gzip), diff/patch (Myers O(ND) algorithm), process tools (ps/top/pstree/pgrep/pmap), and a built-in TUI framework.

Performance

Operation Data Size Time
grep -c 10 MB 54 ms
cat 10 MB 63 ms
wc 10 MB 17 ms
sort 100K lines 32 ms
diff 100K lines (similar) 79 ms
  • grep/cat/wc use streaming I/O — reading /dev/urandom won't exhaust memory
  • diff uses Myers O(ND) algorithm; sort precomputes keys to avoid repeated allocation
  • Zero external dependencies: hand-written lightweight deflate/inflate replaces zlib

Quick Start

# Build
cmake -B build
cmake --build build

# Test
ctest --test-dir build --output-on-failure   # 379 GTest unit tests
bash tests/integration/run_all.sh            # 54 integration test scripts

# Run via subcommand
./build/cfbox echo "Hello, World!"

# Or install symbolic links
./scripts/gen_links.sh /usr/local/bin
echo "Hello, World!"   # now calls cfbox via symlink

Supported Commands (115)

Text Processing (31)

echo, printf, cat, head, tail, wc, sort, uniq, grep, sed, fold, expand, cut, paste, nl, comm, tr, tac, rev, shuf, factor, od, split, seq, tsort, expr, awk, diff, patch, cmp, ed

File Operations (22)

mkdir, rm, cp, mv, ls, find, ln, touch, stat, install, mktemp, truncate, du, df, readlink, realpath, rmdir, link, unlink, chmod, chown, chgrp

Archive & Compression (6)

tar (ustar format), cpio (newc format), ar (static library), unzip, gzip, gunzip

Shell & Scripting (2)

sh (POSIX shell: pipes, redirections, variable expansion, command substitution, if/while/for, 15 builtins), xargs

System Info (20)

pwd, basename, dirname, uname, hostname, whoami, id, tty, date, nproc, logname, hostid, printenv, env, uptime, free, cal, dmesg, who, test

Process Management (15)

ps, top, kill, pgrep/pkill, pidof, pstree, pmap, fuser, pwdx, sysctl, iostat, watch, nice, renice, timeout

Other (19)

true, false, yes, sleep, usleep, sync, nohup, cksum, md5sum, sum, hexdump, more, tee, init (PID 1 initramfs init system), mkfifo, mknod, clear, which, mountpoint

All applets support --help / --version

Requirements

  • Compiler: GCC 13+ / Clang 17+ (C++23 support required)
  • CMake: 3.26+
  • Platform: Linux (x86_64 / aarch64)

Documentation

Document Description
Architecture & Design Dispatch mechanism, core infrastructure, error handling, testing
Production Roadmap Production roadmap docs for Phase 4.5 to v1.0; currently maintained in Chinese
Cross-Compilation & Embedded Toolchains, CMake options, build examples, binary sizes
QEMU Testing User-mode / system-mode testing, init applet, kernel config
Continuous Integration CI pipeline overview
Contributing Guide Build, test, code style, submission

Project Structure

cfbox/
├── CMakeLists.txt
├── cmake/
│   ├── Config.cmake                  # Per-applet configuration (CFBOX_ENABLE_xxx options)
│   ├── compile/CompilerFlag.cmake    # Compiler warnings & optimization flags
│   ├── third_party/CPM.cmake        # CPM dependency manager (GTest only)
│   └── toolchain/                   # Cross-compilation toolchains
├── include/cfbox/
│   ├── applet.hpp / applets.hpp     # Registry & dispatch
│   ├── args.hpp                     # Short + long option argument parser
│   ├── error.hpp                    # std::expected error handling + CFBOX_TRY
│   ├── io.hpp                       # Streaming I/O (for_each_line, read_all, write_all)
│   ├── stream.hpp                   # Line-by-line pipeline, LineProcessor
│   ├── deflate.hpp / inflate.hpp    # Hand-written lightweight DEFLATE (zero deps)
│   ├── compress.hpp                 # gzip wrapper
│   ├── utf8.hpp                     # Unicode width/count (constexpr + static_assert)
│   ├── term.hpp                     # ANSI colored output (NO_COLOR support)
│   ├── terminal.hpp                 # Terminal control (RawMode RAII, cursor, double buffer)
│   ├── tui.hpp                      # TUI framework (ScreenBuffer, Key, TuiApp)
│   ├── proc.hpp                     # /proc parser (processes, memory, CPU, disks)
│   ├── regex.hpp                    # POSIX regex RAII (scoped_regex)
│   └── ...                          # help.hpp, fs_util.hpp, escape.hpp, checksum.hpp
├── src/
│   ├── main.cpp                     # Dispatch entry
│   └── applets/                     # 115 command implementations
├── tests/
│   ├── unit/                        # GTest unit tests (379 cases)
│   └── integration/                 # Shell integration tests (54 scripts)
└── scripts/                         # Build, test, install scripts

Next Steps

Current release: v0.2.0 (Phase 1 Wave 1 + Phase 1.5 code quality review complete). Now entering Phase 2: core command deepening.

Phase 2: Core Command Deepening (In Progress)

Deepening existing commands from ~30% to ~70% feature completeness, in batches by operational frequency:

Batch Commands Key Additions
Batch 1 tail, cp, test, ls tail -f, cp -a, full POSIX test, ls -R/--color
Batch 2 grep, tar, sed, sort grep -A/-B/-C, tar -z/-v, sed -i, sort -k
Batch 3 find, sh, ps, df, du find boolean expressions, sh case/heredoc/functions

See document/todo/README.md for the full roadmap.

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE for details.