Hi EROFS maintainers, As a prospective GSoC 2026 contributor interested in low-level filesystem work, here's a small documentation improvement to README.md:
- Added a prominent Quick Start section early for better onboarding - Full beginner workflow: build → mkfs.erofs → fsck → erofsfuse mount → cleanup - Compressed example + multithreading note - Shields badges and upstream/community links Patch attached (generated from my fork: https://github.com/Aayushmaan-24/erofs-utils/tree/feature/readme-quick-start). All commands verified locally. Happy to revise or split changes. Thanks for considering! Aayushmaan GitHub: Aayushmaan-24 signed off by: Aayushmaan Chakraborty <[email protected]> >From b50fd7d848bb3ad05080d3ded862d0bc74254b65 Mon Sep 17 00:00:00 2001 From: Aayushmaan <[email protected]> Date: Sat, 28 Feb 2026 14:50:05 +0530 Subject: [PATCH] README: Add Quick Start section with beginner-friendly build, test, verify, and mount guide - Inserted early for better onboarding - Debian/Ubuntu deps (Crostini tested) - End-to-end flow incl. fsck success hint and compressed example - Shields badges + upstream/community links - No changes to existing technical sections --- README | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/README b/README index 1ca376f..68a00b1 100644 --- a/README +++ b/README @@ -1,6 +1,9 @@ erofs-utils =========== +[](https://github.com/erofs/erofs-utils/commits/dev) +[](COPYING) + Userspace tools for EROFS filesystem, currently including: mkfs.erofs filesystem formatter @@ -11,6 +14,7 @@ Userspace tools for EROFS filesystem, currently including: as extractor + EROFS filesystem overview ------------------------- @@ -49,6 +53,61 @@ For more details on how to build erofs-utils, see `docs/INSTALL.md`. For more details about filesystem performance, see `docs/PERFORMANCE.md`. +Quick Start: Build, Create, Mount, and Verify an EROFS Image +------------------------------------------------------------ + +1. Install dependencies: + ```bash + sudo apt update + sudo apt install -y autoconf automake libtool pkg-config \ + libfuse-dev liblz4-dev liblzma-dev libzstd-dev uuid-dev zlib1g-dev + ``` + +2. Clone and build: + ```bash + git clone https://github.com/erofs/erofs-utils.git + cd erofs-utils + ./autogen.sh + ./configure --enable-lz4 --enable-lzma --enable-fuse --with-libzstd [--enable-multithreading] + make -j$(nproc) + ``` + +3. Create a simple test image: + ```bash + mkdir src_dir + echo "Hello, EROFS world!" > src_dir/hello.txt + echo "This is a test file." > src_dir/test.txt + ./mkfs/mkfs.erofs test.img src_dir/ + ``` + +4. Verify integrity: + ```bash + ./fsck/fsck.erofs test.img + # Expected output: "No errors found" or filesystem statistics (no error messages) + ``` + +5. Mount and explore (using FUSE — no kernel module required): + ```bash + mkdir mnt + ./fuse/erofsfuse test.img mnt/ + ls mnt/ # Should list hello.txt and test.txt + cat mnt/hello.txt # Hello, EROFS world! + fusermount -u mnt/ # Unmount when done + ``` + +6. Clean up: + ```bash + rm -rf src_dir mnt test.img + ``` + +7. Compressed images: + ```bash + ./mkfs/mkfs.erofs -zlz4hc test-compressed.img src_dir/ + ``` + For compressed images, add e.g. `-zlz4hc` or `-zzstd` (or other algorithms) to `mkfs.erofs`. + See the `mkfs.erofs` section below for advanced options (big pclusters, + multi-algorithms, reproducible builds, etc.). + mkfs.erofs ---------- @@ -283,6 +342,14 @@ feel free to send feedback and/or patches to: linux-erofs mailing list <[email protected]> +Upstream and Community +---------------------- + +- Canonical upstream: https://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git +- Discussion / patches: [email protected] (subscribe: https://lists.ozlabs.org/listinfo/linux-erofs) +- Kernel docs: https://www.kernel.org/doc/html/next/filesystems/erofs.html + + Comments -------- -- 2.39.5
