docs: Add build deps and distro testing wrappers (#191)

- Add missing build dependencies (html2markdown, qemu)
- Document distro testing wrapper scripts with usage examples
- Add interactive shell targets for debugging docker builds
- Fix usage in krun-ubuntu.sh

Author: stanek-michal

README.md

@@ -95,8 +95,13 @@ quark can be built natively or via a container, native is preferred and depends
 - clang
 - gnumake
 - gcc
-- mandoc (for docs).
+- mandoc (for docs)
+- html2markdown utility  
+  (for docs, pre-built binaries are available at  
+  https://github.com/JohannesKaufmann/html-to-markdown/releases)
 - m4
+- qemu (for testing)
+- zstd
 
 Make sure to clone the repository recursively: [*git clone --recursive*](#git).
 
@@ -116,6 +121,10 @@ Clean object files from quark.
 
 Builds quark inside a docker container, so you don't have to worry about having build dependencies.
 
+[*docker-shell*](#docker-shell)
+
+Spawns an interactive shell inside the same builder container created by ‘make docker’. Handy for debugging failed builds, inspecting artifacts etc.
+
 [*docker-cross-arm64*](#docker-cross-arm64)
 
 Builds quark for arm64 inside a docker container.
@@ -124,9 +133,17 @@ Builds quark for arm64 inside a docker container.
 
 Builds quark inside a centos7 docker container, useful for linking against ancient glibc-2.17.
 
+[*centos7-shell*](#centos7-shell)
+
+Opens an interactive shell in the centos7 builder container.
+
 [*alpine*](#alpine)
 
-Builds quark inside an alpine docker container, so we can track musl builds.
+Builds quark inside an Alpine Linux docker container, so we can track musl builds.
+
+[*alpine-shell*](#alpine-shell)
+
+Interactive shell inside the Alpine builder image.
 
 [*test*](#test)
 
@@ -201,7 +218,24 @@ $ make initramfs.gz
 $ ./krun.sh initramfs.gz kernel-images/amd64/linux-4.18.0-553.el8_10.x86_64 quark-test -vvv
 ```
 
-Note that you can pass arguments to the utility and you have to make initramfs.gz first.
+Convenience wrappers for Fedora, RHEL, and Ubuntu, automate the above by fetching the appropriate kernel packages, extracting vmlinuz and boot-strapping qemu-system-x86\_64:
+
+```
+$ make initramfs.gz
+$ ./krun-fedora.sh initramfs.gz 40 quark-test -vvv
+$ ./krun-rhel.sh -v initramfs.gz 9 quark-test
+$ ./krun-ubuntu.sh initramfs.gz 24.04 quark-test -b t_dns
+```
+
+The version number after ‘initramfs.gz’ selects the Fedora, RHEL, or Ubuntu version. All remaining arguments are passed verbatim to [quark-test(8)](https://elastic.github.io/quark/quark-test.8.html), enabling targeted runs such as:
+
+```
+$ ./krun-fedora.sh initramfs.gz 41 quark-test -b t_fork_exec_exit
+```
+
+These scripts require KVM access and therefore must be executed on a host kernel as root. They are unsuitable for container environments; the docker targets only build quark and do not attempt to run the test suite.
+
+*make test-valgrind* runs the same suite under valgrind and is useful for catching memory errors, while *make test-kernel* cycles through a set of kernel images in kernel\_images folder to ensure probe compatibility.
 
 # [INCLUDED BINARIES](#INCLUDED_BINARIES)
 

docs/index.html

@@ -163,8 +163,15 @@ <h1 class="Sh" id="BUILDING"><a class="permalink" href="#BUILDING">BUILDING</a><
   <li>clang</li>
   <li>gnumake</li>
   <li>gcc</li>
-  <li>mandoc (for docs).</li>
+  <li>mandoc (for docs)</li>
+  <li>html2markdown utility
+    <br/>
+     (for docs, pre-built binaries are available at
+    <br/>
+     https://github.com/JohannesKaufmann/html-to-markdown/releases)</li>
   <li>m4</li>
+  <li>qemu (for testing)</li>
+  <li>zstd</li>
 </ul>
 <p class="Pp" id="git">Make sure to clone the repository recursively:
     <a class="permalink" href="#git"><i class="Em">git clone
@@ -190,15 +197,23 @@ <h1 class="Sh" id="BUILDING"><a class="permalink" href="#BUILDING">BUILDING</a><
   <dt id="docker"><a class="permalink" href="#docker"><i class="Em">docker</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> inside a docker container, so you
       don't have to worry about having build dependencies.</dd>
+  <dt id="docker-shell"><a class="permalink" href="#docker-shell"><i class="Em">docker-shell</i></a></dt>
+  <dd>Spawns an interactive shell inside the same builder container created by
+      &#x2018;make docker&#x2019;. Handy for debugging failed builds, inspecting
+      artifacts etc.</dd>
   <dt id="docker-cross-arm64"><a class="permalink" href="#docker-cross-arm64"><i class="Em">docker-cross-arm64</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> for arm64 inside a docker
     container.</dd>
   <dt id="centos7"><a class="permalink" href="#centos7"><i class="Em">centos7</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> inside a centos7 docker container,
       useful for linking against ancient glibc-2.17.</dd>
+  <dt id="centos7-shell"><a class="permalink" href="#centos7-shell"><i class="Em">centos7-shell</i></a></dt>
+  <dd>Opens an interactive shell in the centos7 builder container.</dd>
   <dt id="alpine"><a class="permalink" href="#alpine"><i class="Em">alpine</i></a></dt>
-  <dd>Builds <code class="Nm">quark</code> inside an alpine docker container, so
-      we can track musl builds.</dd>
+  <dd>Builds <code class="Nm">quark</code> inside an Alpine Linux docker
+      container, so we can track musl builds.</dd>
+  <dt id="alpine-shell"><a class="permalink" href="#alpine-shell"><i class="Em">alpine-shell</i></a></dt>
+  <dd>Interactive shell inside the Alpine builder image.</dd>
   <dt id="test"><a class="permalink" href="#test"><i class="Em">test</i></a></dt>
   <dd>Builds and runs
     <a class="Xr" href="quark-test.8.html">quark-test(8)</a>.</dd>
@@ -267,8 +282,31 @@ <h1 class="Sh" id="TESTING"><a class="permalink" href="#TESTING">TESTING</a></h1
 <pre>$ make initramfs.gz
 $ ./krun.sh initramfs.gz kernel-images/amd64/linux-4.18.0-553.el8_10.x86_64 quark-test -vvv</pre>
 </div>
-<p class="Pp">Note that you can pass arguments to the utility and you have to
-    make <span class="Pa">initramfs.gz</span> first.</p>
+<p class="Pp">Convenience wrappers for Fedora, RHEL, and Ubuntu, automate the
+    above by fetching the appropriate kernel packages, extracting
+    <span class="Pa">vmlinuz</span> and boot-strapping
+    <span class="Pa">qemu-system-x86_64</span>:</p>
+<div class="Bd Pp Li">
+<pre>$ make initramfs.gz
+$ ./krun-fedora.sh initramfs.gz 40 quark-test -vvv
+$ ./krun-rhel.sh -v initramfs.gz 9 quark-test
+$ ./krun-ubuntu.sh initramfs.gz 24.04 quark-test -b t_dns</pre>
+</div>
+The version number after &#x2018;initramfs.gz&#x2019; selects the Fedora, RHEL,
+  or Ubuntu version. All remaining arguments are passed verbatim to
+  <a class="Xr" href="quark-test.8.html">quark-test(8)</a>, enabling targeted
+  runs such as:
+<div class="Bd Pp Li">
+<pre>$ ./krun-fedora.sh initramfs.gz 41 quark-test -b t_fork_exec_exit</pre>
+</div>
+These scripts require KVM access and therefore must be executed on a host kernel
+  as root. They are unsuitable for container environments; the
+  <span class="Pa">docker</span> targets only build
+  <code class="Nm">quark</code> and do not attempt to run the test suite.
+<p class="Pp"><i class="Em">make test-valgrind</i> runs the same suite under
+    valgrind and is useful for catching memory errors, while <i class="Em">make
+    test-kernel</i> cycles through a set of kernel images in kernel_images
+    folder to ensure probe compatibility.</p>
 </section>
 <section class="Sh">
 <h1 class="Sh" id="INCLUDED_BINARIES"><a class="permalink" href="#INCLUDED_BINARIES">INCLUDED
@@ -416,7 +454,7 @@ <h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1
 </div>
 <table class="foot">
   <tr>
-    <td class="foot-date">June 4, 2025</td>
+    <td class="foot-date">June 16, 2025</td>
     <td class="foot-os">Linux</td>
   </tr>
 </table>

docs/quark.7.html

@@ -163,8 +163,15 @@ <h1 class="Sh" id="BUILDING"><a class="permalink" href="#BUILDING">BUILDING</a><
   <li>clang</li>
   <li>gnumake</li>
   <li>gcc</li>
-  <li>mandoc (for docs).</li>
+  <li>mandoc (for docs)</li>
+  <li>html2markdown utility
+    <br/>
+     (for docs, pre-built binaries are available at
+    <br/>
+     https://github.com/JohannesKaufmann/html-to-markdown/releases)</li>
   <li>m4</li>
+  <li>qemu (for testing)</li>
+  <li>zstd</li>
 </ul>
 <p class="Pp" id="git">Make sure to clone the repository recursively:
     <a class="permalink" href="#git"><i class="Em">git clone
@@ -190,15 +197,23 @@ <h1 class="Sh" id="BUILDING"><a class="permalink" href="#BUILDING">BUILDING</a><
   <dt id="docker"><a class="permalink" href="#docker"><i class="Em">docker</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> inside a docker container, so you
       don't have to worry about having build dependencies.</dd>
+  <dt id="docker-shell"><a class="permalink" href="#docker-shell"><i class="Em">docker-shell</i></a></dt>
+  <dd>Spawns an interactive shell inside the same builder container created by
+      &#x2018;make docker&#x2019;. Handy for debugging failed builds, inspecting
+      artifacts etc.</dd>
   <dt id="docker-cross-arm64"><a class="permalink" href="#docker-cross-arm64"><i class="Em">docker-cross-arm64</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> for arm64 inside a docker
     container.</dd>
   <dt id="centos7"><a class="permalink" href="#centos7"><i class="Em">centos7</i></a></dt>
   <dd>Builds <code class="Nm">quark</code> inside a centos7 docker container,
       useful for linking against ancient glibc-2.17.</dd>
+  <dt id="centos7-shell"><a class="permalink" href="#centos7-shell"><i class="Em">centos7-shell</i></a></dt>
+  <dd>Opens an interactive shell in the centos7 builder container.</dd>
   <dt id="alpine"><a class="permalink" href="#alpine"><i class="Em">alpine</i></a></dt>
-  <dd>Builds <code class="Nm">quark</code> inside an alpine docker container, so
-      we can track musl builds.</dd>
+  <dd>Builds <code class="Nm">quark</code> inside an Alpine Linux docker
+      container, so we can track musl builds.</dd>
+  <dt id="alpine-shell"><a class="permalink" href="#alpine-shell"><i class="Em">alpine-shell</i></a></dt>
+  <dd>Interactive shell inside the Alpine builder image.</dd>
   <dt id="test"><a class="permalink" href="#test"><i class="Em">test</i></a></dt>
   <dd>Builds and runs
     <a class="Xr" href="quark-test.8.html">quark-test(8)</a>.</dd>
@@ -267,8 +282,31 @@ <h1 class="Sh" id="TESTING"><a class="permalink" href="#TESTING">TESTING</a></h1
 <pre>$ make initramfs.gz
 $ ./krun.sh initramfs.gz kernel-images/amd64/linux-4.18.0-553.el8_10.x86_64 quark-test -vvv</pre>
 </div>
-<p class="Pp">Note that you can pass arguments to the utility and you have to
-    make <span class="Pa">initramfs.gz</span> first.</p>
+<p class="Pp">Convenience wrappers for Fedora, RHEL, and Ubuntu, automate the
+    above by fetching the appropriate kernel packages, extracting
+    <span class="Pa">vmlinuz</span> and boot-strapping
+    <span class="Pa">qemu-system-x86_64</span>:</p>
+<div class="Bd Pp Li">
+<pre>$ make initramfs.gz
+$ ./krun-fedora.sh initramfs.gz 40 quark-test -vvv
+$ ./krun-rhel.sh -v initramfs.gz 9 quark-test
+$ ./krun-ubuntu.sh initramfs.gz 24.04 quark-test -b t_dns</pre>
+</div>
+The version number after &#x2018;initramfs.gz&#x2019; selects the Fedora, RHEL,
+  or Ubuntu version. All remaining arguments are passed verbatim to
+  <a class="Xr" href="quark-test.8.html">quark-test(8)</a>, enabling targeted
+  runs such as:
+<div class="Bd Pp Li">
+<pre>$ ./krun-fedora.sh initramfs.gz 41 quark-test -b t_fork_exec_exit</pre>
+</div>
+These scripts require KVM access and therefore must be executed on a host kernel
+  as root. They are unsuitable for container environments; the
+  <span class="Pa">docker</span> targets only build
+  <code class="Nm">quark</code> and do not attempt to run the test suite.
+<p class="Pp"><i class="Em">make test-valgrind</i> runs the same suite under
+    valgrind and is useful for catching memory errors, while <i class="Em">make
+    test-kernel</i> cycles through a set of kernel images in kernel_images
+    folder to ensure probe compatibility.</p>
 </section>
 <section class="Sh">
 <h1 class="Sh" id="INCLUDED_BINARIES"><a class="permalink" href="#INCLUDED_BINARIES">INCLUDED
@@ -416,7 +454,7 @@ <h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1
 </div>
 <table class="foot">
   <tr>
-    <td class="foot-date">June 4, 2025</td>
+    <td class="foot-date">June 16, 2025</td>
     <td class="foot-os">Linux</td>
   </tr>
 </table>

krun-ubuntu.sh

@@ -30,8 +30,8 @@ usage() {
 	echo "  command...      Command to run in guest"
 	echo
 	echo "Examples:"
-	echo "  $SCRIPT initramfs.gz 40 /bin/bash"
-	echo "  $SCRIPT -v initramfs.gz rawhide quark-test -vvv"
+	echo "  $SCRIPT initramfs.gz 22.04 /bin/bash"
+	echo "  $SCRIPT -v initramfs.gz 24.04 quark-test -vvv"
 	exit 1
 }
 
@@ -51,7 +51,7 @@ while getopts "vh" opt; do
 done
 shift $((OPTIND - 1))
 
-[[ $# -lt 2 ]] && usage
+[[ $# -lt 3 ]] && usage
 [[ $ARCH =~ ^(amd64|arm64)$ ]] || die "Invalid architecture: $ARCH"
 
 INITRAMFS="$1"; shift

quark.7

@@ -152,9 +152,17 @@ gnumake
 .It
 gcc
 .It
-mandoc (for docs).
+mandoc (for docs)
+.It
+html2markdown utility
+     (for docs, pre-built binaries are available at
+     https://github.com/JohannesKaufmann/html-to-markdown/releases)
 .It
 m4
+.It
+qemu (for testing)
+.It
+zstd
 .El
 .Pp
 Make sure to clone the repository recursively:
@@ -201,6 +209,10 @@ Builds
 .Nm quark
 inside a docker container, so you don't have to worry about
 having build dependencies.
+.It Em docker-shell
+Spawns an interactive shell inside the same builder container created by
+.Sq make docker .
+Handy for debugging failed builds, inspecting artifacts etc.
 .It Em docker-cross-arm64
 Builds
 .Nm quark
@@ -210,10 +222,14 @@ Builds
 .Nm quark
 inside a centos7 docker container, useful for linking against
 ancient glibc-2.17.
+.It Em centos7-shell
+Opens an interactive shell in the centos7 builder container.
 .It Em alpine
 Builds
 .Nm quark
-inside an alpine docker container, so we can track musl builds.
+inside an Alpine Linux docker container, so we can track musl builds.
+.It Em alpine-shell
+Interactive shell inside the Alpine builder image.
 .It Em test
 Builds and runs
 .Xr quark-test 8 .
@@ -294,9 +310,40 @@ $ make initramfs.gz
 $ ./krun.sh initramfs.gz kernel-images/amd64/linux-4.18.0-553.el8_10.x86_64 quark-test -vvv
 .Ed
 .Pp
-Note that you can pass arguments to the utility and you have to make
-.Pa initramfs.gz
-first.
+Convenience wrappers for Fedora, RHEL, and Ubuntu, automate the
+above by fetching the appropriate kernel packages, extracting
+.Pa vmlinuz
+and boot-strapping
+.Pa qemu-system-x86_64 :
+.Bd -literal
+$ make initramfs.gz
+$ ./krun-fedora.sh initramfs.gz 40 quark-test -vvv
+$ ./krun-rhel.sh -v initramfs.gz 9 quark-test
+$ ./krun-ubuntu.sh initramfs.gz 24.04 quark-test -b t_dns
+.Ed
+The version number after
+.Sq initramfs.gz
+selects the Fedora, RHEL, or Ubuntu version.
+All remaining arguments are passed verbatim to
+.Xr quark-test 8 ,
+enabling targeted runs such as:
+.Bd -literal
+$ ./krun-fedora.sh initramfs.gz 41 quark-test -b t_fork_exec_exit
+.Ed
+These scripts require KVM access and therefore must be executed on a host
+kernel as root.
+They are unsuitable for container environments; the
+.Pa docker
+targets only build
+.Nm
+and do not attempt to run the test suite.
+.Pp
+.Em make test-valgrind
+runs the same suite under valgrind
+and is useful for catching memory errors, while
+.Em make test-kernel
+cycles through a set of kernel images in kernel_images
+folder to ensure probe compatibility.
 .Sh INCLUDED BINARIES
 .Xr quark-mon 8
 is a program that dumps