summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 14:14:34 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 14:14:34 +0200
commita35bf2eb54cceb5cb8e3f8302cf19e15ca60a170 (patch)
treea990dd52d7b505cfd627db9f0d5eb4812189e622 /README.md
parent75a055895c06bd67c1a0d99e1da1a8a79f3929ea (diff)
Update documentation
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
Diffstat (limited to 'README.md')
-rw-r--r--README.md67
1 files changed, 45 insertions, 22 deletions
diff --git a/README.md b/README.md
index 48c4e7f..8efea3d 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ on embedded devices, live systems or simply as a compressed archive format.
Think of it as a .tar.gz that you can mount (or XZ, LZO, LZ4, ZSTD).
As the name suggests, this is not the original user space tooling for
-SquashFS, which are currently maintained in parallel elsewhere. After a
+SquashFS, which is currently maintained in parallel elsewhere. After a
long period of silence on the SourceForge site and mailing list, I
attempted to fork the existing code base with the intention to
restructure/clean it up and add many features I personally perceived to
@@ -14,10 +14,12 @@ be missing, but I ultimately decided that it would be easier to start
from scratch than to work with the existing code.
Here are some of the features that primarily distinguish this package from
-the (at the time of writing recent) squashfs-tools 4.3:
+the squashfs-tools 4.3 (latest recent version at the time this project was
+started):
- - Reproducible SquashFS images, i.e. deterministic packing without
- any local time stamps.
+ - A shared library that encapsulates code for accessing SquashFS images,
+ usable by 3rd party applications.
+ - Reproducible, deterministic SquashFS images.
- Linux `gen_init_cpio` like file listing for micro managing the
file system contents, permissions, and ownership without having to replicate
the file system (and especially permissions) locally.
@@ -42,6 +44,13 @@ together with the existing tools:
- `tar2sqfs` can turn a tarball (read from stdin) into a SquashFS image.
- `sqfsdiff` can compare the contents of two SquashFS images.
+
+Most of the actual logic of those tools is implemented in the `libsquashfs.so`
+library that (by default) gets installed on the system along with its header
+files, allowing 3rd party applications to use it (e.g. for embedding SqushFS
+inside a custom container format without having to implement the SquashFS
+part).
+
# Getting and Building the Source Code
Official release tarballs can be obtained here:
@@ -65,36 +74,43 @@ If you work on the git tree, you need to bootstrap the build system first:
## Structure of the Source Code
-The main functionality of the package is split up into a number of static
-libraries. The actual tools are mainly wrappers around the libraries that
-combine their functionality in a useful way.
+The main functionality of the package is split up into a number libraries.
+The actual tools are mainly wrappers around the libraries that combine their
+functionality in a useful way.
The headers of all the libraries can be found in the `include` directory,
whereas the source code is in a per-library sub-directory within `lib`.
+The `include` directory has a sub-directory `sqfs` which contains the public
+headers of `libsquashfs.so` which are installed along with the library. All
+other headers are private to this package.
+
The following components exist:
- - `libutil.a` built from files in `lib/util` contains miscellaneous helper
+ - `libutil.la` built from files in `lib/util` contains miscellaneous helper
functions.
- - `libcompress.a` built from files in `lib/comp/` contains an abstract
- interface for block compression and concrete implementations using
- different compressor libraries. It uses an enum from `squashfs.h` to
- identify compressors but it only depends on functions from `libutil.a`.
- A program using `libcompress.a` also has to link against the various
- compressor libraries.
- `libfstree.a` built from files in `lib/fstree` contains functions for
- manipulating a file system tree. It only depends on `libutil.a`
+ manipulating a file system tree. It only depends on `libutil.la`
- `libtar.a` built from files in `lib/tar` contains data structures and
functions for parsing and creating tar files. It only depends
- on `libutil.a`.
- - `libsquashfs.a` built from files in `lib/sqfs` contains all kinds of
- data structures for reading and writing SquashFS archives. It is built
- on top of `libutil.a`, `libfstree.a` and `libcompress.a`.
+ on `libutil.la`.
+ - `libsquashfs.so` built from files in `lib/sqfs` contains all kinds of
+ data structures for reading and writing SquashFS archives. Abstractions
+ for data compression and so on. It contains the actual brains of this
+ package. It uses `libutil.la` internally.
+ - `libsqfshelper.a` built from files in `lib/sqfshelper` contains a bunch
+ of high level glue code that combines `libfstree.a` and `libsquashfs.so`
+ and provides common functionality used by all the tools.
The headers in `include` are stuffed with comments on functions an data
structures.
The `tests` sub-directory contains unit tests for the libraries.
+To allow 3rd party applications to use `libsquashfs.so` without restricting
+their choice of license, the code in the `lib/sqfs` and `lib/util`
+sub-directories is licensed under the LGPLv3, in contrast to the rest of this
+package.
+
## Further Information
A documentation of the SquashFS on-disk format can be found here:
@@ -103,9 +119,16 @@ https://dr-emann.github.io/squashfs/
# Copyright & License
-The software in this package is released under the terms and conditions of the
-GNU General Public License version 3 or later. The file `LICENSE` contains a
-copy of the license.
+The code of the `libsquashfs` library is released under the terms and
+conditions of the GNU Lesser General Public License version 3 or later. The
+file `LICENSE-lgpl.txt` contains a copy of the license. Since the license is
+based on the General Public License version 3 and makes references to it
+instead of duplicating text, a copy of the GPL version 3 is also provided
+by the file `LICENSE-gpl.txt`.
+
+The rest of the software in this package is released under the terms and
+conditions of the GNU General Public License version 3 or later. The
+file `LICENSE-gpl.txt` contains a copy of the license.
The original source code in this package has been written by David
Oberhollenzer in 2019. Additional contributions have been added since the