Skip to content

Installation Guide

This guide helps you install and configure Gthulhu and Qumun.

System Requirements

Hardware Requirements

  • CPU: x86_64 architecture processor
  • Memory: At least 4GB RAM
  • Storage: At least 10GB free space

Software Requirements

Kernel Version Requirement

Linux Kernel 6.12+ with sched_ext enabled is required. Please make sure your kernel meets this requirement.

Required Packages

Package Version Requirement Purpose
Go 1.22+ User-space scheduler development
LLVM/Clang 17+ BPF program compilation
libbpf Latest BPF library
make - Build tool
git - Version control

Distribution-Specific Installation

Choose your Linux distribution below for detailed installation instructions.

Ubuntu 25.04

To save time, we skip kernel compilation/installation and use Ubuntu 25.04 which directly supports sched_ext: https://canonical.com/blog/canonical-releases-ubuntu-25-04-plucky-puffin

Verify Kernel Support

# Check kernel version
uname -r

# Check sched_ext support
grep -r "CONFIG_SCHED_CLASS_EXT" /boot/config-$(uname -r) || \
cat /proc/config.gz | gunzip | grep "CONFIG_SCHED_CLASS_EXT"

# Check BPF support
grep -r "CONFIG_BPF" /boot/config-$(uname -r) | head -5

Install Dependencies

sudo apt-get update
sudo apt-get install --yes bsdutils
sudo apt-get install --yes build-essential
sudo apt-get install --yes pkgconf
sudo apt-get install --yes llvm-17 clang-17 clang-format-17
sudo apt-get install --yes libbpf-dev libelf-dev libzstd-dev zlib1g-dev
sudo apt-get install --yes virtme-ng
sudo apt-get install --yes gcc-multilib
sudo apt-get install --yes systemtap-sdt-dev
sudo apt-get install --yes python3 python3-pip ninja-build
sudo apt-get install --yes libseccomp-dev protobuf-compiler
sudo apt-get install --yes meson cmake

Configure Clang

for tool in "clang" "clang-format" "llc" "llvm-strip"
do
  sudo rm -f /usr/bin/$tool
  sudo ln -s /usr/bin/$tool-17 /usr/bin/$tool
done

openSUSE Tumbleweed

openSUSE Tumbleweed provides rolling updates and supports kernel 6.12+ with sched_ext.

Verify Kernel Support

# Check kernel version
uname -r

# Check sched_ext support
grep -r "CONFIG_SCHED_CLASS_EXT" /boot/config-$(uname -r) || \
cat /proc/config.gz | gunzip | grep "CONFIG_SCHED_CLASS_EXT"

# Check BPF support
grep -r "CONFIG_BPF" /boot/config-$(uname -r) | head -5

Install Dependencies

# Update package repository
sudo zypper refresh

# Install build tools and compilers
sudo zypper install -y gcc make cmake meson ninja pkg-config

# Install LLVM/Clang 18+ (minimum required: 17)
sudo zypper install -y llvm18 clang18 clang18-devel

# Install development libraries
sudo zypper install -y libbpf-devel libelf-devel libzstd-devel zlib-devel

# Install additional build dependencies
sudo zypper install -y systemtap-sdt-devel libseccomp-devel jq protobuf-devel

# Install static libraries for static linking
sudo zypper install -y zlib-devel-static libzstd-devel-static

Configure Clang

for tool in "clang" "clang-format" "llc" "llvm-strip"
do
  sudo rm -f /usr/bin/$tool
  sudo ln -s /usr/bin/$tool-18 /usr/bin/$tool
done

CachyOS (6.17.5-1-cachyos)

Verify Kernel Support

# Check kernel version (should be 6.12+)
uname -r

# Check sched_ext support
zcat /proc/config.gz | grep "CONFIG_SCHED_CLASS_EXT"

# Check BPF support
zcat /proc/config.gz | grep "CONFIG_BPF" | head -5

Expected output should show: 

CONFIG_SCHED_CLASS_EXT=y
CONFIG_BPF=y
CONFIG_BPF_SYSCALL=y
CONFIG_BPF_JIT=y
CONFIG_BPF_JIT_ALWAYS_ON=y
CONFIG_BPF_JIT_DEFAULT_ON=y

Install Dependencies

# Update system
sudo pacman -Syu

# Install base development tools
sudo pacman -S --needed base-devel

# Install LLVM/Clang toolchain (minimum required: 17)
sudo pacman -S --needed llvm clang

# Install BPF and development libraries
sudo pacman -S --needed libbpf libelf zstd

# Install build tools
sudo pacman -S --needed pkgconf meson cmake ninja

# Install additional dependencies
sudo pacman -S --needed systemtap python python-pip jq libseccomp protobuf

Install Static Libraries

CachyOS packages only include dynamic libraries by default. Static libraries are required for Gthulhu's static linking:

zstd static library: 

cd /tmp
wget https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-1.5.7.tar.gz
tar xf zstd-1.5.7.tar.gz
cd zstd-1.5.7
make lib-release
sudo cp lib/libzstd.a /usr/lib/

zlib static library: 

cd /tmp
wget https://zlib.net/zlib-1.3.1.tar.gz
tar xf zlib-1.3.1.tar.gz
cd zlib-1.3.1
./configure --static
make
sudo cp libz.a /usr/lib/

Install Go

Before building Gthulhu, install Golang (required version: 1.22+):

wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz

Add the following to ~/.profile:

export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$GOROOT/bin:$GOPATH/bin:$PATH

After adding, run source ~/.profile to apply the changes.

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Build Gthulhu

After the prerequisites are installed, clone and build Gthulhu:

# Clone repository
git clone https://github.com/Gthulhu/Gthulhu.git
cd Gthulhu

# Clone libbpf dependency
make dep

# Initialize and update submodules
git submodule init
git submodule sync
git submodule update

# Build sched_ext framework
cd scx
cargo build --release -p scx_rustland
cd ..

# Build libbpfgo
cd libbpfgo
make
cd ..

# Build Gthulhu
make

After compilation, Gthulhu should run successfully on your system:

image

You can observe Gthulhu’s output to see how many tasks are currently being scheduled by Gthulhu.

Troubleshooting

Issue 1: ERROR: Program 'clang' not found or not executable

If you see this when running meson setup build --prefix ~, try: 

sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-17 100
sudo update-alternatives --install /usr/bin/llvm-strip llvm-strip /usr/bin/llvm-strip-17 100

Next Steps

After installation, you can:

  • 📖 Read How It Works (how-it-works.md) to understand the scheduler’s mechanisms
  • 🎯 See Project Goals (project-goals.md) for design principles
  • 🔧 Refer to the API Reference (api-reference.md) for custom development

Installation Complete

Congratulations! You have successfully installed the Gthulhu scheduler. If you encounter any issues, check the FAQ (faq.md) or open an issue on GitHub.