* [PATCH] erofs-utils: document erofsfuse in README
[not found] <20201205151545.10935-1-hsiangkao.ref@aol.com>
@ 2020-12-05 15:15 ` Gao Xiang via Linux-erofs
2020-12-05 15:41 ` [PATCH v2] " Gao Xiang via Linux-erofs
0 siblings, 1 reply; 2+ messages in thread
From: Gao Xiang via Linux-erofs @ 2020-12-05 15:15 UTC (permalink / raw)
To: linux-erofs
From: Gao Xiang <hsiangkao@aol.com>
We are about to release erofs-utils 1.2, add some words
to README about erofsfuse itself.
Signed-off-by: Gao Xiang <hsiangkao@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
^ permalink raw reply related [flat|nested] 2+ messages in thread
* [PATCH v2] erofs-utils: document erofsfuse in README
2020-12-05 15:15 ` [PATCH] erofs-utils: document erofsfuse in README Gao Xiang via Linux-erofs
@ 2020-12-05 15:41 ` Gao Xiang via Linux-erofs
0 siblings, 0 replies; 2+ messages in thread
From: Gao Xiang via Linux-erofs @ 2020-12-05 15:41 UTC (permalink / raw)
To: linux-erofs
From: Gao Xiang <hsiangkao@aol.com>
We are about to release erofs-utils 1.2, add some words
to README about erofsfuse itself.
Signed-off-by: Gao Xiang <hsiangkao@aol.com>
---
changes since v1:
- fix some typos;
- add libfuse dependency and "How to build erofsfuse" section.
README | 90 +++++++++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 73 insertions(+), 17 deletions(-)
diff --git a/README b/README
index 980f1d02cb19..0001a67fc37c 100644
--- a/README
+++ b/README
@@ -2,26 +2,14 @@ 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 & build
+--------------------
-Dependencies
-~~~~~~~~~~~~
+ lz4 1.8.0+ for lz4 enabled [2], lz4 1.9.3+ highly recommended [4][5].
- lz4-1.8.0+ for lz4 enabled [2], lz4-1.9.3+ highly recommended [4].
+ libfuse 2.6+ for erofsfuse enabled as a plus.
How to build for lz4-1.9.0 or above
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -39,6 +27,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 +47,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 +91,51 @@ 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 build erofsfuse
+~~~~~~~~~~~~~~~~~~~~~~
+
+It's disabled by default as an experimental feature for now, to enable
+and build it manually:
+
+ $ ./configure --enable-fuse
+ $ make
+
+erofsfuse binary will be generated under fuse folder.
+
+How to mount an 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 +201,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
^ permalink raw reply related [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-12-05 16:21 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <20201205151545.10935-1-hsiangkao.ref@aol.com>
2020-12-05 15:15 ` [PATCH] erofs-utils: document erofsfuse in README Gao Xiang via Linux-erofs
2020-12-05 15:41 ` [PATCH v2] " Gao Xiang via Linux-erofs
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).