From de3679c1a07d680a4b3907071574c09b27b03814 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 8 Jun 2026 15:39:12 +0000 Subject: [PATCH 1/5] docs: document build process --- README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 217f13b..0411010 100644 --- a/README.md +++ b/README.md @@ -41,15 +41,84 @@ dnf install -y krunvm ### Building from sources -#### Dependencies +The build generates man pages from the files in `docs/`, so `asciidoctor` must be installed and available in `PATH`. -* Rust Toolchain -* [libkrun](https://github.com/containers/libkrun) -* [buildah](https://github.com/containers/buildah) +#### Build-time dependencies + +* Rust stable toolchain, including `cargo` +* [libkrun](https://github.com/containers/libkrun) headers and libraries * [asciidoctor](https://github.com/asciidoctor/asciidoctor) +* A C toolchain and the platform libraries required by `libkrun` + +[buildah](https://github.com/containers/buildah) is required at runtime to create and manage VMs, but it is not linked into the `krunvm` binary. + +On macOS, install the Homebrew build dependencies with: + +```sh +brew tap slp/krun +brew install asciidoctor libkrun +``` + +On Debian or Ubuntu systems, the CI setup builds `libkrun` from source after installing its package dependencies: + +```sh +sudo apt-get update +sudo apt-get install -y \ + asciidoctor \ + libvirglrenderer-dev \ + libepoxy-dev \ + libdrm-dev \ + libpipewire-0.3-dev \ + libclang-dev +curl -OL https://github.com/containers/libkrun/archive/refs/tags/v1.17.0.tar.gz +tar xf v1.17.0.tar.gz +make -C libkrun-1.17.0 +sudo make -C libkrun-1.17.0 PREFIX=/usr install +``` #### Building +Use the Makefile for normal local builds: + +```sh +make ``` + +This creates a release binary at `target/release/krunvm`. +On macOS, the Makefile also signs the release binary with `krunvm.entitlements`. + +For a debug build: + +```sh +make debug +``` + +You can also build directly with Cargo: + +```sh cargo build --release ``` + +If you build directly with Cargo on macOS, sign the resulting binary before running it. + +#### Installing + +Install the release binary with: + +```sh +make install PREFIX=/usr/local +``` + +Use `DESTDIR` when staging an install for packaging: + +```sh +make install PREFIX=/usr DESTDIR=/tmp/krunvm-root +``` + +#### Checking changes + +Run the same Clippy check used by CI with: + +```sh +cargo clippy --locked -- -D warnings +``` From dc3783312a2517b9abc2c710858a12c0e98bb131 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 8 Jun 2026 15:57:22 +0000 Subject: [PATCH 2/5] docs: simplify libkrun build requirements --- README.md | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 0411010..7006886 100644 --- a/README.md +++ b/README.md @@ -48,33 +48,12 @@ The build generates man pages from the files in `docs/`, so `asciidoctor` must b * Rust stable toolchain, including `cargo` * [libkrun](https://github.com/containers/libkrun) headers and libraries * [asciidoctor](https://github.com/asciidoctor/asciidoctor) -* A C toolchain and the platform libraries required by `libkrun` +* A working C linker/toolchain for native linking -[buildah](https://github.com/containers/buildah) is required at runtime to create and manage VMs, but it is not linked into the `krunvm` binary. - -On macOS, install the Homebrew build dependencies with: - -```sh -brew tap slp/krun -brew install asciidoctor libkrun -``` - -On Debian or Ubuntu systems, the CI setup builds `libkrun` from source after installing its package dependencies: +Install `libkrun` from your platform packages when available. +If you need to build it from source, follow the upstream [`libkrun` repository](https://github.com/containers/libkrun) documentation. -```sh -sudo apt-get update -sudo apt-get install -y \ - asciidoctor \ - libvirglrenderer-dev \ - libepoxy-dev \ - libdrm-dev \ - libpipewire-0.3-dev \ - libclang-dev -curl -OL https://github.com/containers/libkrun/archive/refs/tags/v1.17.0.tar.gz -tar xf v1.17.0.tar.gz -make -C libkrun-1.17.0 -sudo make -C libkrun-1.17.0 PREFIX=/usr install -``` +[buildah](https://github.com/containers/buildah) is required at runtime to create and manage VMs, but it is not linked into the `krunvm` binary. #### Building From 02faf827df879bbabbc81e8090b81924b99e0291 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 8 Jun 2026 16:27:33 +0000 Subject: [PATCH 3/5] add verbose build flag documentation --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 7006886..749d86d 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,12 @@ You can also build directly with Cargo: cargo build --release ``` +For more info on build errors run: + +```sh +RUSTFLAGS='--verbose' make +``` + If you build directly with Cargo on macOS, sign the resulting binary before running it. #### Installing From d675d0377b692c8d8ad87241a7ef137a155b226b Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 8 Jun 2026 17:13:24 +0000 Subject: [PATCH 4/5] build: find libkrun in local system paths --- README.md | 1 + build.rs | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 88 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 749d86d..c6fe5a3 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ The build generates man pages from the files in `docs/`, so `asciidoctor` must b Install `libkrun` from your platform packages when available. If you need to build it from source, follow the upstream [`libkrun` repository](https://github.com/containers/libkrun) documentation. +If `libkrun` is installed outside the common system or Homebrew library directories, set `LIBKRUN_LIB_DIR` to the directory containing the shared library before building `krunvm`. [buildah](https://github.com/containers/buildah) is required at runtime to create and manage VMs, but it is not linked into the `krunvm` binary. diff --git a/build.rs b/build.rs index e46457a..87b6e9b 100644 --- a/build.rs +++ b/build.rs @@ -1,4 +1,4 @@ -use std::path::Path; +use std::path::{Path, PathBuf}; use std::{env, fs, io, process}; const COMMANDS: [&str; 7] = [ @@ -10,6 +10,7 @@ const COMMANDS: [&str; 7] = [ "krunvm-list", "krunvm-start", ]; +const LIBKRUN_LIB_DIR_ENV: &str = "LIBKRUN_LIB_DIR"; fn main() { let outdir = match env::var_os("OUT_DIR") { @@ -26,8 +27,92 @@ fn main() { } } + configure_libkrun_linking(); +} + +/// Configure native linker search paths for libkrun. +fn configure_libkrun_linking() { + println!("cargo:rerun-if-env-changed={}", LIBKRUN_LIB_DIR_ENV); + + if let Some(dir) = env::var_os(LIBKRUN_LIB_DIR_ENV) { + println!( + "cargo:rustc-link-search=native={}", + PathBuf::from(dir).display() + ); + return; + } + + for dir in candidate_libkrun_dirs() { + if dir.join(libkrun_library_name()).exists() { + println!("cargo:rustc-link-search=native={}", dir.display()); + return; + } + } + + println!( + "cargo:warning=unable to find libkrun in common library directories; set {} to the directory containing {}", + LIBKRUN_LIB_DIR_ENV, + libkrun_library_name() + ); +} + +/// Return common system library directories where libkrun may be installed. +fn candidate_libkrun_dirs() -> Vec { + let mut dirs = Vec::new(); + + #[cfg(target_os = "linux")] + { + if let Some(multiarch) = linux_multiarch_dir() { + push_unique( + &mut dirs, + PathBuf::from(format!("/usr/local/lib/{multiarch}")), + ); + push_unique(&mut dirs, PathBuf::from(format!("/usr/lib/{multiarch}"))); + } + + push_unique(&mut dirs, PathBuf::from("/usr/local/lib64")); + push_unique(&mut dirs, PathBuf::from("/usr/local/lib")); + push_unique(&mut dirs, PathBuf::from("/usr/lib64")); + push_unique(&mut dirs, PathBuf::from("/usr/lib")); + } + #[cfg(target_os = "macos")] - println!("cargo:rustc-link-search=/opt/homebrew/lib"); + { + push_unique(&mut dirs, PathBuf::from("/opt/homebrew/lib")); + push_unique(&mut dirs, PathBuf::from("/usr/local/lib")); + } + + dirs +} + +/// Return the Debian-style multiarch library directory for the target. +#[cfg(target_os = "linux")] +fn linux_multiarch_dir() -> Option<&'static str> { + match env::var("CARGO_CFG_TARGET_ARCH").as_deref() { + Ok("x86_64") => Some("x86_64-linux-gnu"), + Ok("aarch64") => Some("aarch64-linux-gnu"), + _ => None, + } +} + +/// Return the platform-specific libkrun shared library filename. +fn libkrun_library_name() -> &'static str { + #[cfg(target_os = "macos")] + { + "libkrun.dylib" + } + + #[cfg(not(target_os = "macos"))] + { + "libkrun.so" + } +} + +/// Add a path once while preserving search order. +fn push_unique(dirs: &mut Vec, dir: PathBuf) { + if !dirs.contains(&dir) { + dirs.push(dir); + } } fn generate_man_page>(outdir: P, command: &str) -> io::Result<()> { From 158d3c4ede1be567889a841a478c9124862b3a65 Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Mon, 8 Jun 2026 17:24:34 +0000 Subject: [PATCH 5/5] simplify instruction changes a bit more --- README.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c6fe5a3..5ce5751 100644 --- a/README.md +++ b/README.md @@ -41,20 +41,19 @@ dnf install -y krunvm ### Building from sources -The build generates man pages from the files in `docs/`, so `asciidoctor` must be installed and available in `PATH`. +#### Dependencies -#### Build-time dependencies - -* Rust stable toolchain, including `cargo` -* [libkrun](https://github.com/containers/libkrun) headers and libraries +* [Rust Toolchain](https://rustup.rs/) +* [libkrun](https://github.com/containers/libkrun) +* [buildah](https://github.com/containers/buildah) * [asciidoctor](https://github.com/asciidoctor/asciidoctor) -* A working C linker/toolchain for native linking -Install `libkrun` from your platform packages when available. -If you need to build it from source, follow the upstream [`libkrun` repository](https://github.com/containers/libkrun) documentation. -If `libkrun` is installed outside the common system or Homebrew library directories, set `LIBKRUN_LIB_DIR` to the directory containing the shared library before building `krunvm`. -[buildah](https://github.com/containers/buildah) is required at runtime to create and manage VMs, but it is not linked into the `krunvm` binary. +For example, on Debian/Ubuntu: + +```sh +apt install asciidoctor buildah +``` #### Building @@ -82,7 +81,7 @@ cargo build --release For more info on build errors run: ```sh -RUSTFLAGS='--verbose' make +make RUSTFLAGS='--verbose' ``` If you build directly with Cargo on macOS, sign the resulting binary before running it.