MVGAL Build Guide

Version: 0.2.2

Prerequisites

Required

Package	Fedora/RHEL
CMake ≥ 3.16	`cmake`
Ninja	`ninja-build`
GCC ≥ 11 or Clang ≥ 13	`gcc-c++`
libdrm	`libdrm-devel`
libpci / pciaccess	`pciutils-devel`
libudev	`systemd-devel`
pkg-config	`pkgconfig`

Optional

Package	Purpose	Fedora/RHEL
Vulkan SDK	Vulkan layer build	`vulkan-devel vulkan-tools`
OpenCL headers	OpenCL layer build	`opencl-headers ocl-icd-devel`
Rust ≥ 1.75	Safety crates	`rustup`
Go ≥ 1.21	REST API server	`golang`
Qt5 or Qt6	Dashboard	`qt5-qtbase-devel` or `qt6-qtbase-devel`
Linux kernel headers	Kernel module	`kernel-devel`

Automated install

bash scripts/install_dependencies.sh

All privileged steps use pkexec.

CMake Build (Primary)

Quick build

mkdir -p build_output && cd build_output
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Full build with all options

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DMVGAL_BUILD_KERNEL=ON \
  -DMVGAL_BUILD_RUNTIME=ON \
  -DMVGAL_BUILD_API=ON \
  -DMVGAL_BUILD_TOOLS=ON \
  -DMVGAL_ENABLE_RUST=ON \
  -DMVGAL_BUILD_TESTS=ON \
  -G Ninja
ninja -j$(nproc)

CMake Options

Option	Default	Description
`MVGAL_BUILD_KERNEL`	ON	Build kernel module source
`MVGAL_BUILD_RUNTIME`	ON	Build C++20 runtime daemon
`MVGAL_BUILD_API`	OFF	Build API layers (Vulkan, OpenCL, CUDA)
`MVGAL_BUILD_GAMING`	OFF	Build gaming integration
`MVGAL_BUILD_TOOLS`	ON	Build CLI tools
`MVGAL_ENABLE_RUST`	ON	Build Rust safety crates
`MVGAL_BUILD_TESTS`	ON	Build test suite
`MVGAL_ENABLE_SANITIZERS`	OFF	Enable ASan + UBSan (Debug only)
`MVGAL_ENABLE_COVERAGE`	OFF	Enable gcov coverage
`MVGAL_USE_CCACHE`	ON	Use ccache if available

Build targets

cmake --build build_output --target mvgald          # daemon only
cmake --build build_output --target mvgal-info      # single tool
cmake --build build_output --target VK_LAYER_MVGAL  # Vulkan layer
cmake --build build_output --target mvgal_opencl    # OpenCL layer

Meson Build (Alternative)

meson setup builddir \
  -Dwith_vulkan=true \
  -Dwith_opencl=true \
  -Dwith_daemon=true \
  -Dwith_tests=true \
  -Dbuildtype=release
ninja -C builddir
ninja -C builddir test

Meson options (`meson_options.txt`)

Option	Default	Description
`with_vulkan`	false	Build Vulkan layer
`with_opencl`	false	Build OpenCL layer
`with_cuda`	false	Build CUDA shim
`with_daemon`	true	Build daemon
`with_tests`	false	Build tests
`with_benchmarks`	false	Build benchmarks
`with_kernel_module`	false	Build kernel module

Zig Build

zig build                                    # build all defaults
zig build -Dbuild-runtime=true              # daemon + frame pacer
zig build -Dbuild-tools=true                # CLI tools
zig build -Dbuild-tests=true test           # run tests

Rust Components

# Build all crates
cargo build --release

# Build individual crates
cargo build --release -p fence_manager
cargo build --release -p memory_safety
cargo build --release -p capability_model

# Run tests
cargo test
cargo test --release

# Check without building
cargo check --all

Kernel Module

The kernel module requires kernel headers and must be built with kbuild:

cd kernel
make -C /lib/modules/$(uname -r)/build M=$(pwd) modules

# Load (requires pkexec)
pkexec insmod mvgal.ko
pkexec insmod mvgal.ko enable_debug=1   # with debug logging

# Verify
dmesg | grep MVGAL
ls /dev/mvgal0

# Unload
pkexec rmmod mvgal

The kernel module is tested on Linux 6.19. It uses class_create compatibility shims for kernels 6.4+.

Qt Dashboard

mkdir -p ui/build && cd ui/build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
./mvgal-dashboard

Requires Qt5 or Qt6 with Widgets and Network modules.

Go REST Server

cd ui
go build -o mvgal-rest-server ./mvgal_rest_server.go
./mvgal-rest-server --listen :7474

Running Tests

# C tests (via CTest)
cd build_output
ctest --output-on-failure --timeout 60

# Rust tests
cargo test

# Standalone tool tests
./tools/mvgal-info
./tools/mvgal-bench all
./tools/mvgal-compat --system

Installation

Generic installer (recommended)

bash build/install.sh [--prefix /usr] [--no-kernel] [--no-daemon]

All privileged steps use pkexec:

Kernel module → /lib/modules/$(uname -r)/extra/mvgal.ko
udev rules → /etc/udev/rules.d/99-mvgal.rules
Vulkan layer → /usr/share/vulkan/implicit_layer.d/VK_LAYER_MVGAL.json
OpenCL ICD → /etc/OpenCL/vendors/mvgal.icd
Systemd service → /etc/systemd/system/mvgald.service
Config → /etc/mvgal/mvgal.conf

CMake install

cd build_output
pkexec make install   # or: pkexec cmake --install .

Cross-Compilation (ARM64)

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=build/cmake/toolchains/aarch64-linux-gnu.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DMVGAL_BUILD_KERNEL=OFF   # kernel module requires native build
make -j$(nproc)

sudo dnf install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

Requires aarch64-linux-gnu-gcc cross-compiler:

Packaging

RPM (Fedora / RHEL / openSUSE)

rpmbuild -bb packaging/rpm/mvgal.spec
# Output: ~/rpmbuild/RPMS/x86_64/mvgal-0.2.2-1.x86_64.rpm
pkexec rpm -ivh ~/rpmbuild/RPMS/x86_64/mvgal-0.2.2-1.x86_64.rpm

CI / GitHub Actions

Both workflows are manual-only (workflow_dispatch). To run:

Go to Actions tab on GitHub
Select CI or Build on Fedora COPR
Click Run workflow

The CI workflow runs:

Build matrix: Fedora 40 + 41, GCC + Clang
Unit tests via CTest
Vulkan layer smoke test (lavapipe)
clang-tidy static analysis
clang-format check
Rust clippy + rustfmt
Packaging check
shellcheck on all .sh files

Troubleshooting

`libdrm not found`

sudo dnf install libdrm-devel  # Fedora

`vulkan/vulkan.h not found`

sudo dnf install vulkan-devel
cmake .. -DMVGAL_BUILD_API=ON

Kernel module fails to load: `-EBUSY`

pkexec rmmod mvgal
pkexec insmod kernel/mvgal.ko

The module uses alloc_chrdev_region to avoid conflicts. If /dev/mvgal0 already exists from a previous load:

Rust build fails: `MSRV`

rustup update stable
rustup default stable

MVGAL requires Rust 1.75+: