From: Gao Xiang <hsiang...@aol.com> We are about to release erofs-utils 1.2, add some words to README about erofsfuse itself.
Signed-off-by: Gao Xiang <hsiang...@aol.com> --- README | 79 +++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/README b/README index 980f1d02cb19..8e4335449b6d 100644 --- a/README +++ b/README @@ -2,26 +2,12 @@ erofs-utils =========== erofs-utils includes user-space tools for erofs filesystem. -Currently only mkfs.erofs is available. +Currently mkfs.erofs and erofsfuse (experimental) are available. -mkfs.erofs ----------- - -It can generate 2 primary kinds of erofs images: (un)compressed. - - - For uncompressed images, there will be none of compression - files in these images. However, it can decide whether the tail - block of a file should be inlined or not properly [1]. - - - For compressed images, it will try to use lz4(hc) algorithm - first for each regular file and see if storage space can be - saved with compression. If not, fallback to an uncompressed - file. - -Dependencies -~~~~~~~~~~~~ +Dependencies & build +-------------------- - lz4-1.8.0+ for lz4 enabled [2], lz4-1.9.3+ highly recommended [4]. + lz4-1.8.0+ for lz4 enabled [2], lz4-1.9.3+ highly recommended [4][5]. How to build for lz4-1.9.0 or above ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -39,6 +25,10 @@ mkfs.erofs binary will be generated under mkfs folder. * For lz4 < 1.9.2, there are some stability issues about LZ4_compress_destSize(). (lz4hc isn't impacted) [3]. +** For lz4 = 1.9.2, there is a noticeable regression about + LZ4_decompress_safe_partial() [5], which impacts erofsfuse + functionality for legacy images (without 0PADDING). + How to build for lz4-1.8.0~1.8.3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -55,6 +45,20 @@ However, it's still not recommended using those versions directly since there are serious bugs in these compressors, see [2] [3] [4] as well. +mkfs.erofs +---------- + +two main kinds of erofs images can be generated: (un)compressed. + + - For uncompressed images, there will be none of compression + files in these images. However, it can decide whether the tail + block of a file should be inlined or not properly [1]. + + - For compressed images, it will try to use lz4(hc) algorithm + first for each regular file and see if storage space can be + saved with compression. If not, fallback to an uncompressed + file. + How to generate erofs images ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -85,6 +89,40 @@ git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git -b obsoleted PLEASE NOTE: This version is highly _NOT recommended_ now. +erofsfuse (experimental, unstable) +---------------------------------- + +erofsfuse is introduced to support erofs format for various platforms +(including older linux kernels) and new on-disk features iteration. +It can also be used as an unpacking tool for unprivileged users. + +It supports fixed-sized output decompression *without* any in-place +I/O or in-place decompression optimization, Also like the other FUSE +implementations, it suffers from most common performance issues (e.g. +significant I/O overhead, double caching, etc.) + +Therefore, NEVER use it if performance is the top concern. + +Note that xattr & ACL aren't implemented yet due to the current Android +use-case vs limited time. If you have some interest, contribution is, +as always, welcome. + +How to mount a erofs image with erofsfuse +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As the other FUSE implementations, it's quite simple to mount with +erofsfuse, e.g.: + $ erofsfuse foo.erofs.img foo/ + +Alternatively, to make it run in foreground (with debugging level 3): + $ erofsfuse -f --dbglevel=3 foo.erofs.img foo/ + +To debug erofsfuse (also automatically run in foreground): + $ erofsfuse -d foo.erofs.img foo/ + +To unmount an erofsfuse mountpoint as a non-root user: + $ fusermount -u foo/ + Contribution ------------ @@ -150,3 +188,8 @@ Comments and already included in lz4-1.9.3, see: https://github.com/lz4/lz4/releases/tag/v1.9.3 +[5] LZ4_decompress_safe_partial is broken in 1.9.2 + https://github.com/lz4/lz4/issues/783 + + which is also resolved in lz4-1.9.3. + -- 2.24.0