[PATCH 4/4] docs: expand build instructions and multithreading documentation
Saksham
aghi.saksham5 at gmail.com
Mon Mar 30 16:28:40 AEDT 2026
The previous build documentation was somewhat minimal and did not fully
emphasize the available configuration options, particularly regarding
multithreading. While the feature was mentioned, its importance for
performance in large image creation was not sufficiently highlighted,
and it lacked clear context on its default behavior and requirements.
This commit refactors docs/INSTALL.md to provide a more comprehensive
and professional guide for developers and users. Key changes include:
1. Consolidated dependencies list: Grouped all mandatory and optional
dependencies (LZ4, XZ, libfuse, libzstd, libuuid) for better
clarity, including specific version recommendations and links to
related issues for LZ4.
2. Enhanced Multithreading documentation: Expanded the section on
--enable-multithreading to explain its role in accelerating data
compression in mkfs.erofs. Clarified that the configuration script
attempts to auto-detect support and provided explicit instructions
on how to force the feature on or off.
3. Added advanced configuration section: Introduced a dedicated section
for LZMA and multithreading, making it easier for users to find
performance-related options.
4. Included other notable options: Added mentions of --enable-lz4,
--enable-zstd, and --with-selinux to give users a broader overview
of the tool suite's capabilities.
5. Improved formatting and copy: Standardized headers and lists, fixed
minor phrasing, and ensured that the installation instructions are
clear and follow best practices.
These improvements ensure that the build documentation is as high-quality
as the project's source code, providing a clear path for anyone looking
to build and optimize erofs-utils for their specific environment.
Signed-off-by: Saksham <aghi.saksham5 at gmail.com>
---
docs/INSTALL.md | 97 ++++++++++++++++++++++++++++++-------------------
1 file changed, 60 insertions(+), 37 deletions(-)
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index d96b15c..d51c153 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,8 +1,8 @@
This document describes how to configure and build erofs-utils from
source.
-See the [README](../README) file in the top level directory about
-the brief overview of erofs-utils.
+See the [README](../README) file in the top level directory for
+a brief overview of erofs-utils.
## Quick Start
@@ -24,25 +24,23 @@ $ make
# make install
```
-## Dependencies & build
+## Dependencies & Build Requirements
-LZ4 1.9.3+ for LZ4(HC) enabled [^1].
+- **LZ4 1.9.3+**: Required for LZ4 and LZ4HC compression support [^1].
+- **XZ Utils 5.3.2alpha+**: Required for LZMA support. Version 5.4+ is highly
+ recommended for better performance and stability.
+- **libfuse 2.6+**: Required if you wish to build `erofsfuse`.
+- **libzstd 1.4.0+**: Required for Zstandard (zstd) compression support.
+- **libuuid**: Required for filesystem UUID support.
-[XZ Utils 5.3.2alpha+](https://tukaani.org/xz/xz-5.3.2alpha.tar.gz) for
-LZMA enabled, [XZ Utils 5.4+](https://tukaani.org/xz/xz-5.4.1.tar.gz)
-highly recommended.
+[^1]: It is not recommended to use LZ4 versions below 1.9.3 due to potential
+crashes related to `LZ4_compress_destSize()`, `LZ4_compress_HC_destSize()`, or
+`LZ4_decompress_safe_partial()`.
-libfuse 2.6+ for erofsfuse enabled.
+## Core Build Process
-[^1]: It's not recommended to use LZ4 versions under 1.9.3 since
-unexpected crashes could make trouble to end users due to broken
-LZ4_compress_destSize() (fixed in v1.9.2),
-[LZ4_compress_HC_destSize()](https://github.com/lz4/lz4/commit/660d21272e4c8a0f49db5fc1e6853f08713dff82) or
-[LZ4_decompress_safe_partial()](https://github.com/lz4/lz4/issues/783).
-
-## How to build with LZ4
-
-To build, the following commands can be used in order:
+To build the core utilities (`mkfs.erofs`, `dump.erofs`, and `fsck.erofs`),
+execute the following commands:
``` sh
$ ./autogen.sh
@@ -50,54 +48,79 @@ $ ./configure
$ make
```
-`mkfs.erofs`, `dump.erofs` and `fsck.erofs` binaries will be
-generated under the corresponding folders.
+The resulting binaries will be located in their respective project
+subdirectories.
-## How to build with liblzma
+## Advanced Configuration Options
-In order to enable LZMA support, build with the following commands:
+### Enabling LZMA Support
+
+LZMA compression is not enabled by default. To include it in your build:
``` sh
$ ./configure --enable-lzma
$ make
```
-Additionally, you could specify liblzma target paths with
-`--with-liblzma-incdir` and `--with-liblzma-libdir` manually.
+If your LZMA libraries are in non-standard locations, you can specify them
+using:
+`--with-liblzma-incdir=DIR` and `--with-liblzma-libdir=DIR`.
+
+### Enabling Multithreading Support
-## How to build with multithreading
+Multithreading significantly accelerates the compression process in
+`mkfs.erofs` by utilizing multiple CPU cores.
-To enable multithreading support for mkfs.erofs, use the following:
+To explicitly enable multithreading support:
``` sh
$ ./configure --enable-multithreading
$ make
```
-Note that multithreading is enabled by default if the compiler supports it.
-To disable it explicitly, use `--disable-multithreading`.
+**Note:** The configuration script attempts to detect multithreading support
+(e.g., via pthreads) and may enable it by default if compatible libraries and
+headers are found on your system. To ensure it is disabled, use
+`--disable-multithreading`.
-## How to build erofsfuse
+When enabled, `mkfs.erofs` will use multiple worker threads for data
+compression, which is highly recommended for large image creation on
+multiprocessor systems.
-It's disabled by default as an experimental feature for now due
-to the extra libfuse dependency, to enable and build it manually:
+### Building erofsfuse
+
+`erofsfuse` is currently considered an experimental feature and is disabled
+by default to avoid a mandatory `libfuse` dependency. To build it:
``` sh
$ ./configure --enable-fuse
$ make
```
-`erofsfuse` binary will be generated under `fuse` folder.
+The `erofsfuse` binary will be generated in the `fuse/` directory.
+
+### Other Notable Configure Options
+
+- `--enable-lz4`: Enable LZ4 compression support (default: auto).
+- `--enable-zstd`: Enable Zstandard compression support (default: auto).
+- `--with-selinux`: Enable SELinux support for labeling (default: auto).
-## How to install erofs-utils manually
+Run `./configure --help` for a complete list of available options.
-Use the following command to install erofs-utils binaries:
+## Installation
+
+To install the compiled utilities to your system:
``` sh
# make install
```
-By default, `make install` will install all the files in
-`/usr/local/bin`, `/usr/local/lib` etc. You can specify an
-installation prefix other than `/usr/local` using `--prefix`,
-for instance `--prefix=$HOME`.
+By default, files are installed into `/usr/local/bin`, `/usr/local/lib`, etc.
+You can change the installation target using the `--prefix` option during
+configuration:
+
+``` sh
+$ ./configure --prefix=$HOME/mytools
+$ make
+# make install
+```
--
2.53.0
More information about the Linux-erofs
mailing list