Updated README with documentation of general information and build options

2 files changed, 70 insertions, 13 deletions

diff --git a/README.md b/README.md
index b61682b..f9074a0 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,74 @@
-The master branch supports 4.19.x kernels.
+# xloop - eXtended loop device
 
-Building the modules:
+The eXtended loop (xloop) device provides a subsystem for the Linux kernel to register custom file format drivers. Those file format drivers enable the possibility to write and read file formats in the kernel space rather than in the user space.
+
+This repository contains the source code for the xloop Linux kernel modules
+
+  - **xloop**: eXtended loop device with file format subsystem
+  - **xloop_file_format_raw**: file format subsystem driver for RAW files
+  - **xloop_file_format_qcow**: file format subsystem driver for QCOW files
+
+and the user space utility **xlosetup** to configure xloop devices.
+
+
+## Build
+
+### Preparation
+Before a build takes place, you should create a `build` directory inside the root folder of the repository. After that, change your working directory to that new directory as follows:
+
+```shell
+mkdir build
+cd build
+```
+
+
+### Configuration
+A build of the xloop Linux kernel modules and the xlosetup utiliy can be configured and customized by the following configuration variables (CMake cache entries):
+
+| Variable                  | Type   | Values                                  | Default value           | Description                                         |
+|:--------------------------|:-------|:----------------------------------------|:------------------------|-----------------------------------------------------|
+| `CMAKE_BUILD_TYPE`        | STRING | {`Debug`, `Release`}                    | `Debug`                 | Build configuration of the xloop project.           |
+| `KERNEL_DIR`              | PATH   | {`a` .. `z`, `A` .. `Z`, `/`, `_`, `-`} | /lib/modules/`uname -r` | Path to Linux kernel modules to compile against.    |
+| `XLOOP_MAJOR`             | NUMBER | {`0` .. `255`}                          | `120`                   | Major number for xloop devices.                     |
+| `XLOOP_CTRL_MINOR`        | NUMBER | {`0` .. `255`}                          | `15`                    | Minor number for the xloop-control device.          |
+| `BLK_DEV_XLOOP_MIN_COUNT` | NUMBER | {`0` .. `255`}                          | `8`                     | Number of xloop devices to pre-create at init time. |
+
+A value from the range of appropriate values can be assigend to each configuration variable by executing CMake once with the following command pattern:
+
+```shell
+cmake -D<VARIABLE>=<VALUE> [-D ...] ../.
+```
+
+
+### Debug
+In the `Debug` build configuration, all Linux kernel modules and the utility can be built by calling `make`:
+
+```shell
+make
+```
+
+Optionally, the output files can be installed with superuser permissions on the local system using the Makefile target `install`:
 
 ```shell
-$ make CONFIG_BLK_DEV_LOOP=m CONFIG_BLK_DEV_LOOP_FILE_FMT_QCOW=m CONFIG_BLK_DEV_LOOP_FILE_FMT_RAW=m
+sudo make install
 ```
 
-Results in:
-* xloop.ko
-* loop_file_fmt_raw.ko
-* loop_file_fmt_qcow.ko
 
-Clean:
+### Packages
+In the `Release` build configuration, installation packages can be built by calling the make target `package`:
+
 ```shell
-$ make clean
+make package
 ```
+
+This target creates a Debian installation package (\*.deb) and a compressed archive (\*.tar.gz) containing the built xloop Linux kernel modules and the xlosetup utility executable as well as its man page and bash-completion support.
+
+
+### Sources
+In the `Release` build configuration, sources can be built by calling the make target `package_source`:
+
+```shell
+make package_source
+```
+
+This target creates compressed archives (\*_sources.tar.gz and \*_sources.zip) containing the source code of this repository for code distribution purposes.
diff --git a/kernel/CMakeLists.txt b/kernel/CMakeLists.txt
index ffa97e6..8d08c15 100644
--- a/kernel/CMakeLists.txt
+++ b/kernel/CMakeLists.txt
@@ -8,15 +8,15 @@ include(kernel)
 
 # set Linux kernel directory
 set(KERNEL_DIR "/lib/modules/${CMAKE_SYSTEM_VERSION}"
-    CACHE PATH "Path to kernel sources to compile against")
+    CACHE PATH "Path to Linux kernel modules to compile against")
 
 # define xloop device specific options
 set(XLOOP_CTRL_MINOR 15
-   CACHE STRING "Minor number for xloop-control device")
+   CACHE STRING "Minor number for the xloop-control device")
 
 # print configured settings
-message(STATUS "Kernel module path is " ${KERNEL_DIR})
-message(STATUS "Minor number for xloop-control device is " ${XLOOP_CTRL_MINOR})
+message(STATUS "Path to Linux kernel modules to compile against is " ${KERNEL_DIR})
+message(STATUS "Minor number for the xloop-control device is " ${XLOOP_CTRL_MINOR})
 
 # set C flags for a Linux kernel module
 set(KERNEL_C_FLAGS "-DCONFIG_BLK_DEV_XLOOP_MIN_COUNT=${BLK_DEV_XLOOP_MIN_COUNT} -DXLOOP_MAJOR=${XLOOP_MAJOR} -DXLOOP_CTRL_MINOR=${XLOOP_CTRL_MINOR}"