# fstool
Build disk images and filesystem images from a directory tree and a TOML
spec — in the spirit of `genext2fs`, but going further:
- **Multiple filesystems** — ext2 / ext3 / ext4 (v1), FAT32 to follow.
- **Whole disk images** — MBR and GPT partition tables, not just bare FS images.
- **Streaming** — file contents are never preloaded in memory regardless of
size. Generation is a two-pass scan-then-stream.
- **Modular** — block devices, partition tables, and filesystems each go
through a small trait; adding a new partition scheme or filesystem is a
drop-in plugin.
- **Inspectable** — the same trait stack reads existing images, so the
CLI ships `fstool ls`, `fstool cat`, and `fstool info` alongside `build`.
- **In-place modification** — add, remove, and replace whole files inside an
existing image without rewriting it.
fstool is implemented in Rust and ships as a library (`fstool`) plus a thin CLI
binary (`fstool`).
## Status
Early in development. Public API is **unstable** until v0.5.
| 1. `BlockDevice` foundation | ✅ done |
| 2. MBR + GPT partition tables | ✅ done |
| 3. ext2 writer | ✅ done |
| 4. ext2 reader + ext3/4 feature matrix | planned |
| 5. TOML spec + CLI | planned |
| 6. FAT32 | post-v1 |
What works today:
- `fstool::block::{FileBackend, MemoryBackend, SlicedBackend}` — sparse
file-backed devices, in-memory devices for tests, bounds-checked sub-range
views for carving partitions.
- `fstool::part::{Mbr, Gpt}` — write and read 4-primary MBR and 128-entry GPT
layouts. GPT includes the protective MBR, primary and backup headers, and
CRC32 on both the header and the partition entry array. Cross-checked
against `sgdisk -v`.
- `fstool::fs::ext::Ext` — write ext2 images from in-memory geometry plus a
populate API:
- `Ext::format_with(dev, opts)` → an empty FS with the root directory
(and `/lost+found` if requested). Layout matches `genext2fs -d <dir>
-f -q -B 1024` structurally; verified with `e2fsck -fn` and a
`dumpe2fs -h` diff.
- `Ext::add_file_to(dev, parent, name, FileSource, meta)` — regular
files via direct + single-indirect blocks. File data is streamed
straight to the device; never fully resident in memory.
- `Ext::add_dir_to`, `Ext::add_symlink_to` (with fast-symlink inline
storage for ≤ 60-byte targets), `Ext::add_device_to` (char / block /
FIFO / socket).
- `Ext::flush(dev)` — persists metadata, primary superblock last.
- `Ext::populate_rootdevs(dev, kind, uid, gid, mtime)` — drops a
`Minimal` or `Standard` `/dev/*` tree into the image (console, null,
zero, ptmx, tty, fuse, random, urandom — plus tty0..15, ttyS0..3,
kmsg, mem, port, hda..hdd + 4 partitions, sda..sdd + 4 partitions for
`Standard`). Lets a non-root user build a Linux root FS without
needing CAP_MKNOD.
## Architecture
```
┌────────────────────────────────────────────┐
│ CLI (clap) — bin/fstool │
└────────────────────────────────────────────┘
│
┌────────────────────────────────────────────┐
│ Spec layer (TOML → ImageSpec / FsSpec) │
└────────────────────────────────────────────┘
│
┌────────────────────────────────────────────┐
│ Filesystem trait → ext::Ext (2/3/4) │
└────────────────────────────────────────────┘
│
┌────────────────────────────────────────────┐
│ PartitionTable trait → Mbr, Gpt │
└────────────────────────────────────────────┘
│
┌────────────────────────────────────────────┐
│ BlockDevice trait → FileBackend, Sliced… │
└────────────────────────────────────────────┘
```
Each layer is substitutable. A filesystem implementation talks only to a
`BlockDevice`; it doesn't know or care whether the device is a real file, an
in-memory buffer in a test, or a slice carved out of a larger disk by a
partition table.
## Try it
GPT demo (requires `sgdisk` for the validation step):
```sh
cargo run --example inspect_gpt -- /tmp/demo.img
sgdisk -p /tmp/demo.img
sgdisk -v /tmp/demo.img # "No problems found."
```
Run the test suite:
```sh
cargo test # unit tests + external cross-checks if tools present
```
## Roadmap
The streaming invariant is the project's load-bearing constraint: regardless
of image size, no file's contents are ever fully resident in memory. The
writer scans the source twice — once to compute geometry (inode count, block
count, dir-entry sizes), once to stream bytes from each file directly to the
image. This is the difference between fstool and a "build a Vec<u8> and dump
it" approach.
In-place modification is restricted to whole-file granularity in v1 (add,
remove, replace). Partial-file rewrites are explicitly out of scope until
there's a use case that demands them.
## Licence
MIT. Copyright © 2026 Karpelès Lab Inc. See [LICENSE](LICENSE).